Carbon SetupGL An OpenGL setup utility

9-26-2001

Version 1.7: Modified support for shared textures to be supplied to by
the calling application.  NOTE: This is an API change and requires
applications o explicitly pass in the shared context or NULL.  Have not
updated full screen handling yet. Also supply a CW6 and CW7 project
along with Project Builder project.  Fully tested on Mac OS 10.1.

Version 1.6: Fixed support for shared textures when original context is
destroyed, recover gracefully

Version 1.5: Added support for shared textures.  Share all contexts by
default and add menu command to toggle texturing on and off

Version 1.4: Updated for Mac OS X 10.0.

- DrawSprocket version < 1.99 on Mac OS X do not provide drawing surface
that can be used by GL.  The work around is to use aglFullScreen instead
for these versions.

Version 1.3: Optimized for Carbon and bug fixes.

Version 1.2: Carbonized for Mac OS X.

Version 1.1: Adds windowed mode that allows creation of an OpenGL
context on an already existing window.  Also, cleans up existing
implementation of full screen mode.  SetupGL still handles all aspects
of GL setup on the Macintosh.

Version 1.0: Added PreflightGL () function.  Fixed various minor errors.
 Corrected fade implementation.  Added a little more robustness in the
application end in failure conditions, fixed problem with aglFont
handling.

----

The Carbon SetupGL Test is a demonstration application which shows
multi-window support with multiple OpenGL contexts using data stored in
the window refcons.  It shows proper handling Carbon TImers for
animation, window resize (with and without buffer rects), and shared
texturing among other things.

Carbon SetupGL is a set of functions that can be used in new and
existing applications to handle all aspects of OpenGL setup on the
Macintosh under OS 9.  It is designed to handle windowed or full screen
set up with good error handling and fall back cases.  The key to SetupGL
is that it attempts to match your 3D context requests with the device
that is able to handle them rather than pick a single device and hoping
that it can handle the 3D requirements.  A version of SetupGL is used in
the "Quake III Arena" for the Macintosh by id Software.

To use it one fills out the structGLInfo structure (outlined in
SetupGL.h) with the requirements and request for the context desired.
Then a call to BuildGL will allocate the best matching context if able.
BuildGL will set through all available graphics devices attempting to
allocate the requested context.  If it is unable an error will be
reported thought the ReportError function.  Currently, ReportError is
set to send a debugstr on error, applications will likely need to
override this with a more appropriate error reporting method.

Additionally, Carbon SetupGL now supports creation of GL contexts on
existing windows.  See the structGLWindowInfo structure in Carbon
SetupGL.h.

----

SetupGL also has some unique features:

- The texture RAM variable in the structGLInfo allows you to specify an
amount of texture memory, over and above the buffer requirements, that
the device must have to satisfy your requirements.  This allows you to
pick a maximum resolution and bit depth and allow SetupGL to find the
resolution and bit depth that can actually be used while maintaining the
requested amount of VRAM.  This is done by setting fDepthMust and
fSizeMust to false on entry, which allows SetupGL to set down in
resolutions and pixel depths to get a match.

- It allows specification of a screen device to try first by enumeration
of the screens.  -1 indicates the main screen.  Other screens are
enumerated in order returned by DMGetFirstScreenDevice and
DMGetNextScreenDevice with 0 being the first screen returned.  If
allocations on the desired screen fails SetupGL will automatically check
the other screens.

- SetupGL provides the function BuildGLFromWindow and
DestroyGLFromWindow to handle cases where you want to setup OpenGL on a
preexisting window.  Ensure you call the DestroyGLFromWindow to destroy
the context.

- PauseGL and ResumeGL are provided to allow the user control over the
screen.  Suppose you wish to draw a movie in the same window as OpenGL
is using, just call PauseGL, play your movie and then ResumeGL when
finished to start drawing your OpenGL scene again.

- PreflightGL checks for existence of OpenGL and if required
DrawSprocket

----

Compile time options to be aware of: Error Handler.c: kVerboseErrors:
are error strings reported

SetupDSp.c: kUseFades: are fades between resolution switches used
kUseRAMCheck: is estimated device RAM usage done

SetupGL is provided as sample code and is under constant updates.  The
areas where work is being done are:

- better frequency support for multiple resolution step down.  Need to
store frequency information with resolutions to enable better step down
logic.

Any suggestions and/or bugs can be directed to the Apple bug reporter
at: <http://developer.apple.com/bugreporter/index.html>

Descriptions of the operation of the major functions and the structures
can be found in the SetupGL.h header file.

Note: Some of the access paths will have to reset to point to the
location of the OpenGL SDK on your local system and this is built using
CodeWarrior 6, Universal Interfaces 3.4b5 and Carbon SDK 1.3d6.

We hope this helps people get up and running with OpenGL in a quick and
painless manner.

ggs