QuickDraw Reference (Legacy)

Framework
ApplicationServices/ApplicationServices.h
Companion guide
Declared in
IOMacOSTypes.h
IONDRVLibraries.h
QDOffscreen.h
QDPictToCGContext.h
Quickdraw.h
QuickdrawAPI.h
QuickdrawTypes.h

Overview

QuickDraw is the legacy 2D drawing engine for Macintosh computers. QuickDraw provides routines for drawing, manipulating, and displaying graphic objects such as lines, arcs, rectangles, ovals, regions, and bitmap images. Carbon supports most of the classic QuickDraw programming interface.

Functions by Task

Drawing QuickDraw Pictures in a Quartz Context

Using Quartz 2D to Draw in a Graphics Port

Other Quartz-Related Functions in QuickDraw

Calculating Black-and-White Fills

Calculating Color Fills

Changing Black-and-White Cursors

Changing Color Cursors

Changing the Background Bit Pattern

Changing the Background Pixel Pattern

Compressing and Decompressing Data

Converting Between Angle and Slope Values

Copying Images

Creating, Altering, and Disposing of Offscreen Graphics Worlds

Creating and Disposing of Color Tables

Creating and Disposing of Pictures

Creating and Disposing of Pixel Patterns

Creating and Managing Polygons

Creating and Managing Rectangles

Creating and Managing Regions

Creating, Setting, and Disposing of GDevice Records

Creating, Setting, and Disposing of Pixel Maps

Customizing Color QuickDraw Operations

Customizing QuickDraw Operations

Determining Current Colors and Best Intermediate Colors

Determining the Characteristics of a Video Device

Determining Whether QuickDraw Has Finished Drawing

Drawing Arcs and Wedges

Drawing Lines

Drawing Ovals

Drawing Pictures

Drawing Polygons

Drawing Rectangles

Drawing Regions

Drawing Rounded Rectangles

Drawing With Color QuickDraw Colors

Drawing With the Eight-Color System

Getting Pattern Resources

Getting the Available Graphics Devices

Hiding and Showing Cursors

Managing a Color Graphics Pen

Managing an Offscreen Graphics World’s Pixel Image

Managing Bitmaps, Port Rectangles, and Clipping Regions

Managing Color Tables

Managing Colors

Managing the Graphics Pen

Manipulating Points in Graphics Ports

Obtaining a Pseudorandom Number

Operations on Search and Complement Functions

Reporting Data Structure Changes to QuickDraw

Retrieving Color QuickDraw Result Codes

Saving and Restoring Graphics Ports

Saving and Restoring Graphics Ports and Offscreen Graphics Worlds

Scaling and Mapping Points, Rectangles, Polygons, and Regions

Miscellaneous

Functions

QDBeginCGContext

Returns a Quartz 2D drawing environment associated with a graphics port.

OSStatus QDBeginCGContext (
   CGrafPtr inPort,
   CGContextRef *outContext
);
Parameters
port

A color graphics port in which to draw. Offscreen graphics worlds with pixel depths of 1, 2, 4, and 8 are not supported. When using Quartz 2D to draw in a offscreen graphics world, alpha information is always ignored.

contextPtr

A pointer to your storage for a Quartz context. Upon completion, contextPtr points to a context associated with the port. The context matches the port’s pixel depth, width, and height. Otherwise the context is in a default state and does not necessarily match other port attributes such as foreground color, background color, or clip region.

You should not retain or release the context. When you are finished using the context, you should call QDEndCGContext.

Return Value

A result code. If noErr, the context was successfully initiated.

Discussion

Applications running in Mac OS X can use Quartz 2D to draw in a QuickDraw graphics port. When you call this function, you obtain a Quartz context that’s associated with the specified port. To improve performance, contexts returned by this function are cached and reused during subsequent calls whenever possible.

Each block of Quartz 2D drawing code in your application should be surrounded by calls to this function and QDEndCGContext. Nested calls to this function for the same graphics port are not permitted—that is, for a given port you should not call this function more than once without an intervening call to QDEndCGContext.

While the Quartz context is in use, all Quickdraw imaging operations in the associated graphics port are disabled. This is done because the operations would fail during printing.

For information about how to use a Quartz context, see Quartz 2D Programming Guide.

Availability
  • Available in OS X v10.1 and later.
  • Not available to 64-bit applications.
Declared In
Quickdraw.h

QDEndCGContext

Terminates a Quartz 2D drawing environment associated with a graphics port.

OSStatus QDEndCGContext (
   CGrafPtr inPort,
   CGContextRef *inoutContext
);
Parameters
port

A graphics port specified in a preceding call to QDBeginCGContext.

contextPtr

A pointer to the context obtained in the preceding call to QDBeginCGContext for the port. Upon completion, the storage pointed to by contextPtr is set to NULL.

Return Value

A result code. If noErr, the context is terminated.

Discussion

After you finish using Quartz 2D to draw in a graphics port, you should call this function to terminate the context. For more information, see QDBeginCGContext.

Before calling this function, you should do one of the following:

  • Call CGContextSynchronize to mark the affected areas of the port for update.

  • Call CGContextFlush to immediately update the destination device.

Availability
  • Available in OS X v10.1 and later.
  • Not available to 64-bit applications.
Declared In
Quickdraw.h

Callbacks

ColorComplementProcPtr

Defines a pointer to a color inversion callback function that overrides the Color Manager’s color inversion method.

typedef Boolean (*ColorComplementProcPtr) (
   RGBColor * rgb
);

If you name your function MyColorComplementProc, you would declare it like this:

Boolean ColorComplementProcPtr (
   RGBColor * rgb
);

Parameters
rgb

A pointer to the RGBColor data structure. Change it to reflect the inverted value.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

ColorSearchProcPtr

Defines a pointer to a color search callback function that overrides the Color Manager’s code for inverse table mapping.

typedef Boolean (*ColorSearchProcPtr) (
   RGBColor * rgb,
   long * position
);

If you name your function MyColorSearchProc, you would declare it like this:

Boolean ColorSearchProcPtr (
   RGBColor * rgb,
   long * position
);

Parameters
rgb

A pointer to the RGBColor data structure passed to your search function. Your function should set the ColorSpec.value field to the index corresponding to the color indicated here.

position

A pointer to the index of the best-mapping color your function finds.

Return Value

True if your function succeeds, false if your function cannot find a match.

Discussion

Your MyColorSearchCallback function should examine the RGBColor data structure passed to it by the Color Manager and return the index to the best-mapping color in the current GDevice data structure.

The Color Manager specifies the desired color in the RGBColor field of a ColorSpec data structure and passes it by a pointer on the stack. Your function should return the corresponding index in the ColorSpec.value field. If your function cannot handle the search, return false as the function value, and pass the RGBColor data structure back to the Color Manager in the rgb parameter.

The Color Manager calls each search function in the list until one returns the Boolean value true. If no search function installed in the linked list returns true, the Color Manager calls the default search function.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

CustomXFerProcPtr

typedef void (*CustomXFerProcPtr) (
   CustomXFerRecPtr info
);

If you name your function MyCustomXFerProc, you would declare it like this:

void CustomXFerProcPtr (
   CustomXFerRecPtr info
);

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawAPI.h

DeviceLoopDrawingProcPtr

typedef void (*DeviceLoopDrawingProcPtr) (
   short depth,
   short deviceFlags,
   GDHandle targetDevice,
   long userData
);

If you name your function MyDeviceLoopDrawingProc, you would declare it like this:

void DeviceLoopDrawingProcPtr (
   short depth,
   short deviceFlags,
   GDHandle targetDevice,
   long userData
);

Parameters
depth

The pixel depth of the graphics device.

deviceFlags

Constants which represent bits that are set to 1 in the gdFlags field of the GDevice structure for the current device. See “Device Attribute Constants” for a description of the values which you can receive in this parameter.

targetDevice

A handle to the GDevice structure for the current device.

userData

A value that your application supplies to the DeviceLoop function, which in turn passes the value to your drawing function for whatever purpose you deem useful.

Discussion

For each video device that intersects a drawing region that you define (generally, the update region of a window), DeviceLoop calls your drawing function. Your drawing function should analyze the pixel depth passed in the depth parameter and the values passed in the deviceFlags parameter, and then draw in a manner that is optimized for the current device.

When highlighting, for example, your application might invert black and white when drawing onto a 1-bit video device but use magenta as the highlight color when drawing onto a color video device. In this case, even were your window to span both a black-and-white and a color screen, the user sees the selection inverted on the black-and-white screen, while magenta would be used to highlight the selection on the color screen.

You must provide a pointer to your MyDeviceLoopDrawingCallback function in the drawingProc parameter for DeviceLoop.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

DragGrayRgnProcPtr

typedef void (*DragGrayRgnProcPtr) (
);

If you name your function MyDragGrayRgnProc, you would declare it like this:

void DragGrayRgnProcPtr ();

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDArcProcPtr

typedef void (*QDArcProcPtr) (
   GrafVerb verb,
   const Rect * r,
   short startAngle,
   short arcAngle
);

If you name your function MyQDArcProc, you would declare it like this:

void QDArcProcPtr (
   GrafVerb verb,
   const Rect * r,
   short startAngle,
   short arcAngle
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDBitsProcPtr

typedef void (*QDBitsProcPtr) (
   const BitMap * srcBits,
   const Rect * srcRect,
   const Rect * dstRect,
   short mode,
   RgnHandle maskRgn
);

If you name your function MyQDBitsProc, you would declare it like this:

void QDBitsProcPtr (
   const BitMap * srcBits,
   const Rect * srcRect,
   const Rect * dstRect,
   short mode,
   RgnHandle maskRgn
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDCommentProcPtr

typedef void (*QDCommentProcPtr) (
   short kind,
   short dataSize,
   Handle dataHandle
);

If you name your function MyQDCommentProc, you would declare it like this:

void QDCommentProcPtr (
   short kind,
   short dataSize,
   Handle dataHandle
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDGetPicProcPtr

typedef void (*QDGetPicProcPtr) (
   void * dataPtr,
   short byteCount
);

If you name your function MyQDGetPicProc, you would declare it like this:

void QDGetPicProcPtr (
   void * dataPtr,
   short byteCount
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDJShieldCursorProcPtr

typedef void (*QDJShieldCursorProcPtr) (
   short left,
   short top,
   short right,
   short bottom
);

If you name your function MyQDJShieldCursorProc, you would declare it like this:

void QDJShieldCursorProcPtr (
   short left,
   short top,
   short right,
   short bottom
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDLineProcPtr

typedef void (*QDLineProcPtr) (
   Point newPt
);

If you name your function MyQDLineProc, you would declare it like this:

void QDLineProcPtr (
   Point newPt
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDOpcodeProcPtr

typedef void (*QDOpcodeProcPtr) (
   const Rect * fromRect,
   const Rect * toRect,
   UInt16 opcode,
   SInt16 version
);

If you name your function MyQDOpcodeProc, you would declare it like this:

void QDOpcodeProcPtr (
   const Rect * fromRect,
   const Rect * toRect,
   UInt16 opcode,
   SInt16 version
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDOvalProcPtr

typedef void (*QDOvalProcPtr) (
   GrafVerb verb,
   const Rect * r
);

If you name your function MyQDOvalProc, you would declare it like this:

void QDOvalProcPtr (
   GrafVerb verb,
   const Rect * r
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDPolyProcPtr

typedef void (*QDPolyProcPtr) (
   GrafVerb verb,
   PolyHandle poly
);

If you name your function MyQDPolyProc, you would declare it like this:

void QDPolyProcPtr (
   GrafVerb verb,
   PolyHandle poly
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDPrinterStatusProcPtr

typedef OSStatus (*QDPrinterStatusProcPtr) (
   PrinterStatusOpcode opcode,
   CGrafPtr currentPort,
   void * printerStatus
);

If you name your function MyQDPrinterStatusProc, you would declare it like this:

OSStatus QDPrinterStatusProcPtr (
   PrinterStatusOpcode opcode,
   CGrafPtr currentPort,
   void * printerStatus
);

Return Value
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDPutPicProcPtr

typedef void (*QDPutPicProcPtr) (
   const void * dataPtr,
   short byteCount
);

If you name your function MyQDPutPicProc, you would declare it like this:

void QDPutPicProcPtr (
   const void * dataPtr,
   short byteCount
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDRectProcPtr

typedef void (*QDRectProcPtr) (
   GrafVerb verb,
   const Rect * r
);

If you name your function MyQDRectProc, you would declare it like this:

void QDRectProcPtr (
   GrafVerb verb,
   const Rect * r
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDRgnProcPtr

typedef void (*QDRgnProcPtr) (
   GrafVerb verb,
   RgnHandle rgn
);

If you name your function MyQDRgnProc, you would declare it like this:

void QDRgnProcPtr (
   GrafVerb verb,
   RgnHandle rgn
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDRRectProcPtr

typedef void (*QDRRectProcPtr) (
   GrafVerb verb,
   const Rect * r,
   short ovalWidth,
   short ovalHeight
);

If you name your function MyQDRRectProc, you would declare it like this:

void QDRRectProcPtr (
   GrafVerb verb,
   const Rect * r,
   short ovalWidth,
   short ovalHeight
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDStdGlyphsProcPtr

typedef OSStatus (*QDStdGlyphsProcPtr) (
   void * dataStream,
   ByteCount size
);

If you name your function MyQDStdGlyphsProc, you would declare it like this:

OSStatus QDStdGlyphsProcPtr (
   void * dataStream,
   ByteCount size
);

Return Value
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDTextProcPtr

typedef void (*QDTextProcPtr) (
   short byteCount,
   const void * textBuf,
   Point numer,
   Point denom
);

If you name your function MyQDTextProc, you would declare it like this:

void QDTextProcPtr (
   short byteCount,
   const void * textBuf,
   Point numer,
   Point denom
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDTxMeasProcPtr

typedef short (*QDTxMeasProcPtr) (
   short byteCount,
   const void * textAddr,
   Point * numer,
   Point * denom,
   FontInfo * info
);

If you name your function MyQDTxMeasProc, you would declare it like this:

short QDTxMeasProcPtr (
   short byteCount,
   const void * textAddr,
   Point * numer,
   Point * denom,
   FontInfo * info
);

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

RegionToRectsProcPtr

typedef OSStatus (*RegionToRectsProcPtr) (
   UInt16 message,
   RgnHandle rgn,
   const Rect * rect,
   void * refCon
);

If you name your function MyRegionToRectsProc, you would declare it like this:

OSStatus RegionToRectsProcPtr (
   UInt16 message,
   RgnHandle rgn,
   const Rect * rect,
   void * refCon
);

Return Value
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

Data Types

BitMap

struct BitMap {
   Ptr baseAddr;
   short rowBytes;
   Rect bounds;
};
typedef struct BitMap BitMap;
   typedef BitMap * BitMapPtr;
Fields
baseAddr

A pointer to the beginning of the bit image.

rowBytes

The offset in bytes from one row of the image to the next. The value of the rowBytes field must be less than $4000.

bounds

The bitmap’s boundary rectangle by default, the entire main screen.

Discussion

A bitmap, which is a data structure of type BitMap, defines a bit image in terms of the QuickDraw coordinate plane. (A bit image is a collection of bits in memory that form a grid.)

A bitmap has three parts: a pointer to a bit image, the row width of that image, and a boundary rectangle that links the local coordinate system of a graphics port to QuickDraw’s global coordinate system and defines the area of the bit image into which QuickDraw can draw.

The width of the boundary rectangle determines how many bits of one row are logically owned by the bitmap. This width must not exceed the number of bits in each row of the bit image. The height of the boundary rectangle determines how many rows of the image are logically owned by the bitmap. The number of rows enclosed by the boundary rectangle must not exceed the number of rows in the bit image.

The boundary rectangle defines the local coordinate system used by the port rectangle for a graphics port (described next). The upper-left corner (which for a window is called the window origin) of the port rectangle usually has a vertical coordinate of 0 and a horizontal coordinate of 0, although you can use the function SetOrigin to change the coordinates of the window origin.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

Bits16

typedef short Bits16[16];
Discussion

The Bits16 array is used by the Cursor structure to hold a black-and-white, 16-by-16 pixel square image.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

CCrsr

struct CCrsr {
   short crsrType;
   PixMapHandle crsrMap;
   Handle crsrData;
   Handle crsrXData;
   short crsrXValid;
   Handle crsrXHandle;
   Bits16 crsr1Data;
   Bits16 crsrMask;
   Point crsrHotSpot;
   long crsrXTable;
   long crsrID;
};
typedef struct CCrsr CCrsr;
   typedef CCrsr * CCrsrPtr;
Fields
crsrType

The type of cursor. Possible values are $8000 for a black-and-white cursor and $8001 for a color cursor.

crsrMap

A handle to the PixMap structure defining the cursor’s characteristics. When the screen depth is greater than 2 bits per pixel, the crsrMap field and the crsrData field define the image. The pixels within the mask replace the destination pixels. Color QuickDraw transfers the pixels outside the mask into the destination pixels using the XOR Boolean transfer mode. Therefore, if pixels outside the mask are white, the destination pixels aren’t changed. If pixels outside the mask are all black, the destination pixels are inverted. All other values outside of the mask cause unpredictable results.

crsrData

A handle to the cursor’s pixel data. To work properly, a color cursor’s image should contain white pixels (R=G= B=$FFFF) for the transparent part of the image, and black pixels (R=G=B=$0000) for the part of the image to be inverted, in addition to the other colors in the cursor’s image. Thus, to define a cursor that contains two colors, it’s necessary to use a 2-bit cursor image (that is, a four-color image.

crsrXData

A handle to the expanded pixel image used internally by Color QuickDraw.

crsrXValid

The depth of the expanded cursor image. If you change the cursor’s data or color table, set this field to 0 to cause the cursor to be re-expanded. Never set it to any other values.

crsrXHandle

Reserved for future use.

crsr1Data

A 16-by-16 pixel image with a pixel depth of 1 to be displayed when the cursor is on screens with pixel depths of 1 or 2 bits.

crsrMask

The cursor’s mask data. QuickDraw uses the mask to crop the cursor’s outline into a background color or pattern. QuickDraw then draws the cursor into this shape. The same 1-bit mask is used with images specified by the crsrData and crsr1Data fields.

crsrHotSpot

The cursor’s hot spot.

crsrXTable

Reserved for future use.

crsrID

The color table seed for the cursor.

Discussion

Your application typically does not create CCrsr structures. Although you can create a CCrsr structure, it is usually easier to create a color cursor in a color cursor resource, ‘crsr’.

A color cursor is a 256-pixel color image in a 16-by-16 pixel square defined in a color cursor ( 'crsr') resource. When your application uses the GetCCursor function to get a color cursor from a 'crsr' resource, GetCCursor loads the resource into memory as a CCrsr structure. Your application can then display the color cursor by using the SetCCursor function.

CCrsr is substantially different from the Cursor structure. The fields crsr1Data, crsrMask, and crsrHotSpot in the CCrsr structure are the only ones that have counterparts in the Cursor structure.

The first four fields of the CCrsr structure are similar to the first four fields of the PixPat record, and are used in the same manner by QuickDraw.

The display of a cursor involves a relationship between a mask, stored in the crsrMask field with the same format used for 1-bit cursor masks, and an image. There are two possible sources for a color cursor’s image. When the cursor is on a screen whose depth is 1 or 2 bits per pixel, the image for the cursor is taken from the crsr1Data field, which contains bitmap cursor data, similar to the bitmap in a 'CURS' resource.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

CGrafPort

struct CGrafPort {
   SInt16 device;
   PixMapHandle portPixMap;
   SInt16 portVersion;
   Handle grafVars;
   SInt16 chExtra;
   SInt16 pnLocHFrac;
   Rect portRect;
   RgnHandle visRgn;
   RgnHandle clipRgn;
   PixPatHandle bkPixPat;
   RGBColor rgbFgColor;
   RGBColor rgbBkColor;
   Point pnLoc;
   Point pnSize;
   SInt16 pnMode;
   PixPatHandle pnPixPat;
   PixPatHandle fillPixPat;
   SInt16 pnVis;
   SInt16 txFont;
   StyleField txFace;
   SInt16 txMode;
   SInt16 txSize;
   Fixed spExtra;
   SInt32 fgColor;
   SInt32 bkColor;
   SInt16 colrBit;
   SInt16 patStretch;
   Handle picSave;
   Handle rgnSave;
   Handle polySave;
   CQDProcsPtr grafProcs;
};

CGrafPtr

typedef GrafPtr CGrafPtr;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

ColorComplementUPP

typedef ColorComplementProcPtr ColorComplementUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

ColorSearchUPP

typedef ColorSearchProcPtr ColorSearchUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

ColorSpec

struct ColorSpec {
   short value;
   RGBColor rgb;
};
typedef struct ColorSpec ColorSpec;
   typedef ColorSpec * ColorSpecPtr;
Fields
value

The pixel value assigned by QuickDraw for the color specified in the rgb field of this structure. QuickDraw assigns a pixel value based on the capabilities of the user’s screen. For indexed devices, the pixel value is an index number assigned by QuickDraw to the closest color available on the indexed device for direct devices, this value expresses the best available red, green, and blue values for the color on the direct device.

rgb

An RGBColor structure that fully specifies the color whose approximation QuickDraw specifies in the value field.

Discussion

When creating a PixMap structure for an indexed device, QuickDraw creates a ColorTable structure that defines the best colors available for the pixel image on that graphics device. QuickDraw also stores a ColorTable structure for the currently available colors in the graphics device’s CLUT.

One of the fields in a ColorTable structure requires a value of type cSpecArray, which is defined as an array of ColorSpec structures. Typically, your application never needs to create ColorTable structures or ColorSpec structures. For completeness, the data structure of type ColorSpec is shown here.

Availability
  • Available in OS X v10.0 and later.
Declared In
IOMacOSTypes.h

ColorTable

struct ColorTable {
   long ctSeed;
   short ctFlags;
   short ctSize;
   CSpecArray ctTable;
};
typedef struct ColorTable ColorTable;
   typedef ColorTable * CTabPtr;
   typedef CTabPtr * CTabHandle;
Fields
ctSeed

Identifies a particular instance of a color table. QuickDraw uses the ctSeed value to compare an indexed device’s color table with its associated inverse table (a table it uses for fast color lookup). When the color table for a graphics device has been changed, QuickDraw needs to rebuild the inverse table.

ctFlags

Flags that distinguish pixel map color tables from color tables in GDevice structures.

ctSize

One less than the number of entries in the table.

ctTable

An array of ColorSpec entries, each containing a pixel value and a color specified by an RGBColor structure.

Discussion

When creating a PixMap structure for a particular graphics device, QuickDraw creates a ColorTable structure that defines the best colors available for the pixel image on that particular graphics device. QuickDraw also creates a ColorTable structure of all available colors for use by the CLUT on indexed devices.

Typically, your application needs to create ColorTable structures only if it uses the Palette Manager.

Your application should never need to directly change the fields of a ColorTable structure. If you find it absolutely necessary for your application to do so, immediately use the CTabChanged function to notify QuickDraw that your application has changed the ColorTable structure.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

ConstPatternParam

typedef const Pattern* ConstPatternParam;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

CProcRec

struct CProcRec {
   Handle nxtComp;
   ColorComplementUPP compProc;
};
typedef struct CProcRec CProcRec;
   typedef CProcRec * CProcPtr;
Fields
nxtComp

A handle to the next CPRocRec data structure in the list.

compProc

A pointer to a complement function, as described in ColorComplementProcPtr.

Discussion

The CProcRec data structure contains a pointer to a custom complement function and a pointer to the next complement function in the list.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

CQDProcs

struct CQDProcs {
   QDTextUPP textProc;
   QDLineUPP lineProc;
   QDRectUPP rectProc;
   QDRRectUPP rRectProc;
   QDOvalUPP ovalProc;
   QDArcUPP arcProc;
   QDPolyUPP polyProc;
   QDRgnUPP rgnProc;
   QDBitsUPP bitsProc;
   QDCommentUPP commentProc;
   QDTxMeasUPP txMeasProc;
   QDGetPicUPP getPicProc;
   QDPutPicUPP putPicProc;
   QDOpcodeUPP opcodeProc;
   UniversalProcPtr newProc1;
   QDStdGlyphsUPP glyphsProc;
   QDPrinterStatusUPP printerStatusProc;
   UniversalProcPtr newProc4;
   UniversalProcPtr newProc5;
   UniversalProcPtr newProc6;
};
typedef struct CQDProcs CQDProcs;
   typedef CQDProcs * CQDProcsPtr;
Fields
textProc

A pointer to the low-level function that draws text. The standard QuickDraw function is the StdText function.

lineProc

A pointer to the low-level function that draws lines. The standard QuickDraw function is the StdLine function.

rectProc

A pointer to the low-level function that draws rectangles. The standard QuickDraw function is the StdRect function.

rRectProc

A pointer to the low-level function that draws rounded rectangles. The standard QuickDraw function is the StdRRect function.

ovalProc

A pointer to the low-level function that draws ovals. The standard QuickDraw function is the StdOval function.

arcProc

A pointer to the low-level function that draws arcs. The standard QuickDraw function is the StdArc function.

polyProc

A pointer to the low-level function that draws polygons. The standard QuickDraw function is the StdPoly function.

rgnProc

A pointer to the low-level function that draws regions. The standard QuickDraw function is the StdRgn function.

bitsProc

A pointer to the low-level function that copies bitmaps. The standard QuickDraw function is the StdBits function.

commentProc

A pointer to the low-level function for processing a picture comment. The standard QuickDraw function is the StdComment function.

txMeasProc

A pointer to the low-level function for measuring text width. The standard QuickDraw function is the StdTxMeas function.

getPicProc

A pointer to the low-level function for retrieving information from the definition of a picture. The standard QuickDraw function is the StdGetPic function.

putPicProc

A pointer to the low-level function for saving information as the definition of a picture. The standard QuickDraw function is the StdPutPic function.

opcodeProc

Reserved for future use.

newProc1

Reserved for future use.

glyphsProc

Reserved for future use.

printerStatusProc

Reserved for future use.

newProc4

Reserved for future use.

newProc5

Reserved for future use.

newProc6

Reserved for future use.

Discussion

Use the CQDProcs structure only if you customize one or more of QuickDraw’s standard low-level drawing functions. Use the SetStdCProcs function to create a CQDProcs structure.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

CSpecArray

typedef ColorSpec CSpecArray[1];
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

Cursor

struct Cursor {
   Bits16 data;
   Bits16 mask;
   Point hotSpot;
};
typedef struct Cursor Cursor;
   typedef Cursor * CursPtr;
Fields
data

Cursor image data, which must begin on a word boundary.

mask

The cursor’s mask. QuickDraw uses the mask to crop the cursor’s outline into a background color or pattern. QuickDraw then draws the cursor into this shape.

hotSpot

A point in the image that aligns a point (not a bit) in the image with the mouse location on the screen. Whenever the user moves the mouse, the low-level interrupt-driven mouse functions move the cursor. When the user clicks, the Event Manager function WaitNextEvent reports the location of the cursor’s hot spot in global coordinates.

Discussion

Your application typically does not create Cursor structures. Although you can create a Cursor structure and its associated Bits16 array in your program code, it is usually easier to create a black-and-white cursor in a cursor resource,‘CURS’.

A cursor is a 256-pixel, black-and-white image in a 16-by-16 pixel square. When your application uses the GetCursor function to get a cursor from a 'CURS' resource, GetCursor loads the resource into memory as a Cursor structure. Your application then displays the color cursor by using the SetCursor function.

The cursor appears on the screen as a 16-by-16 pixel square. The appearance of each bit if the square is determined by the corresponding bits in the data and the mask and, if the mask bit is 0, by the pixel under the cursor. The four possible combinations of values for the data bit and the mask bit are:

  • Data bit 0, Mask bit 1. The resulting pixel on the screen is white.

  • Data bit 1, Mask bit 1. The resulting pixel on the screen is black.

  • Data bit 0, Mask bit 0. The resulting pixel on the screen is the same as the pixel under the cursor.

  • Data bit 1, Mask bit 0. The resulting pixel on the screen is the inverse of the pixel under the cursor.

Notice that if all mask bits are 0, the cursor is completely transparent, in that the image under the cursor can still be viewed. Pixels under the white part of the cursor appear unchanged; under the black part of the cursor, black pixels show through as white.

Basic QuickDraw supplies a predefined cursor in the global variable named arrow; this is the standard arrow cursor.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

CursorImageRec

struct CursorImageRec {
   UInt16 majorVersion;
   UInt16 minorVersion;
   PixMapHandle cursorPixMap;
   BitMapHandle cursorBitMask;
};
typedef struct CursorImageRec CursorImageRec;
   typedef CursorImageRec * CursorImagePtr;
Availability
  • Available in OS X v10.0 through OS X v10.4.
Declared In
Quickdraw.h

CursorInfo

struct CursorInfo {
   long version;
   long capabilities;
   long animateDuration;
   Rect bounds;
   Point hotspot;
   long reserved;
};
typedef struct CursorInfo CursorInfo;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawAPI.h

CustomXFerRec

struct CustomXFerRec {
   UInt32 version;
   void * srcPixels;
   void * destPixels;
   void * resultPixels;
   UInt32 refCon;
   UInt32 pixelSize;
   UInt32 pixelCount;
   Point firstPixelHV;
   Rect destBounds;
};
typedef struct CustomXFerRec CustomXFerRec;
   typedef CustomXFerRec * CustomXFerRecPtr;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawAPI.h

CWindowPtr

typedef WindowPtr CWindowPtr;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

DeviceLoopDrawingUPP

typedef DeviceLoopDrawingProcPtr DeviceLoopDrawingUPP;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

DeviceLoopFlags

typedef unsigned long DeviceLoopFlags;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

DialogPtr

An opaque type that represents a dialog.

typedef struct OpaqueDialogPtr * DialogPtr;
Discussion

This is a Dialog Manager data type, defined in QuickDraw for historical reasons. Its role in Mac OS X is to serve as the basis for the widely used DialogRef data type.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

DragConstraint

typedef UInt16 DragConstraint;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

DragGrayRgnUPP

typedef DragGrayRgnProcPtr DragGrayRgnUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

GammaTbl

struct GammaTbl {
   short gVersion;
   short gType;
   short gFormulaSize;
   short gChanCnt;
   short gDataCnt;
   short gDataWidth;
   short gFormulaData[1];
};
typedef struct GammaTbl GammaTbl;
   typedef GammaTbl * GammaTblPtr;
Availability
  • Available in OS X v10.0 and later.
Declared In
IOMacOSTypes.h

GDevice

struct GDevice {
   short gdRefNum;
   short gdID;
   short gdType;
   ITabHandle gdITable;
   short gdResPref;
   SProcHndl gdSearchProc;
   CProcHndl gdCompProc;
   short gdFlags;
   PixMapHandle gdPMap;
   long gdRefCon;
   GDHandle gdNextGD;
   Rect gdRect;
   long gdMode;
   short gdCCBytes;
   short gdCCDepth;
   Handle gdCCXData;
   Handle gdCCXMask;
   long gdReserved;
};
typedef struct GDevice GDevice;
   typedef GDevice * GDPtr;
   typedef GDPtr * GDHandle;
Fields
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 structure, set this field to 0.

gdType

The general type of graphics device. See “Graphics Device Type Constants” for a description of the values which you can use in this field.

gdITable

A handle to the inverse table for color mapping.

gdResPref

The preferred resolution for inverse tables.

gdSearchProc

A handle to the list of search functions. Its value is NULL for the default function.

gdCompProc

A handle to a list of complement functions. Its value is NULL for the default function.

gdFlags

The GDevice structure’s attributes. To set the attribute bits in the gdFlags field, use the SetDeviceAttribute function. Do not set gdFlags directly in the GDevice structure.

gdPMap

A handle to a PixMap structure giving the dimension of the image buffer, along with the characteristics of the graphics device (resolution, storage format, color depth, and color table). For GDevice structures, the high bit of the global variable

(((**TheGDevice).**gdPMap).**pmTable).ctFlags

is always set.

gdRefCon

A value used by system software to pass device-related parameters. Since a graphics device is shared, do not 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 structure. 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 do not need this information.

gdCCBytes

The rowBytes value of the expanded cursor. Your application should not change this field.

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.

Discussion

Color QuickDraw stores state information for video devices and offscreen graphics worlds in GDevice structures. When the system starts up, it allocates and initializes one handle to a GDevice structure for each video device it finds. When you use the Offscreen Graphics Devices function, NewGWorld, Color QuickDraw automatically creates a GDevice structure for the new offscreen graphics world. The system links these GDevice structures 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 structure 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.

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 structures 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. Application-created GDevice structures usually don’t require drivers.

Your application should never need to directly change the fields of a GDevice structure. If you find it absolutely necessary for your application to so, immediately use the GDeviceChanged function to notify QuickDraw that your application has changed the GDevice structure.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

GrafPort

struct GrafPort {
   SInt16 device;
   BitMap portBits;
   Rect portRect;
   RgnHandle visRgn;
   RgnHandle clipRgn;
   Pattern bkPat;
   Pattern fillPat;
   Point pnLoc;
   Point pnSize;
   SInt16 pnMode;
   Pattern pnPat;
   SInt16 pnVis;
   SInt16 txFont;
   StyleField txFace;
   SInt16 txMode;
   SInt16 txSize;
   Fixed spExtra;
   SInt32 fgColor;
   SInt32 bkColor;
   SInt16 colrBit;
   SInt16 patStretch;
   Handle picSave;
   Handle rgnSave;
   Handle polySave;
   QDProcsPtr grafProcs;
};

GrafPtr

typedef struct OpaqueGrafPtr * GrafPtr;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

GrafVars

struct GrafVars {
   RGBColor rgbOpColor;
   RGBColor rgbHiliteColor;
   Handle pmFgColor;
   short pmFgIndex;
   Handle pmBkColor;
   short pmBkIndex;
   short pmFlags;
};
typedef struct GrafVars GrafVars;
   typedef GrafVars * GVarPtr;
Fields
rgbOpColor

The color for the arithmetic transfer operations addPin, subPin, and blend.

rgbHiliteColor

The highlight color for this graphics port.

pmFgColor

A handle to the palette that contains the foreground color.

pmFgIndex

The index value into the palette for the foreground color.

pmBkColor

A handle to the palette that contains the background color.

pmBkIndex

The index value into the palette for the background color.

pmFlags

Flags private to the Palette Manager.

Discussion

The GrafVars structure contains color information in addition to that in the CGrafPort structure, of which it is logically a part; the information is used by QuickDraw and the Palette Manager.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

GrafVerb

typedef SInt8 GrafVerb;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

GWorldFlags

typedef unsigned long GWorldFlags;
Discussion

Several functions expect or return values defined by the GWorldFlags data type. See “Graphics World Flags” for a detailed description of these flags.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

GWorldPtr

Defines a pointer to a structure that your application can use to refer to an offscreen graphics world.

typedef CGrafPtr GWorldPtr;
Discussion

An offscreen graphics world in color QuickDraw contains a CGrafPort structure—and its handles to associated PixMap and ColorTable structures—that describes an offscreen graphics port and contains references to a GDevice structure and other state information. The actual data structure for an offscreen graphics world is kept private to allow for future extensions. However, when your application uses the NewGWorld function to create an offscreen world, NewGWorld returns a pointer of type GWorldPtr by which your application refers to the offscreen graphics world.

On computers lacking color QuickDraw, GWorldPtr points to an extension of the GrafPort structure.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

ITab

struct ITab {
   long iTabSeed;
   short iTabRes;
   Byte iTTable[1];
};
typedef struct ITab ITab;
   typedef ITab * ITabPtr;
   typedef ITabPtr * ITabHandle;
Fields
iTabSeed

The iTabSeed value, initially set from the corresponding CLUT’s ctSeed field. If at any time these do not match, then the color table was changed, and the inverse table needs to be rebuilt.

iTabRes

The resolution of this inverse table.

iTTable

An array of index values. The size of the iTabTable field in bytes is 23*iTabRes.

Discussion

The ITab data structure contains the inverse table information that the Color Manager uses for fast mapping of RGB color values.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

MacPolygon

struct MacPolygon {
   short polySize;
   Rect polyBBox;
   Point polyPoints[1];
};
typedef struct MacPolygon MacPolygon;
   typedef MacPolygon Polygon;
   typedef MacPolygon * PolyPtr;
   typedef PolyPtr * PolyHandle;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

MacRegion

struct MacRegion {
   UInt16 rgnSize;
   Rect rgnBBox;
};
typedef struct MacRegion MacRegion;

MatchRec

struct MatchRec {
   unsigned short red;
   unsigned short green;
   unsigned short blue;
   long matchData;
};
typedef struct MatchRec MatchRec;
Fields
red

Red value of the seed.

green

Green value of the seed.

blue

Blue value of the seed.

matchData

The value passed in the matchData parameter of the SeedCFill or CalcCMask function.

Discussion

When SeedCFill or CalcCMask calls your color search function, the GDRefCon field of the current GDevice structure contains a pointer to a MatchRec structure. This structure contains the RGB value of the seed pixel or seed color for which your color search function searches.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

OpenCPicParams

struct OpenCPicParams {
   Rect srcRect;
   Fixed hRes;
   Fixed vRes;
   short version;
   short reserved1;
   long reserved2;
};
typedef struct OpenCPicParams OpenCPicParams;
Fields
srcRect

The optimal bounding rectangle for the resolution indicated by the hRes and vRes fields. When you later call the DrawPicture function to play back the saved picture, specify a destination rectangle and DrawPicture scales the picture so that it is completely aligned with the destination rectangle.

hRes

The best horizontal resolution for the picture. A value of $00480000 specifies a horizontal resolution of 72 dpi.

vRes

The best vertical resolution for the picture. A value of $00480000 specifies a vertical resolution of 72 dpi.

version

Always set this field to –2.

reserved1

Reserved; set to 0.

reserved2

Reserved; set to 0.

Discussion

When you use the OpenCPicture function to begin creating a picture, you must pass it information in an OpenCPicParams structure. This structure provides a simple mechanism for specifying resolutions when creating images. For example, applications that create pictures from scanned images can specify resolutions higher than 72 dpi for these pictures in OpenCPicParams structures.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

Pattern

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

Your application typically does not create Pattern structures. Although you can create Pattern structures in your program code, it is usually easier to create bit patterns using the pattern, ‘PAT’, or pattern list, ‘PAT#’, resource.

A bit pattern is a 64-bit image, organized as an 8-by-8 bit square, that defines a repeating design or tone. When a pattern is drawn, it is aligned so that adjacent areas of the same pattern in the same graphics port form a continuous, coordinated pattern. QuickDraw provides predefined patterns in global variables named white, black, gray, ltGray, and dkGray. The row width of a pattern is 1 byte.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

PenState

struct PenState {
   Point pnLoc;
   Point pnSize;
   short pnMode;
   Pattern pnPat;
};
typedef struct PenState PenState;
Fields
pnLoc

For the current graphics port at the time the GetPenState function was called, the value of that graphics port’s pnLoc field. This value is the point where QuickDraw begins drawing next. The location of the graphics pen is a point in the graphics port’s coordinate system, not a pixel in a bit image. The upper-left corner of the pen is at the pen location the graphics pen hangs below and to the right of this point.

pnSize

For the current graphics port at the time the GetPenState function was called, the value of that graphics port’s pnSize field. The graphics pen is rectangular in shape, and its width and height are specified by the values in the pnSize field. The default size is a 1-by-1 bit square; the width and height can range from 0 by 0 to 32,767 by 32,767. If either the pen width or the pen height is 0, the pen does not draw. Heights or widths of less than 0 are undefined.

pnMode

The pattern mode—that is, for the current graphics port at the time the GetPenState function was called, the value of that graphics port’s pnMode field. This value determines how the pen pattern is to affect what’s already in the bit image when lines or shapes are drawn. When the graphics pen draws, QuickDraw first determines what bits in the bit image are affected, finds their corresponding bits in the pattern, and then transfers the bits from the pattern into the image according to this mode, which specifies one of eight Boolean transfer operations. The resulting bit is stored into its proper place in the bit image.

pnPat

For the current graphics port at the time the GetPenState function was called, the pen pattern for that graphics port. This pattern determines how the bits under the graphics pen are affected when lines or shapes are drawn.

Discussion

The GetPenState function saves the location, size, pattern, and pattern mode of the graphics pen for the current graphics port in a PenState structure, which is a data structure of type PenState. After changing the graphics pen as necessary, you can later restore these pen states with the SetPenState function.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

Picture

struct Picture {
   short picSize;
   Rect picFrame;
};
typedef struct Picture Picture;
   typedef Picture * PicPtr;
   typedef PicPtr * PicHandle;
Fields
picSize

The size of the rest of this structure for a version 1 picture. To maintain compatibility with the version 1 picture format, the picSize field was not changed for the version 2 picture or extended version 2 formats. The information in this field is used only for version 1 pictures, which cannot exceed 32 KB in size. Because version 2 and extended version 2 pictures can be much larger than the 32 KB limit imposed by the 2-byte picSize field, you should use the Memory Manager function GetHandleSize to determine the size of a picture in memory; you should use the File Manager function PBGetFInfo to determine the size of a picture in a 'PICT' file; and you should use the Resource Manager function GetMaxResourceSize to determine the size of a 'PICT' resource.

picFrame

The bounding rectangle for the picture defined in the rest of this structure. The DrawPicture function uses this rectangle to scale the picture if you draw it into a destination rectangle of a different size.

Discussion

When you use the OpenCPicture or OpenPicture function, QuickDraw begins collecting your subsequent drawing commands in a Picture structure. (You use the ClosePicture function to complete a picture definition.) When you use the GetPicture function to retrieve a picture stored in a resource, GetPicture reads the resource into memory as a Picture structure. By using the DrawPicture procedure, you can draw onscreen the picture defined by the commands stored in the Picture structure.

A picture opcode is a number that the DrawPicture function uses to determine what object to draw or what mode to change for subsequent drawing. Generally, do not read or write this picture data directly. Instead, use the OpenCPicture (or OpenPicture), ClosePicture, and DrawPicture functions to process these opcodes.

The Picture structure can also contain picture comments. Created by applications using the PicComment function, picture comments contain data or commands for special processing by output devices, such as PostScript printers.

You can use File Manager functions to save the picture in a file of type 'PICT', you can use Resource Manager functions to save the picture in a resource of type 'PICT', and you can use the Scrap Manager function PutScrap to store the picture in 'PICT' scrap format.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

PixelType

typedef SInt8 PixelType;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

PixMap

struct PixMap {
   Ptr baseAddr;
   short rowBytes;
   Rect bounds;
   short pmVersion;
   short packType;
   long packSize;
   Fixed hRes;
   Fixed vRes;
   short pixelType;
   short pixelSize;
   short cmpCount;
   short cmpSize;
   long planeBytes;
   CTabHandle pmTable;
   long pmReserved;
};
typedef struct PixMap PixMap;
   typedef PixMap * PixMapPtr;
   typedef PixMapPtr * PixMapHandle;
Fields
baseAddr

For an onscreen pixel image, a pointer to the first byte of the image. For optimal performance, this should be a multiple of 4. The pixel image that appears on a screen is normally stored on a graphics card rather than in main memory.

Note that the baseAddr field of the PixMap structure for an offscreen graphics world contains a handle instead of a pointer. You must use the GetPixBaseAddr function to obtain a pointer to the PixMap structure for an offscreen graphics world. Your application should never directly access the baseAddr field of the PixMap structure for an offscreen graphics world.

rowBytes

The offset in bytes from one row of the image to the next. The value must be even, less than $4000, and for best performance it should be a multiple of 4. The high 2 bits of rowBytes are used as flags. If bit 15 = 1, the data structure pointed to is a PixMap structure; otherwise it is a BitMap structure.

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 bit image into which QuickDraw can draw. By default, the boundary rectangle is the entire main screen. Do not use the value of this field to determine the size of the screen instead use the value of the gdRect field of the GDevice structure for the screen.

pmVersion

The version number of QuickDraw that created this PixMap structure. The value of pmVersion is normally 0. If pmVersion is 4, QuickDraw treats the PixMap structure’s baseAddr field as 32-bit clean. All other flags are private. Most applications never need to set this field.

packType

The packing algorithm used to compress image data. QuickDraw currently supports a packType of 0, which means no packing, and values of 1 to 4 for packing direct pixels.

packSize

The size of the packed image in bytes. When the packType field contains the value 0, this field is always set to 0.

hRes

The horizontal resolution of the pixel image in pixels per inch. This value is of type Fixed; by default, the value here is $00480000 (for 72 pixels per inch).

vRes

The vertical resolution of the pixel image in pixels per inch. This value is of type Fixed; by default, the value here is $00480000 (for 72 pixels per inch).

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 for a direct device, this field is set to the constant RGBDirect when the screen depth is set.

pixelSize

Pixel depth; that is, the number of bits used to represent a pixel. Indexed pixels can have sizes of 1, 2, 4, and 8 bits; direct pixel sizes are 16 and 32 bits.

cmpCount

The number of components used to represent a color for a pixel. With indexed pixels, each pixel is a single value representing an index in a color table, and therefore this field contains the value 1—the index is the single component. 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

The size in bits of each component for a pixel. QuickDraw expects that the sizes of all components are the same, and that the value of the cmpCount field multiplied by the value of the cmpSize field is less than or equal to the value in the pixelSize field.

For an indexed pixel value, which has only one component, the value of the cmpSize field is the same as the value of the pixelSize field—that is, 1, 2, 4, or 8.

For direct pixels there are two additional possibilities:

  • A 16-bit pixel, which has three components, has a cmpSize value of 5. This leaves an unused high-order bit, which QuickDraw sets to 0.

  • A 32-bit pixel, which has three components (red, green, and blue), has a cmpSize value of 8. This leaves an unused high-order byte, which QuickDraw sets to 0.

Generally, therefore, your application should clear the memory for the image to 0 before creating a 16-bit or 32-bit image. The Memory Manager functions NewHandleClear and NewPtrClear assist you in allocating pre-zeroed memory.

planeBytes

The offset in bytes from one drawing plane to the next. This field is set to 0.

pmTable

A handle to a ColorTable structure for the colors in this pixel map.

pmReserved

Reserved for future expansion. This field must be set to 0 for future compatibility.

Discussion

The PixMap structure contains information about the dimensions, contents, storage format, depth, resolution, and color usage of a pixel image. The pixel map for a window’s color graphics port always consists of the pixel depth, color table, and boundary rectangle of the main screen, even if the window is created on or moved to an entirely different screen.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

PixPat

struct PixPat {
   short patType;
   PixMapHandle patMap;
   Handle patData;
   Handle patXData;
   short patXValid;
   Handle patXMap;
   Pattern pat1Data;
};
typedef struct PixPat PixPat;
   typedef PixPat * PixPatPtr;
   typedef PixPatPtr * PixPatHandle;
Fields
patType

The pattern’s type. The value 0 specifies a basic QuickDraw bit pattern, the value 1 specifies a full-color pixel pattern, and the value 2 specifies an RGB pattern.

patMap

A handle to a PixMap structure that describes the pattern’s pixel image. The PixMap structure can contain indexed or direct pixels.

patData

A handle to the pattern’s pixel image.

patXData

A handle to an expanded pixel image used internally by QuickDraw.

patXValid

A flag that, when set to –1, invalidates the expanded data.

patXMap

Reserved for use by QuickDraw.

pat1Data

A bit pattern to be used when this pattern is drawn into a GrafPort structure. The NewPixPat function sets this field to 50 percent gray.

Discussion

Your application typically does not create PixPat structures. Although you can create such structures in your program code, it is usually easier to create pixel patterns using the pixel pattern resource, 'ppat'.

When used for a color graphics port, the basic QuickDraw functions PenPat and BackPat store pixel patterns in, respectively, the pnPixPat and bkPixPat fields of the CGrafPort structure and set the patType field of the PixPat field to 0 to indicate that the PixPat structure contains a bit pattern. Such patterns are limited to 8-by-8 pixel dimensions and, instead of being drawn in black and white, are always drawn using the colors specified in the CGrafPort structure’s rgbFgColor and rgbBkColor fields, respectively.

In a full-color pixel pattern, the patType field contains the value 1, and the pattern’s dimensions, depth, resolution, set of colors, and other characteristics are defined by a PixMap structure, referenced by the handle in the patMap field of the PixPat structure. Full-color pixel patterns contain color tables that describe the colors they use. Generally such a color table contains one entry for each color used in the pattern. For instance, if your pattern has five colors, you would probably create a 4 bits per pixel pattern that uses pixel values 0–4, and a color table with five entries, numbered 0–4, that contain the RGB specifications for those pixel values.

However, if you don’t specify a color table for a pixel value, QuickDraw assigns a color to that pixel value. The largest unassigned pixel value becomes the foreground color the smallest unassigned pixel value is assigned the background color. Remaining unassigned pixel values are given colors that are evenly distributed between the foreground and background.

For instance, in the color table mentioned above, pixel values 5–15 are unused. Assume that the foreground color is black and the background color is white. Pixel value 15 is assigned the foreground color, black pixel value 5 is assigned the background color, white the nine pixel values between them are assigned evenly distributed shades of gray. If the PixMap structure’s color table is set to NULL, all pixel values are determined by blending the foreground and background colors.

Full-color pixel patterns are not limited to a fixed size: their height and width can be any power of 2, as specified by the height and width of the boundary rectangle for the PixMap structure specified in the patMap field. A pattern 8 bits wide, which is the size of a bit pattern, has a row width of just 1 byte, contrary to the usual rule that the rowBytes field must be even. Read this pattern type into memory using the GetPixPat function, and set it using the PenPixPat or BackPixPat functions.

The pixel map specified in the patMap field of the PixPat structure defines the pattern’s characteristics. The baseAddr field of the PixMap structure for that pixel map is ignored. For a full-color pixel pattern, the actual pixel image defining the pattern is stored in the handle in the patData field of the PixPat structure. The pattern’s pixel depth need not match that of the pixel map into which it’s transferred the depth is adjusted automatically when the pattern is drawn. QuickDraw maintains a private copy of the pattern’s pixel image, expanded to the current screen depth and aligned to the current graphics port, in the patXData field of the PixPat structure.

In an RGB pixel pattern, the patType field contains the value 2. Using the MakeRGBPat function, your application can specify the exact color it wants to use. QuickDraw selects a pattern to approximate that color. In this way, your application can effectively increase the color resolution of the screen. RGB pixel patterns are particularly useful for dithering: mixing existing colors together to create the illusion of a third color that’s unavailable on an indexed device. The MakeRGBPat function aids in this process by constructing a dithered pattern to approximate a given absolute color. An RGB pixel pattern can display 125 different patterns on a 4-bit screen, or 2197 different patterns on an 8-bit screen.

An RGB pixel pattern has an 8-by-8 pixel pattern that is 2 bits deep. For an RGB pixel pattern, the RGBColor structure that you specify to the MakeRGBPat function defines the image; there is no image data.

Your application should never need to directly change the fields of a PixPat structure. If you find it absolutely necessary for your application to so, immediately use the PixPatChanged function to notify QuickDraw that your application has changed the PixPat structure.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

Polygon

typedef MacPolygon Polygon;
Discussion

After you use the OpenPoly function to create a polygon, QuickDraw begins collecting the line-drawing information you provide into a MacPolygon structure. The OpenPoly function returns a handle to the newly allocated MacPolygon structure. Thereafter, your application normally refers to your new polygon by this handle, because QuickDraw functions such as FramePoly and PaintPoly expect a handle to a Polygon as their first parameter.

A polygon is defined by a sequence of connected lines. A MacPolygon structure consists of two fixed-length fields followed by a variable-length array of points: the starting point followed by each successive point to which a line is drawn.

Your application typically does not need to create a MacPolygon structure.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

PrinterFontStatus

struct PrinterFontStatus {
   SInt32 oResult;
   SInt16 iFondID;
   Style iStyle;
};
typedef struct PrinterFontStatus PrinterFontStatus;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

PrinterScalingStatus

struct PrinterScalingStatus {
   Point oScalingFactors;
};
typedef struct PrinterScalingStatus PrinterScalingStatus;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

PrinterStatusOpcode

typedef SInt32 PrinterStatusOpcode;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDArcUPP

typedef QDArcProcPtr QDArcUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDBitsUPP

typedef QDBitsProcPtr QDBitsUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDByte

typedef SignedByte QDByte;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

QDCommentUPP

typedef QDCommentProcPtr QDCommentUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDErr

typedef short QDErr;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDGetPicUPP

typedef QDGetPicProcPtr QDGetPicUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDGlobals

struct QDGlobals {
   char privates[76];
   long randSeed;
   BitMap screenBits;
   Cursor arrow;
   Pattern dkGray;
   Pattern ltGray;
   Pattern gray;
   Pattern black;
   Pattern white;
   GrafPtr thePort;
};
typedef struct QDGlobals QDGlobals;
   typedef QDGlobals * QDGlobalsPtr;

QDJShieldCursorUPP

typedef QDJShieldCursorProcPtr QDJShieldCursorUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDLineUPP

typedef QDLineProcPtr QDLineUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDOpcodeUPP

typedef QDOpcodeProcPtr QDOpcodeUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDOvalUPP

typedef QDOvalProcPtr QDOvalUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDPictRef

Defines an opaque data type that represents a QuickDraw picture in the Quartz 2D graphics environment.

typedef struct QDPict * QDPictRef;
Discussion

This opaque type is used to draw QuickDraw picture data in a Quartz context. (Quartz 2D defines an analogous opaque type called CGPDFDocumentRef which is used to draw PDF data in a Quartz context.) An instance of the QDPictRef type is called a QDPict picture. There are two ways to create a QDPict picture:

  • You can call QDPictCreateWithProvider, passing in a Quartz data provider for the picture data. Typically the source of this data is a 'PICT' resource.

  • You can call QDPictCreateWithURL, passing in a Core Foundation URL that specifies a file with picture data in the data fork.

Both functions verify that picture header information is present, starting at either byte 1 or byte 513 of the picture data.

To draw a QDPict picture in a Quartz context, you call QDPictDrawToCGContext. To get the bounds or native resolution of a QDPict picture, you call QDPictGetBounds or QDPictGetResolution.

When you draw a QDPict picture in a PDF context, you can save the drawing in a PDF file. This is the recommended way to convert QuickDraw pictures into single-page PDF documents.

These additional sources of information may be helpful:

  • The sample Carbon program CGDrawPicture shows how to use this opaque type to draw QuickDraw pictures in a Quartz context.

  • For general information about QuickDraw pictures and the PICT graphics format, see Chapter 7 in Inside Macintosh: Imaging With QuickDraw.

Availability
  • Available in OS X v10.1 through OS X v10.6.
Declared In
QDPictToCGContext.h

QDPolyUPP

typedef QDPolyProcPtr QDPolyUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDPrinterStatusUPP

typedef QDPrinterStatusProcPtr QDPrinterStatusUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDProcs

struct QDProcs {
   QDTextUPP textProc;
   QDLineUPP lineProc;
   QDRectUPP rectProc;
   QDRRectUPP rRectProc;
   QDOvalUPP ovalProc;
   QDArcUPP arcProc;
   QDPolyUPP polyProc;
   QDRgnUPP rgnProc;
   QDBitsUPP bitsProc;
   QDCommentUPP commentProc;
   QDTxMeasUPP txMeasProc;
   QDGetPicUPP getPicProc;
   QDPutPicUPP putPicProc;
};
typedef struct QDProcs QDProcs;
   typedef QDProcs * QDProcsPtr;
Fields
textProc

A pointer to the low-level function that draws text. The standard QuickDraw function is the StdText function.

lineProc

A pointer to the low-level function that draws lines. The standard QuickDraw function is the StdLine function.

rectProc

A pointer to the low-level function that draws rectangles. The standard QuickDraw function is the StdRect function.

rRectProc

A pointer to the low-level function that draws rounded rectangles. The standard QuickDraw function is the StdRRect function.

ovalProc

A pointer to the low-level function that draws ovals. The standard QuickDraw function is the StdOval function.

arcProc

A pointer to the low-level function that draws arcs. The standard QuickDraw function is the StdArc function.

polyProc

A pointer to the low-level function that draws polygons. The standard QuickDraw function is the StdPoly function.

rgnProc

A pointer to the low-level function that draws regions. The standard QuickDraw function is the StdRgn function.

bitsProc

A pointer to the low-level function that copies bitmaps. The standard QuickDraw function is the StdBits function.

commentProc

A pointer to the low-level function for processing a picture comment. The standard QuickDraw function is the StdComment function.

txMeasProc

A pointer to the low-level function for measuring text width. The standard QuickDraw function is the StdTxMeas function.

getPicProc

A pointer to the low-level function for retrieving information from the definition of a picture. The standard QuickDraw function is the StdGetPic function.

putPicProc

A pointer to the low-level function for saving information as the definition of a picture. The standard QuickDraw function is the StdPutPic function.

Discussion

You need to use the QDProcs structure only if you customize one or more of QuickDraw’s low-level drawing functions. Use SetStdProcs to create a QDProcs structure.

The QDProcs structure contains pointers to low-level drawing functions. You can change the fields of this structure to point to functions of your own devising.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

QDPutPicUPP

typedef QDPutPicProcPtr QDPutPicUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDRectUPP

typedef QDRectProcPtr QDRectUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDRegionBitsRef

typedef struct OpaqueQDRegionBitsRef * QDRegionBitsRef;
Availability
  • Available in OS X v10.1 through OS X v10.6.
Declared In
QuickdrawAPI.h

QDRegionParseDirection

typedef SInt32 QDRegionParseDirection;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDRgnUPP

typedef QDRgnProcPtr QDRgnUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDRRectUPP

typedef QDRRectProcPtr QDRRectUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDStdGlyphsUPP

typedef QDStdGlyphsProcPtr QDStdGlyphsUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDTextUPP

typedef QDTextProcPtr QDTextUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

QDTxMeasUPP

typedef QDTxMeasProcPtr QDTxMeasUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

RegionToRectsUPP

typedef RegionToRectsProcPtr RegionToRectsUPP;
Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

ReqListRec

struct ReqListRec {
   short reqLSize;
   short reqLData[1];
};
typedef struct ReqListRec ReqListRec;
Fields
reqLSize

The size of this ReqListRec data structure minus one.

reqLData

An array of integers representing offsets into a color table.

Discussion

The ReqListRec data structure is a parameter to the SaveEntries function by which you can describe color table entries to be saved.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

RGBColor

struct RGBColor {
   unsigned short red;
   unsigned short green;
   unsigned short blue;
};
typedef struct RGBColor RGBColor;
   typedef RGBColor * RGBColorPtr;
Fields
red

An unsigned integer specifying the red value of the color.

green

An unsigned integer specifying the green value of the color.

blue

An unsigned integer specifying the blue value of the color.

Discussion

You usually specify a color to QuickDraw by creating an RGBColor structure in which you assign the red, green, and blue values of the foreground color. For example, when you want to set the foreground color for drawing, you create an RGBColor structure that defines the foreground color you desire; then you pass that structure as a parameter to the RGBForeColor function.

In an RGBColor structure, three 16-bit unsigned integers give the intensity values for the three additive primary colors.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

RgnHandle

An opaque type that represents a QuickDraw region.

typedef struct OpaqueRgnHandle * RgnHandle;
Discussion

A region is an arbitrary area or set of areas on the QuickDraw coordinate plane. The outline of a region should be one or more closed loops.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

SProcRec

struct SProcRec {
   Handle nxtSrch;
   ColorSearchUPP srchProc;
};
typedef struct SProcRec SProcRec;
   typedef SProcRec * SProcPtr;
Fields
nxtSrch

A handle to the next SProcRec data structure in the chain of search functions.

srchProc

A pointer to a custom search function (described in ColorSearchProcPtr).

Discussion

The SProcRec data structure contains a pointer to a custom search function and a handle to the next SProcRec data structure in the function list.

Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

WindowPtr

An opaque type that represents a window.

typedef struct OpaqueWindowPtr * WindowPtr;
Discussion

This is a Window Manager data type, defined in QuickDraw for historical reasons. Its role in Mac OS X is to serve as the basis for the widely used WindowRef data type.

Availability
  • Available in OS X v10.0 and later.
Declared In
Quickdraw.h

xColorSpec

struct xColorSpec {
   short value;
   RGBColor rgb;
   short xalpha;
};
typedef struct xColorSpec xColorSpec;
   typedef xColorSpec * xColorSpecPtr;
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

xCSpecArray

typedef xColorSpec xCSpecArray[1];
Availability
  • Available in OS X v10.0 through OS X v10.6.
Declared In
QuickdrawTypes.h

Constants

chunky

enum {
   chunky = 0,
   chunkyPlanar = 1,
   planar = 2
};

Color Constants

enum {
   blackColor = 33,
   whiteColor = 30,
   redColor = 205,
   greenColor = 341,
   blueColor = 409,
   cyanColor = 273,
   magentaColor = 137,
   yellowColor = 69
};
Constants
blackColor

Represents black.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

whiteColor

Represents white.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

redColor

Represents red.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

greenColor

Represents green.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

blueColor

Represents blue.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

cyanColor

Represents cyan.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

magentaColor

Represents magenta.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

yellowColor

Represents yellow.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

Discussion

These constants are used in the color parameter of the ForeColor and BackColor functions to specify one of the eight basic QuickDraw colors.

colorXorXFer

enum {
   colorXorXFer = 52,
   noiseXFer = 53,
   customXFer = 54
};

Cursor ID Constants

enum {
   sysPatListID = 0,
   iBeamCursor = 1,
   crossCursor = 2,
   plusCursor = 3,
   watchCursor = 4
};
Constants
iBeamCursor

The I-beam cursor; to select text

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

crossCursor

The crosshairs cursor; to draw graphics

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

plusCursor

The plus sign cursor; to select cells

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

watchCursor

The wristwatch cursor; to indicate a short operation in progress

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

Discussion

When passing a value to the Show_Cursor function, use the Cursors data type to represent the kind of cursor to show.

cursorDoesAnimate

enum {
   cursorDoesAnimate = 1L << 0,
   cursorDoesHardware = 1L << 1,
   cursorDoesUnreadableScreenBits = 1L << 2
};

Device Attribute Constants

enum {
   interlacedDevice = 2,
   hwMirroredDevice = 4,
   roundedDevice = 5,
   hasAuxMenuBar = 6,
   burstDevice = 7,
   ext32Device = 8,
   ramInit = 10,
   mainScreen = 11,
   allInit = 12,
   screenDevice = 13,
   noDriver = 14,
   screenActive = 15,
   hiliteBit = 7,
   pHiliteBit = 0,
   defQDColors = 127,
   RGBDirect = 16,
   baseAddr32 = 4
};
Constants
burstDevice

If this bit is set to 1, the graphics device supports block transfer.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

ext32Device

If this bit is set to 1, the graphics device must be used in 32-bit mode.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

ramInit

If this bit is set to 1, the graphics device has been initialized from RAM.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

mainScreen

If this bit is set to 1,the graphics device is the main screen.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

allInit

If this bit is set to 1, all graphics devices were initialized from the 'scrn' resource.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

screenDevice

If this bit is set to 1, the graphics device is a screen.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

noDriver

If this bit is set to 1, the GDevice structure has no driver.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

screenActive

If this bit is set to 1, the graphics device is active.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

Discussion

These constants are used in the attribute parameters of the SetDeviceAttribute and TestDeviceAttribute functions, and in the deviceFlags parameter of the DeviceLoopDrawingProcPtr callback. These constants represent the GDevice structure’s attributes, as bits in the gdFlags field.

Device Loop Flags

enum {
   singleDevices = 1 << singleDevicesBit,
   dontMatchSeeds = 1 << dontMatchSeedsBit,
   allDevices = 1 << allDevicesBit
};
Constants
singleDevices

If this flag is not set, DeviceLoop calls your drawing function only once for each set of similar graphics devices, and the first one found is passed as the target device. (It is assumed to be representative of all the similar graphics devices.) If you set the singleDevices flag, then DeviceLoop does not group similar graphics devices, (that is, those having identical pixel depths, black-and-white or color settings, and matching color table seeds), when it calls your drawing function.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

dontMatchSeeds

If you set the dontMatchSeeds flag, then DeviceLoop does not consider the ctSeed field of ColorTable structures for graphics devices when comparing them; DeviceLoop ignores this flag if you set the singleDevices flag.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

allDevices

If you set the allDevices flag, DeviceLoop ignores the drawingRgn parameter and calls your drawing function for every device. The value of the current graphics port’s visRgn field is not affected when you set this flag.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

Discussion

When you use the DeviceLoop function, you can change its default behavior by using the flags parameter to specify one or more members of the set of flags defined by the DeviceLoopFlags data type. If you want to use the default behavior of DeviceLoop, specify 0 in the flags parameter.

deviceIsIndirect

enum {
   deviceIsIndirect = (1L << 0),
   deviceNeedsLock = (1L << 1),
   deviceIsStatic = (1L << 2),
   deviceIsExternalBuffer = (1L << 3),
   deviceIsDDSurface = (1L << 4),
   deviceIsDCISurface = (1L << 5),
   deviceIsGDISurface = (1L << 6),
   deviceIsAScreen = (1L << 7),
   deviceIsOverlaySurface = (1L << 8)
};

Drag Constraint Constants

When passed to the DragControl function, specify how a user can move a control.

enum {
   kNoConstraint = 0,
   kVerticalConstraint = 1,
   kHorizontalConstraint = 2
};
Constants
kNoConstraint

No constraint.

Available in OS X v10.0 and later.

Declared in Quickdraw.h.

kVerticalConstraint

Constrain movement to horizontal axis only.

Available in OS X v10.0 and later.

Declared in Quickdraw.h.

kHorizontalConstraint

Constrain movement to vertical axis only.

Available in OS X v10.0 and later.

Declared in Quickdraw.h.

Graphics Device Type Constants

enum {
   picLParen = 0,
   picRParen = 1,
   clutType = 0,
   fixedType = 1,
   directType = 2,
   gdDevType = 0
};
Constants
clutType

Represents a CLUT device--that is, one with colors mapped with a color lookup table.

Available in OS X v10.0 and later.

Declared in IONDRVLibraries.h.

fixedType

Represents a fixed colors device --that is, the color lookup table can't be changed.

Available in OS X v10.0 and later.

Declared in IONDRVLibraries.h.

directType

Represents a device with direct RGB colors.

Available in OS X v10.0 and later.

Declared in IONDRVLibraries.h.

gdDevType

If this bit is set to 0, the graphics device is black and white; if it is set to 1, the graphics device supports color.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

Discussion

These constants represent the general type of graphics device for the gdType field of the GDevice structure.

Graphics World Flags

Specify additional information passed to and from NewGWorld and related functions in parameters of type GWorldFlags.

enum {
   pixPurge = 1L << pixPurgeBit,
   noNewDevice = 1L << noNewDeviceBit,
   useTempMem = 1L << useTempMemBit,
   keepLocal = 1L << keepLocalBit,
   useDistantHdwrMem = 1L << useDistantHdwrMemBit,
   useLocalHdwrMem = 1L << useLocalHdwrMemBit,
   pixelsPurgeable = 1L << pixelsPurgeableBit,
   pixelsLocked = 1L << pixelsLockedBit,
   kNativeEndianPixMap = 1L << nativeEndianPixMapBit,
   kAllocDirectDrawSurface = 1L << 14,
   mapPix = 1L << mapPixBit,
   newDepth = 1L << newDepthBit,
   alignPix = 1L << alignPixBit,
   newRowBytes = 1L << newRowBytesBit,
   reallocPix = 1L << reallocPixBit,
   clipPix = 1L << clipPixBit,
   stretchPix = 1L << stretchPixBit,
   ditherPix = 1L << ditherPixBit,
   gwFlagErr = 1L << gwFlagErrBit
};
Constants
pixPurge

If you specify this flag for the flags parameter of the NewGWorld function, UpdateGWorld makes the base address for the offscreen pixel image purgeable.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

noNewDevice

If you specify this flag for the flags parameter of the UpdateGWorld function, NewGWorld does not create a new offscreen GDevice structure; instead, NewGWorld uses either the GDevice structure you specify or the GDevice structure for a video card on the user’s system.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

useTempMem

If you specify this in the flags parameter of the UpdateGWorld function, NewGWorld creates the base address for an offscreen pixel image in temporary memory. You generally should not use this flag. You should use temporary memory only for fleeting purposes and only with the GetPixelsState function so that other applications can launch.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

keepLocal

If you specify this in the flags parameter of the UpdateGWorld function, NewGWorld creates a pixel image in Macintosh main memory where it cannot be cached to a graphics accelerator card.

If you specify this in the flags parameter of GetPixelsState, UpdateGWorld keeps the offscreen pixel image in Macintosh main memory.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

pixelsPurgeable

If you specify this in the state parameter of the UpdateGWorld function, SetPixelsState makes the base address for an offscreen pixel map purgeable. If you use the SetPixelsState function without passing it this flag, then SetPixelsState makes the base address for an offscreen pixel map unpurgeable. If the GetPixelsState function returns this flag, then the base address for an offscreen pixel is purgeable.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

pixelsLocked

If you specify this flag for the state parameter of the SetPixelsState function, SetPixelsState locks the base address for an offscreen pixel image. If you use the SetPixelsState function without passing it this flag, then SetPixelsState unlocks the offscreen pixel image. If the GetPixelsState function returns this flag, then the base address for an offscreen pixel is locked.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

kNativeEndianPixMap

By default, the function NewGWorld allocates pixel buffers with big-endian byte ordering regardless of the system architecture. If this flag is passed in the flags parameter of NewGWorld, the pixel format will be set to k32ARGBPixelFormat or k16BE555PixelFormat on a PowerPC system, and to k32BGRAPixelFormat or k16LE555PixelFormat on an Intel system, for depths 32 or 16, respectively. Note that NewGWorld is the only function where this flag is observed; NewGWorldFromPtr and UpdateGWorld ignore it.

Available in OS X v10.3 through OS X v10.6.

Declared in QDOffscreen.h.

mapPix

If the UpdateGWorld function returns this flag, then it remapped the colors in the offscreen pixel map to a new color table.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

newDepth

If the UpdateGWorld function returns this flag, then it translated the offscreen pixel map to a different pixel depth.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

alignPix

If the UpdateGWorld function returns this flag, then it realigned the offscreen pixel image to an onscreen window.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

newRowBytes

If the UpdateGWorld function returns this flag, then it changed the rowBytes field of the PixMap structure for the offscreen graphics world.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

reallocPix

If the UpdateGWorld function returns this flag, then it reallocated the base address for the offscreen pixel image. Your application should then reconstruct the pixel image or draw directly in a window instead of preparing the image in an offscreen graphics world.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

clipPix

If you specify this flag in the flags parameter of the UpdateGWorld function, then UpdateGWorld updates and clips the pixel image to the new boundary rectangle specified. If the UpdateGWorld function returns this flag, then it clipped the pixel image.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

stretchPix

If you specify this flag in the flags parameter of the UpdateGWorld function, then UpdateGWorld updates and stretches or shrinks the pixel image to the new boundary rectangle specified. If the UpdateGWorld function returns this flag, then it stretched or shrank the offscreen image.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

ditherPix

If you specify this flag in the flags parameter of the UpdateGWorld function, then UpdateGWorld dithers the pixel image to the new boundary rectangle specified. Include this flag with the clipPix or stretchPix flag. If the UpdateGWorld function returns this flag, then it dithered the offscreen image.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

gwFlagErr

If the UpdateGWorld function returns this flag, then it was unsuccessful and the offscreen graphics world was left unchanged.

Available in OS X v10.0 through OS X v10.6.

Declared in QDOffscreen.h.

invalColReq

enum {
   invalColReq = -1
};

italicBit

enum {
   italicBit = 1,
   ulineBit = 2,
   outlineBit = 3,
   shadowBit = 4,
   condenseBit = 5,
   extendBit = 6
};

Pixel Formats

enum {
   k16LE555PixelFormat = 'L555',
   k16LE5551PixelFormat = '5551',
   k16BE565PixelFormat = 'B565',
   k16LE565PixelFormat = 'L565',
   k24BGRPixelFormat = '24BG',
   k32BGRAPixelFormat = 'BGRA',
   k32ABGRPixelFormat = 'ABGR',
   k32RGBAPixelFormat = 'RGBA',
   kYUVSPixelFormat = 'yuvs',
   kYUVUPixelFormat = 'yuvu',
   kYVU9PixelFormat = 'YVU9',
   kYUV411PixelFormat = 'Y411',
   kYVYU422PixelFormat = 'YVYU',
   kUYVY422PixelFormat = 'UYVY',
   kYUV211PixelFormat = 'Y211',
   k2vuyPixelFormat = '2vuy'
};

k1MonochromePixelFormat

enum {
   k1MonochromePixelFormat = 0x00000001,
   k2IndexedPixelFormat = 0x00000002,
   k4IndexedPixelFormat = 0x00000004,
   k8IndexedPixelFormat = 0x00000008,
   k16BE555PixelFormat = 0x00000010,
   k24RGBPixelFormat = 0x00000018,
   k32ARGBPixelFormat = 0x00000020,
   k1IndexedGrayPixelFormat = 0x00000021,
   k2IndexedGrayPixelFormat = 0x00000022,
   k4IndexedGrayPixelFormat = 0x00000024,
   k8IndexedGrayPixelFormat = 0x00000028
};

kCursorComponentInit

enum {
   kCursorComponentInit = 0x0001,
   kCursorComponentGetInfo = 0x0002,
   kCursorComponentSetOutputMode = 0x0003,
   kCursorComponentSetData = 0x0004,
   kCursorComponentReconfigure = 0x0005,
   kCursorComponentDraw = 0x0006,
   kCursorComponentErase = 0x0007,
   kCursorComponentMove = 0x0008,
   kCursorComponentAnimate = 0x0009,
   kCursorComponentLastReserved = 0x0050
};

kCursorComponentsVersion

enum {
   kCursorComponentsVersion = 0x00010001
};

kCursorComponentType

enum {
   kCursorComponentType = 'curs'
};

kCursorImageMajorVersion

enum {
   kCursorImageMajorVersion = 0x0001,
   kCursorImageMinorVersion = 0x0000
};

kPrinterFontStatus

enum {
   kPrinterFontStatus = 0,
   kPrinterScalingStatus = 1
};

kQDGrafVerbFrame

enum {
   kQDGrafVerbFrame = 0,
   kQDGrafVerbPaint = 1,
   kQDGrafVerbErase = 2,
   kQDGrafVerbInvert = 3,
   kQDGrafVerbFill = 4
};

kQDParseRegionFromTop

enum {
   kQDParseRegionFromTop = (1 << 0),
   kQDParseRegionFromBottom = (1 << 1),
   kQDParseRegionFromLeft = (1 << 2),
   kQDParseRegionFromRight = (1 << 3),
   kQDParseRegionFromTopLeft = kQDParseRegionFromTop | kQDParseRegionFromLeft,
   kQDParseRegionFromBottomRight = kQDParseRegionFromBottom |  kQDParseRegionFromRight
};

kQDRegionToRectsMsgInit

enum {
   kQDRegionToRectsMsgInit = 1,
   kQDRegionToRectsMsgParse = 2,
   kQDRegionToRectsMsgTerminate = 3
};

kQDUseDefaultTextRendering

enum {
   kQDUseDefaultTextRendering = 0,
   kQDUseTrueTypeScalerGlyphs = (1 << 0),
   kQDUseCGTextRendering = (1 << 1),
   kQDUseCGTextMetrics = (1 << 2),
   kQDSupportedFlags = kQDUseTrueTypeScalerGlyphs | kQDUseCGTextRendering  |  kQDUseCGTextMetrics,
   kQDDontChangeFlags = 0xFFFFFFFF
};

kRenderCursorInHardware

enum {
   kRenderCursorInHardware = 1L << 0,
   kRenderCursorInSoftware = 1L << 1
};

kXFer1PixelAtATime

enum {
   kXFer1PixelAtATime = 0x00000001,
   kXFerConvertPixelToRGB32 = 0x00000002
};

normalBit

enum {
   normalBit = 0,
   inverseBit = 1,
   redBit = 4,
   greenBit = 3,
   blueBit = 2,
   cyanBit = 8,
   magentaBit = 7,
   yellowBit = 6,
   blackBit = 5
};

pixPurgeBit

enum {
   pixPurgeBit = 0,
   noNewDeviceBit = 1,
   useTempMemBit = 2,
   keepLocalBit = 3,
   useDistantHdwrMemBit = 4,
   useLocalHdwrMemBit = 5,
   pixelsPurgeableBit = 6,
   pixelsLockedBit = 7,
   nativeEndianPixMapBit = 8,
   mapPixBit = 16,
   newDepthBit = 17,
   alignPixBit = 18,
   newRowBytesBit = 19,
   reallocPixBit = 20,
   clipPixBit = 28,
   stretchPixBit = 29,
   ditherPixBit = 30,
   gwFlagErrBit = 31
};

singleDevicesBit

enum {
   singleDevicesBit = 0,
   dontMatchSeedsBit = 1,
   allDevicesBit = 2
};

Source, Pattern, and Arithmetic Transfer Mode Constants

enum {
   srcCopy = 0,
   srcOr = 1,
   srcXor = 2,
   srcBic = 3,
   notSrcCopy = 4,
   notSrcOr = 5,
   notSrcXor = 6,
   notSrcBic = 7,
   patCopy = 8,
   patOr = 9,
   patXor = 10,
   patBic = 11,
   notPatCopy = 12,
   notPatOr = 13,
   notPatXor = 14,
   notPatBic = 15,
   grayishTextOr = 49,
   hilitetransfermode = 50,
   hilite = 50,
   blend = 32,
   addPin = 33,
   addOver = 34,
   subPin = 35,
   addMax = 37,
   adMax = 37,
   subOver = 38,
   adMin = 39,
   ditherCopy = 64,
   transparent = 36
};
Constants
srcCopy

For basic graphics ports, force the destination pixel black where the source pixel is black; where the source pixel is white, force the destination pixel white.

For color graphics ports, determines how close the color of the source pixel is to black, and assigns this relative amount of foreground color to the destination pixel. Determines how close the color of the source pixel is to white, and assigns this relative amount of background color to the destination pixel.

Available in OS X v10.0 and later.

Declared in Quickdraw.h.

srcOr

For basic graphics ports, forces the destination pixel black if the source pixel is black; where the source pixel is white, leaves the destination pixel unaltered.

For color graphics ports, determines how close the color of the source pixel is to black, and assigns this relative amount of foreground color to the destination pixel.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

srcXor

For basic and color graphics ports, inverts destination pixel where the source pixel is black. For a basic graphics port, where the source pixel is white, leaves the destination pixel unaltered.

For a color graphics port, for a colored destination pixel, uses the complement of its color if the pixel is direct, or inverts its index if the pixel is indexed.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

srcBic

For a basic graphics port, forces destination pixel white where source pixel is black; where source pixel is white, leaves the destination pixel unaltered.

For a color graphics port, determines how close the color of the source pixel is to black, and assigns this relative amount of background color to the destination pixel.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

notSrcCopy

For a basic graphics port, forces the destination pixel white where the source pixel is black; where the source pixel is white, forces the destination pixel black.

For a color graphics port, determines how close the color of the source pixel is to black, and assigns this relative amount of background color to the destination pixel. Determines how close the color of the source pixel is to white, and assigns this relative amount of foreground color to the destination pixel.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

notSrcOr

For a basic graphics port, leaves the destination pixel unaltered where the source pixel is black; where the source pixel is white, forces the destination pixel black.

For a color graphics port, determines how close the color of the source pixel is to white, and assigns this relative amount of foreground color to the destination pixel.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

notSrcXor

For basic and color graphics ports, where the source pixel is white, inverts the destination pixel. For a basic graphics port, where the source pixel is black, leaves the destination pixel unaltered.

For a color graphics port, for a colored destination pixel, uses the complement of its color if the pixel is direct, or inverts its index if the pixel is indexed.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

notSrcBic

For a basic graphics port, where the source pixel is black, leaves the destination pixel unaltered; where the source pixel is white, forces the destination pixel white.

For a color graphics port, determines how close the color of the source pixel is to white, and assigns this relative amount of background color to the destination pixel.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

patCopy

Where the pattern pixel is black, applies foreground color to the destination pixel; where the pattern pixel is white, applies background color to the destination pixel.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

patOr

Where the pattern pixel is black, inverts the destination pixel; where the pattern pixel is white, leaves the destination pixel unaltered.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

patXor

Where the pattern pixel is black, inverts the destination pixel; where the pattern pixel is white, leaves the destination pixel unaltered.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

patBic

Where the pattern pixel is black, applies the background color to destination pixel; where the pattern pixel is white, leaves the destination pixel unaltered.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

notPatCopy

Where the pattern pixel is black, applies background color to destination pixel; where the pattern pixel is white, applies foreground color to the destination pixel

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

notPatOr

Where the pattern pixel is black, leaves the destination pixel unaltered; where the pattern pixel is white, applies foreground color to the destination pixel

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

notPatXor

Where the pattern pixel is black, leaves the destination pixel unaltered; where the pattern pixel is white, inverts the destination pixel

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

notPatBic

Where the pattern pixel is black, leaves the destination pixel unaltered; where the pattern pixel is white, applies background color to the destination pixel.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

grayishTextOr

Draws dimmed text on the screen. You can use it for black-and-white or color graphics ports. The grayishTextOr transfer mode is not considered a standard transfer mode because currently it is not stored in pictures, and printing with it is undefined. (It does not pass through the QuickDraw bottleneck functions.)

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

hilite

Adds highlighting to the source or pattern mode. With highlighting, QuickDraw replaces the background color with the highlight color when your application copies images between graphics ports. This has the visual effect of using a highlighting pen to select the object. (The global variable HiliteRGB is read from parameter RAM when the machine starts. Basic graphics ports use the color stored in the HiliteRGB global variable as the highlight color. Color graphics ports default to the HiliteRGB global variable, but can be overridden by the HiliteColor function.)

For text, specifies that the caret position should be determined according to the primary line direction, based on the value of SysDirection.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

blend

Replaces the destination pixel with a blend of the source and destination pixel colors. If the destination is a bitmap or 1-bit pixel map, reverts to srcCopy mode.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

addPin

Replaces the destination pixel with the sum of the source and destination pixel colors-- up to a maximum allowable values. If the destination is a bitmap or 1-bit pixel map, reverts to srcBic mode.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

addOver

Replaces the destination pixel with the sum of the source and destination pixel colors, except if the value of the red, green, or blue component exceeds 65,536, then addOver subtracts 65,536 from that value. If the destination is a bitmap or 1-bit pixel map, reverts to srcXor mode.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

subPin

Replaces the destination pixel with the difference of the source and destination pixel colors, but not less than a minimum allowable value. If the destination is a bitmap or 1-bit pixel map, reverts to srcOr mode.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

addMax

Compares the source and destination pixels, and replaces the destination pixel with the color containing the greater saturation of each of the RGB components. If the destination is a bitmap or 1-bit pixel map, reverts to srcBic mode.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

subOver

Replaces the destination pixel with the difference of the source and destination pixel colors, except if the value of the red, green, or blue component is less than 0, then it adds the negative result to 65,536. if the destination is a bitmap or 1-bit pixel map, revert to srcXor mode.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

adMin

Compares the source and destination pixels, and replaces the destination pixel with the color containing the lesser saturation of each of the RGB components. If the destination is a bitmap or 1-bit pixel map, reverts to srcOr mode.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

ditherCopy

On computers running System 7, you can add dithering to any source mode by adding this constant or the value it represents to the source mode.

Dithering is a technique that mixes existing colors to create the effect of additional colors. It also improves images that you shrink or that you copy from a direct pixel device to an indexed device.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

transparent

Replaces the destination pixel with the source pixel if the source pixel is not equal to the background color. The transparent mode replaces the destination pixel with the source pixel if the source pixel isn’t equal to the background color. This mode is most useful in 8-bit, 4-bit, or 2-bit color modes.

Available in OS X v10.0 through OS X v10.6.

Declared in QuickdrawTypes.h.

Discussion

CopyBits uses the source and arithmetic transfer mode constants in the mode parameter to specify the manner in which pixels are transferred from a source pixel map to a destination pixel map.

PenMode uses the pattern mode constants in the mode parameter to specify source modes for transferring the bits from a source bitmap to a destination bitmap.

The TextMode function uses these constants to set the transfer mode in the graphics port txMode field.

The transfer mode determines the interplay between what an application is drawing (the source) and what already exists on the display device (the destination), resulting in the text display.

There are two basic kinds of modes: pattern ( pat) and source ( src).

The pattern mode constants are patCopy, patOr, patXor, patBic, notPatCopy, notPatOr, notPatXor, and notPatBic.

Source is the kind that you use for drawing text. There are four basic Boolean operations: Copy, Or, Xor, and Bic (bit clear), each of which has an inverse variant in which the source is inverted before the transfer, yielding eight operations in all. Basic QuickDraw supports these eight transfer modes. Color QuickDraw interprets the source mode constants differently than basic QuickDraw does. Color QuickDraw enables your application to achieve color effects within those basic transfer modes, and offers an additional set of transfer modes that perform arithmetic operations on the RGB values of the source and destination pixels. Other transfer modes are grayishTextOr, transparent mode, and text mask mode.

The arithmetic transfer modes are addOver, addPin, subOver, subPin, addMax, adMax, adMin, and blend. For color, the arithmetic modes change the destination pixels by performing arithmetic operations on the source and destination pixels. Arithmetic transfer modes calculate pixel values by adding, subtracting, or averaging the RGB components of the source and destination pixels. They are most useful for 8-bit color, but they work on 4-bit and 2-bit color also. When the destination bitmap is one bit deep, the mode reverts to the basic transfer mode that best approximates the arithmetic mode requested.

Verb Constants

enum {
   frame = kQDGrafVerbFrame,
   paint = kQDGrafVerbPaint,
   erase = kQDGrafVerbErase,
   invert = kQDGrafVerbInvert,
   fill = kQDGrafVerbFill
};
Constants
frame

Specifies the frame action.

paint

Specifies the paint action.

erase

Specifies the erase action.

invert

Specifies the invert action.

fill

Specifies the fill action.

Discussion

When you use the StdRect , StdRRect , StdOval , StdArc , StdPoly , or StdRgn functions, these constants are used in the verb parameter to specify the type of action taken by those low-level drawing functions.

Result Codes

The table below lists the result codes specific to QuickDraw.

Result CodeValueDescription
updPixMemErr -125

Insufficient memory to update a pixmap.

Available in OS X v10.0 and later.

noMemForPictPlaybackErr -145

Insufficient memory for drawing the picture.

Available in OS X v10.0 and later.

pixMapTooDeepErr -148

Pixel map is deeper than 1 bit per pixel.

Available in OS X v10.0 and later.

nsStackErr -149

Insufficient stack

Available in OS X v10.0 and later.

cMatchErr -150

Color2Index failed to find an index.

Available in OS X v10.0 and later.

cTempMemErr -151

Failed to allocate memory for temporary structures.

Available in OS X v10.0 and later.

cNoMemErr -152

Failed to allocate memory for structures.

Available in OS X v10.0 and later.

cRangeErr -153

Range error on color table requests.

Available in OS X v10.0 and later.

cProtectErr -154

ColorTable structure entry protection violation.

Available in OS X v10.0 and later.

cDevErr -155

Invalid type of graphics device.

Available in OS X v10.0 and later.

cResErr -156

Invalid resolution for MakeITable.

Available in OS X v10.0 and later.

cDepthErr -157

Invalid pixel depth.

Available in OS X v10.0 and later.

rgnTooBigErr -500

Bitmap too large to convert to a region.

Available in OS X v10.0 and later.

kQDNoPalette -3950

Available in OS X v10.2 and later.

kQDNoColorHWCursorSupport -3951

Available in OS X v10.2 and later.

kQDCursorAlreadyRegistered -3952

Available in OS X v10.2 and later.

kQDCursorNotRegistered -3953

Available in OS X v10.2 and later.

kQDCorruptPICTDataErr -3954

Available in OS X v10.2 and later.