Legacy Document

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

Inside Macintosh: Imaging With QuickDraw /

Chapter 5 - Graphics Devices / Graphics Devices Reference

GDevice
Color QuickDraw stores state information for video devices and offscreen graphics worlds in GDevice records. When the system starts up, it allocates and initializes one handle to a GDevice record for each video device it finds. When you use the NewGWorld function (described in the chapter "Offscreen Graphics Worlds" in this book), Color QuickDraw automatically creates a GDevice record for the new offscreen graphics world. The system links these GDevice records in a list, called the device list. (You can find a handle to the first element in the device list in the global variable DeviceList.) By default, the GDevice record corresponding to the first video device found is marked as the current device; all other graphics devices in the list are initially marked as inactive.

Note
Printing graphics ports, described in the chapter "Printing Manager" in this book, do not have GDevice records.
When the user moves a window or creates a window on another screen, and your application draws into that window, Color QuickDraw automatically makes the video device for that screen the current device. Color QuickDraw stores that information in the global variable TheGDevice.
GDevice records that correspond to video devices have drivers associated with them. These drivers can be used to change the mode of the video device from black and white to color and to change the pixel depth. The set of routines supported by a video driver is defined and described in Designing Cards and Drivers for the Macintosh Family, third edition. Application-created GDevice records usually don't require drivers.
A GDevice record is defined as follows:
TYPE GDevice = 
RECORD
   gdRefNum:      Integer;       {reference number of screen }
                                 { driver}
   gdID:          Integer;       {reserved; set to 0}
   gdType:        Integer;       {device type--indexed or direct}
   gdITable:      ITabHandle;    {handle to inverse table for }
                                 { Color Manager}
   gdResPref:     Integer;       {preferred resolution}
   gdSearchProc:  SProcHndl;     {handle to list of search }
                                 { functions}
   gdCompProc:    CProcHndl;     {handle to list of complement }
                                 { functions}
   gdFlags:       Integer;       {graphics device flags}
   gdPMap:        PixMapHandle;  {handle to PixMap record for }
                                 { displayed image}
   gdRefCon:      LongInt;       {reference value}
   gdNextGD:      GDHandle;      {handle to next graphics device}
   gdRect:        Rect;          {graphics device's global bounds}
   gdMode:        LongInt;       {graphics device's current mode}
   gdCCBytes:     Integer;       {width of expanded cursor data}
   gdCCDepth:     Integer;       {depth of expanded cursor data}
   gdCCXData:     Handle;        {handle to cursor's expanded }
                                 { data}
   gdCCXMask:     Handle;        {handle to cursor's expanded }
                                 { mask}
   gdReserved:    LongInt;       {reserved for future use--must }
                                 { be 0}
END;
Field Description

gdRefNum
The reference number of the driver for the screen associated with the video device. For most video devices, this information is set at system startup time.
gdID
Reserved. If you create your own GDevice record, set this field to 0.
gdType
The general type of graphics device. Values include
               CONST
               clutType = 0;     {CLUT device--that is, one with }
                                 { colors mapped with a color }
                                 { lookup table}
               fixedType = 1;    {fixed colors--that is, the }
                                 { color lookup table can't }
                                 { be changed}
               directType = 2;   {direct RGB colors}
These types are described in more detail in the chapter "Color Manager" in Advanced Color Imaging on the Mac OS.
gdITable
A handle to the inverse table for color mapping; the inverse table is described in the chapter "Color Manager" in Advanced Color Imaging on the Mac OS.
gdResPref
The preferred resolution for inverse tables.
gdSearchProc
A handle to the list of search functions, as described in the chapter "Color Manager" in Advanced Color Imaging on the Mac OS; its value is NIL for the default function.
gdCompProc
A handle to a list of complement functions, as described in the chapter "Color Manager" in Advanced Color Imaging on the Mac OS; its value is NIL for the default function.
gdFlags
The GDevice record's attributes. To set the attribute bits in the gdFlags field, use the SetDeviceAttribute procedure (described on page 5-21)--do not set these flags directly in the GDevice record. The constants representing each bit are listed here.
CONST {flag bits for gdFlags field of GDevice record}
gdDevType      = 0;  {if bit is set to 0, graphics device is }
                     { black and white; if set to 1, }
                     { graphics device supports color}
burstDevice    = 7;  {if bit is set to 1, graphics device }
                     { supports block transfer}
ext32Device    = 8;  {if bit is set to 1, graphics device }
                     { must be used in 32-bit mode}
ramInit        = 10; {if bit is set to 1, graphics device has }
                     { been initialized from RAM}
mainScreen     = 11; {if bit is set to 1, graphics device is }
                     { the main screen}
allInit        = 12; {if bit is set to 1, all graphics devices }
                     { were initialized from 'scrn' resource}
screenDevice   = 13; {if bit is set to 1, graphics device is }
                     { a screen}
noDriver       = 14; {if bit is set to 1, GDevice }
                     { record has no driver}
screenActive   = 15; {if bit is set to 1, graphics device is }
                     { active}
gdPMap
A handle to a PixMap record giving the dimension of the image buffer, along with the characteristics of the graphics device (resolution, storage format, color depth, and color table). PixMap records are described in the chapter "Color QuickDraw" in this book. For GDevice records, the high bit of the global variable
TheGDevice^^.gdPMap^^.pmTable^^.ctFlagsis always set.
gdRefCon
A value used by system software to pass device-related parameters. Since a graphics device is shared, you shouldn't store data here.
gdNextGD
A handle to the next graphics device in the device list. If this is the last graphics device in the device list, the field contains 0.
gdRect
The boundary rectangle of the graphics device represented by the GDevice record. The main screen has the upper-left corner of the rectangle set to (0,0). All other graphics devices are relative to this point.
gdMode
The current setting for the graphics device mode. This value is passed to the video driver to set its pixel depth and to specify color or black and white; applications don't need this information. See Designing Cards and Drivers for the Macintosh Family, third edition, for more information about the modes specified in this field.
gdCCBytes
The rowBytes value of the expanded cursor. Your application should not change this field. Cursors are described in the chapter "Cursor Utilities."
gdCCDepth
The depth of the expanded cursor. Your application should not change this field.
gdCCXData
A handle to the cursor's expanded data. Your application should not change this field.
gdCCXMask
A handle to the cursor's expanded mask. Your application should not change this field.
gdReserved
Reserved for future expansion; it must be set to 0 for future compatibility.
Your application should never need to directly change the fields of a GDevice record. If you find it absolutely necessary for your application to so, immediately use the GDeviceChanged procedure to notify Color QuickDraw that your application has changed the GDevice record. The GDeviceChanged procedure is described in the chapter "Color QuickDraw" in this book.