ADC Home > Reference Library > Reference > Carbon > Games > Apple Game Sprockets Reference (Not Recommended) >

< Previous PageNext Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Deprecated Apple Game Sprockets Reference (Not Recommended) Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

DSpContext_Dispose

(Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_Dispose (
   DSpContextReference inContext
);

Parameters
inContext
Return Value

A result code. See “Game Sprockets Result Codes.”

Availability
Declared In
DrawSprocket.h

DSpContext_FadeGamma

Sets brightness of the display to the specified intensity. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_FadeGamma (
   DSpContextReference inContext,
   SInt32 inPercentOfOriginalIntensity,
   RGBColor *inZeroIntensityColor
);

Parameters
inContext

A reference to the context whose display is to be faded. If you pass NULL for this parameter, the fade operation applies simultaneously to all displays.

inPercentOfOriginalIntensity

The percentage (0–100) of the display’s full intensity that you want to achieve with this call. Values above 100 percent begin to converge on white. If you have specified an intensity color, values less than zero begin to converge on black.

inZeroIntensityColor

A pointer to the color that is to correspond to zero intensity (represented by a value of 0 in the inPercentOfOriginalIntensity parameter). If you pass NULL for this parameter, the zero-intensity color is black.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

Fading the display is an aesthetically pleasing way to transition into and out of your game and between different sections of it. When performing a resolution-mode switch (as when activating and deactivating your context’s play state), it is important to fade the display to hide the flash that occurs.

DSpContext_FadeGamma performs a gamma fade, which gives better results than a simple indexed fade.

Fading using DSpContext_FadeGamma is an incremental process. That is, over a period of time, you make repeated, timed calls to DSpContext_FadeGamma, each time passing it an incrementally different value for the inPercentOfOriginalIntensity parameter, until the final desired intensity is achieved. The intensity value you pass is usually an integer between 0 and 100. It can be greater than 100, if you want to use fading to create a high-intensity burst of light, or less than 100 if you have specified a zero-intensity color and want to fade the color toward black.

The zero-intensity value that you fade out to is by default black, but it can be any color that you specify in the inZeroIntensityColor parameter. You can achieve special effects by fading partially toward one zero-intensity color and then completing the fade to a different one. At the point when you actually switch resolution modes, the zero-intensity color must be black and your display must be completely faded if there is to be no visible flash.

To automatically accomplish a smooth fade all the way from full intensity to zero intensity, or vice versa, in a single operation, use the function DSpContext_FadeGammaIn and the DSpContext_FadeGammaOut function.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_FadeGammaIn

Completely fades in a display to a color of your choice. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_FadeGammaIn (
   DSpContextReference inContext,
   RGBColor *inZeroIntensityColor
);

Parameters
inContext

A reference to the context whose display is to be faded. The function fades the display from 0 percent to 100 percent intensity over a period of one second. If you pass NULL for this parameter, the fade operation applies simultaneously to all displays.

inZeroIntensityColor

The color that is to correspond to zero intensity. If you pass NULL for this parameter, the zero-intensity color is black.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

A key press or a mouse-button click will jump the fade to its end point immediately.

You can perform a manual fade with the function DSpContext_FadeGamma.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_FadeGammaOut

Completely fades out a display to a color of your choice. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_FadeGammaOut (
   DSpContextReference inContext,
   RGBColor *inZeroIntensityColor
);

Parameters
inContext

A reference to the context whose display is to be faded. The function fades the display from 100 percent to 0 percent intensity over a period of one second. If you pass NULL for this parameter, the fade operation applies simultaneously to all displays.

inZeroIntensityColor

A pointer to the color that is to correspond to zero intensity. If you pass NULL for this parameter, the zero-intensity color is black.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

The initial gamma is that set by DrawSprocket when DSpStartup was called, or the last gamma value set by calling the DSpContext_FadeGamma function. If you had changed the system gamma to a different value, you may see a flash at the beginning of the fade due to the change in the initial gamma.

A key press or a mouse button click will jump the fade to its end point immediately.

You can perform a manual fade with the DSpContext_FadeGamma function.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_GetAttributes

Obtains the attributes of a given context. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_GetAttributes (
   DSpContextReferenceConst inContext,
   DSpContextAttributesPtr outAttributes
);

Parameters
inContext

The context whose attributes you want to obtain.

outAttributes

On return, outAttributes points to a context attributes structure. See DSpContextAttributes for more information.

Return Value

A result code. See “Game Sprockets Result Codes.”

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_GetBackBuffer

Obtains the back buffer for the context. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_GetBackBuffer (
   DSpContextReference inContext,
   DSpBufferKind inBufferKind,
   CGrafPtr *outBackBuffer
);

Parameters
inContext

A reference to the context whose back buffer is to be returned.

inBufferKind

The kind of buffer. Currently the only supported buffer kind is kDSpBufferKind_Normal.

outBackBuffer

On return, a pointer to the back buffer (that is, to a CGrafPort).

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

The back buffer, which is where the game should draw to, is the next buffer that will be displayed on a call to the function DSpContext_SwapBuffers.

The pointer to the back buffer may change after a call to DSpContext_SwapBuffers, so you must call this function before rendering every frame.

If you have specified an underlay for the context, the back buffer will have the underlay image restored before this call returns.

If there are no available back buffers (they are all queued up for display), this function will block until one is available. To avoid blocking, call the DSpContext_IsBusy function until it returns false.

Note that 3D hardware accelerators typically must draw using a graphics device ( GDevice) rather than a graphics port.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_GetCLUTEntries

Retrieves one or more color entries from a color lookup table. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_GetCLUTEntries (
   DSpContextReferenceConst inContext,
   ColorSpec *outEntries,
   UInt16 inStartingEntry,
   UInt16 inLastEntry
);

Parameters
inContext

The context whose color lookup table is to be accessed.

outEntries

On return, an array of color specification records that contain the retrieved table entries.

inStartingEntry

The (zero-based) index position in the color lookup table of the first entry to retrieve.

inLastEntry

The number of entries to retrieve.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

After you get the entries you can modify them and reassign them to the color table, for purposes such as color-table animation, with the function DSpContext_SetCLUTEntries.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_GetDisplayID

Obtains the ID of the display a context is associated with. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_GetDisplayID (
   DSpContextReferenceConst inContext,
   DisplayIDType *outDisplayID
);

Parameters
inContext

A reference to the context whose monitor display ID you want to determine.

outDisplayID

On return, the display ID for the monitor associated with the context.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

Note that 3D hardware accelerators (such as RAVE) typically must draw using a graphics device ( GDevice) rather than a graphics port. To do so, you can call DSpContext_GetDisplayID to get the display ID of the device associated with the context and then call the Display Manager function DMGetDeviceByDisplayID to obtain the GDevice.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_GetFrontBuffer

Obtains the front buffer for the context. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_GetFrontBuffer (
   DSpContextReferenceConst inContext,
   CGrafPtr *outFrontBuffer
);

Parameters
inContext

A reference to the context whose front buffer is to be returned.

outFrontBuffer

On return, a pointer to the front buffer (that is, to a CGrafPort).

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

The front buffer is the screen display. Typically you use this function when you are not using backbuffers and you want to pass a CGrafPtr so another interface can draw to the screen (for example, by using OpenGL or QuickTime, or you simply want to change resolutions). However, if you are drawing to the screen yourself, you must call DSpContext_GetFrontBuffer each time through your game’s drawing cycle to compensate for possible page flipping.

Note that 3D hardware accelerators (such as RAVE) typically must draw using a graphics device ( GDevice) rather than a graphics port. To do so, you should call DSpContext_GetDisplayID to get the display ID of the device the context is on and then call the Display Manager function DMGetDeviceByDisplayID to obtain the GDevice.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.1.2.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_GetMonitorFrequency

Obtains the frequency for the display associated with a context. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_GetMonitorFrequency (
   DSpContextReferenceConst inContext,
   Fixed *outFrequency
);

Parameters
inContext

A reference to a context for which you want to get the display frequency.

outFrequency

On return, the display frequency. The context must have been active for a reasonable amount of time (at least two seconds) in order to receive a correct value, because the value given by this parameter on return is calculated by timing the frame rate of the active context.

Return Value

A result code. See “Game Sprockets Result Codes.”

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Declared In
DrawSprocket.h

DSpContext_GetState

Determines the current play state of a context. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_GetState (
   DSpContextReferenceConst inContext,
   DSpContextState *outState
);

Parameters
inContext

A reference to the context whose play state you want to get.

outState

On return, the play state of the context. Valid return values are kDSpContextState_Active, kDSpContextState_Paused, and kDSpContextState_Inactive. See “Play State Constants” for more information.

Return Value

A result code. See “Game Sprockets Result Codes.”

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Declared In
DrawSprocket.h

DSpContext_GlobalToLocal

Translates a point in global coordinates into local coordinates for a context. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_GlobalToLocal (
   DSpContextReferenceConst inContext,
   Point *ioPoint
);

Parameters
inContext

A reference to the context whose local coordinates you want to translate into.

ioPoint

Takes a point in global coordinates. On return, contains the point in local coordinates.

Return Value

A result code. See “Game Sprockets Result Codes.”

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Declared In
DrawSprocket.h

DSpContext_IsBusy

Finds out whether a back buffer is available. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_IsBusy (
   DSpContextReferenceConst inContext,
   Boolean *outBusyFlag
);

Parameters
inContext

A reference to the context associated with the desired back buffer.

outBusyFlag

On return, contains true if no back buffer is available, false if a back buffer is available.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

You can use this function to determine whether a call to DSpContext_GetBackBuffer will block.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Declared In
DrawSprocket.h

DSpContext_LocalToGlobal

Translates a point from a context’s local coordinates into global coordinates. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_LocalToGlobal (
   DSpContextReferenceConst inContext,
   Point *ioPoint
);

Parameters
inContext

The context whose local coordinate system describes the point’s coordinates.

ioPoint

Takes a point’s local coordinates. On return, contains the point’s global coordinates.

Return Value

A result code. See “Game Sprockets Result Codes.”

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Declared In
DrawSprocket.h

DSpContext_Queue

Queues a context you want to switch to. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_Queue (
   DSpContextReference inParentContext,
   DSpContextReference inChildContext,
   DSpContextAttributesPtr inDesiredAttributes
);

Parameters
inParentContext

The current active context.

inChildContext

The context you want to switch to.

inDesiredAttributes

A pointer to a context attributes structure that describes the context you want to switch to.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

Typically, you use this function to queue up contexts in addition to the one specified by the function DSpContext_Reserve. After you queue a context, you make it active by calling the function DSpContext_Switch. To release a queued context, you must call the function DSpContext_Release.

Calling DSpContext_Queue also determines whether the desired context switch is actually possible. For example, among other things, DrawSprocket will check to see that both contexts are on the same display. If the contexts are incompatible, this call returns an error.

Note that you can also use this function to modify attributes of the context to be switched to.

Version Notes

Introduced with DrawSprocket 1.7.

Availability
Declared In
DrawSprocket.h

DSpContext_Release

Releases a context you are finished using. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_Release (
   DSpContextReference inContext
);

Parameters
inContext

A reference to the context to be released. Releasing the context does not necessarily remove the blanking window from the corresponding display. All displays remain covered by the blanking window until all contexts have been released or put in an inactive play state.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

You must release the context whether it was reserved or queued.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_Reserve

Reserves a context so that you can begin using it in your game. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_Reserve (
   DSpContextReference inContext,
   DSpContextAttributesPtr inDesiredAttributes
);

Parameters
inContext

A reference to the context to reserve. 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. The context will show up on the display once the context has been placed in the active state.

inDesiredAttributes

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. 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.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

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.

To release a reserved context, you must call the function DSpContext_Release.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_SetCLUTEntries

Assigns one or more color entries to a color lookup table. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_SetCLUTEntries (
   DSpContextReference inContext,
   const ColorSpec *inEntries,
   UInt16 inStartingEntry,
   UInt16 inLastEntry
);

Parameters
inContext

The context whose color lookup table is to be modified.

inEntries

A pointer to an array of color specification records.

inStartingEntry

The (zero-based) index position in the color lookup table of the first entry to replace.

inLastEntry

The number of entries to replace.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

The DSpContext_SetCLUTEntries function allows you to change a range of entries in a color lookup table, for purposes such as color-table animation.

Because of video hardware limitations, the changes you make to a color table with this function may not take effect until the next vertical retrace. Nevertheless, this function attempts to execute asynchronously and return immediately, so your program can continue execution without having to wait for the changes to be made.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_SetState

Sets the play state of a context. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_SetState (
   DSpContextReference inContext,
   DSpContextState inState
);

Parameters
inContext

A reference to the context whose play state you want to set.

inState

A constant specifying the desired play state. Valid input values for this parameter are kDSpContextState_Active, kDSpContextState_Paused, and kDSpContextState_Inactive. See “Play State Constants” for more information.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

In summary, you can make these choices:

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_SwapBuffers

Draws a context’s back buffer to the screen. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

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

Parameters
inContext

A reference to the context whose buffers are to be swapped. The function causes the invalid parts of the back buffer of the context specified in this parameter (or the entire back buffer, if its invalid-rectangle list is empty) to be drawn to the screen.

inBusyProc

A pointer to a callback function that performs any required pre-swap tasks. See DSpCallbackProcPtr for more information about implementing this function.

inUserRefCon

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

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

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 function DSpContext_IsBusy 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. When DrawSprocket calls the callback routine, it passes the reference constant you passed to DspContext_SwapBuffers in the refCon parameter.

See the callback function under DSpCallbackProcPtr for more information.

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.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpContext_Switch

Switches display contexts. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpContext_Switch (
   DSpContextReference inOldContext,
   DSpContextReference inNewContext
);

Parameters
inOldContext

The current display context.

inNewContext

The display context to switch to.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

Calling this function switches the display context immediately without any intermediate switch to the default display mode. Note that switching contexts will kill any piggyback VBL routines attached to the context you are switching out.

If you did not queue the contexts you want to switch (by calling the function DSpContext_Queue ), DSpContext_Switch returns an error.

Version Notes

Introduced with DrawSprocket 1.7.

Availability
Declared In
DrawSprocket.h

DSpFindBestContext

Finds the context that best matches the requirements you specify. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpFindBestContext (
   DSpContextAttributesPtr inDesiredAttributes,
   DSpContextReference *outContext
);

Parameters
inDesiredAttributes

A pointer to a context attributes structure describing the desired display characteristics of the context, such as display height and width, preferred pixel depth, and color capability. See DSpContextAttributes for more information about this structure.

outContext

On return, a reference to the context that best meets or exceeds the specified attribute requirements, or NULL if no such context exists.

Return Value

A result code. See “Game Sprockets Result Codes.” If no context meets the requirements you specified, the function returns kDSpContextNotFoundErr.

Discussion

Even if the call to DSpFindBestContext returns successtully, the game should check the attributes of the chosen context by calling the function 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.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpFindBestContextOnDisplayID

Determines the best context to use for a given display. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpFindBestContextOnDisplayID (
   DSpContextAttributesPtr inDesiredAttributes,
   DSpContextReference *outContext,
   DisplayIDType inDisplayID
);

Parameters
inDesiredAttributes

A pointer to a structure describing the desired attributes for the context. See DSpContextAttributes for more information.

outContext

On return, outContext points to the context that best matches the desired attributes, or NULL if no such context exists.

inDisplayID

The ID of the display to check for contexts.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

You can obtain the display ID of a monitor by calling the Display Manager.

Special Considerations
Version Notes

Introduced with DrawSprocket 1.7.

Availability
Declared In
DrawSprocket.h

DSpFindContextFromPoint

Finds out which context contains a point given in global coordinates. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpFindContextFromPoint (
   Point inGlobalPoint,
   DSpContextReference *outContext
);

Parameters
inGlobalPoint

A point in global coordinates.

outContext

On return, a reference to the context that contains that point.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

If the user moves the mouse, the game needs to know which context contains it so that the global coordinates can be properly translated into local coordinates for the context.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Declared In
DrawSprocket.h

DSpGetCurrentContext

Obtains a reference to the current display context for a given display. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpGetCurrentContext (
   DisplayIDType inDisplayID,
   DSpContextReference *outContext
);

Parameters
inDisplayID

The ID of the display whose context you want to obtain.

outContext

On return, outContext points to the current context in the given display.

Return Value

A result code. See “Game Sprockets Result Codes.”

Version Notes

Introduced with DrawSprocket 1.7.

Availability
Declared In
DrawSprocket.h

DSpGetFirstContext

Obtains the first context in the list of contexts available for a specified display. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpGetFirstContext (
   DisplayIDType inDisplayID,
   DSpContextReference *outContext
);

Parameters
inDisplayID

The ID of the display whose context you desire. You can obtain the display ID by calling the Display Manager.

outContext

On return, a reference to the first context in the list of available contexts for the specified display. You cannot use this context with any function other than DSpContext_GetAttributes, DSpContext_GetFlattendSize, DSpContext_Flatten, and DSpContext_GetDisplayID unless you reserve it with DSpContext_Reserve.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

Using the function DSpGetFirstContext in combination with DSpGetNextContext allows you to iterate over the list of contexts and choose one that best suits your needs. You may also have DrawSprocket find one for you with DSpFindBestContext or let the user select one by calling DSpUserSelectContext.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpGetMouse

Obtains the global coordinates of the mouse position. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpGetMouse (
   Point *outGlobalPoint
);

Parameters
outGlobalPoint

On return, the global coordinates of the mouse position.

Return Value

A result code. See “Game Sprockets Result Codes.”

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Declared In
DrawSprocket.h

DSpGetNextContext

Obtains the next context in a list of available contexts for a display. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpGetNextContext (
   DSpContextReference inCurrentContext,
   DSpContextReference *outContext
);

Parameters
inCurrentContext

A reference to a context in the list of contexts available for a display. This should be a reference that was just returned by DSpGetFirstContext or DSpGetNextContext. If this parameter contains the last context in the list, DSpGetNextContext returns an error.

outContext

On return, a reference to the next context in the list of available contexts.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

Using the function DSpGetNextContext in combination with DSpGetFirstContext allows you to iterate over the list of contexts and choose one that best suits your needs. For example, you could have code such as the following:

DSpContextReference theContext;
theError = DSpGetFirstContext(theDisplayID, &theContext)
/* process the error */
while (theContext)
{
    /* process the context */
    /* get the next context */
    theError = DSpGetNextContext(theContext, &theContext)
    /* process the error */
}

You may also have DrawSprocket find a display context for you by calling DSpFindBestContext or DSpFindBestContextOnDisplayID.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpGetVersion

Determines the version of DrawSprocket installed on the host computer. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

NumVersion DSpGetVersion (
   void
);

Parameters
Return Value

The version number of DrawSprocket installed.

Discussion
Special Considerations
Version Notes

Introduced with DrawSprocket 1.7.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpProcessEvent

Passes system events through to DrawSprocket so that it can correctly handle events it must know about. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpProcessEvent (
   EventRecord *inEvent,
   Boolean *outEventWasProcessed
);

Parameters
inEvent

A pointer to the event to be passed to DrawSprocket.

outEventWasProcessed

On return, true if DrawSprocket processed the event; false if the event was not processed.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

Whenever your game receives a suspend or resume event, it must call the DSpProcessEvent function so that DrawSprocket can correctly set the system state for the process switch.

When DrawSprocket is suspended, it returns the display to the resolution mode it was in before your context’s play state first became active. When DrawSprocket resumes, it restores the display to the resolution mode used by your context. However, it is your responsibility to update the contents of the display at this time.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpSetBlankingColor

Assigns a background color to the blanking window for all displays. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpSetBlankingColor (
   const RGBColor *inRGBColor
);

Parameters
inRGBColor

A pointer to the background color to use for the blanking window.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

The blanking color replaces the desktop and system adornments, such as the menu bar, for all display devices as long as any context is active.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpSetDebugMode

Keeps the screen and system resources visible during debugging. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpSetDebugMode (
   Boolean inDebugMode
);

Parameters
inDebugMode

Set this value to true if the desktop display is to remain visible, even after fading; false otherwise.

Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

During development, if you drop into the debugger when the display has been faded out, you cannot fade the display back in so that you can see the debugger screen. Calling the DSpSetDebugMode function with the inDebugMode flag set to a value of true causes your program to enter a mode in which the blanking window is not drawn and every fade operation (either in or out) causes only a partial dimming and immediate restoration of the screen intensity. Calling this function with the inDebugMode flag set to a value of false ends the mode and resumes normal operation.

To make use of this function, you must call it before activating your context. Once the blanking window is in place, this function effects only gamma fades.

This function is ignored in nondebugging builds of DrawSprocket.

Note the when using debugging builds, you can also enter debug mode by placing a folder named DSpDebugMode in your application folder.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Declared In
DrawSprocket.h

DSpShutdown

Shuts down DrawSprocket. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpShutdown (
   void
);

Parameters
Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

You must call this function before quitting the application.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

DSpStartup

Initializes DrawSprocket. (Deprecated in Mac OS X v10.4. Use Quartz Display Services instead; see Quartz Display Services Reference.)

OSStatus DSpStartup (
   void
);

Parameters
Return Value

A result code. See “Game Sprockets Result Codes.”

Discussion

You must call this function before attempting to call any DrawSprocket functions (except for DSpGetVersion ).

Note that the debug version of DrawSprocket will notify you if you did not call the DSpStartup function.

Special Considerations

Do not call at interrupt time.

Version Notes

Introduced with DrawSprocket 1.0.

Availability
Related Sample Code
Declared In
DrawSprocket.h

< Previous PageNext Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-13)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.