Inside Macintosh: Apple Game Sprockets Guide /

Chapter 2 - DrawSprocket / DrawSprocket Reference

DrawSprocket Functions / Manipulating a Context

DSpContext_Reserve

You can use the DSpContext_Reserve function to reserve a context so that you can begin using it in your game.

OSStatus DSpContext_Reserve (
DSpContextReference inContext,
const DSpContextAttributesPtr inDesiredAttributes);

inContext

A reference to the context to reserve.

DSpContextAttributesPtr

A pointer to an attributes structure that specifies the configuration you would like for the display when it is in the active or paused state.

function result

A result code.

DESCRIPTION

You pass the function a reference to the context to reserve in the inContext parameter. When the context is reserved, it is in the inactive state. There will be no visible indication that the context has been reserved at this point. To enable your context, call DSpContext_SetState (page 2-43). The context will show up on the display once the context has been placed in the active state.

The attributes structure you can specify in the DSpContextAttributesPtr parameter provides the configuration information for the display when it is in the active or paused states. If you would like to override the attributes of the context, you may do so in the attributes structure. For example, if you ask for a 320x240x16 display but the closest match is a context that is 640x480x32, passing in your requested attributes when you reserve the context will cause the DSpContext_GetBackBuffer function to return a graphics pointer that refers to a 320x240x16 drawing environment.

Along the same lines, you should turn off features that you are not interested in when you reserve the context. For example, if the context supports page flipping (and you know this because you requested the actual capabilities of the context using DSpContext_GetAttributes), you can turn off the page-flipping bit in your desired attributes so that you will be assured of using software buffering.

You should only specify a back buffer bit depth different from the display bit depth when you absolutely must, as it is the worst case scenario for DrawSprocket and will result in a synchronous call to CopyBits to bring your back buffer to the display.

CALLING RESTRICTIONS

Do not call this function during an interrupt.