Inside Macintosh: Apple Game Sprockets Guide /

Chapter 2 - DrawSprocket / DrawSprocket Reference

DrawSprocket Functions / Choosing a Context and Saving Preferences

DSpFindBestContext

You can use the DSpFindBestContext function to find the context that best matches a context you describe.

OSStatus DSpFindBestContext (
const DSpContextAttributesPtr inDesiredAttributes,
DSpContextReference *outContext);

inDesiredAttributes

A pointer to a context attributes structure. You should specify as best as possible the details of a context you would like to use.

outContext

On exit, a reference to the context that best meets or exceeds the specified attribute requirements.

function result

A result code.

DESCRIPTION

The function DSpFindBestContext takes, in the inDesiredAttributes parameter, a pointer to a context attributes structure describing display characteristics, such as display height and width, preferred pixel depth, and color capability, that your program needs. It returns, in the outContext parameter, a reference to the context that best matches the description. All display contexts are considered that meet or exceed the requirements in the attributes. If no such contexts exist, then an error is returned.

The game should check the attributes of the chosen context by calling DSpContext_GetAttributes. It is possible that the game may want to use attributes of the context that exceed those asked for. For example, the game may request a mode such as 320x200x8 but the best match is a 640x480x8 display; the game can adapt to a full screen mode once it is aware of the situation.

CALLING RESTRICTIONS

Do not call this function during an interrupt.