Inside Macintosh: Apple Game Sprockets Guide /

Chapter 2 - DrawSprocket / DrawSprocket Reference

DrawSprocket Functions / Drawing and Double Buffering

DSpContext_SwapBuffers

You can use the DSpContext_SwapBuffers function to draw a context's back buffer to the screen.

OSStatus DSpContext_SwapBuffers(DSpContextReference inContext,
DSpCallbackProcPtr inBusyProc, 
void *inUserRefCon);

inContext

A reference to the context whose buffers are to be swapped.

inBusyProc

A pointer to an application-supplied callback function that performs any required pre-swap tasks.

inUserRefCon

A reference constant to be handed back by DrawSprocket when it calls the callback specified by the inBusyProc parameter.

function result

A result code.

DESCRIPTION

Calling the DSpContext_SwapBuffers function causes the invalid parts of the back buffer of the context specified in the inContext parameter (or the entire back buffer, if its invalid-rectangle list is empty) to be drawn to the screen.

This function returns immediately, even if the buffer swap has not yet occurred. To determine when the next call to DSpContext_GetBackBuffer will not block, you can repeatedly call the DSpContext_IsBusy function (page 2-52) until it returns a value of false.

Before performing the buffer swap, DrawSprocket repeatedly calls an application-supplied callback function, pointed to by the inBusyProc parameter, to make sure that any constraints you impose are satisfied before the swap occurs. For example, your callback might check to ensure that any QuickDraw 3D acceleration hardware has completed its rendering. When DrawSprocket calls the callback routine, it passes the callback the reference constant you passed to DspContext_SwapBuffers in the refCon parameter.

The buffer swap does not occur until the callback function returns false. The callback pointer must be of this type:

typedef Boolean (*DSpCallbackProcPtr)(DSpContextReference inContext,
             void *inRefCon);

See the MyCallbackFunction function (page 2-75) for a description of the callback function.

In a worst case scenario where the back buffer and the display have different bit depths, DSpContext_SwapBuffers immediately calls CopyBits to transfer the data. To avoid this, and to use the optimized DrawSprocket blitters, always insure that your back buffer and display bit depths are identical.

CALLING RESTRICTIONS

Do not call this function during an interrupt.