Inside Macintosh: Apple Game Sprockets Guide /

Chapter 2 - DrawSprocket / DrawSprocket Reference

Data Structures

Context Attributes Structure

The context attributes structure describes a set of characteristics that apply to a given context.

You use the context attributes structure to request specific characteristics when creating a context, and you also use it to retrieve the actual characteristics of a given context. There are field descriptions for input values and output values, but the structure never contains both input and output information at the same time. The context attributes structure is defined by the DSpContextAttributes data type.

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

Field Description

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. Always set this field to 0

colorNeeds

Input: A value that specifies whether the display needs to be in color. Valid constants for this field are described in "Color Needs" (page 2-23).
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 Features" (page 2-24).
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 Masks" (page 2-22).
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 Masks" (page 2-22).
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.
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: Ignored.
Output: Gives the number of hardware video pages available. A value of 1 indicates that hardware page flipping is not supported.

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[4]

Reserved. Always set this field to 0.