Inside Macintosh: Apple Game Sprockets Guide /

Chapter 2 - DrawSprocket

Summary of DrawSprocket

Constants

Depth Masks

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

typedef enum DSpDepthMask DSpDepthMask;

Color Needs

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

typedef enum DSpColorNeeds DSpColorNeeds;

Special Display Features

enum DSpContextOption {
   kDSpContextOption_QD3DAccel= 1U<<0,
   kDSpContextOption_PageFlip= 1U<<1,
   kDSpContextOption_TripleBuffer= 1U<<2
};

typedef enum DSpContextOption DSpContextOption;

Buffer Kind

enum DSpBufferKind {
   kDSpBufferKind_Normal   = 0U
};

typedef enum DSpBufferKind DSpBufferKind;

Pixel Scaling

enum DSpBufferScale {
   kDSpBufferScale_1       = 0x00000001U,
   kDSpBufferScale_2       = 0x00000002U,
   kDSpBufferScale_2Interpolate= 0x80000002U,
   kDSpBufferScale_3       = 0x00000003U,
   kDSpBufferScale_3Interpolate= 0x80000003U,
   kDSpBufferScale_4       = 0x00000004U,
   kDSpBufferScale_4Interpolate= 0x80000004U
};

typedef enum DSpBufferScale DSpBufferScale;

Play State

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

typedef enum DSpContextState DSpContextState;

Data Types

typedef struct DSpContextPrivate 	*DSpContextReference;

typedef struct DSpAltBufferPrivate 	*DSpAltBufferReference;

typedef Boolean (*DSpEventProcPtr)	(EventRecord *inEvent);

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

Context Attributes Structure

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;
   Boolean        gameMustConfirmSwitch;
   UInt32         reserved3[4];
}

typedef struct DSpContextAttributes DSpContextAttributes;
typedef struct DSpContextAttributes *DSpContextAttributesPtr

DrawSprocket Functions

Using DrawSprocket

OSStatus DSpStartup        (void);
OSStatus DSpShutdown       (void);

Choosing a Context and Saving Preferences

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

OSStatus DSpGetFirstContext		(DisplayIDType displayID,
                            		DSpContextReference *outContext);

OSStatus DSpGetNextContext 		(DSpContextReference inCurrentContext,
                            		DSpContextReference *outContext);

OSStatus DSpContext_GetAttributes	(DSpContextReference inContext,
                            		DSpContextAttributesPtr outAttributes);

OSStatus DSpCanUserSelectContext	(DSpContextAttributesPtr inDesiredAttributes
                            		Boolean *outUserCanSelectContext );

OSStatus DSpUserSelectContext		(DSpContextAttributesPtr inDesiredAttributes,
                            		DisplayIDType inDialogDisplayLocation,
                            		DSpEventProcPtr inEventProc,
                            		DSpContextReference *outContext );

OSStatus DSpContext_Restore		(void *inFlatContext,
                            		DSpContextReference *outRestoredContext);

OSStatus DSpContext_GetFlattenedSize	(DSpContextReference inContext,
                                     	UInt32 *outFlatContextSize);

OSStatus DSpContext_Flatten         	(DSpContextReference inContext,
                                     	void *outFlatContext);

OSStatus DSpContext_GetDisplayID    	(DSpContextReference inContext,
                                     	DisplayIDType *outDisplayID);

Manipulating a Context

OSStatus DSpContext_Reserve		(DSpContextReference inContext,
                         		const DSpContextAttributesPtr inDesiredAttributes);

OSStatus DSpContext_Release         (DSpContextReference inContext);

OSStatus DSpContext_SetState        (DSpContextReference inContext, 
                                     DSpContextState inState);

OSStatus DSpContext_GetState        (DSpContextReference inContext, 
                                     DSpContextState *outState);

OSStatus DSpSetBlankingColor        (const RGBColor *inRGBColor);

Drawing and Double Buffering

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

OSStatus DSpContext_FadeGammaOut    (DSpContextReference inContext,
                                     RGBColor *inZeroIntensityColor);

OSStatus DSpContext_FadeGammaIn     (DSpContextReference inContext,
                                     RGBColor *inZeroIntensityColor);

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

OSStatus DSpContext_InvalBackBufferRect(DSpContextReference inContext,
                                     const Rect *inRect);

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

OSStatus DSpContext_IsBusy          (DSpContextReference inContext,
                                     Boolean *outBusyFlag);

OSStatus DSpContext_SetDirtyRectGridSize(DSpContextReference inContext,
                                     UInt32 inCellPixelWidth, 
                                     UInt32 inCellPixelHeight);

OSStatus DSpContext_GetDirtyRectGridSize(DSpContextReference inContext,
                                     UInt32 *outCellPixelWidth, 
                                     UInt32 *outCellPixelHeight);

OSStatus DSpContext_GetDirtyRectGridUnits(DSpContextReference inContext,
                                     UInt32 *outCellPixelWidth, 
                                     UInt32 *outCellPixelHeight);

OSStatus DSpContext_SetMaxFrameRate (DSpContextReference inContext,
                                     UInt32 inMaxFPS);

OSStatus DSpContext_GetMaxFrameRate (DSpContextReference inContext,
                                     UInt32 *outMaxFPS);

OSStatus DSpContext_GetMonitorFrequency(DSpContextReference inContext,
                                     Fixed *outFrequency);

OSStatus DSpContext_SetScale        (DSpContextReference inContext,
                                     DSpBufferScale inScale);

OSStatus DSpContext_GetScale        (DSpContextReference inContext, 
                                     DSpBufferScale *outScale);

Using Alternate Buffers

OSStatus DSpAltBuffer_New           (DSpContextReference inContext, 
                                     Boolean inVRAMBuffer,
                                     DSpAltBufferReference *outAltBuffer);

OSStatus DSpAltBuffer_Dispose       (DSpAltBufferReference inAltBuffer);

OSStatus DSpAltBuffer_GetCGrafPtr   (DSpAltBufferReference inAltBuffer,
                                     DSpBufferKind inBufferKind, 
                                     CGrafPtr *outCGrafPtr);

OSStatus DSpContext_SetOverlayAltBuffer(DSpContextReference inContext,
                                     DSpAltBufferReference inNewOverlay);

OSStatus DSpContext_GetOverlayAltBuffer(DSpContextReference inContext,
                                     DSpAltBufferReference *outOverlay);

OSStatus DSpContext_SetUnderlayAltBuffer(DSpContextReference inContext,
                                     DSpAltBufferReference inNewUnderlay);

OSStatus DSpContext_GetUnderlayAltBuffer(DSpContextReference inContext,
                                     DSpAltBufferReference *outUnderlay);

OSStatus DSpAltBuffer_InvalRect     (DSpAltBufferReference inAltBuffer,
                                     const Rect *inInvalidRect);

OSStatus DSpAltBuffer_RebuildTransparencyMask(DSpAltBufferReference inAltBuffer,
                                     UInt32 inTransparencyValue);

Handling a Mouse

OSStatus DSpFindContextFromPoint    (Point inGlobalPoint,
                                     DSpContextReference *outContext);

OSStatus DSpGetMouse                (Point *outGlobalPoint);

OSStatus DSpContext_GlobalToLocal   (DSpContextReference inContext,
                                     Point *ioPoint);

OSStatus DSpContext_LocalToGlobal   (DSpContextReference inContext,
                                     Point *ioPoint);

Manipulating Color Lookup Tables

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

OSStatus DSpContext_GetCLUTEntries  (DSpContextReference inContext,
                                     ColorSpec *outEntries,
                                     UInt16 inStartingEntry,
                                     UInt16 inEntryCount);

Processing System Events

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

Utility Functions

OSStatus DSpSetDebugMode            (Boolean inDebugMode);

OSStatus DSpContext_SetVBLProc      (DSpContextReference inContext,
                                     DSpCallbackProcPtr inProcPtr, 
                                     void *inRefCon);

Application-Defined Functions

Boolean MyCallbackFunction          (DSpContextReference inContext,
                                     void *inRefCon);pascal Boolean

pascal Boolean MyEventHandler       (EventRecord* event);

Result Codes

kDSpNotInitializedErr	-30440L	DSpStartup has not yet been called.
kDSpSystemSWTooOldErr	-30441L	System software too old.
kDSpInvalidContextErr	-30442L	Invalid context reference.
kDSpInvalidAttributesErr	-30443L	Some field in an attributes structure has an invalid value.
kDSpContextAlreadyReservedErr	-30444L	The context is already reserved.
kDSpContextNotReservedErr	-30445L	The context is not reserved.
kDSpContextNotFoundErr	-30446L	DrawSprocket couldn't find the context.
kDSpFrameRateNotReadyErr	-30447L	Not enough time has passed for DrawSprocket to calculate a frame rate.
kDSpConfirmSwitchWarning	-30448L	The gameMustConfirmSwitch flag is set.
kDSpInternalErr	-30449L	Corrupted DrawSprocket or other error.