This chapter serves as a prelude to Chapter 12 - Drawing With QuickDraw, and introduces certain matters which need to be discussed before the matter of actually drawing with QuickDraw is addressed. These matters include the history of QuickDraw, RGB colours, colour and the video device, the colour graphics port, translation of RGB values, and graphics devices.

History of QuickDraw

• Basic QuickDraw, which was designed for the early black-and-white Macintoshes. System 7 added new capabilities to basic QuickDraw, including support for offscreen graphics worlds.

• The original version of Color QuickDraw, which was introduced with the first Macintosh II systems, and which could support up to 256 colours.

• The current version of Color QuickDraw, which was originally introduced as 32-bit Color QuickDraw. This version has been expanded to support millions of colours.

You specify a colour to QuickDraw by creating an RGBColor structure in which you use three 16-bit unsigned integers to assign intensity values for the three additive primary colours. The RGBColor data type is defined as follows:

     struct RGBColor
     {
       unsigned short  red;    // Magnitude of red component.
       unsigned short  green;  // Magnitude of green component.
       unsigned short  blue;   // Magnitude of blue component.
     };
     typedef struct RGBColor RGBColor;

On a video device, the primary colours are referred to as additive because, when each of the three colour components is at maximum intensity, the result is the colour white. On a printer, the primary colours are referred to as subtractive because the colour black results when the three colour components are at maximum intensity.

A pixel (picture element) is the smallest dot that QuickDraw can draw. Each colour pixel represents up to 48 bits in memory.

Colour and the Video Device

The video device that controls a screen may have either:

• Indexed colours, which support pixels of 1-bit, 2-bit, 4-bit, or 8-bit pixel depths. The indexed colour system was introduced with the Macintosh II, that is, at a time when memory was scarce and moving megabyte images around was impractical.

  Pixel depth means the number of bits assigned to each pixel, and thus determines the maximum number of colours that can be displayed at the one time. A 4-bit pixel depth, for example, means that an individual pixel can be displayed in any one of 16 separate colours. An 8-bit pixel depth means that an individual pixel can be displayed in any one of 256 separate colours.

• Direct colours, which support pixels of 16-bit and 32-bit depths. Most video devices in the current day are direct colour devices. (However, as will be seen, there are circumstances in which a direct colour device will act like an indexed colour device.)

Video devices implementing indexed colour contain a data structure called a colour lookup table (or, more commonly, a CLUT). The CLUT, in turn, contains entries for all possible colour values.

256 colours is, for many images, sufficient for near-photographic quality. The problem is that the colours needed for one photographic image may not be appropriate for another. Because most indexed video devices use a variable CLUT, however, you can display one image using one set of 256 colours and then use system software to reload the CLUT with a second set of 256 colours that are appropriate for the next image. If your application needs this sort of control on indexed video devices, you can use the Palette Manager to arrange palettes (that is, sets of colours) for particular images and for video devices with differing colour capabilities.

Some Macintosh computers, such as grayscale PowerBook computers, have a fixed CLUT, which your application cannot change.

If your application uses a 48-bit RGBColor structure to specify a colour, the Color Manager examines the colours available in the CLUT on the video device. Comparing the CLUT entries to the RGBColor structure you specify, the Color Manager determines which colour in the CLUT is closest, and gives QuickDraw the index to this colour. QuickDraw then draws with this colour.

Fig 1 illustrates this process. In Fig 1, the user selects a colour for some object in an application (1). Using a 48-bit RGBColor structure to specify the colour, the application calls a QuickDraw routine to draw the object in that colour (2). QuickDraw uses the Color Manager to determine what colour in the video devices's CLUT comes closest to the requested colour (3).

At startup, the video device's declaration ROM supplies information for the creation of a GDevice structure (see below) that describes the characteristics of the device. The resulting structure contains a ColorTable structure that is kept synchronised with the card's CLUT.

The Color Manager examines the GDevice structure to find what colours are currently available (4) and to decide which colour comes closest to the one requested by the application. The Color Manager gets the index value for the best match and returns the value to QuickDraw (5), which puts the index value into those places in video RAM which store the object.

The video device continually displays video RAM by taking the index values, converting them to colours according to CLUT entries at those indexes (7), and sending them to the digital-to-analog converters (8) which produce a signal for the screen (9).

Direct Colour Devices

When you specify a colour using a 48-bit RGBColor structure on a direct colour system, QuickDraw truncates the least significant bits of its red, green and blue components to either 16 bits (five bits each for red, green and blue, with one bit unused) or 32 bits (eight bits for red, green and blue, with eight bits unused). (See Translation of RGB Colours to Pixel Values, below.) Using 16 bits, direct video devices can display 32,768 different colours. Using 32 bits, the device can display 16,777,215 different colours

Fig 2 illustrates the direct colour system. A user chooses a colour for some object (1) and, using a 48-bit RGBColor structure to specify the colour, the application uses a QuickDraw routine to draw the object in that colour (2).

QuickDraw knows from the GDevice structure (3) that the screen is controlled by a direct device in which pixels are, say, 32 bits deep, which means that eight bits are used for each of the red, green and blue components of the requested colour. Accordingly, QuickDraw passes the high eight bits from each 16-bit component of the 48-bit RGBColor structure to the video device (4), which stores the resulting 24-bit value in video RAM for the object. The video device continually displays video RAM by sending the 8-bit red, green and blue values for the colour to digital-to-analog converters (5) which produce a signal for the screen (6).

Direct colour not only removes much of the complexity of the CLUT mechanism for video device developers, but it also allows the display of thousands or millions of colours simultaneously, resulting in near-photographic resolution.

Direct Devices Operating Like Indexed Devices

A colour graphics port defines a complete drawing environment that determines where and how colour graphics operations take place. Amongst other things, a colour graphics port:

• Contains a handle to a pixel map which, in turn, contains a pointer to the area of memory in which your drawing operations take place.

• Contains a metaphorical graphics pen with which to perform drawing operations. (You can set this pen to different sizes, patterns and colours.)

• Holds information about text, which is styled and sized according to information in the graphics port.

You can open many colour graphics ports at the same time. Each has its own local coordinate system, drawing pattern, background pattern, pen size and location, foreground colour, background colour, pixel map, etc. You can instantly switch from one graphics port to another using the function SetPort.

When you use Window Manager and Dialog Manager functions to create windows, dialog boxes, and alert boxes, those managers automatically create colour graphics ports for you The CGrafPort structure is as follows:

     struct CGrafPort
     {
       short         device;       // Device-specific information.
       PixMapHandle  portPixMap;   // Handle to pixel map.
       short         portVersion;  // Flags and version number.
       Handle        grafVars;     // Handle to additional colour fields.
       short         chExtra;      // Extra width added to non-space characters.
       short         pnLocHFrac;   // Fractional horizontal pen position.
       Rect          portRect;     // Port rectangle.
       RgnHandle     visRgn;       // Visible region.
       RgnHandle     clipRgn;      // Clipping region.
       PixPatHandle  bkPixPat;     // Background pattern
       RGBColor      rgbFgColor;   // Requested foreground colour.
       RGBColor      rgbBkColor;   // Requested background colour
       Point         pnLoc;        // Pen location.
       Point         pnSize;       // Pen size.
       short         pnMode;       // Pattern mode.
       PixPatHandle  pnPixPat;     // Pen pattern.
       PixPatHandle  fillPixPat;   // Fill pattern.
       short         pnVis;        // Pen visibility.
       short         txFont;       // Font number for text.
       Style         txFace;       // Text font style.
       SInt8         filler;
       short         txMode;       // Text source mode.
       short         txSize;       // Font size for text.
       Fixed         spExtra;      // Extra width added to space characters.
       long          fgColor;      // Actual foreground colour.
       long          bkColor;      // Actual background colour.
       short         colrBit;      // Colour bit (reserved).
       short         patStretch;   // (Used internally.)
       Handle        picSave;      // Picture being saved. (Used internally.)
       Handle        rgnSave;      // Region being saved. (Used internally.)
       Handle        polySave;     // Polygon being saved. (Used internally.)
       CQDProcsPtr   grafProcs;    // Pointer to low-level drawing routines.
     };
     typedef struct CGrafPort CGrafPort,*CGrafPtr;
     typedef CGrafPtr CWindowPtr;

portPixMap	A handle to a PixMap structure (see below) which describes the pixels in this colour graphics port.
portVersion	In the highest two bits, flags set to indicate that this is a CGrafPort structure and, in the remainder of the field, the version number of QuickDraw that created this structure.
grafVars	A handle to a GrafVars structure, which contains colour information additional to that contained in the CGrafPort structure itself, and which is used by QuickDraw and the Palette Manager. For example, one field contains the RGB colour for highlighting.
portRect	The port rectangle that defines a subset of the pixel map to be used for drawing. All drawing done by your application occurs inside the port rectangle. (In a window's graphics port, the port rectangle is also called the content region.) The port rectangle uses the local coordinate system defined by the boundary rectangle in the portPixMap field of the PixMap structure (see below). The upper-left corner (which, for a window, is called the window origin) of the port rectangle has a vertical coordinate of 0 and a horizontal coordinate of 0. The port rectangle usually falls within the boundary rectangle, but it is not required to do so.
visRgn	The region of the graphics port that is actually visible on screen, that is, the part of the window not covered by other windows (see Fig 3). By default, the visible region is equivalent to the port rectangle.
clipRgn	The graphics port's clipping region, an arbitrary region that you can use to limit drawing to any region within the port rectangle. The default clipping region is set arbitrarily large; however, you can change the clipping region using the function ClipRect. At Fig 3, for example, Window B's clipping region has been set by the application to prevent the scroll bar areas being over-drawn.
bkPixPat	A handle to a PixPat structure that describes the background pixel pattern. Various QuickDraw functions use this pattern for filling scrolled or erased areas.
rgbFgColor	An RGBColor structure that contains the requested foreground colour. By default, the foreground colour is black.
rgbBkColor	An RGBColor structure that contains the requested background colour. By default, the background colour is white.
pnLoc	The point where QuickDraw will begin drawing the next line, shape, or character. It can be anywhere on the coordinate plane.
pnSize	The vertical height and horizontal width of the graphics pen. The default size is a 1-by-1 pixel square. If either the pen width or height is 0, the pen does not draw.
pnMode	The pen transfer mode, that is, a Boolean or arithmetic operation that determines how QuickDraw transfers the pen pattern to the pixel map during drawing operations. When the graphics pen draws into a pixel map, QuickDraw first determines what pixels in the pixel image are affected and finds their corresponding pixels in the pen pattern. QuickDraw then does a pixel-by-pixel comparison based on the transfer mode. QuickDraw stores the resulting pixel in its proper place in the image.
pnPixPat	A handle to a PixPat structure (see below) that describes the pixel pattern used by the graphics pen for drawing lines and framed shapes, and for painting shapes
fillPixpat	A handle to a PixPat structure (see below) that describes the pixel pattern that is used when you call QuickDraw shape filling functions.
pnVis	The graphics pen's visibility, that is, whether it draws on the screen.
txFont	A font family ID number that identifies the font to be used in the graphics port.
txFace	The style of the text, for example, bold, italic, and/or underlined.
txMode	The transfer mode for text drawing, which functions much like the transfer mode specified in the pnMode field (see above).
txSize	The text size in pixels. The Font Manager uses this information to provide the bitmaps for text drawing. The value in this field can be represented by point size x device resolution / 72 dpi where point is a typographical term meaning approximately 1/72 inch.
fgColor	The pixel value of the foreground colour supplied by the Color Manager. (See Colour and the Video Device, above, and Translation of RGB Colours to Pixel Values, below.) This is the colour actually displayed on the device, that is, it is the the best available approximation to the requested color in the rgbFgColor field.
bkColor	The pixel value of the background colour supplied by the Color Manager. (See Colour and the Video Device, above, and Translation of RGB Colours to Pixel Values, below.) This is the colour actually displayed on the device, that is, it is the the best available approximation to the requested color in the rgbBkColor field.

Pixel Maps

     struct PixMap
     {
       Ptr         baseAddr;    // Pointer to image data.
       short       rowBytes;    // Flags, and bytes in a row.
       Rect        bounds;      // Boundary rectangle.
       short       pmVersion;   // Pixel Map version number.
       short       packType;    // Packing format.
       long        packSize;    // Size of data in packed state.
       Fixed       hRes;        // Horizontal resolution in dots per inch.
       Fixed       vRes;        // Vertical resolution in dots per inch.
       short       pixelType;   // Format of pixel image.
       short       pixelSize;   // Physical bits per pixel.
       short       cmpCount;    // Number of components in each pixel.
       short       cmpSize;     // Number of bits in each component.
       long        planeBytes;  // Offset to next plane.
       CTabHandle  pmTable;     // Handle to a colour table for this image.
       long        pmReserved;  // (Reserved.)
     };
     typedef struct PixMap PixMap,*PixMapPtr,**PixMapHandle;

baseAddr	For an onscreen pixel image, a pointer to the first byte of the image. The pixel image that appears on the screen is normally stored on a graphics card rather than in main memory. Note that there can be several pixel maps pointing to the same pixel image, each imposing its own coordinate system on it. A pixel image is analogous to the bit image used by basic QuickDraw. A bit image is a collection of bits in memory that form a grid. Fig 4 illustrates a bit image, which can be visualised as a matrix of rows and columns of bits with each row containing the same number of bytes. Each bit corresponds to one screen pixel. If a bit's value is 0, its screen pixel is white; if the bit's value is 1, the screen pixel is black. A bit image can be any length that is a multiple of the row's width in bytes. On black-and-white Macintoshes, the screen itself is one large visible bit image. A pixel image is essentially the same as a bit image, except that a number of bits, not just one bit, are assigned to each pixel. The number of bits per pixel in a pixel image is called the pixel depth.
rowBytes	The offset in bytes from one row of the image to the next. The value must be even and less than 0x4000. For best performance it should be a multiple of 4. Bit 15 is used as a flag. If bit 15 = 1, the data structure is a PixMap structure, otherwise it is a BitMap structure. (The rowbytes bytes in a PixMap structure occupy the same bytes (fifth and sixth) as they do is a BitMap.)
bounds	The boundary rectangle, which links the local coordinate system of a graphics port to QuickDraw's global coordinate system and defines the area of the pixel image into which QuickDraw can draw. All drawing in a colour graphics port occurs in the intersection of the boundary rectangle and the port rectangle (and, within that intersection, all drawing is cropped to the colour graphics port's visible region and its clipping region.) As shown at Fig 5, QuickDraw assigns the entire screen as the boundary rectangle. The boundary rectangle shares the same local coordinate system as the port rectangle of the window. Do not use the bounds field to determine the size of the screen; instead, use the gdRect field of the GDevice structure (see below) for the screen
pmVersion	The version number of QuickDraw that created this PixMap structure.
packType	The packing algorithm used to compress image data.
packSize	The size of the packed image in bytes.
hRes	The horizontal resolution of the image in pixels per inch, abbreviated as dpi (dots per inch). By default, the value here is 0x00480000 (for 72 dpi), but QuickDraw supports PixMap structures of other resolutions. For example, PixMap structures for scanners can have dpi resolutions of 150, 200, 300, or greater.
vRes	Describes the vertical resolution. (See hRes).
pixelType	The storage format for a pixel image. Indexed pixels are indicated by a value of 0. Direct pixels are specified by a value of RGBDirect, or 16. In the PixMap structure of the GDevice structure (see below) for a direct device, this field is set to the constant RGBDirect when the screen depth is set.
pixelSize	The pixel depth, that is, the number of bits used to represent a pixel. Indexed pixels can have sizes of 1, 2, 4, or 8 bits. Direct pixel sizes are 16 or 32 bits.
cmpCount	The number of components used to represent a colour for a pixel. With indexed pixels, each pixel is a single value representing an index in a colour table, so this field contains the value 1. With direct pixels, each pixel contains three components (one integer each for the intensities of red, green, and blue), so this field contains the value 3.
cmpSize	Specifies how large each colour component is. For indexed devices, it is the same value as that in the pixelSize field. For direct devices, each of the three colour components can be either 5 bits for a 16-bit pixel (one of these 16 bits is unused), or 8 bits for a 32 bit pixel (8 of these 32 bits are unused). (See Translation of RGB Colours to Pixel Values, below.)
planeBytes	QuickDraw does not support multiple-plane images, so the value of this field is always 0.
pmTable	Contains a handle to the ColorTable structure. ColorTable structures define the colours available for pixel images on indexed devices. (The Color Manager stores a colour table for the currently available colours in the graphic's device's CLUT. You use the Palette Manager to assign different colour tables to your different windows.) You can create colour tables using either ColorTable structures or 'clut' resources. Pixel images on direct devices do not need a colour table because the colours are stored right in the pixel values. In such cases, pmTable points to a dummy colour table.

Pixel Patterns and Bit Patterns

Bit Patterns

Five bit patterns are pre-defined as QuickDraw global variables. The five pre-defined patterns are available not only through the QuickDraw globals but also as system resources stored in the System resource file. Fig 7 shows images drawn using some some of the 38 available system-supplied bit patterns.

You can create your own bit patterns in your program code, but it is usually simpler and more convenient to store them in resources of type 'PAT ' or 'PAT#'. Fig 8 shows a 'PAT ' resource being created using Resorcerer, together with the contents of the pat field of the structure of type Pattern that is created when the resource is loaded.

Creating Colour Graphics Ports

• When drawing on indexed devices, QuickDraw calls the Color Manager to supply the index to the colour that most closely matches the requested colour in the current device's CLUT. This index becomes the pixel value for that colour.

• When drawing on direct devices, QuickDraw truncates the least significant bits from the red, green and blue fields of the RGBColor structure. The result becomes the pixel value that QuickDraw sends to the graphics device.

The application might later use GetCPixel to determine the colour of a particular pixel. As shown at Fig 10, the Color Manager uses the index number stored as the pixel value to find the RGBColor structure stored in the CLUT for that pixel's colour. Also as shown at Fig 10, this is not necessarily the exact colour first specified.

Derivation of Pixel Values on Direct Devices

Fig 12 shows how QuickDraw converts an RBGColor structure into a 32-bit pixel value on a direct device by storing the most significant 8 bits of each 16-bit field of the structure into the lower 3 bytes of the pixel value, leaving 8 unused bits in the high byte of the pixel value. Fig 12 also shows how QuickDraw expands a 32-bit pixel value to an RBGColor structure by dropping the unused high byte of the pixel value and doubling each of its 8-bit components. Note that the resulting 48-bit value differs in the least significant 8 bits of each component from the original RBGColor structure.

Colours on Grayscale Screens

A grayscale device can be a colour graphics device that the user sets to grayscale by using the Monitors and Sound control panel. For such a graphics device, Colour QuickDraw places an evenly spaced set of grays in the graphics device's CLUT.

By using the GetCTable function, your application can obtain the default colour tables for various graphics devices, including grayscale devices.

Graphics Devices and GDevice Structures

• Video devices, such as video cards and built-in video interfaces, that control screens.

• Offscreen graphics worlds, which allow your application to build complex images offscreen before displaying them.

  See Chapter 13 - Offscreen Graphics Worlds, Pictures, Cursors, and Icons.

• Printing graphics ports for printers.

  See Chapter 15 - Printing.

When the system starts up, QuickDraw uses information supplied by the Slot Manager to create and initialise a GDevice structure for each video device found during startup. When you use the NewGWorld function to create an offscreen graphics world, QuickDraw automatically creates a GDevice structure.

All existing GDevice structures are linked together in a list called a device list. The global variable DeviceList holds a handle to the first structure in the list. At any given time, exactly one graphics device is the current device (also called the active device), that is, the one in which drawing is actually taking place. A handle to its GDevice structure is stored in the global variable TheGDevice. By default, the GDevice structure corresponding to the first video device found is marked as the current device.

Your application generally never needs to create GDevice structures; however, in may need to examine GDevice structures to determine the capabilities of the user's screens. The GDevice structure is as follows:

     struct GDevice
     {
       short         gdRefNum;     // Reference Number of Driver.
       short         gdID;         // Client ID for search procedures.
       short         gdType;       // Type of device (indexed or direct).
       ITabHandle    gdITable;     // Handle to inverse lookup 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 pixel map for displayed image.
       long          gdRefCon;     // Reference value.
       Handle        gdNextGD;     // Handle to next GDevice structure.
       Rect          gdRect;       // Device's global boundaries.
       long          gdMode;       // 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.  Must be 0.)
     };
     typedef struct GDevice GDevice;
     typedef GDevice *GDPtr, **GDHandle;

Flag Bits of gdType Field

Flag Bits of gdFlags Field

Setting a Device's Pixel Depth

The Monitors and Sound control panel is the user interface for changing the pixel depth of video devices. Since the user can control the capabilities of the video device, your application should be flexible, that is, although it may have a preferred pixel depth, it should do its best to accommodate less than ideal conditions. Your application can use the SetDepth function to change the pixel depth, but it should not do so without the consent of the user. Before calling SetDepth, you should use the HasDepth function to determine whether the available hardware can support the pixel depth you require.

Other Graphics Managers

Relevant QuickDraw Constants, Data Types, and Functions

clutType    = 0
fixedType   = 1
directType  = 2

gdDevType     = 0
burstDevice   = 7
ext32Device   = 8
ramInit       = 10
mainScreen    = 11
allInit       = 12
screenDevice  = 13
noDriver      = 14
screenActive  = 15

RGBDirect = 16  //16 and 32 bits-per-pixel pixelType value.

struct CGrafPort
{
  short         device;       // Device-specific information.
  PixMapHandle  portPixMap;   // Handle to pixel map.
  short         portVersion;  // Flags and version number.
  Handle        grafVars;     // Handle to additional colour fields.
  short         chExtra;      // Extra width added to non-space characters.
  short         pnLocHFrac;   // Fractional horizontal pen position.
  Rect          portRect;     // Port rectangle.
  RgnHandle     visRgn;       // Visible region.
  RgnHandle     clipRgn;      // Clipping region.
  PixPatHandle  bkPixPat;     // Background pattern
  RGBColor      rgbFgColor;   // Requested foreground colour.
  RGBColor      rgbBkColor;   // Requested background colour
  Point         pnLoc;        // Pen location.
  Point         pnSize;       // Pen size.
  short         pnMode;       // Pattern mode.
  PixPatHandle  pnPixPat;     // Pen pattern.
  PixPatHandle  fillPixPat;   // Fill pattern.
  short         pnVis;        // Pen visibility.
  short         txFont;       // Font number for text.
  Style         txFace;       // Text font style.
  SInt8         filler;
  short         txMode;       // Text source mode.
  short         txSize;       // Font size for text.
  Fixed         spExtra;      // Extra width added to space characters.
  long          fgColor;      // Actual foreground colour.
  long          bkColor;      // Actual background colour.
  short         colrBit;      // Colour bit (reserved).
  short         patStretch;   // (Used internally.)
  Handle        picSave;      // Picture being saved. (Used internally.)
  Handle        rgnSave;      // Region being saved. (Used internally.)
  Handle        polySave;     // Polygon being saved. (Used internally.)
  CQDProcsPtr   grafProcs;    // Pointer to low-level drawing routines.
};
typedef struct CGrafPort CGrafPort,*CGrafPtr;
typedef CGrafPtr CWindowPtr;

struct GrafVars
{
  RGBColor  rgbOpColor;      // Color for addPin, subPin and average.
  RGBColor  rgbHiliteColor;  // Color for highlighting.
  Handle    pmFgColor;       // Palette handle for foreground color.
  short     pmFgIndex;       // Index value for foreground.
  Handle    pmBkColor;       // Palette handle for background color.
  short     pmBkIndex;       // Index value for background.
  short     pmFlags;         // Flags for Palette Manager.
};
typedef struct GrafVars GrafVars,*GVarPtr,**GVarHandle;

struct PixMap
{
  Ptr         baseAddr;    // Pointer to image data.
  short       rowBytes;    // Flags, and bytes in a row.
  Rect        bounds;      // Boundary rectangle.
  short       pmVersion;   // Pixel Map version number.
  short       packType;    // Packing format.
  long        packSize;    // Size of data in packed state.
  Fixed       hRes;        // Horizontal resolution in dots per inch.
  Fixed       vRes;        // Vertical resolution in dots per inch.
  short       pixelType;   // Format of pixel image.
  short       pixelSize;   // Physical bits per pixel.
  short       cmpCount;    // Number of components in each pixel.
  short       cmpSize;     // Number of bits in each component.
  long        planeBytes;  // Offset to next plane.
  CTabHandle  pmTable;     // Handle to a colour table for this image.
  long        pmReserved;  // (Reserved.)
};
typedef struct PixMap PixMap,*PixMapPtr,**PixMapHandle;

struct ColorTable 
{
  long         ctSeed;   // Unique identifier for table.
  short        ctFlags;  // High bit: 0 = PixMap, 1 = device.
  short        ctSize;   // Number of entries in ctTable minus 1.
  CSpecArray   ctTable;  // Array of ColorSpec structures.
};
typedef struct ColorTable ColorTable;
typedef ColorTable *CTabPtr;
typedef CTabPtr *CTabHandle;

struct ColorSpec 
{
  short     value;  // Index or other value.
  RGBColor  rgb;    // True color.
};
typedef struct ColorSpec ColorSpec;
typedef ColorSpec *ColorSpecPtr;
typedef ColorSpec CSpecArray[1];

struct BitMap
{
  Ptr    baseAddr;  // Pointer to bit image.
  short  rowBytes;  // Row width.
  Rect   bounds;    // Boundary rectangle.
};
typedef struct BitMap BitMap;
typedef BitMap *BitMapPtr, **BitMapHandle;

struct PixPat 
{
  short         patType;    // Type of pattern.
  PixMapHandle  patMap;     // The pattern's pixel map.
  Handle        patData;    // Pixel map's data.
  Handle        patXData;   // Expanded Pattern data (internal use).
  short         patXValid;  // Flags whether expanded Pattern valid.
  Handle        patXMap;    // Handle to expanded Pattern data (reserved).
  Pattern        pat1Data;  // Bit map's data.
};
typedef struct PixPat PixPat;
typedef PixPat *PixPatPtr;
typedef PixPatPtr *PixPatHandle;

struct Pattern
{
  UInt8  pat[8];
};
typedef struct Pattern Pattern;
typedef Pattern *PatPtr;
typedef PatPtr *PatHandle;

     typedef unsigned char Pattern[8];

struct GDevice
{
  short         gdRefNum;      // Reference Number of Driver.
  short         gdID;          // Client ID for search procedures.
  short         gdType;        // Type of device (indexed or direct).
  ITabHandle    gdITable;      // Handle to inverse lookup 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 pixel map for displayed image.
  long          gdRefCon;      // Reference value.
  Handle        gdNextGD;      // Handle to next GDevice structure.
  Rect          gdRect;        // Device's global boundaries.
  long          gdMode;        // 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.  Must be 0.)
};
typedef struct GDevice GDevice;
typedef GDevice *GDPtr, **GDHandle;

void  OpenCPort(CGrafPtr port);
void  InitCPort(CGrafPtr port);
void  CloseCPort(CGrafPtr port);

void  GetPort(GrafPtr *port);
void  SetPort(GrafPtr port);

PixMapHandle  NewPixMap(void);
void          CopyPixMap(PixMapHandle srcPM,PixMapHandle dstPM);
void          SetPortPix(PixMapHandle pm);
void          DisposePixMap(PixMapHandle pm);

GDHandle  NewGDevice(short refNum,long mode);
void      InitGDevice(short qdRefNum,long mode,GDHandle gdh);
void      SetDeviceAttribute(GDHandle gdh,short attribute,Boolean value);
void      SetGDevice(GDHandle gd);
void      DisposeGDevice(GDHandle gdh);

GDHandle  GetGDevice(void);
GDHandle  LMGetMainDevice(void);
GDHandle  GetNextDevice(GDHandle curDevice);
GDHandle  LMGetDeviceList(void);

Boolean  TestDeviceAttribute(GDHandle gdh,short attribute);
void     ScreenRes(short *scrnHRes,short *scrnVRes);

OSErr  SetDepth(GDHandle gd,short depth,short whichFlags,short flags);
short  HasDepth(GDHandle gd,short depth,short whichFlags,short flags);