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

Summary of Graphics Devices

Pascal Summary

Constants

CONST
   {flag bits for gdType field of GDevice record}
   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}
{flag bits for gdFlags field of GDevice record}
   gdDevType      = 0;  {if bit is set to 0, graphics device is black }
                        { and white; if bit is 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 current }
                        { device}

Data Types

TYPE  
GDHandle    = ^GDPtr;
GDPtr       = ^GDevice;
GDevice     = 
RECORD
   gdRefNum:      Integer;       {reference number of screen driver}
   gdID:          Integer;       {reserved; set to 0}
   gdType:        Integer;       {type of device--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 boundary in global }
                                 { coordinates}
   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;
QDErr = Integer;
DeviceLoopDrawingProcPtr = ProcPtr;
DeviceLoopFlags = SET OF   {for flags parameter of DeviceLoop}
   (singleDevices,         {DeviceLoop doesn't group similar graphics }
                           { devices when calling drawing procedure}
   dontMatchSeeds,         {DeviceLoop doesn't consider ctSeed fields }
                           { of ColorTable records for graphics devices }
                           { when comparing them}
   allDevices);            {DeviceLoop ignores value of drawingRgn }
                           { parameter--instead, it calls drawing procedure }
                           { for every screen}

Routines for Graphics Devices

Creating, Setting, and Disposing of GDevice Records

{ DisposeGDevice is also spelled as DisposGDevice }
FUNCTION NewGDevice      (refNum: Integer; mode: LongInt): GDHandle;
PROCEDURE InitGDevice    (gdRefNum: Integer; mode: LongInt; 
                          gdh: GDHandle);
PROCEDURE SetDeviceAttribute
                         (gdh: GDHandle; attribute: Integer; 
                          value: Boolean);
PROCEDURE SetGDevice     (gdh: GDHandle);
PROCEDURE DisposeGDevice (gdh: GDHandle);

Getting the Available Graphics Devices

FUNCTION GetGDevice      : GDHandle;
FUNCTION GetDeviceList   : GDHandle;
FUNCTION GetMainDevice   : GDHandle;
FUNCTION GetMaxDevice    (globalRect: Rect): GDHandle;
FUNCTION GetNextDevice   (curDevice: GDHandle): GDHandle;

Determining the Characteristics of a Video Device

PROCEDURE DeviceLoop     (drawingRgn: RgnHandle; 
                          drawingProc: DeviceLoopDrawingProcPtr; 
                          userData: LongInt; flags: DeviceLoopFlags);
FUNCTION TestDeviceAttribute
                         (gdh: GDHandle; 
                          attribute: Integer): Boolean;
PROCEDURE ScreenRes      (VAR scrnHRes,scrnVRes: Integer);

Changing the Pixel Depth for a Video Device

FUNCTION HasDepth        (aDevice: GDHandle; depth: Integer; 
                          whichFlags: Integer; flags: Integer): Integer;
FUNCTION SetDepth        (aDevice: GDHandle; depth: Integer; 
                          whichFlags: Integer; flags: Integer): OSErr;

Application-Defined Routine

PROCEDURE MyDrawingProc  (depth: Integer; deviceFlags: Integer; 
                          targetDevice: GDHandle; userData: LongInt);

C Summary

Constants

enum {
   /* flag bits for gdType field of GDevice record */
   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 */
/* 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, device is 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 was 
                           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 
                           device */
   noDriver       = 14, /* if bit is set to 1, GDevice record has 
                           no driver */
   screenActive   = 15, /* if bit is set to 1, graphics device is current 
                           device */
};

Data Types

struct GDevice {
   short          gdRefNum;      /* reference number of screen driver */
   short          gdID;          /* reserved; set to 0 */
   short          gdType;        /* type of device--indexed or direct */
   ITabHandle     gdITable;      /* handle to inverse table for Color  
                                    Manager */
   short          gdResPref;     /* preferred resolution */
   SProcHndl      gdSearchProc;  /* handle to list of search functions */
   CProcHndl      gdCompProc;    /* handle to list of complement functions */
   short          gdFlags;       /* graphics device flags */
   PixMapHandle   gdPMap;        /* handle to PixMap record for displayed  
                                    image */
   long           gdRefCon;      /* reference value */
   GDHandle       gdNextGD;      /* handle to next graphics device */
   Rect           gdRect;        /* graphics device's boundary in global 
                                    coordinates */
   long           gdMode;        /* graphics device's current mode */
   short          gdCCBytes;     /* width of expanded cursor data */
   short          gdCCDepth;     /* depth of expanded cursor data */
   Handle         gdCCXData;     /* handle to cursor's expanded data */
   Handle         gdCCXMask;     /* handle to cursor's expanded mask */
   long           gdReserved;    /* reserved for future use; must be 0 */
};
typedef struct GDevice GDevice;
typedef GDevice *GDPtr, **GDHandle;
typedef short QDErr;
typedef pascal void  (*DeviceLoopDrawingProcPtr)
                     (short depth, short deviceFlags, 
                      GDHandle targetDevice, long userData);
/* for flags parameter of DeviceLoop */
enum  {singleDevicesBit = 0,dontMatchSeedsBit = 1,allDevicesBit = 2};
enum  {singleDevices = 1 << singleDevicesBit,   /* DeviceLoop doesn't group
                                                   similar graphics devices
                                                   when calling drawing
                                                   procedure */
      dontMatchSeeds = 1 << dontMatchSeedsBit,  /* DeviceLoop doesn't 
                                                   consider ctSeed fields of 
                                                   ColorTable records for
                                                   graphics devices when 
                                                   comparing them */
      allDevices = 1 << allDevicesBit};         /* DeviceLoop ignores value 
                                                   of drawingRgn parameter--
                                                   instead it calls drawing
                                                   procedure for every 
                                                   screen */
typedef unsigned long DeviceLoopFlags;

Functions for Graphics Devices

Creating, Setting, and Disposing of GDevice Records

/* DisposeGDevice is also spelled as DisposGDevice */
pascal GDHandle NewGDevice     (short refNum, long mode); 
pascal void InitGDevice        (short gdRefNum, long mode, GDHandle gdh); 
pascal void SetDeviceAttribute
                               (GDHandle gdh, short attribute, Boolean value); 
pascal void SetGDevice         (GDHandle gdh); 
pascal void DisposeGDevice     (GDHandle gdh);

Getting the Available Graphics Devices

pascal GDHandle GetGDevice     (void); 
pascal GDHandle GetDeviceList
                               (void); 
pascal GDHandle GetMainDevice
                               (void); 
pascal GDHandle GetMaxDevice
                               (const Rect *globalRect); 
pascal GDHandle GetNextDevice
                               (GDHandle curDevice);

Determining the Characteristics of a Video Device

pascal void DeviceLoop         (RgnHandle drawingRgn, 
                                DeviceLoopDrawingProcPtr drawingProc, 
                                long userData, DeviceLoopFlags flags);
pascal Boolean TestDeviceAttribute
                               (GDHandle gdh, short attribute);
pascal void ScreenRes          (short *scrnHRes, short *scrnVRes);

Changing the Pixel Depth for a Video Device

pascal Integer HasDepth        (GDHandle aDevice, Integer depth, 
                                Integer whichFlags, Integer flags);
pascal OSErr SetDepth          (GDHandle aDevice, Integer depth, 
                                Integer whichFlags, Integer flags);

Application-Defined Function

pascal void MyDrawingProc      (Integer depth, Integer deviceFlags, 
                                GDHandle targetDevice, LongInt userData);

Assembly-Language Summary

Data Structure

GDevice Data Structure
0 gdRefNum word `refNum` of screen driver
2 gdID word reserved; set to 0
4 gdType word general type of graphics device
6 gdITable long handle to inverse table
10 gdResPref word preferred resolution for inverse tables
12 gdSearchProc long search function pointer
16 gdCompProc long complement function pointer
20 gdFlags word graphics device flags word
22 gdPMap long handle to pixel map describing graphics device
26 gdRefCon long reference value
30 gdNextGD long handle to next `GDevice record`
34 gdRect 8 bytes graphics device's bounds in global coordinates
42 gdMode long device's current mode
46 gdCCBytes word width of expanded cursor data
48 gdCCDepth word depth of expanded cursor data
50 gdCCXData long handle to cursor's expanded data
54 gdCCXMask long handle to cursor's expanded mask
58 gdReserved long reserved; must be 0

Global Variables
DeviceList Handle to the first `GDevice` record in the device list.
MainDevice Handle to the `GDevice` record for the main screen.
ScrHRes The horizontal resolution, in pixels per inch, for the current device.
ScrVRes The vertical resolution, in pixels per inch, for the current device.
TheGDevice Handle to the `GDevice` record for the current device.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

0	gdRefNum	word	`refNum` of screen driver
2	gdID	word	reserved; set to 0
4	gdType	word	general type of graphics device
6	gdITable	long	handle to inverse table
10	gdResPref	word	preferred resolution for inverse tables
12	gdSearchProc	long	search function pointer
16	gdCompProc	long	complement function pointer
20	gdFlags	word	graphics device flags word
22	gdPMap	long	handle to pixel map describing graphics device
26	gdRefCon	long	reference value
30	gdNextGD	long	handle to next `GDevice record`
34	gdRect	8 bytes	graphics device's bounds in global coordinates
42	gdMode	long	device's current mode
46	gdCCBytes	word	width of expanded cursor data
48	gdCCDepth	word	depth of expanded cursor data
50	gdCCXData	long	handle to cursor's expanded data
54	gdCCXMask	long	handle to cursor's expanded mask
58	gdReserved	long	reserved; must be 0

DeviceList	Handle to the first `GDevice` record in the device list.
MainDevice	Handle to the `GDevice` record for the main screen.
ScrHRes	The horizontal resolution, in pixels per inch, for the current device.
ScrVRes	The vertical resolution, in pixels per inch, for the current device.
TheGDevice	Handle to the `GDevice` record for the current device.