Next Page >

Hide TOC

Legacy Document

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

Apple Game Sprockets Reference (Not Recommended)

Framework	DrawSprocket/DrawSprocket.h
Declared in	DrawSprocket.h

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

Overview

Game Sprockets is a set of libraries that supported the creation of games in Mac OS 8 and 9. The libraries provided services for working with sound, imaging, user input, and network gaming. Most of Game Sprockets—including the InputSprocket, NetSprocket, and SoundSprocket libraries—is not available in Mac OS X. For documentation on these legacy APIs, see Apple Game Sprockets Legacy Reference. For detailed information on using Game Sprockets in Mac OS 8 and 9, see Apple Game Sprockets.

A subset of the DrawSprocket library, which provides functions to configure and control displays, has remained available in Carbon to facilitate the porting of legacy applications to Mac OS X. The DrawSprocket API has been deprecated for deployment targets Mac OS X version 10.4 and later. The replacement is Quartz Display Services, a modern Mac OS X API that provides similar functionality. For more information, see Quartz Display Services Reference.

Functions by Task

Activating and Deactivating DrawSprocket

Choosing a Context

Drawing and Double Buffering

Handling a Mouse

Manipulating a Context

Manipulating Color Lookup Tables

Processing System Events

Utility Functions

Miscellaneous

Callbacks

DSpBlitDoneProc

Defines a pointer to a blitting completion function. Your callback function handles any tasks required after DrawSprocket finishes blitting between buffers.

typedef void (*DSpBlitDoneProc) (
   DSpBlitInfo * info
);

If you name your function My, you would declare it like this:

void DSpBlitDoneProc (
   DSpBlitInfo * info
);

Parameters

info: A pointer to a data structure containing information about the completed blitting operation. See DSpBlitInfo for more information.

Return Value

Discussion

If you are performing multiple asynchronous blitting operations, your application-defined completion function can check the blitter information structure passed to it to determine which operation was completed.

Version Notes

Introduced with DrawSprocket 1.1

Availability

Available in Mac OS X v10.0 and later.

Declared In

DrawSprocket.h

DSpCallbackProcPtr

Defines a pointer to a callback function. Your callback function performs any necessary tasks in preparation for swapping display buffers or piggybacking VBL tasks to a context.

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

If you name your function MyDSpCallbackProc, you would declare it like this:

Boolean DSpCallbackProcPtr (
   DSpContextReference inContext,
   void * inRefCon
);

Parameters

inContext: A reference to a context.
inRefCon: A reference constant to be handed back to the game by the DrawSprocket function that calls MyCallbackFunction.

Return Value

The function should return false if your tasks or checks are complete. If it returns true, the function is still performing necessary tasks.

Discussion

Calls to MyCallbackFunction result from calls to DSpContext_SwapBuffers.

Version Notes

Introduced with DrawSprocket 1.0.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DrawSprocket.h

Data Types

DSpAltBufferAttributes

Describes the characteristics of an alternate buffer.

struct DSpAltBufferAttributes {
   UInt32 width;
   UInt32 height;
   DSpAltBufferOption options;
   UInt32 reserved[4];
};
typedef struct DSpAltBufferAttributes DSpAltBufferAttributes;

Fields

width: The width of the alternate buffer, in pixels.
height: The height of the alternate buffer, in pixels.
options: Any desired options for the alternate buffer. See “Alternate Buffer Options Constant.”
reserved: Reserved. Set to 0.

Discussion

When handling allocating an alternate drawing buffer, you can specify additional attributes by passing a structure of type DSpAltBufferAttributes.

Version Notes

Introduced with DrawSprocket 1.1.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DrawSprocket.h

DSpAltBufferReference

Represents an alternate drawing buffer,

typedef struct OpaqueDSpAltBufferReference * DSpAltBufferReference;

Version Notes

Introduced with DrawSprocket 1.0.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DrawSprocket.h

DSpBlitInfo

Specifies the type of blitting operation when blitting between buffers.

struct DSpBlitInfo {
   Boolean completionFlag;
   char filler[3];
   DSpBlitDoneProc completionProc;
   DSpContextReference srcContext;
   CGrafPtr srcBuffer;
   Rect srcRect;
   UInt32 srcKey;
   DSpContextReference dstContext;
   CGrafPtr dstBuffer;
   Rect dstRect;
   UInt32 dstKey;
   DSpBlitMode mode;
   UInt32 reserved[4];
};
typedef struct DSpBlitInfo DSpBlitInfo;
typedef DSpBlitInfo * DSpBlitInfoPtr;

Fields

completionFlag: Set to true on output when the blitting operation has completed.
filler: Reserved. These bytes are included to preserve proper alignment.
completionProc: A pointer to the function that DrawSprocket should call when the blitting operation has completed. See DSpBlitDoneProc for more information about implementing this function. Pass NULL if you don’t want to specify a completion function.
srcContext: A reference to the source context. Pass NULL if the source buffer does not belong to a context.
srcBuffer: A pointer of type CGrafPtr that specifes the buffer containing the image data you want to blit to the destination buffer.
srcRect: The rectangle specifying the location of the image data in the source buffer. If the source and destination rectangles are different sizes, DrawSprocket scales the image to fit.
srcKey: An integer specifying the source color key. See “Blit Mode Constants” for more information on using this key.
dstContext: A reference to the destination context. Pass NULL if the destination buffer does not belong to a context.
dstBuffer: A pointer of type CGrafPtr that specifes the buffer you want to blit the image to.
dstRect: The rectangle specifying where to write the image data in the destination buffer. If the source and destination rectangles are different sizes, DrawSprocket scales the image to fit.
dstKey: An integer specifying the destination color key. See “Blit Mode Constants” for more information on using this key.
mode: The blit mode to use. See “Blit Mode Constants” for a list of possible values.
reserved: Reserved.

Version Notes

Introduced with DrawSprocket 1.1.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DrawSprocket.h

DSpContextAttributes

Indicates the characteristics of a drawing context.

struct DSpContextAttributes {
   Fixed frequency;
   UInt32 displayWidth;
   UInt32 displayHeight;
   UInt32 reserved1;
   UInt32 reserved2;
   UInt32 colorNeeds;
   CTabHandle colorTable;
   OptionBits contextOptions;
   OptionBits backBufferDepthMask;
   OptionBits displayDepthMask;
   UInt32 backBufferBestDepth;
   UInt32 displayBestDepth;
   UInt32 pageCount;
   char filler[3];
   Boolean gameMustConfirmSwitch;
   UInt32 reserved3[4];
};
typedef struct DSpContextAttributes DSpContextAttributes;
typedef DSpContextAttributes * DSpContextAttributesPtr;

Fields

frequency

Input: Ignored.

Output: The frame-refresh frequency (in Hz) specified by the current resolution mode. (This value is 0 if the actual frequency is not available.

displayWidth

Input: The requested display width (in pixels).

Output: The display width for the specified context.

displayHeight

Input: The requested display height (in pixels).

Output: The display height for the specified context.

reserved1

Reserved. Always set this field to 0.

reserved2

Reserved.

colorNeeds

Input: A value that specifies whether the display needs to be in color. Valid constants for this field are described in “Color Need Constants.”

Output: The color support provided by the current resolution mode.

colorTable

Input: A handle to the color table to use with the context to which this attributes structure applies. (This field applies only to indexed devices; direct devices do not use a color table.)

Output: Ignored.

contextOptions

Input: A set of bit flags that define requested special display features for which either hardware or software implementation is acceptable. Valid constants for this field are described in “Special Display Feature Constants.”

Output: The special display features supported in software by the current resolution mode.

backBufferDepthMask

Input: A bit array that defines the acceptable pixel depths for the back buffer. Valid constants for this field are described in “Depth Mask Constants.” This value should match the depth of the front buffer. You must specify a back buffer depth mask and pixel depth when reserving a back buffer context.

Output: The bit depth DrawSprocket recommends for the context.

displayDepthMask

Input: A bit array that defines the acceptable pixel depths for the front buffer. Valid constants for this field are described in “Depth Mask Constants.”

Output: A bit array that specifies the pixel depth of the specified context.

backBufferBestDepth

Input: The preferred pixel depth, or video mode, for the back buffer. his value should match the depth of the front buffer. You must specify a back buffer depth mask and pixel depth when reserving a back buffer context.

Output: The bit depth DrawSprocket recommends for the context.

displayBestDepth

Input: The preferred pixel depth for the display.

Output: The pixel depth of the specified context.

pageCount

Input: Indicates the desired number of video pages. For example, if you desire double-buffering, you should pass 2. For triple buffering, pass 3. If you pass 1, then DrawSprocket only provides a front buffer and does not allocate any memory for back buffers. You cannot pass 0 for the page count.

Output: Gives the number of hardware video pages available. A value of 1 indicates that hardware page flipping is not supported.

filler

Reserved. These bytes are included to preserve alignment.

gameMustConfirmSwitch

Input: Ignored.

Output: A value of true indicates that the context may have problems being displayed on the user’s system, and the game should confirm that the context is visible after being set to the active state by asking the user if the display can be seen (via a dialog box or some other mechanism). Additionally, a warning code will be returned from DSpContext_SetState indicating that the game should confirm that the context is visible.

reserved3

Reserved. Always set this field to 0.

Discussion

You use the context attributes structure to request specific characteristics when creating a context or to retrieve the actual characteristics of a given context. The field descriptions cover their use as both input or output values, but the structure never contains both input and output information at the same time.

You can use the debug version of the DrawSprocket library to catch most context errors.

Version Notes

Introduced with DrawSprocket 1.0.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DrawSprocket.h

DSpContextReference

Represents a drawing context.

typedef struct OpaqueDSpContextReference * DSpContextReference;

Version Notes

Introduced with DrawSprocket 1.0.

Availability

Available in Mac OS X v10.0 and later.

Declared In

DrawSprocket.h

DSpContextReferenceConst

typedef const struct OpaqueDSpContextReference * DSpContextReferenceConst;

Availability

Available in Mac OS X v10.0 and later.

Declared In

DrawSprocket.h

Constants

Alternate Buffer Options Constant

Describes options when allocating an alternate buffer.

enum DSpAltBufferOption {
   kDSpAltBufferOption_RowBytesEqualsWidth = 1 << 0
};
typedef enum DSpAltBufferOption DSpAltBufferOption;

Constants

kDSpAltBufferOption_RowBytesEqualsWidth

Forces the row and width of the alternate buffer to have the same number of pixels. The number of row bytes can vary depending on the screen depth. For example, if you specify 16-bit color, then there will be twice as many row bytes as there are pixels in the width, because it takes 2 bytes to represent one pixel.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

Version Notes

Introduced with DrawSprocket 1.1.

Blit Mode Constants

Indicate the type of blitter operation to perform.

enum DSpBlitMode {
   kDSpBlitMode_Plain = 0,
   kDSpBlitMode_SrcKey = 1 << 0,
   kDSpBlitMode_DstKey = 1 << 1,
   kDSpBlitMode_Interpolation = 1 << 2
};
typedef enum DSpBlitMode DSpBlitMode;

Constants

kDSpBlitMode_Plain

Copy all pixels from the source to the destination.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpBlitMode_SrcKey

Copies all image data where the source image is not the same color as the source key. For example, say the buffer holds a sprite image on a black background. If you specify the source color key to be black, then DrawSprocket writes only nonblack images (that is, the sprite) to the destination.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpBlitMode_DstKey

Overwrites data in the destination image where the color is the same as the destination key. For example, say the destination buffer holds an image of a a city skyline against a blue sky, and you want to draw a blimp moving behind the buildings. If you set the destination color key to blue, then DrawSprocket will draw the blimp only in areas that are blue. That is, the blimp will not overwrite the nonblue buildings, so it will appear to be behind them.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpBlitMode_Interpolation

Interpolate between color values when scaling pixels.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

Discussion

You use these constants in the structure DSpBlitInfo . Note that you can use these constants in combination with each other.

Version Notes

Introduced with DrawSprocket 1.1.

Buffer Kind Constant

Defines the type of buffer.

enum DSpBufferKind {
   kDSpBufferKind_Normal = 0
};
typedef enum DSpBufferKind DSpBufferKind;

Constants

kDSpBufferKind_Normal

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

Discussion

Currently, DrawSprocket supports only one kind of buffer. You pass this constant to the DSpContext_GetBackBuffer, DSpAltBuffer_InvalRect, and DSpAltBuffer_GetCGrafPtr functions.

Version Notes

Introduced with DrawSprocket 1.0.

Color Need Constants

Specify your program’s preferences or requirements for color display in the colorNeeds field of the context attributes structure.

enum DSpColorNeeds {
   kDSpColorNeeds_DontCare = 0,
   kDSpColorNeeds_Request = 1,
   kDSpColorNeeds_Require = 2
};
typedef enum DSpColorNeeds DSpColorNeeds;

Constants

kDSpColorNeeds_DontCare

Display can be either color or grayscale.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpColorNeeds_Request

Color display is preferred, but not required.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpColorNeeds_Require

Color display is required.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

Version Notes

Introduced with DrawSprocket 1.0.

Depth Mask Constants

Define the allowable bit depth.

enum DSpDepthMask {
   kDSpDepthMask_1 = 1 << 0,
   kDSpDepthMask_2 = 1 << 1,
   kDSpDepthMask_4 = 1 << 2,
   kDSpDepthMask_8 = 1 << 3,
   kDSpDepthMask_16 = 1 << 4,
   kDSpDepthMask_32 = 1 << 5,
   kDSpDepthMask_All = -1L
};
typedef enum DSpDepthMask DSpDepthMask;

Constants

kDSpDepthMask_1

1-bit pixel depth is acceptable.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpDepthMask_2

2-bit pixel depth is acceptable.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpDepthMask_4

4-bit pixel depth is acceptable.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpDepthMask_8

8-bit pixel depth is acceptable.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpDepthMask_16

16-bit pixel depth is acceptable.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpDepthMask_32

32-bit pixel depth is acceptable.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpDepthMask_All

Any pixel depth is acceptable.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

Discussion

You provide a depth mask in the backBufferDepthMask and displayDepthMask fields of the context attributes structure to specify the pixel depths that are acceptable to your program.

Version Notes

Introduced with DrawSprocket 1.0.

Play State Constants

Indicate the current state of a drawing context.

enum DSpContextState {
   kDSpContextState_Active = 0,
   kDSpContextState_Paused = 1,
   kDSpContextState_Inactive = 2
};
typedef enum DSpContextState DSpContextState;

Constants

kDSpContextState_Active

The display is completely controlled by your program. The display is configured as specified in its context attributes structure. All system adornments, such as the menu bar, floating windows, and the desktop, are hidden (removed or covered by the blanking window). In this state you cannot make system calls to managers, such as the Window Manager and Dialog Manger, that expect the display to be in a normal state.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpContextState_Paused

The menu bar and other system adornments are restored, although the resolution mode is still that specified in the context attributes structure for the display. The desktop is still not visible; the blanking window covers it. In this state you can make normal system calls. Page flipping and double buffering are inactive in this state; the display page is set to page 0 if page flipping has been enabled.

In this state it is safe for your program to call Mac OS system software functions. The paused state gives the user access to the process menu; if your game is suspended because the user switches to another application, you must call the function DSpProcessEvent.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpContextState_Inactive

The display is in exactly the state the user has specified from the Monitors control panel. The blanking window is hidden and the resolution mode specified in the context attributes structure for this display is not in effect.

The user’s configuration is restored only if there are no other currently active or paused contexts. As long as there is at least one active or paused context, all displays are covered by the blanking window, and the resolution mode for each is that of the context, which may not be what the user has selected in the Monitors control panel.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

Discussion

You set the play state of a context by calling the function DSpContext_SetState and passing it one of these values.

Version Notes

Introduced with DrawSprocket 1.0.

Special Display Feature Constants

Indicate special display features in the contextOptions field of the context attributes structure.

enum DSpContextOption {
   kDSpContextOption_PageFlip = 1 << 1,
   kDSpContextOption_DontSyncVBL = 1 << 2,
   kDSpContextOption_Stereoscopic = 1 << 3
};
typedef enum DSpContextOption DSpContextOption;

Constants

kDSpContextOption_PageFlip

Use page flipping (a hardware feature). Note that you should never allow page flipping unless you have tested your code extensively on a computer with page-flipping capability.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpContextOption_DontSyncVBL

Do not synchronize context updates with the vertical retrace of the display.

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

kDSpContextOption_Stereoscopic

Available in Mac OS X v10.0 and later.

Declared in DrawSprocket.h.

Version Notes

Introduced with DrawSprocket 1.0.

Result Codes

The most common result codes returned by Game Sprockets are listed below.

Result Code	Value	Description
`noErr`	0	No error Available in Mac OS X v10.0 and later.
`kNSpInitializationFailedErr`	-30360	NetSprocket could not be initialized Available in Mac OS X v10.0 and later.
`kNSpAlreadyInitializedErr`	-30361	NetSprocket has already been initialized Available in Mac OS X v10.0 and later.
`kNSpTopologyNotSupportedErr`	-30362	The requested topology is unimplemented, or invalid value Available in Mac OS X v10.0 and later.
`kNSpProtocolNotAvailableErr`	-30366	A protocol reference indicated a protocol that is unavailable Available in Mac OS X v10.0 and later.
`kNSpInvalidGameRefErr`	-30367	An invalid game reference was passed Available in Mac OS X v10.0 and later.
`kNSpInvalidParameterErr`	-30369	A generic parameter error occurred Available in Mac OS X v10.0 and later.
`kNSpOTNotPresentErr`	-30370	Open Transport is not installed or not installed correctly Available in Mac OS X v10.0 and later.
`kNSpOTVersionTooOldErr`	-30371	The version of Open Transport available is too old to use with NetSprocket Available in Mac OS X v10.0 and later.
`kNSpMemAllocationErr`	-30373	NetSprocket has run out of memory Available in Mac OS X v10.0 and later.
`kNSpAlreadyAdvertisingErr`	-30374	The game is already being advertised on the specified protocol Available in Mac OS X v10.0 and later.
`kNSpNotAdvertisingErr`	-30376	The game is not being advertised at this time Available in Mac OS X v10.0 and later.
`kNSpInvalidAddressErr`	-30377	An invalid address was passed Available in Mac OS X v10.0 and later.
`kNSpFreeQExhaustedErr`	-30378	NetSprocket has exhausted its allocated queue elements and new messages will be dropped Available in Mac OS X v10.0 and later.
`kNSpRemovePlayerFailedErr`	-30379	Your attempt to remove a player failed Available in Mac OS X v10.0 and later.
`kNSpAddressInUseErr`	-30380	You are attempting to use an address that is already in use Available in Mac OS X v10.0 and later.
`kNSpCreateGroupFailedErr`	-30388	The attempt to create a group failed Available in Mac OS X v10.0 and later.
`kNSpTimeoutErr`	-30393	A time out error has occurred Available in Mac OS X v10.0 and later.
`kNSpGameTerminatedErr`	-30394	An attempt to terminate the game has failed Available in Mac OS X v10.0 and later.
`kNSpConnectFailedErr`	-30395	A connection attempt has failed Available in Mac OS X v10.0 and later.
`kNSpSendFailedErr`	-30396	An attempt to send a message has failed Available in Mac OS X v10.0 and later.
`kNSpMessageTooBigErr`	-30397	The message you wanted to send was too long Available in Mac OS X v10.0 and later.
`kNSpCantBlockErr`	-30398	The player you sent a message to is not playing the game Available in Mac OS X v10.0 and later.
`kNSpJoinFailedErr`	-30399	The attempt to join the game failed Available in Mac OS X v10.0 and later.
`kISpInternalErr`	-30420	Internal error. Available in Mac OS X v10.0 and later.
`kISpSystemListErr`	-30421	Operation is not allowed a system-maintained element list. Available in Mac OS X v10.0 and later.
`kISpBufferToSmallErr`	-30422	The buffer is too small. Available in Mac OS X v10.0 and later.
`kISpElementInListErr`	-30423	The element is already in the element list. Available in Mac OS X v10.0 and later.
`kISpElementNotInListErr`	-30424	The element is not in the element list. Available in Mac OS X v10.0 and later.
`kISpSystemInactiveErr`	-30425	InputSprocket is currently inactive. Available in Mac OS X v10.0 and later.
`kISpDeviceInactiveErr`	-30426	The device is currently inactive. Available in Mac OS X v10.0 and later.
`kISpSystemActiveErr`	-30427	Input Sprocket is currently active. Available in Mac OS X v10.0 and later.
`kISpDeviceActiveErr`	-30428	The device is currently active. Available in Mac OS X v10.0 and later.
`kISpListBusyErr`	-30429	The element list is marked as busy. Available in Mac OS X v10.0 and later.
`kDSpNotInitializedErr`	-30440	DSpStartup has not yet been called. Available in Mac OS X v10.0 and later.
`kDSpSystemSWTooOldErr`	-30441	System software too old. Available in Mac OS X v10.0 and later.
`kDSpInvalidContextErr`	-30442	Invalid context reference. Available in Mac OS X v10.0 and later.
`kDSpInvalidAttributesErr`	-30443	Some field in an attributes structure has an invalid value. Available in Mac OS X v10.0 and later.
`kDSpContextAlreadyReservedErr`	-30444	The context is already reserved. Available in Mac OS X v10.0 and later.
`kDSpContextNotReservedErr`	-30445	The context is not reserved. Available in Mac OS X v10.0 and later.
`kDSpContextNotFoundErr`	-30446	DrawSprocket couldn’t find the context. Available in Mac OS X v10.0 and later.
`kDSpFrameRateNotReadyErr`	-30447	Not enough time has passed for DrawSprocket to calculate a frame rate. Available in Mac OS X v10.0 and later.
`kDSpConfirmSwitchWarning`	-30448	The gameMustConfirmSwitch flag is set. Available in Mac OS X v10.0 and later.
`kDSpInternalErr`	-30449	Corrupted DrawSprocket or other error. Available in Mac OS X v10.0 and later.
`kDSpStereoContextErr`	-30450	DrawSprocket attempted to process a stereo context. (DrawSprocket no longer supports GoggleSprocket.) Available in Mac OS X v10.0 and later.

Next Page >

Hide TOC

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.