EdenCGL

Interface to the Apple CGL API for full screen OpenGL rendering.

Version: 1.1.0

Includes: <ApplicationServices/ApplicationServices.h>

Discussion

The purpose of EdenCGL is to create and manage one or more full screen OpenGL context using Apple's CoreGraphics DirectDisplay and Core OpenGL (CGL) applications programming interfaces (APIs).

Fullscreen OpenGL contexts may exploit certain OpenGL driver optimisations including hardware accelerated rendering, direct memory access (DMA) to pixels and page-flipped buffer swaps.

Updated:: Tuesday, April 05, 2005

Functions

EdenCGLCleanup: Cleanup and remve all full screen OpenGL contexts and restore displays.
EdenCGLContextFlush: Flush all pending OpenGL commands and swap the back buffer to the screen.
EdenCGLContextSelect: Select the context to which subsequent OpenGL commands will apply.
EdenCGLContextSetVBLSync: Turn synchronisation of buffer swaps to VBL on or off for an established fullscreen CGL context.
EdenCGLSetup: Use CGL to setup full screen OpenGL contexts on one or more displays.

EdenCGLCleanup

Cleanup and remve all full screen OpenGL contexts and restore displays.

EDEN_BOOL EdenCGLCleanup(
    void);

Return Value

Returns TRUE if successful, FALSE if an error occured.

Discussion

This function destroys all full screen OpenGL contexts, disposes of the resources used, and returns all captured displays to the system.

EdenCGLContextFlush

Flush all pending OpenGL commands and swap the back buffer to the screen.

void EdenCGLContextFlush(
    const int index);

Parameters

index: Index to context which is to be flushed to the screen. An index of 0 is the first display set up by EdenCGLSetup(), and index numbers increase consecutively with the number of full screen CGL contexts active.

The context which is to be flushed does not have to be the current context selected for OpenGL commands.

Discussion

This routine calls through to CGL's implementation of the familiar OpenGL buffer swap routine, and should be called at the completion of each drawing frame.

EdenCGLContextSelect

Select the context to which subsequent OpenGL commands will apply.

EDEN_BOOL EdenCGLContextSelect(
    const int index);

Parameters

index: Index to context which is to select for future OpenGL commands. An index of 0 is the first display set up by EdenCGLSetup(), and index numbers increase consecutively with the number of full screen CGL contexts active.

Return Value

Returns TRUE if successful, FALSE if an error occured.

Discussion

Before issuing commands to OpenGL, a rendering context must be active. The purpose of EdenCGL is to create and manage such a context. This function makes a particular CGL context (set up with a call to EdenCGLSetup()) the target for future OpenGL commands. Only one context can be the active for OpenGL commands at any one time. The context to make active is specified in the index parameter. Where more than one context has been created with EdenCGLSetup(), this function should be used to switch between the contexts.

EdenCGLContextSetVBLSync

Turn synchronisation of buffer swaps to VBL on or off for an established fullscreen CGL context.

EDEN_BOOL EdenCGLContextSetVBLSync(
    const int index,
    const EDEN_BOOL sync);

Parameters

index: Index to context which is to have its syncToVBL state changed. An index of 0 is the first display set up by EdenCGLSetup(), and index numbers increase consecutively with the number of full screen CGL contexts active.
sync: Pass a value of TRUE to have the contexts buffer swaps synced with the VBL, or FALSE to have buffer swaps occur immediately. See also the notes in the discussion of the EDEN_CGL_DISPLAY_MODE type.

Return Value

Returns TRUE if successful, FALSE if an error occured.

Discussion

When a full screen CGL context is first set up, a parameter in the EDEN_CGL_DISPLAY_MODE structure specifies whether buffer swaps are to be synchronised to the display's vertical blanking interval (VBL). This function allows the synchronisation to be turned on or off.

EdenCGLSetup

Use CGL to setup full screen OpenGL contexts on one or more displays.

EDEN_BOOL EdenCGLSetup(
    const int displayCountDesired,
    const EDEN_CGL_DISPLAY_MODE *displayModesDesired,
    const EDEN_BOOL captureAll);

Parameters

displayCountDesired: This specifies the number of fullscreen contexts to be created.
displayModesDesired: An array of EDEN_CGL_DISPLAY_MODE structures, which specify the mode the display is to be switched to prior to creating the full screen context upon it. There must be exactly as many entries in this array as the value specified by parameter displayCountDesired. See the discussion for the EDEN_CGL_DISPLAY_MODE type for more details.
captureAll: If the value TRUE is passed in, all displays on the system will be captured and covered by a blanking window prior to any display's mode being switched. This is the most optimal usage and will prevent any existing windows being moved, resized or rearranged. If set to FALSE, each display which is to have a context created on it will be captured individually. This may be useful if you need to run a debugger window on an uncaptured display.

Return Value

Returns TRUE if successful, FALSE if an error occured.

Discussion

This function creates one or more full screen accelerated OpenGL contexts via the CGL API. Each display on which a context is set up is captured, preventing its use by other programs in the system. Optionally, a more optimal path in which all displays on the system are captured can be enabled.

This function may be called more than once. Subsequent calls will add to the number of full screen contexts already set up. The parameter captureAll is ignored on subsequent calls unless EdenCGLCleanup() is called first.

Typedefs

EDEN_CGL_DISPLAY_MODE

Structure to specify a mode at which to drive a display for a fullscreen OpenGL context.

typedef struct { 
    size_t width; 
    size_t height; 
    size_t depth; 
    CGRefreshRate refresh; 
    int display; 
    EDEN_BOOL syncToVBL; 
    EDEN_BOOL stereo; 
} EDEN_CGL_DISPLAY_MODE;

Fields

width
Width of the desired display mode, in pixels (e.g. 640).

height
Height of the desired display mode, in pixels (e.g. 480).

depth
Depth of the desired display mode, in bits per pixel (e.g. 32).

refresh
Refresh rate of the desired display mode, in hertz (e.g. 60.0), or 0.0 if any available refresh rate may be used. Specifying a non-zero value for this parameter may have no effect on digitally-driven displays (e.g. LCD panels) which do not have a conventional refresh cycle.

display
Index to the display which is to be set to this mode. This is a zero-based index, where display 0 is always the main display.

display
A value of TRUE indicates that buffer swaps on this display should be synced to the vertical blanking interval (VBL) to prevent "tearing" which might occur when a swap occurs part way through a display refresh. Specifying a value for this parameter may have no effect for digitally-driven displays which do not have a VBL period.

Discussion

Prior to building an OpenGL fullscreen context on a display, it switches the display to a mode requested by user. This structure is used to specify the requested mode for a single display.

Globals

gEdenCGLActive

Indicates whether the displays are in use by EdenCGL.

extern EDEN_BOOL gEdenCGLActive;

Discussion

Will be TRUE after a successful call to EdenCGLSetup() has been made and EdenCGL is using the displays, and will be FALSE if after a call to EdenCGLCleanup() or if EdenCGLSetup() has never been called.