OVERVIEW OpenGL is a high-performance 3-D-oriented renderer. It is available on the Macintosh as a shared library. Use aglQueryVersion to establish what version is supported. The color buffer that OpenGL renders to is specified via a pixel format structure. These are accessed via handles, AGLPixelFmtID. To obtain a handle, a list of required attributes, together with a list of graphics devices the format must be viewable on, is passed to the system. AGL, via pixel formats, extends drawables with several buffers other than the standard color buffer. These buffers include back and auxiliary color buffers, a depth buffer, a stencil buffer, and a color accumulation buffer. To render into a drawable (window or off-screen graphics world) using OpenGL, you must first choose a pixel format that defines the required OpenGL buffers. aglChoosePixelFmt can be used to simplify selecting a pixel format. Use the selected pixel format to create both an AGL context and an AGL drawable. AGL contexts are created with aglCreateContext, and drawables are created with either the window manager or aglCreateAGLPixmap. Finally, bind the context and the drawable together using aglMakeCurrent. This context/drawable pair becomes the current context and current drawable, and it is used by all OpenGL commands until aglMakeCurrent is called with different arguments. Both QuickDraw and OpenGL commands can be used to operate on the current drawable. Note: AGL pixel formats are different from the pixel formats discussed in the chapter on drawing pixels, bitmaps, fonts, and images in the OpenGL Programming Guide. EXAMPLE Below is the minimum code required to create an RGBA-format, OpenGL- compatible window and clear it to black and generate a colored polygon. The code is correct, but only performs minimal error checking. The return values pxlfmt, cx, and status should all be tested. The full source for this example can be found in the test folder. /* * This program is based on the example program described * in "glXIntro" in the OpenGL Reference Book. * * The following routines are convenience routines for creating * and handling windows - * mac_init * mac_createWindow * mac_eventLoop * mac_destroyWindow */ #include #include #include #include "mac.h" /* Prototypes for convenience routines */ static int attributeList[] = { AGL_RGBA, AGL_NONE }; int main( int argc, char *argv[] ) { WindowPtr macwin; GLboolean status; AGLPixelFmtID pxlfmt; AGLContext cx; if( mac_init() ) { macwin = mac_createWindow( 40, 40, 300, 300 ); if( macwin != NULL ) { SetPort( macwin ); ShowWindow( macwin ); } } else { SysBeep( 30 ); return; } /******************** AGL Stuff *********************/ /* Get an appropriate pixel format */ pxlfmt = aglChoosePixelFmt( NULL, 0, attributeList); /* Create AGL context */ cx = aglCreateContext( pxlfmt, 0 ); /* Connect context to window */ status = aglMakeCurrent( (AGLDrawable)macwin, cx ); /******************** OGL Stuff *********************/ /* Clear the buffer */ glDrawBuffer( GL_FRONT ); glClearColor( 0.0, 0.0, 0.0, 0.0 ); glClear( GL_COLOR_BUFFER_BIT ); /* Set the view */ glMatrixMode( GL_PROJECTION ); glLoadIdentity(); glOrtho( -1.0, 1.0, -1.0, 1.0, -1.0, 1.0 ); /* Draw colored polygon in the window */ glColor3f( 1.0, 0.5, 0.25 ); glBegin( GL_POLYGON ); glVertex2f( -0.5, -0.5 ); glVertex2f( -0.5, 0.5 ); glVertex2f( 0.5, 0.5 ); glVertex2f( 0.5, -0.5 ); glEnd(); glFinish(); /******************** Mac Stuff *********************/ mac_eventLoop(); mac_destroyWindow( macwin ); } NOTES An AGL context must be created and attached to an AGL drawable before OpenGL commands can be executed. OpenGL commands issued while no context/drawable pair is current are ignored. Update events indicate that all buffers associated with the specified window may be damaged and should be repainted. Although certain buffers on some systems may never require repainting (the depth buffer, for example), it is incorrect to code assuming that these buffers will not be damaged. SEE ALSO glFinish, glFlush, aglChoosePixelFmt, aglCopyContext, aglCreateContext, aglCreateAGLPixmap, aglDestroyContext, aglGetConfig, aglMakeCurrent, aglQueryVersion, aglSwapBuffers, aglUseFont .i.aglChoosePixelFmt$; NAME aglChoosePixelFmt P return a pixel format that matches specified attributes and device capabilities C SPECIFICATION AGLPixelFmtID aglChoosePixelFmt( GDHandle *dev, int ndev, int *attribs ) PARAMETERS dev Specifies a list of graphics devices. ndev Specifies the number of devices in the list. attribs Specifies a list of Boolean attributes and integer attribute/value pairs. The last attribute must be AGL_NONE. DESCRIPTION aglChoosePixelFmt returns a handle to a pixel format that best meets the minimum specification of the supplied attributes matched with the list of graphics devices. If dev is NULL or ndev is zero, then the default graphics device is used in determining which pixel format to use. The Boolean AGL attributes of the handle that is returned will match the specified values, and the integer AGL attributes will meet or exceed the specified minimum values. If no conforming pixel format exists, NULL is returned. All Boolean AGL attributes default to GL_FALSE except AGL_USE_GL, which defaults to GL_TRUE. All integer AGL attributes default to zero. Default specifications are superseded by attributes included in attribs. Boolean attributes included in attribs are understood to be GL_TRUE. Integer attributes are followed immediately by the corresponding desired or minimum value. The list must be terminated with AGL_NONE. NULL is returned if an undefined AGL attribute or a request that cannot be met is encountered in attribs. Use aglGetError to determine the cause of the error. The interpretations of the various AGL attributes are as follows: AGL_USE_GL Ignored. AGL_BUFFER_SIZE Must be followed by a nonnegative integer that indicates the desired color index buffer size. The smallest index buffer of at least the specified size is preferred. Ignored if AGL_RGBA is asserted. AGL_LEVEL Must be followed by an integer buffer-level specification. This specification is honored exactly. Buffer level zero corresponds to the default frame buffer of the display. Buffer level one is the first overlay frame buffer, level two the second overlay frame buffer, and so on. Negative buffer levels correspond to underlay frame buffers. AGL_RGBA If present, color buffers store RGBA values. Otherwise, color index values are stored. AGL_DOUBLEBUFFER If present, only double-buffered formats are considered. Otherwise, only single-buffered formats are considered. AGL_STEREO If present, only stereo formats are considered. Otherwise, only monoscopic formats are considered. AGL_AUX_BUFFERS Must be followed by a nonnegative integer that indicates the desired number of auxiliary buffers. Formats with the smallest number of auxiliary buffers that meets or exceeds the specified number are preferred. AGL_RED_SIZE Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available red buffer is preferred. Otherwise, the largest available red buffer of at least the minimum size is preferred. AGL_GREEN_SIZE Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available green buffer is preferred. Otherwise, the largest available green buffer of at least the minimum size is preferred. AGL_BLUE_SIZE Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available blue buffer is preferred. Otherwise, the largest available blue buffer of at least the minimum size is preferred. AGL_ALPHA_SIZE Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available alpha buffer is preferred. Otherwise, the largest available alpha buffer of at least the minimum size is preferred. AGL_DEPTH_SIZE Must be followed by a nonnegative minimum size specification. If this value is zero, formats with no depth buffer are preferred. Otherwise, the largest available depth buffer of at least the minimum size is preferred. AGL_STENCIL_SIZE Must be followed by a nonnegative integer that indicates the desired number of stencil bitplanes. The smallest stencil buffer of at least the specified size is preferred. If the desired value is zero, formats with no stencil buffer are preferred. AGL_ACCUM_RED_SIZE Must be followed by a nonnegative minimum size specification. If this value is zero, formats with no red accumulation buffer are preferred. Otherwise, the largest possible red accumulation buffer of at least the minimum size is preferred. AGL_ACCUM_GREEN_SIZE Must be followed by a nonnegative minimum size specification. If this value is zero, formats with no green accumulation buffer are preferred. Otherwise, the largest possible green accumulation buffer of at least the minimum size is preferred. AGL_ACCUM_BLUE_SIZE Must be followed by a nonnegative minimum size specification. If this value is zero, formats with no blue accumulation buffer are preferred. Otherwise, the largest possible blue accumulation buffer of at least the minimum size is preferred. AGL_ACCUM_ALPHA_SIZE Must be followed by a nonnegative minimum size specification. If this value is zero, formats with no alpha accumulation buffer are preferred. Otherwise, the largest possible alpha accumulation buffer of at least the minimum size is preferred. EXAMPLES int attribs[] = {AGL_RGBA, AGL_RED_SIZE, 4, AGL_GREEN_SIZE, 4, AGL_BLUE_SIZE, 4, AGL_NONE}; Specifies a single-buffered RGB pixel format in the normal frame buffer, not an overlay or underlay buffer. The returned format supports at least four bits each of red, green, and blue, and possibly no bits of alpha. It does not support color index mode, double-buffering, or stereo display. It may or may not have one or more auxiliary color buffers, a depth buffer, a stencil buffer, or an accumulation buffer. NOTES Graphics devices can change their characteristics asynchronously. It is up to the application to detect when this occurs and select a new pixel format accordingly. ERRORS Possible error values are: AGL_BAD_ATTRIBUTE Unrecognized attribute AGL_ATTRIBUTE_UNAVAIL Attribute not available with selected GDevices AGL_INVALID_GDEV Bad or unsupported GDevice SEE ALSO aglCreateContext, aglGetConfig, aglListPixelFmts .i.aglCopyContext$; NAME aglCopyContext P copy state from one rendering context to another C SPECIFICATION GLboolean aglCopyContext( AGLContext src, AGLContext dst, GLuint mask ) PARAMETERS src Specifies the source context. dst Specifies the destination context. mask Specifies which portions of src state are to be copied to dst. DESCRIPTION aglCopyContext copies selected groups of state variables from src to dst. mask indicates which groups of state variables are to be copied. mask contains the bitwise OR of the same symbolic names that are passed to the OpenGL command glPushAttrib. The single symbolic constant GL_ALL_ATTRIB_BITS can be used to copy the maximum possible portion of rendering state. The copy can be done only if the renderers named by src and dst share an address space. Two rendering contexts share an address space if both are owned by a single process. Not all values for OpenGL state can be copied. For example, pixel pack and unpack state, render mode state, and select and feedback state are not copied. The state that can be copied is exactly the state that is manipulated by OpenGL command glPushAttrib. An implicit glFlush is done by aglCopyContext if src is the current context for the calling thread. If src is not the current context for the thread issuing the request, then the state of the src context is undefined. This function returns GL_TRUE on success. If GL_FALSE is returned, use aglGetError to determine the cause of the error. NOTES A process is a single execution environment, implemented in a single address space, consisting of one or more threads. A thread is one of a set of subprocesses that share a single address space, but maintain separate program counters, stack spaces, and other related global data. A thread that is the only member of its subprocess group is equivalent to a process. ERRORS Possible error values are: AGL_BAD_ATTRIBUTE Unrecognized attribute AGL_BAD_CONTEXT One or both of src/dst are invalid SEE ALSO glPushAttrib, aglCreateContext .i.aglCreateAGLPixmap$; NAME aglCreateAGLPixmap P create an off-screen AGL rendering area C SPECIFICATION AGLPixmap aglCreateAGLPixmap ( AGLPixelFmtID pix, GWorldPtr pixmap ) PARAMETERS pix Specifies the pixel format handle to be used with pixmap. pixmap Specifies the off-screen graphics world that will be used as the front left color buffer of the off-screen rendering area. DESCRIPTION aglCreateAGLPixmap creates an off-screen rendering area and returns a handle. Any AGL rendering context that was created with respect to pix can be used to render into this off-screen area. Use aglMakeCurrent to associate the rendering area with an AGL rendering context. The off-screen graphics world identified by pixmap is used as the front left buffer of the resulting off-screen rendering area. All other buffers specified by pix, including color buffers other than the front left buffer, are created without externally visible names. AGL pixmaps with double-buffering are supported. However, aglSwapBuffers is ignored by these pixmaps. If an error occurs, AGL_NONE is returned. Use aglGetError to determine the cause of the error. ERRORS Possible error values are: AGL_BAD_DRAWABLE Pixmap is not compatible with pix or pixmap is not a valid off-screen graphics world AGL_BAD_PIXELFMT Invalid pixel format AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause SEE ALSO aglCreateContext, aglMakeCurrent .i.aglCreateContext$; NAME aglCreateContext P create a new AGL rendering context C SPECIFICATION AGLContext aglCreateContext ( AGLPixelFmtID pix, AGLContext shareList ) PARAMETERS pix Specifies the pixel format handle that defines the frame buffer resources available to the rendering context. shareList Specifies the context with which to share display lists. NULL indicates that no sharing is to take place. DESCRIPTION aglCreateContext creates an AGL rendering context and returns its handle. This context can be used to render into both windows and AGL pixmaps. If aglCreateContext fails to create a rendering context, NULL is returned. Use aglGetError to determine the cause of the error. If shareList is not NULL, then all display-list indexes and definitions are shared by context shareList and by the newly created context. An arbitrary number of contexts can share a single display-list space. However, all rendering contexts that share a single display-list space must themselves exist in the same address space. Two rendering contexts share an address space if both are owned by a single process. NOTES A process is a single execution environment, implemented in a single address space, consisting of one or more threads. A thread is one of a set of subprocesses that share a single address space, but maintain separate program counters, stack spaces, and other related global data. A thread that is the only member of its subprocess group is equivalent to a process. ERRORS Possible error values are: AGL_BAD_PIXELFMT Invalid pixel format AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. AGL_LICENSE_ERROR CouldnUt find a valid license SEE ALSO aglDestroyContext, aglGetConfig, aglMakeCurrent .i.aglDestroyAGLPixmap$; NAME aglDestroyAGLPixmap P destroy an AGL pixmap C SPECIFICATION GLboolean aglDestroyAGLPixmap( AGLPixmap pix ) PARAMETERS pix Specifies the AGL pixmap to be destroyed. DESCRIPTION If AGL pixmap pix is not current, aglDestroyAGLPixmap destroys it immediately. Otherwise, pix is destroyed when it becomes not current. In either case, the resource ID is freed immediately. Any associated buffers, e.g., depth or stencil, for this drawable are destroyed at this time. This function returns GL_TRUE on success. If GL_FALSE is returned, use aglGetError to determine the cause of the error. ERRORS Possible error values are: AGL_BAD_DRAWABLE Invalid pixmap AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. SEE ALSO aglCreateAGLPixmap, aglMakeCurrent .i.aglDestroyContext$; NAME aglDestroyContext P destroy an AGL context C SPECIFICATION GLboolean aglDestroyContext( AGLContext ctx ) PARAMETERS ctx Specifies the AGL context to be destroyed. DESCRIPTION If AGL rendering context ctx is not current to any thread, aglDestroyContext destroys it immediately. Otherwise, ctx is destroyed when it becomes not current to any thread. In either case, the resource ID referenced by ctx is freed immediately. This function returns GL_TRUE on success. If GL_FALSE is returned, use aglGetError to determine the cause of the error. ERRORS Possible error values are: AGL_BAD_CONTEXT Invalid AGL context AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. SEE ALSO aglCreateContext, aglMakeCurrent .i.aglGetConfig$; NAME aglDestroyContext P destroy an AGL context C SPECIFICATION GLboolean aglDestroyContext( AGLContext ctx ) PARAMETERS ctx Specifies the AGL context to be destroyed. DESCRIPTION If AGL rendering context ctx is not current to any thread, aglDestroyContext destroys it immediately. Otherwise, ctx is destroyed when it becomes not current to any thread. In either case, the resource ID referenced by ctx is freed immediately. This function returns GL_TRUE on success. If GL_FALSE is returned, use aglGetError to determine the cause of the error. ERRORS Possible error values are: AGL_BAD_CONTEXT Invalid AGL context AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. SEE ALSO aglCreateContext, aglMakeCurrent .i.aglGetConfig$; NAME aglGetConfig P return information about AGL pixel formats C SPECIFICATION GLboolean aglGetConfig( AGLPixelFmtID pix, int attrib, int *value ) PARAMETERS pix Specifies the pixel format handle. attrib Specifies the pixel format attribute to be returned. value Returns the requested value. RETURN VALUE GL_TRUE Successful. GL_FALSE Unsuccessful. Use aglGetError to determine the cause of the error. DESCRIPTION aglGetConfig sets value to the attrib value of windows or AGL pixmaps created with respect to pix. aglGetConfig returns GL_FALSE if it fails for any reason. Otherwise, GL_TRUE is returned. attrib is one of the following: AGL_USE_GL GL_TRUE if OpenGL rendering is supported by this pixel format, GL_FALSE otherwise. AGL_BUFFER_SIZE Number of bits per color buffer. For RGBA pixel formats, AGL_BUFFER_SIZE is the sum of AGL_RED_SIZE, AGL_GREEN_SIZE, AGL_BLUE_SIZE, and AGL_ALPHA_SIZE. For color index pixel formats, AGL_BUFFER_SIZE is the size of the color indexes. AGL_LEVEL Frame buffer level of the format. Level zero is the default frame buffer. Positive levels correspond to frame buffers that overlay the default buffer, and negative levels correspond to frame buffers that underlay the default buffer. AGL_RGBA GL_TRUE if color buffers store red, green, blue, and alpha values, GL_FALSE if they store color indexes. AGL_DOUBLEBUFFER GL_TRUE if color buffers exist in front/back pairs that can be swapped, GL_FALSE otherwise. AGL_STEREO GL_TRUE if color buffers exist in left/right pairs, GL_FALSE otherwise. AGL_AUX_BUFFERS Number of auxiliary color buffers that are available. Zero indicates that no auxiliary color buffers exist. AGL_RED_SIZE Number of bits of red stored in each color buffer. Undefined if AGL_RGBA is GL_FALSE. AGL_GREEN_SIZE Number of bits of green stored in each color buffer. Undefined if AGL_RGBA is GL_FALSE. AGL_BLUE_SIZE Number of bits of blue stored in each color buffer. Undefined if AGL_RGBA is GL_FALSE. AGL_ALPHA_SIZE Number of bits of alpha stored in each color buffer. Undefined if AGL_RGB is GL_FALSE. AGL_DEPTH_SIZE Number of bits in the depth buffer. AGL_STENCIL_SIZE Number of bits in the stencil buffer. AGL_ACCUM_RED_SIZE Number of bits of red stored in the accumulation buffer. AGL_ACCUM_GREEN_SIZE Number of bits of green stored in the accumulation buffer. AGL_ACCUM_BLUE_SIZE Number of bits of blue stored in the accumulation buffer. AGL_ACCUM_ALPHA_SIZE Number of bits of alpha stored in the accumulation buffer. Although an AGL implementation can export many pixel formats that support OpenGL rendering, it must support at least two. One is an RGBA format with at least one color buffer, a stencil buffer of at least 1 bit, a depth buffer of at least 12 bits, and an accumulation buffer. Alpha bitplanes are optional in this format. The color buffer must be available on level zero. The other required pixel format is a color index one with at least one color buffer, a stencil buffer of at least 1 bit, and a depth buffer of at least 12 bits. This format must be made available on level zero. Applications are best written to select the pixel format that most closely meets their requirements. Creating windows or AGL pixmaps with unnecessary buffers can result in reduced rendering performance as well as poor resource allocation. ERRORS Possible error values are: AGL_BAD_ATTRIBUTE Invalid attribute AGL_BAD_PIXELFMT Invalid pixel format SEE ALSO aglChoosePixelFmt, aglCreateContext, aglListPixelFmts .i.aglGetCurrentContext$; NAME aglGetCurrentContext P return the current context C SPECIFICATION AGLContext aglGetCurrentContext( void ) DESCRIPTION aglGetCurrentContext returns the current context, as specified by aglMakeCurrent. If there is no current context, NULL is returned. SEE ALSO aglCreateContext, aglMakeCurrent .i.aglGetCurrentDrawable$; NAME aglGetCurrentDrawable P return the current drawable C SPECIFICATION AGLDrawable aglGetCurrentDrawable( void ) DESCRIPTION aglGetCurrentDrawable returns the current drawable, as specified by aglMakeCurrent. If there is no current drawable, AGL_NONE is returned. SEE ALSO aglCreateAGLPixmap, aglMakeCurrent .i.aglGetError$; NAME aglGetError P return the current error C SPECIFICATION GLenum aglGetError( void ) DESCRIPTION aglGetError returns the current error setting for the AGL context, if one exists, or the global AGL error setting if the current context is NULL. The error setting is then reset to AGL_OK. When an AGL error occurs, it remains flagged until aglGetError is called to reset it. Additional errors occurring while an AGL error is still flagged are lost. In other words, aglGetError returns the oldest error rather than the most recent. This is useful behavior because the oldest error is often the cause of subsequent errors. .i.aglListPixelFmts$; NAME aglListPixelFmts P list the available pixel formats of a graphics device C SPECIFICATION int aglListPixelFmts( GDHandle dev, AGLPixelFmtID **fmts) PARAMETERS dev Specifies a graphics device. fmts Returns a list of the available pixel formats for that graphics device. RETURN VALUE Returns the number of pixel formats available. If zero, use aglGetError to determine if an error occurred. DESCRIPTION aglListPixelFmts provides a way to determine which pixel formats are supported by a particular graphics device. If the dev parameter is NULL, then the default graphics device is used. fmts contains the returned list of pixel formats and must be released with free() when no longer required. fmts is NULL if no pixel formats are available for that device or an invalid device is specified. Any of the pixel formats returned in the list may be used with aglCreateContext() or aglGetConfig(). NOTES The list of formats returned for the device relate to the deviceUs current state. If this state is changed by the user, then the application must check that the desired pixel format is still valid for the device. The pointer returned in fmts should be freed once the list is finished with. ERRORS Possible error values are: AGL_INVALID_GDEV Invalid GDevice AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. SEE ALSO aglChoosePixelFmt, aglCreateContext, aglGetConfig .i.aglMakeCurrent$; NAME aglMakeCurrent P attach an AGL context to a window or an AGL pixmap C SPECIFICATION GLboolean aglMakeCurrent( AGLDrawable drawable, AGLContext ctx ) PARAMETERS drawable Specifies an AGL drawable. Must be either valid window pointer or AGL pixmap. ctx Specifies an AGL rendering context that is to be attached to drawable. DESCRIPTION aglMakeCurrent does two things: It makes ctx the current AGL rendering context of the calling thread, replacing the previously current context if there was one, and it attaches ctx to an AGL drawable, either a window or an AGL pixmap. As a result of these two actions, subsequent OpenGL rendering calls use rendering context ctx to modify AGL drawable drawable. Because aglMakeCurrent always replaces the current rendering context with ctx, there can be only one current context per thread. Pending commands to the previous context, if any, are flushed before it is released. The first time ctx is made current to any thread, its viewport is set to the full size of drawable. Subsequent calls by any thread to aglMakeCurrent with ctx have no effect on its viewport. To release the current context without assigning a new one, call aglMakeCurrent with drawable and ctx set to AGL_NONE and NULL respectively. aglMakeCurrent returns GL_TRUE if it is successful, GL_FALSE otherwise. If GL_FALSE is returned, the previously current rendering context and drawable (if any) remain unchanged. Use aglGetError to determine the cause of the error. NOTES A process is a single-execution environment, implemented in a single address space, consisting of one or more threads. A thread is one of a set of subprocesses that share a single address space, but maintain separate program counters, stack spaces, and other related global data. A thread that is the only member of its subprocess group is equivalent to a process. ERRORS Possible error values are: AGL_BAD_DRAWABLE Invalid drawable AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. AGL_NOT_RENDERING Previous context isnUt in rendering mode SEE ALSO aglCreateContext, aglCreateAGLPixmap .i.aglQueryVersion$; NAME aglQueryVersion P return the version numbers of the OpenGL shared library C SPECIFICATION GLboolean aglQueryVersion( int *major, int *minor ) PARAMETERS major Returns the major version number of the OpenGL shared library. minor Returns the minor version number of the OpenGL shared library. DESCRIPTION aglQueryVersion returns the major and minor version numbers of the OpenGL shared library. Implementations with the same major version number are upward compatible, meaning that the implementation with the higher minor number is a superset of the version with the lower minor number. major and minor do not return values if they are specified as NULL. aglQueryVersion returns GL_FALSE if it fails, GL_TRUE otherwise. major and minor are not updated when GL_FALSE is returned. Use aglGetError to determine the cause of the error. ERRORS Possible error values are: AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. .i.aglSetOptions$; NAME aglSetOptions P set AGL-specific options C SPECIFICATION GLboolean aglSetOptions ( int options) PARAMETERS options Any combination of the following masks: AGL_NONE AGL_PIXEL_OWNERSHIP AGL_CURSOR_BLANKING DESCRIPTION aglQueryVersion is used to set various AGL-specific options. The following options are supported: AGL_NONE This disables all options. AGL_PIXEL_OWNERSHIP This causes pixel store operations to the screen to be checked for windows which would obscure them. By default, testing is enabled. This option can be disabled if the window being rendered to will always be the front window and if no part of it will ever move off- screen. AGL_CURSOR_BLANKING This causes the cursor to be removed during the aglSwapBuffers call. By default, blanking is enabled. If this option is disabled, the user is responsible for ensuring the cursor is hidden during the aglSwapBuffers call. Note: The user is always responsible for blanking the cursor when rendering directly to the front buffer. aglSetOptions returns GL_FALSE if it fails, GL_TRUE otherwise. Use aglGetError to determine the cause of the error. ERRORS Possible error values are: AGL_INVALID_OPT Unrecognized option .i.aglSwapBuffers$; NAME aglSwapBuffers P make back buffer visible C SPECIFICATION GLboolean aglSwapBuffers( AGLDrawable drawable ) PARAMETERS drawable Specifies the window whose buffers are to be swapped. DESCRIPTION aglSwapBuffers promotes the contents of the back buffer of drawable to become the contents of the front buffer of drawable. The contents of the back buffer then become undefined. The update typically takes place during the vertical retrace of the monitor, rather than immediately after aglSwapBuffers is called. All AGL rendering contexts share the same notion of which are front buffers and which are back buffers. An implicit glFlush is done by aglSwapBuffers before it returns. Subsequent OpenGL commands can be issued immediately after calling aglSwapBuffers, but are not executed until the buffer exchange is completed. If drawable was not created with respect to a double-buffered pixel format, aglSwapBuffers has no effect, and no error is generated. This function returns GL_TRUE on success. If GL_FALSE is returned, use aglGetError to determine the cause of the error. ERRORS Possible error values are: AGL_BAD_CONTEXT Invalid current context AGL_BAD_DRAWABLE Invalid drawable AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. SEE ALSO glFlush .i.aglUpdateCurrent$; NAME aglUpdateCurrent P update the current contextUs drawable information C SPECIFICATION GLboolean aglUpdateCurrent( void ) DESCRIPTION aglUpdateCurrent causes the current contextUs drawable information to be updated from the windowing system. This information is initially set up by aglMakeCurrent and requires updating when an on-screen drawable is either moved or resized, or the screen resolution or depth of a GDevice is changed. If there is no current drawable, this routine does nothing. This function returns GL_TRUE on success. If GL_FALSE is returned, use aglGetError to determine the cause of the error. ERRORS Possible error values are: AGL_BAD_PXLFMT Pixel format is no longer valid for GDevice AGL_BAD_CONTEXT Invalid current context AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. Note: When a drawable is grown, GL may run out of heap space for the new buffers. If this occurs, glGetError will return GL_OUT_OF_MEMORY but the context and drawable will still be valid. To resume rendering, return the drawable to its former size and call aglUpdateContext again. SEE ALSO aglMakeCurrent .i.aglUseFont$; NAME aglUseFont P create bitmap display lists from a font C SPECIFICATION GLboolean aglUseFont( int familyID, int size, int first, int count, int listBase ) PARAMETERS familyID Specifies the font family from which character glyphs are to be taken. size Specifies the font size. first Specifies the index of the first glyph to be taken. count Specifies the number of glyphs to be taken. listBase Specifies the index of the first display list to be generated. DESCRIPTION aglUseFont generates count display lists, named listBase through listBase+count-1, each containing a single glBitmap command. The parameters of the glBitmap command of display list listBase+i are derived from glyph first+i. Bitmap parameters xorig, yorig, width, and height are computed from font metrics as descent-1, -lbearing, rbearing-lbearing, and ascent+descent, respectively. xmove is taken from the glyphUs width metric, and ymove is set to zero. Finally, the glyphUs image is converted to the appropriate format for glBitmap. Empty display lists are created for all glyphs that are requested and are not defined in font. aglUseFont is ignored if there is no current AGL context. This function returns GL_TRUE on success. If GL_FALSE is returned, use aglGetError to determine the cause of the error. ERRORS Possible error values are: AGL_DO_ALREADY Already building a display list AGL_GL_ERROR A GL error has occurred, use glGetError to determine the cause. SEE ALSO glBitmap, aglMakeCurrent