Next Page >

Hide TOC

QuickDraw Reference

Framework	ApplicationServices/ApplicationServices.h
Companion guide	Quartz Programming Guide for QuickDraw Developers
Declared in	IOMacOSTypes.h ImageCompression.k.h QDOffscreen.h QDPictToCGContext.h QuickTimeComponents.k.h Quickdraw.h QuickdrawAPI.h QuickdrawTypes.h X.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.

Note: QuickDraw has been deprecated for deployment targets Mac OS X version 10.4 and later. The replacement API is Quartz 2D. Because of the fundamental differences in the imaging models and design goals between QuickDraw and Quartz, there is no direct correspondence between QuickDraw and Quartz concepts and interfaces. For certain purposes, some QuickDraw functions may still be needed during a transition period; nevertheless, most of them have been deprecated to express the overriding goal of eliminating the use of QuickDraw in the future.

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

AddPt

Adds the coordinates of two points.

void AddPt (
   Point src,
   Point *dst
);

Parameters

src: A point, the coordinates of which are to be added to the point in the dstPt parameter.
dst: A pointer to a point, the coordinates of which are to be added to the point in the srcPt parameter. On return, this value contains the result of adding the coordinates of the points you supplied in the srcPt and dstPt parameters.

Discussion

The AddPt function adds the coordinates of the point specified in the srcPt parameter to the coordinates of the point specified in the dstPt parameter, and returns the result in the dstPt parameter.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

CarbonSketch

Declared In

QuickdrawAPI.h

AngleFromSlope

Converts a slope value to an angle value.

short AngleFromSlope (
   Fixed slope
);

Parameters

slope: The slope, defined as Dx/Dy, which is the horizontal change divided by the vertical change between any two points on a line with the slope.

Return Value

The angle corresponding to the slope specified in the slope parameter treated MOD 180. Angles are defined in clockwise degrees from 12 o’clock. The negative y-axis is defined as being at 12 o’clock, and the positive y-axis at 6 o’clock. The x-axis is defined as usual, with the positive side defined as being at 3 o’clock.

Special Considerations

The AngleFromSlope function is most useful when you require speed more than accuracy in performing the calculation. The integer result is within 1 degree of the correct answer, but not necessarily within half a degree.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

CopyRgn

Makes a copy of a region.

void CopyRgn (
   RgnHandle srcRgn,
   RgnHandle dstRgn
);

Parameters

srcRgn: A handle to the region to copy.
dstRgn: A handle to the region to receive the copy.

Discussion

The CopyRgn function copies the mathematical structure of the region whose handle you pass in the srcRgn parameter into the region whose handle you pass in the dstRgn parameter; that is, CopyRgn makes a duplicate copy of srcRgn. When calling CopyRgn, pass handles that have been returned by the NewRgn function in the srcRgn and dstRgn parameters.

Once this is done, the region indicated by srcRgn may be altered (or even disposed of) without affecting the region indicated by dstRgn. The CopyRgn function does not create the destination region; space must already have been allocated for it by using the NewRgn function.

Special Considerations

The CopyRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

DiffRgn

Subtracts one region from another.

void DiffRgn (
   RgnHandle srcRgnA,
   RgnHandle srcRgnB,
   RgnHandle dstRgn
);

Parameters

srcRgnA

A handle to the region to subtract from.

srcRgnB

A handle to the region to subtract.

dstRgn

On return, a handle to the region holding the resulting area. If the first source region is empty, DiffRgn sets the destination to the empty region defined by the rectangle (0,0,0,0).

The DiffRgn function does not create the destination region; you must have already allocated memory for it by using the NewRgn function.

The destination region may be one of the source regions, if desired.

Discussion

The DiffRgn procedure subtracts the region whose handle you pass in the srcRgnB parameter from the region whose handle you pass in the srcRgnA parameter and places the difference in the region whose handle you pass in the dstRgn parameter. If the first source region is empty, DiffRgn sets the destination to the empty region defined by the rectangle (0,0,0,0).

The DiffRgn procedure does not create the destination region; you must have already allocated memory for it by using the NewRgn function. The destination region may be one of the source regions, if desired.

Special Considerations

The DiffRgn function may temporarily use heap space that’s twice the size of the two input regions.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

DisposeRgn

Releases the memory occupied by a region.

void DisposeRgn (
   RgnHandle rgn
);

Parameters

rgn: A handle to the region to dispose. This handle should be a region handle returned by the NewRgn function.

Discussion

Use DisposeRgn only after you are completely through with a region.

Special Considerations

The DisposeRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

QTCarbonShell

Declared In

QuickdrawAPI.h

EmptyRect

Determines whether a rectangle is an empty rectangle.

Boolean EmptyRect (
   const Rect *r
);

Parameters

r: The rectangle to examine.

Return Value

TRUE if the rectangle that you specify in the r parameter is an empty rectangle, FALSE if it is not. A rectangle is considered empty if the bottom coordinate is less than or equal to the top coordinate or if the right coordinate is less than or equal to the left.

Discussion

If the points or rectangles supplied to this function are defined in a graphics port other than your current graphics port, you must convert them to the local coordinate system of your current graphics port. You can accomplish this by using the SetPort function to change to the graphics port containing the points or rectangles, using the LocalGlobal function to convert their locations to global coordinates, using SetPort to return to your starting graphics port, and then using the GlobalToLocal function to convert the locations of points or rectangles to the local coordinates of your current graphics port.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

QuickdrawAPI.h

EmptyRgn

Determines whether a region is empty.

Boolean EmptyRgn (
   RgnHandle rgn
);

Parameters

rgn: A handle to the region to test for emptiness.

Return Value

TRUE if the region whose handle you pass in the rgn parameter is an empty region or FALSE if it is not.

Discussion

The EmptyRgn function does not create an empty region. To create an empty region, you can perform any of the following operations:

Use NewRgn.
Pass the handle to an empty region to CopyRgn.
Pass an empty rectangle to either SetRectRgn or RectRgn.
Call CloseRgn without a previous call to OpenRgn.
Call CloseRgn without performing any drawing after calling OpenRgn.
Pass an empty region to OffsetRgn.
Pass an empty region or too large an inset to InsetRgn
Pass two nonintersecting regions to SectRgn.
Pass two empty regions to UnionRgn.
Pass two identical or nonintersecting regions to DiffRgn or XorRgn.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

EqualPt

Determines whether the coordinates of two given points are equal.

Boolean EqualPt (
   Point pt1,
   Point pt2
);

Parameters

pt1: The first of two points to be compared.
pt2: The second of two points to be compared.

Return Value

TRUE if the coordinates of the two points are equal, or FALSE if they are not.

Discussion

The EqualPt function compares the points specified in the pt1 and pt2 parameters and returns TRUE if their coordinates are equal or FALSE if they are not.

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

EqualRect

Determines whether two rectangles are equal.

Boolean EqualRect (
   const Rect * rect1,
   const Rect * rect2
);

Parameters

rect1: The first of two rectangles to compare.
rect2: The second of two rectangles to compare.

Return Value

TRUE if the rectangles are equal, FALSE if they are not.

Discussion

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

EqualRgn

Determines whether two regions have identical sizes, shapes, and locations.

Boolean EqualRgn (
   RgnHandle rgnA,
   RgnHandle rgnB
);

Parameters

rgnA: A handle to the first of two regions to compare.
rgnB: A handle to the second of two regions to compare.

Return Value

TRUE if the two regions are equal; FALSE if they are not. The two regions must have identical sizes, shapes, and locations to be considered equal. Any two empty regions are always equal.

Discussion

The EqualRgn function compares the two regions whose handles you pass in the rgnA and rgnB parameters and returns TRUE if they’re equal or FALSE if they’re not.

The two regions must have identical sizes, shapes, and locations to be considered equal. Any two empty regions are always equal.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

GetClip

Saves the clipping region of the current graphics port (basic or color). (Deprecated. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)

void GetClip (
   RgnHandle rgn
);

Parameters

rgn: A handle to the region to be clipped. The GetClip function changes this region to one that’s equivalent to the clipping region of the current graphics port. The GetClip function doesn’t change the region handle.

Discussion

You can use the GetClip and SetClip functions to preserve the current clipping region: use GetClip to save the current port’s clipping region, and use SetClip to restore it. If, for example, you want to draw a half-circle on the screen, you can set the clipping region to half of the square that would enclose the whole circle, and then draw the whole circle. Only the half within the clipping region is actually drawn in the graphics port.

The GetClip function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.k.h

GetGWorld

Saves the current graphics port (basic, color, or offscreen) and the current GDevice structure. (Deprecated. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)

void GetGWorld (
   CGrafPtr *port,
   GDHandle *gdh
);

Parameters

port: On return, a pointer to the current graphics port in the port parameter. This parameter can return values of type GrafPtr, CGrafPtr, or GWorldPtr, depending on whether the current graphics port is a basic graphics port, color graphics port, or offscreen graphics world.
gdh: On return, a pointer to a handle to the GDevice structure for the current device.

Discussion

After using GetGWorld to save a graphics port and a GDevice structure, use the SetGWorld function to restore them.

Special Considerations

The GetGWorld function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

ImageCompression.k.h

GetPixBaseAddr

Obtains a pointer to an offscreen pixel map.

Ptr GetPixBaseAddr (
   PixMapHandle pm
);

Parameters

pm: A handle to an offscreen pixel map. To get a handle to an offscreen pixel map, use the GetGWorldPixMap function.

Return Value

A 32-bit pointer to the beginning of a pixel image. If the offscreen buffer has been purged, GetPixBaseAddr returns NULL.

Discussion

The baseAddr field of the PixMap structure for an offscreen graphics world contains a handle instead of a pointer, which is what the baseAddr field for an onscreen pixel map contains. 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; instead, always use GetPixBaseAddr. If your application is using 24-bit mode, use the PixMap32Bit function to determine whether a pixel map requires 32-bit addressing mode for access to its pixel image.

Special Considerations

Any QuickDraw functions that your application uses after calling GetPixBaseAddr may change the base address for the offscreen pixel image.

The GetPixBaseAddr function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

QDOffscreen.h

GetRegionBounds

Rect * GetRegionBounds (
   RgnHandle region,
   Rect *bounds
);

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

HandleToRgn

void HandleToRgn (
   Handle oldRegion,
   RgnHandle region
);

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

HideCursor

Hides the cursor if it is visible on the screen.

void HideCursor (
   void
);

Discussion

The HideCursor function removes the cursor from the screen, restores the bits under the cursor image, and decrements the cursor level (which InitCursor initialized to 0). You might want to use HideCursor when the user is using the keyboard to create content in one of your application’s windows. Every call to HideCursor should be balanced by a subsequent call to the ShowCursor function.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Simple DrawSprocket

Declared In

QuickdrawAPI.h

InitCursor

Sets the cursor to the standard arrow and makes the cursor visible.

void InitCursor (
   void
);

Discussion

This function initializes the standard arrow cursor, sets the current cursor to the standard arrow, and makes the cursor visible. Classic Mac OS applications need to call this function when launching because the system sets the cursor to the watch cursor. Carbon applications running in Mac OS 9 or Mac OS X do not need to call this function.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

QuickdrawAPI.h

InsetRect

Shrinks or expands a rectangle.

void InsetRect (
   Rect * r,
   short dh,
   short dv
);

Parameters

r: A pointer to the rectangle to alter.
dh: The horizontal distance to move the left and right sides in toward or outward from the center of the rectangle.
dv: The vertical distance to move the top and bottom sides in toward or outward from the center of the rectangle.

Discussion

The InsetRect function shrinks or expands the rectangle that you specify in the r parameter: the left and right sides are moved in by the amount you specify in the dh parameter; the top and bottom are moved toward the center by the amount you specify in the dv parameter. If the value you pass in dh or dv is negative, the appropriate pair of sides is moved outward instead of inward. The effect is to alter the size by 2*dh horizontally and 2*dv vertically, with the rectangle remaining centered in the same place on the coordinate plane.

If the resulting width or height becomes less than 1, the rectangle is set to the empty rectangle (0,0,0,0).

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

InsetRgn

Shrinks or expands a region.

void InsetRgn (
   RgnHandle rgn,
   short dh,
   short dv
);

Parameters

rgn: A handle to the region to alter.
dh: The horizontal distance to move points on the left and right boundaries in toward or outward from the center.
dv: The vertical distance to move points on the top and bottom boundaries in toward or outward from the center.

Discussion

The InsetRgn function moves all points on the region boundary of the region whose handle you pass in the rgn parameter inward by the vertical distance that you specify in the dv parameter and by the horizontal distance that you specify in the dh parameter. If you specify negative values for dh or dv, the InsetRgn function moves the points outward in that direction.

The InsetRgn function leaves the region’s center at the same position, but moves the outline in (for positive values of dh and dv) or out (for negative values of dh and dv). Using InsetRgn on a rectangular region has the same effect as using the InsetRect function.

Special Considerations

The InsetRgn function temporarily uses heap space that’s twice the size of the original region.

The InsetRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

IsRegionRectangular

Boolean IsRegionRectangular (
   RgnHandle region
);

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

IsValidRgnHandle

Boolean IsValidRgnHandle (
   RgnHandle rgn
);

Availability

Available in Mac OS X v10.4 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

MapPt

Maps a point in one rectangle to an equivalent position in another rectangle.

void MapPt (
   Point *pt,
   const Rect *srcRect,
   const Rect *dstRect
);

Parameters

pt: Upon input, a pointer to the point in the source rectangle to map; upon completion, a pointer to its mapped position in the destination rectangle.
srcRect: The source rectangle containing the original point.
dstRect: The destination rectangle in which the point will be mapped.

Discussion

The MapPt function maps a point in one rectangle to an equivalent position in another rectangle.

In the pt parameter, you specify a point that lies within the rectangle that you specify in the srcRect parameter. The MapPt function maps this point to a similarly located point within the rectangle that you specify in the dstRect parameter—that is, to where it would fall if it were part of a drawing being expanded or shrunk to fit the destination rectangle. The MapPt function returns the location of the mapped point in the pt parameter. For example, a corner point of the source rectangle would be mapped to the corresponding corner point of the destination rectangle in dstRect, and the center of the source rectangle would be mapped to the center of destination rectangle.

The source and destination rectangles may overlap, and the point you specify need not actually lie within the source rectangle.

If you are going to draw inside the destination rectangle, you’ll probably also want to scale the graphics pen size accordingly with ScalePt.

Special Considerations

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

MapRect

Maps and scales a rectangle within one rectangle to another rectangle.

void MapRect (
   Rect *r,
   const Rect *srcRect,
   const Rect *dstRect
);

Parameters

r: Upon input, a pointer to the rectangle to map; upon completion, the mapped rectangle.
srcRect: The rectangle containing the rectangle to map.
dstRect: The rectangle in which the new rectangle will be mapped.

Discussion

The MapRect function takes a rectangle within one rectangle and maps and scales it to another rectangle. In the r parameter, you specify a rectangle that lies within the rectangle that you specify in the srcRect parameter. By calling the MapPt function to map the upper-left and lower-right corners of the rectangle in the r parameter, MapRect maps and scales it to the rectangle that you specify in the dstRect parameter. The MapRect function returns the newly mapped rectangle in the r parameter.

Special Considerations

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

MapRgn

Maps and scales a region within one rectangle to another rectangle.

void MapRgn (
   RgnHandle rgn,
   const Rect *srcRect,
   const Rect *dstRect
);

Parameters

rgn: A handle to a region. Upon input, this is the region to map. Upon completion, this region is the one mapped to a new location.
srcRect: The rectangle containing the region to map.
dstRect: The rectangle in which the new region will be mapped.

Discussion

The MapRgn function takes a region within one rectangle and maps and scales it to another rectangle. In the rgn parameter, you specify a handle to a region that lies within the rectangle that you specify in the srcRect parameter. By calling the MapPt function to map all the points of the region in the rgn parameter, MapRgn maps and scales it to the rectangle that you specify in the dstRect parameter. The MapRgn function returns the result in the region whose handle you initially passed in the rgn parameter.

The MapRgn function is useful for determining whether a region operation will exceed available memory. By mapping a large region into a smaller one and performing the operation (without actually drawing), you can estimate how much memory will be required by the anticipated operation.

Special Considerations

The MapRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

NewGWorld

Creates an offscreen graphics world. (Deprecated. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)

QDErr NewGWorld (
   GWorldPtr *offscreenGWorld,
   short PixelDepth,
   const Rect *boundsRect,
   CTabHandle cTable,
   GDHandle aGDevice,
   GWorldFlags flags
);

Parameters

offscreenGWorld: On return, a pointer to the offscreen graphics world created by this function. You use this pointer when referring to this new offscreen world in other QuickDraw functions.
PixelDepth: The pixel depth of the offscreen world; possible depths are 1, 2, 4, 8, 16, and 32 bits per pixel. The default parameter (0) uses the pixel depth of the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If you specify 0 in this parameter, NewGWorld also uses the GDevice structure from this device instead of creating a new GDevice structure for the offscreen world. If you use NewGWorld on a computer that supports only basic QuickDraw, you may specify only 0 or 1 in this parameter.
boundsRect: The boundary rectangle and port rectangle for the offscreen pixel map. This becomes the boundary rectangle for the GDevice structure, if NewGWorld creates one. If you specify 0 in the pixelDepth parameter, NewGWorld interprets the boundaries in global coordinates that it uses to determine which screens intersect the rectangle. NewGWorld then uses the pixel depth, color table, and GDevice structure from the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect this rectangle. Typically, your application supplies this parameter with the port rectangle for the onscreen window into which your application will copy the pixel image from this offscreen world.
cTable: A handle to a ColorTable structure. If you pass NULL in this parameter, NewGWorld uses the default color table for the pixel depth that you specify in the pixelDepth parameter. If you set the pixelDepth parameter to 0, NewGWorld ignores the cTable parameter and instead copies and uses the color table of the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If you use NewGWorld on a computer that supports only basic QuickDraw, you may specify only NULL in this parameter.
aGDevice: A handle to a GDevice structure that is used only when you specify the noNewDevice flag in the flags parameter, in which case NewGWorld attaches this GDevice structure to the new offscreen graphics world. If you set the pixelDepth parameter to 0, or if you do not set the noNewDevice flag, NewGWorld ignores the aGDevice parameter, so set it to NULL. If you set the pixelDepth parameter to 0, NewGWorld uses the GDevice structure for the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. You should pass NULL in this parameter if the computer supports only basic QuickDraw. Generally, your application should never create GDevice structures for offscreen graphics worlds.
flags: Options available to your application. You can set a combination of the flags pixPurge, noNewDevice, useTempMem, and keepLocal. If you don’t wish to use any of these flags, specify 0 in this parameter to accept the default behavior for NewGWorld. The default behavior creates an offscreen graphics world where the base address for the offscreen pixel image is unpurgeable, it uses an existing GDevice structure (if you pass 0 in the depth parameter) or creates a new GDevice structure, it uses memory in your application heap, and it allows graphics accelerators to cache the offscreen pixel image. See “Graphics World Flags” for a description of the values you can use here.

Return Value

A result code.

Discussion

Typically, you pass 0 in the pixelDepth parameter, a window’s port rectangle in the boundsRect parameter, NULL in the cTable and aGDevice parameters, and in the flags parameter a 0. This provides your application with the default behavior of NewGWorld, and it supports computers running basic QuickDraw. This also allows QuickDraw to optimize the CopyBits, CopyMask, and CopyDeepMask functions when your application copies the image in an offscreen graphics world into an onscreen graphics port.

The NewGWorld function allocates memory for an offscreen graphics port and its pixel map. On computers that support only basic QuickDraw, NewGWorld creates a 1-bit pixel map that your application can manipulate using other relevant functions described in this chapter. Your application can copy this 1-bit pixel map into basic graphics ports.

Unless you specify 0 in the pixelDepth parameter–or pass the noNewDevice flag in the flags parameter and supply a GDevice structure in the aGDevice parameter– NewGWorld also allocates a new offscreen GDevice structure.

When creating an image, use the NewGWorld function to create an offscreen graphics world that is optimized for an image’s characteristics—for example, its best pixel depth. After creating the image, use the CopyBits, CopyMask, or CopyDeepMask function to copy that image to an onscreen graphics port. Color QuickDraw automatically renders the image at the best available pixel depth for the screen. Creating an image in an offscreen graphics port and then copying it to the screen in this way prevents the visual choppiness that would otherwise occur if your application were to build a complex image directly onscreen.

The NewGWorld function initializes the offscreen graphics port by calling the OpenCPort function. The NewGWorld function sets the offscreen graphics port’s visible region to a rectangular region coincident with its boundary rectangle. The NewGWorld function generates an inverse table with the Color Manager function MakeITable, unless one of the GDevice structures for the screens has the same color table as the GDevice structure for the offscreen world, in which case NewGWorld uses the inverse table from that GDevice structure.

The address of the offscreen pixel image is not directly accessible from the PixMap structure for the offscreen graphics world. However, you can use the GetPixBaseAddr function to get a pointer to the beginning of the offscreen pixel image.

For purposes of estimating memory use, you can compute the size of the offscreen pixel image by using this formula:

rowBytes * (boundsRect.bottom – boundsRect.top)

In the flags parameter, you can specify several options. If you don’t want to use any of these options, pass 0 in the flags parameter:

If you specify the pixPurge flag, NewGWorld stores the offscreen pixel image in a purgeable block of memory. In this case, before drawing to or from the offscreen pixel image, your application should call the LockPixels function and ensure that it returns TRUE. If LockPixels returns FALSE, the memory for the pixel image has been purged, and your application should either call UpdateGWorld to reallocate it and then reconstruct the pixel image, or draw directly in a window instead of preparing the image in an offscreen graphics world. Never draw to or copy from an offscreen pixel image that has been purged without reallocating its memory and then reconstructing it.
If you specify the noNewDevice flag, NewGWorld does not create a new offscreen GDevice structure. Instead, it uses the GDevice structure that you specify in the aGDevice parameter–and its associated pixel depth and color table–to create the offscreen graphics world. (If you set the pixelDepth parameter to 0, NewGWorld uses the GDevice structure for the screen with the greatest pixel depth among all the screens whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter–even if you specify the noNewDevice flag.) The NewGWorld function keeps a reference to the GDevice structure for the offscreen graphics world, and the SetGWorld function uses that structure to set the current graphics device.
If you set the useTempMem flag, NewGWorld creates the base address for an offscreen pixel image in temporary memory. You generally would not use this flag, because you should use temporary memory only for fleeting purposes and only with the AllowPurgePixels function.
If you specify the keepLocal flag, your offscreen pixel image is kept in Macintosh main memory and is not cached to a graphics accelerator card. use this flag carefully, as it negates the advantages provided by any graphics acceleration card that might be present.

If your application needs to change the pixel depth, boundary rectangle, or color table for an offscreen graphics world, use the UpdateGWorld function.

Special Considerations

If you supply a handle to a ColorTable structure in the cTable parameter, NewGWorld makes a copy of the structure and stores its handle in the offscreen PixMap structure. It is your application’s responsibility to make sure that the ColorTable structure you specify in the cTable parameter is valid for the offscreen graphics port’s pixel depth.

If when using NewGWorld you specify a pixel depth, color table, or GDevice structure that differs from those used by the window into which you copy your offscreen image, the CopyBits, CopyMask, and CopyDeepMask functions require extra time to complete.

To use a custom color table in an offscreen graphics world, you need to create the associated offscreen GDevice structure, because Color QuickDraw needs its inverse table.

The NewGWorld function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickTimeComponents.k.h

NewRgn

Begins creating a new region.

RgnHandle NewRgn (
   void
);

Return Value

A handle to the new region.

Discussion

The NewRgn function allocates space for a new, variable-size region and initializes it to the empty region defined by the rectangle (0,0,0,0). This is the only function that creates a new region; other functions merely alter the size or shape of existing regions.

To begin defining a region, use the OpenRgn function.

Special Considerations

The NewRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Use the Memory Manager function MaxMem to determine whether the memory for the region is valid before using NewRgn.

Ensure that the memory for a region is valid before calling this function to manipulate that region if there isn’t sufficient memory, the system may crash. Regions are limited to 32 KB in size in basic QuickDraw and 64 KB in color QuickDraw. Before defining a region, you can use the Memory Manager function MaxMem to determine whether the memory for the region is valid. You can determine the current size of an existing region by calling the Memory Manager function GetHandleSize. When you record drawing operations in an open region, the resulting region description may overflow the 32 KB or 64 KB limit. Should this happen in color QuickDraw, the QDError function returns the result code regionTooBigError.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

QTCarbonShell

Declared In

QuickdrawAPI.h

ObscureCursor

Hides the cursor until the next time the user moves the mouse.

void ObscureCursor (
   void
);

Discussion

Your application normally calls ObscureCursor when the user begins to type. Unlike HideCursor , ObscureCursor has no effect on the cursor level and must not be balanced by a call to ShowCursor.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

OffsetRect

Moves a rectangle.

void OffsetRect (
   Rect * r,
   short dh,
   short dv
);

Parameters

r: A pointer to the rectangle to move.
dh: The horizontal distance to move the rectangle.
dv: The vertical distance to move the rectangle.

Discussion

The OffsetRect function moves the rectangle that you specify in the r parameter by adding the value you specify in the dh parameter to each of its horizontal coordinates and the value you specify in the dv parameter to each of its vertical coordinates. If the dh and dv parameters are positive, the movement is to the right and down; if either is negative, the corresponding movement is in the opposite direction. The rectangle retains its shape and size; it is merely moved on the coordinate plane. The movement does not affect the screen unless you subsequently call a function to draw within the rectangle.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

QuickdrawAPI.h

OffsetRgn

Moves a region.

void OffsetRgn (
   RgnHandle rgn,
   short dh,
   short dv
);

Parameters

rgn: A handle to the region to move.
dh: The horizontal distance to move the region.
dv: The vertical distance to move the region.

Discussion

The OffsetRgn function moves the region whose handle you pass in the rgn parameter by adding the value you specify in the dh parameter to the horizontal coordinates of all points of its region boundary, and by adding the value you specify in the dv parameter to the vertical coordinates of all points of its region boundary. If the values of dh and dv are positive, the movement is to the right and down; if either is negative, the corresponding movement is in the opposite direction. The region retains its size and shape. This does not affect the screen unless you subsequently call a function to draw the region.

The OffsetRgn function is an especially efficient operation, because most of the data defining a region is stored relative to the rgnBBox field in its Region structure and so is not actually changed by OffsetRgn.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

Pt2Rect

Determines the smallest rectangle that encloses two given points.

void Pt2Rect (
   Point pt1,
   Point pt2,
   Rect *dstRect
);

Parameters

pt1: The first of two points to enclose.
pt2: The second of two points to enclose.
dstRect: On return, a pointer to the smallest rectangle that can enclose them.

Discussion

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

PtInRect

Determines whether a pixel below is enclosed in a rectangle.

Boolean PtInRect (
   Point pt,
   const Rect * r
);

Parameters

pt: The point to test.
r: The rectangle to test.

Return Value

TRUE if the pixel below and to the right of the point specified in the pt parameter is enclosed in the rectangle specified in the r parameter. FALSE if it is not.

Discussion

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

PtInRgn

Determines whether a pixel is within a region.

Boolean PtInRgn (
   Point pt,
   RgnHandle rgn
);

Parameters

pt: The point whose pixel is to be checked.
rgn: A handle to the region to test.

Return Value

TRUE if the pixel below and to the right of the point specified in the pt parameter is within the region whose handle is specified in the rgn parameter. FALSE if it is not.

Discussion

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

PtToAngle

Calculates an angle between a vertical line pointing straight up from the center of a rectangle and a line from the center to a given point.

void PtToAngle (
   const Rect *r,
   Point pt,
   short *angle
);

Parameters

r

The rectangle to examine.

pt

The point to which an angle is to be calculated.

angle

On return, a pointer to the resulting angle.

The result returned in the angle parameter is specified in degrees from 0 to 359, measured clockwise from 12 o’clock, with 90 at 3 o’clock, 180 at 6 o’clock, and 270 at 9 o’clock. Other angles are measured relative to the rectangle. If the line to the given point goes through the upper-right corner of the rectangle, the angle returned is 45, even if the rectangle is not square if it goes through the lower-right corner, the angle is 135, and so on.

The angle returned can be used as input to one of the functions that manipulate arcs and wedges, in “Drawing Arcs and Wedges”.

Discussion

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

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 Mac OS X v10.1 and later.
Not available to 64-bit applications.

Related Sample Code

CarbonSketch

Declared In

QuickdrawAPI.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 Mac OS X v10.1 and later.
Not available to 64-bit applications.

Related Sample Code

CarbonSketch

Declared In

QuickdrawAPI.h

QDGetCGDirectDisplayID

Returns the Quartz display ID that corresponds to a QuickDraw graphics device.

CGDirectDisplayID QDGetCGDirectDisplayID (
   GDHandle inGDevice
);

Parameters

inGDevice: A QuickDraw graphics device.

Return Value

A Quartz display ID, or NULL if the inGDevice parameter does not represent a display. For information about using a display ID, see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.3 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

QDPictCreateWithProvider

Creates a QDPict picture, using QuickDraw picture data supplied with a Quartz data provider.

QDPictRef QDPictCreateWithProvider (
   CGDataProviderRef provider
);

Parameters

provider

A Quartz data provider that supplies QuickDraw picture data. The picture data must begin at either the first byte or the 513th byte in the data provider. The picture bounds must not be an empty rectangle.

QuickDraw retains the data provider you pass in, and you may safely release it after this function returns.

Return Value

A new QDPict picture, or NULL if the picture data is not valid. The initial retain count is 1. After you finish using the picture, you should release it by calling QDPictRelease.

Discussion

This function creates a QDPict picture that you can draw in a Quartz context. For general information about QDPict pictures, see QDPictRef.

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

QDPictToCGContext.h

QDPictCreateWithURL

Creates a QDPict picture, using QuickDraw picture data specified with a Core Foundation URL.

QDPictRef QDPictCreateWithURL (
   CFURLRef url
);

Parameters

url: A Core Foundation URL that specifies a PICT file containing the QuickDraw picture data. The picture header data must begin at either the first byte or the 513th byte in the PICT file. The picture bounds must not be an empty rectangle.

Return Value

A new QDPict picture, or NULL if the picture data is not valid. The initial retain count is 1. After you finish using the picture, you should release it by calling QDPictRelease.

Discussion

This function creates a QDPict picture that you can draw in a Quartz context. For general information about QDPict pictures, see QDPictRef.

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

QDPictToCGContext.h

QDPictDrawToCGContext

Draws a QuickDraw picture in a Quartz context.

OSStatus QDPictDrawToCGContext (
   CGContextRef ctx,
   CGRect rect,
   QDPictRef pictRef
);

Parameters

context: The Quartz context in which to draw.
rect: The rectangular area in which to draw the picture. You should specify the origin and size of this rectangle in user space units. The origin is the lower left corner of the picture when drawn. If necessary, the picture is scaled to fit inside this rectangle. To get unscaled results, you should pass the rectangle returned by QDPictGetBounds. For additional information about scaling, see the discussion below.
picture: A QDPict picture.

Return Value

A result code. A non-zero result indicates that the picture was not successfully drawn.

Discussion

This function converts the picture data in a QDPict picture into an equivalent sequence of Quartz 2D graphics operations. Conceptually this is the same processing path taken when an application running in Mac OS X draws into a QuickDraw printing port.

When drawing a QDPict picture in a Quartz context, there are two ways to change the horizontal or vertical scale of the picture:

Construct the drawing rectangle (see the rect parameter) by applying the change of scale to the bounds rectangle returned by QDPictGetBounds. In this case, QuickDraw scales all the graphic elements in the picture except for patterns—the same behavior as DrawPicture.
Prior to calling QDPictDrawToCGContext, apply the change of scale to the current transformation matrix in the Quartz context—for example, by calling CGContextScaleCTM. In this case, QuickDraw scales the entire picture including patterns.

In a bitmap-based context, the picture is rendered into the bitmap. In a PDF-based context, the picture is converted into a PDF content stream. If the picture uses transfer modes such as srcXor that do not have an analog in Quartz 2D, the PDF representation may not match the original exactly.

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

QDPictToCGContext.h

QDPictGetBounds

Returns the intended location and size of a QDPict picture.

CGRect QDPictGetBounds (
   QDPictRef pictRef
);

Parameters

picture: A QDPict picture.

Return Value

A Quartz rectangle that represents the intended location and size of the picture. The rectangle is in default user space with one unit = 1/72 inch, and the origin is the lower-left corner of the picture.

Discussion

If the native resolution in the picture data is not 72 pixels per inch, the bounding rectangle returned by this function is scaled as follows:

    width = width in pixels * 72 / horizontal resolution

    height = height in pixels * 72 / vertical resolution

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

QDPictToCGContext.h

QDPictGetResolution

Returns the horizontal and vertical resolution of a QDPict picture.

void QDPictGetResolution (
   QDPictRef pictRef,
   float *xRes,
   float *yRes
);

Parameters

picture: A QDPict picture.
xRes: A pointer to your storage for a return value. Upon completion, the value is the picture’s horizontal resolution in pixels per inch.
yRes: A pointer to your storage for a return value. Upon completion, the value is the picture’s vertical resolution in pixels per inch.

Discussion

This function returns resolution data that you can use—together with the rectangle returned by QDPictGetBounds—to compute the picture’s size in pixels.

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

QDPictToCGContext.h

QDPictRelease

Releases a QDPict picture.

void QDPictRelease (
   QDPictRef pictRef
);

Parameters

picture: A QDPict picture which you created or retained.

Discussion

After you finish using a QDPict picture that you created or retained, you should call this function to release the picture. If the picture’s retain count becomes 0, this function frees the picture and any associated resources such as the picture’s data provider.

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

QDPictToCGContext.h

QDPictRetain

Retains a QDPict picture.

QDPictRef QDPictRetain (
   QDPictRef pictRef
);

Parameters

picture: A QDPict picture.

Return Value

The retained picture.

Discussion

You should call this function when you obtain a QDPict picture that you did not create and you want to retain the picture for later use. When you no longer need the retained picture, you should call QDPictRelease to release it.

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

QDPictToCGContext.h

QDRegionToRects

OSStatus QDRegionToRects (
   RgnHandle rgn,
   QDRegionParseDirection dir,
   RegionToRectsUPP proc,
   void *userData
);

Return Value

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

RectInRgn

Determines whether a rectangle intersects a region.

Boolean RectInRgn (
   const Rect *r,
   RgnHandle rgn
);

Parameters

r: The rectangle to check for intersection.
rgn: A handle to the region to check.

Return Value

TRUE if the rectangle specified in the r parameter intersects the region whose handle is specified in the rgn parameter. The RectInRgn function returns TRUE if the intersection encloses at least 1 bit or FALSE if it does not.

Discussion

Special Considerations

The RectInRgn function sometimes returns TRUE when the rectangle merely intersects the region’s bounding rectangle. If you need to know exactly whether a given rectangle intersects the actual region, use RectRgn to set the rectangle to a region, and call SectRgn to see whether the two regions intersect. If the result of SectRgn is an empty region, then the rectangle does not intersect the region.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

RectRgn

Changes the structure of an existing region to that of a rectangle.

void RectRgn (
   RgnHandle rgn,
   const Rect *r
);

Parameters

rgn: A handle to the region to restructure as a rectangle.
r: The rectangle structure to use.

Discussion

The RectRgn function destroys the previous structure of the SetRectRgn function, and it then sets the new structure to a rectangle that you specify in the r parameter.

As an alternative to the RectRgn function, use the SetRectRgn function, which accepts as parameters four coordinates instead of a rectangle.

Special Considerations

The RectRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Declared In

QuickdrawAPI.h

RgnToHandle

void RgnToHandle (
   RgnHandle region,
   Handle flattenedRgnDataHdl
);

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

ScalePt

Scales a height and width according to the proportions of two rectangles.

void ScalePt (
   Point *pt,
   const Rect *srcRect,
   const Rect *dstRect
);

Parameters

pt

On input, a pointer to an initial height and width (specified in the two fields of a Point structure) to scale; on return, vertical and horizontal scaling factors derived by multiplying the height and width by ratios of the height and width of the rectangle in the srcRect parameter to the height and width of the rectangle in the dstRect parameter.

You do not pass coordinates in this parameter. Instead, you pass an initial height to scale in the v (or vertical) field of the Point structure, and you pass an initial width to scale in the h (or horizontal) field.

The ScalePt function scales these measurements by multiplying the initial height by the ratio of the height of the rectangle you specify in the dstRect parameter to the height of the rectangle you specify in the srcRect parameter, and by multiplying the initial width by the ratio of the width of the dstRect rectangle to the width of the srcRect rectangle.

srcRect

A rectangle. The ratio of this rectangle’s height to the height of the rectangle in the dstRect parameter provides the vertical scaling factor, and the ratio of this rectangle’s width to the width of the rectangle in the dstRect parameter provides the horizontal scaling factor.

dstRect

A rectangle compared to the rectangle in the srcRect parameter to determine vertical and horizontal scaling factors.

Discussion

The ScalePt function produces horizontal and vertical scaling factors from the proportions of two rectangles. Use ScalePt, for example, to scale the dimensions of the graphics pen.

Where the width of the dstRect rectangle is twice the width of the srcRect rectangle, and its height is three times the height of srcRect, ScalePt scales the width of the graphics pen from 3 to 6 and scales its height from 2 to 6.

Special Considerations

The minimum value ScalePt returns is (1,1).

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

SectRect

Determines whether two rectangles intersect.

Boolean SectRect (
   const Rect *src1,
   const Rect *src2,
   Rect *dstRect
);

Parameters

src1: The first of two rectangles to test for intersection.
src2: The second of two rectangles to test for intersection.
dstRect: On return, a pointer to the rectangle marking the intersection of the first two rectangles.

Return Value

TRUE if the specified rectangles intersect or FALSE if they do not.

Discussion

The SectRect function calculates the rectangle that delineates the intersection of the two rectangles you specify in the src1 and src2 parameters. Rectangles that touch at a line or a point are not considered intersecting, because their intersection rectangle (actually, in this case, an intersection line or point) does not enclose any pixels in the bit image.

If the rectangles do not intersect, the destination rectangle is set to (0,0,0,0). The SectRect function works correctly even if one of the source rectangles is also the destination.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

SoftVDigX

Declared In

QuickdrawAPI.h

SectRgn

Calculates the intersection of two regions.

void SectRgn (
   RgnHandle srcRgnA,
   RgnHandle srcRgnB,
   RgnHandle dstRgn
);

Parameters

srcRgnA

A handle to the first of two regions whose intersection is to be determined.

srcRgnB

A handle to the second of two regions whose intersection is to be determined.

dstRgn

On return, a handle to the region holding the intersection area. If the regions do not intersect, or one of the regions is empty, SectRgn sets the destination to the empty region defined by the rectangle (0,0,0,0).

The SectRgn function does not create a destination region; you must have already allocated memory for it by using the NewRgn function.

The destination region may be one of the source regions, if desired.

Discussion

The SectRgn procedure calculates the intersection of the two regions whose handles you pass in the srcRgnA and srcRgnB parameters, and it places the intersection in the region whose handle you pass in the dstRgn parameter. If the regions do not intersect, or one of the regions is empty, SectRgn sets the destination to the empty region defined by the rectangle (0,0,0,0).

The SectRgn procedure does not create a destination region; you must have already allocated memory for it by using the NewRgn function.

The destination region may be one of the source regions, if desired.

Special Considerations

The SectRgn function may temporarily use heap space that’s twice the size of the two input regions.

The SectRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

SetClip

Changes the clipping region of the current graphics port (basic or color) to a region you specify. (Deprecated. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)

void SetClip (
   RgnHandle rgn
);

Parameters

rgn: A handle to a region. The SetClip function makes this region the clipping region of the current graphics port. The SetClip function doesn’t change the region handle, but instead affects the clipping region itself.

Discussion

Since SetClip copies the specified region into the current graphics port’s clipping region, any subsequent changes you make to the region specified in the rgn parameter do not affect the clipping region of the graphics port.

The initial clipping region of a graphics port is an arbitrarily large rectangle. You can set the clipping region to any arbitrary region, to aid you in drawing inside the graphics port—for example, to avoid drawing over scroll bars when drawing into a window, you could define a clipping region that excludes the scroll bars.

You can use the GetClip and SetClip functions to preserve the current clipping region: use GetClip to save the current port’s clipping region, and use SetClip to restore it.

All other system software functions preserve the current clipping region.

The SetClip function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.k.h

SetEmptyRgn

Sets an existing region to be empty.

void SetEmptyRgn (
   RgnHandle rgn
);

Parameters

rgn: A handle to the region to be made empty.

Discussion

The SetEmptyRgn function destroys the previous structure of the region whose handle you pass in the rgn parameter; it then sets the new structure to the empty region defined by the rectangle (0,0,0,0).

Special Considerations

The SetEmptyRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

SetGWorld

Changes the current graphics port (basic, color, or offscreen). (Deprecated. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)

void SetGWorld (
   CGrafPtr port,
   GDHandle gdh
);

Parameters

port: A pointer to an offscreen graphics world, color graphics port, or basic graphics port. Specify values of type GrafPtr, CGrafPtr, or GWorldPtr, depending on whether you want to set the current graphics port to be a basic graphics port, color graphics port, or offscreen graphics world. Any drawing your application performs then occurs in this graphics port.
gdh: A handle to a GDevice structure. If you pass a pointer to an offscreen graphics world in the port parameter, set this parameter to NULL, because SetGWorld ignores this parameter and sets the current device to the device attached to the offscreen graphics world.

Discussion

The SetGWorld function sets the current graphics port to the one specified by the port parameter and—unless you set the current graphics port to be an offscreen graphics world—sets the current device to that specified by the gdh parameter.

Special Considerations

The SetGWorld function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

ImageCompression.k.h

SetPt

Assigns two coordinates to a point.

void SetPt (
   Point *pt,
   short h,
   short v
);

Parameters

pt: A pointer to the point to be given new coordinates. On return, this point is assigned the horizontal coordinate you specify in the h parameter and the vertical coordinate you specify in the v parameter.
h: The horizontal value of the new coordinates.
v: The vertical value of the new coordinates.

Discussion

The SetPt procedure assigns the horizontal coordinate specified in the h parameter and the vertical coordinate specified in the v parameter to the point returned in the pt parameter.

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

SetRect

Assigns coordinates to a rectangle.

void SetRect (
   Rect * r,
   short left,
   short top,
   short right,
   short bottom
);

Parameters

r: A pointer to the rectangle to set.
left: The horizontal coordinate of the new upper-left corner of the rectangle.
top: The vertical coordinate of the new upper-left corner of the rectangle.
right: The horizontal coordinate of the new lower-right corner of the rectangle.
bottom: The vertical coordinate of the new lower-right corner of the rectangle.

Discussion

The SetRect function assigns the coordinates you specify in the left, top, right, and bottom parameters to the rectangle that you specify in the r parameter. This function is provided to help you shorten your program text. If you want a more readable text, at the expense of source text length, you can instead assign integers (or points) directly into the fields of a Rect structure.

You can use a rectangle to specify locations and sizes for various graphics operations.

Availability

Available in Mac OS X v10.0 and later.

Related Sample Code

Declared In

QuickdrawAPI.h

SetRectRgn

Changes the structure of an existing region to that of a rectangle.

void SetRectRgn (
   RgnHandle rgn,
   short left,
   short top,
   short right,
   short bottom
);

Parameters

rgn: A handle to the region to restructure as a rectangle.
left: The horizontal coordinate of the upper-left corner of the rectangle to set as the new region.
top: The vertical coordinate of the upper-left corner of the rectangle to set as the new region.
right: The horizontal coordinate of the lower-right corner of the rectangle to set as the new region.
bottom: The vertical coordinate of the lower-right corner of the rectangle to set as the new region.

Discussion

The SetRectRgn function destroys the previous structure of the region whose handle you pass in the rgn parameter, and it then sets the new structure to the rectangle that you specify in the left, top, right, and bottom parameters. If you specify an empty rectangle (that is, right is greater than or equal to left or bottom = top), the SetRectRgn function sets the region to the empty region defined by the rectangle (0,0,0,0).

As an alternative to the SetRectRgn function, you can change the structure of an existing region to that of a rectangle by using the RectRgn function, which accepts as a parameter a rectangle instead of four coordinates.

Special Considerations

The SetRectRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

ShieldCursor

Hides the cursor in a rectangle.

void ShieldCursor (
   const Rect *shieldRect,
   Point offsetPt
);

Parameters

shieldRect: A rectangle in which the cursor is hidden whenever the cursor intersects the rectangle. The rectangle may be specified in global or local coordinates. If you are using global coordinates, pass (0,0) in the offsetPt parameter. If you are using the local coordinates of a graphics port, pass the coordinates for the upper-left corner of the graphics port’s boundary rectangle in the offsetPt parameter.
offsetPt: A point value for the offset of the rectangle. Like the basic QuickDraw function LocalToGlobal, the ShieldCursor function offsets the coordinates of the rectangle by the coordinates of this point.

Discussion

If the cursor and the given rectangle intersect, ShieldCursor hides the cursor. If they do not intersect, the cursor remains visible while the mouse is not moving, but is hidden when the mouse moves. Use this function with a feature such as QuickTime to display content in a specified rectangle. When a QuickTime movie is animating, the cursor should not be visible in front of the movie.

The ShieldCursor function decrements the cursor level and should be balanced by a call to the ShowCursor function.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

ShowCursor

Displays a cursor hidden by the HideCursor or ShieldCursor functions.

void ShowCursor (
   void
);

Discussion

ShowCursor increments the cursor level, which has been decremented by the HideCursor or ShieldCursor function and displays the cursor on the screen when the level is 0. A call to the ShowCursor function balances each previous call to the HideCursor or ShieldCursor function. The level is not incremented beyond 0, so extra calls to ShowCursor have no effect.

Low-level interrupt-driven functions link the cursor with the mouse position, so that if the cursor level is 0 and visible, the cursor automatically follows the mouse.

If the cursor has been changed with the SetCursor function while hidden, ShowCursor displays the new cursor.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Related Sample Code

Simple DrawSprocket

Declared In

QuickdrawAPI.h

SlopeFromAngle

Converts an angle value to a slope value.

Fixed SlopeFromAngle (
   short angle
);

Parameters

angle: The angle, expressed in clockwise degrees from 12 o’clock and treated MOD 180. (90 degrees is thus at 3 o’clock and –90 degrees is at 9 o’clock.

Return Value

The slope corresponding to the angle specified in the angle parameter. Slopes are defined as Dx/Dy, the horizontal change divided by the vertical change between any two points on a line with the given angle. The negative y-axis is defined as being at 12 o’clock, and the positive y-axis at 6 o’clock. The x-axis is defined as usual, with the positive side defined as being at 3 o’clock.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

SubPt

Subtracts the coordinates of one point from another.

void SubPt (
   Point src,
   Point *dst
);

Parameters

src

A point, the coordinates of which are to be subtracted from the coordinates of the point specified in the dst parameter.

dst

The address of a point. Upon completion, the coordinates of this point contain the differences between the coordinates of the two points specified in the entry parameters.

If you pass NULL in the dst parameter, this function sets the QDError result code to paramErr and returns.

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

UnionRect

Calculates the smallest rectangle that encloses two rectangles.

void UnionRect (
   const Rect * src1,
   const Rect * src2,
   Rect * dstRect
);

Parameters

src1: The first of two rectangles to enclose.
src2: The second of two rectangles to enclose.
dstRect: On return, a pointer to the smallest rectangle that encloses both of the rectangles you specify in the src1 and src2 parameters. One of the source rectangles may also be the destination.

Discussion

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

UnionRgn

Calculates the union of two regions.

void UnionRgn (
   RgnHandle srcRgnA,
   RgnHandle srcRgnB,
   RgnHandle dstRgn
);

Parameters

srcRgnA

A handle to the first of two regions whose union is to be determined.

srcRgnB

A handle to the second of two regions whose union is to be determined.

dstRgn

On return, a handle to the region holding the resulting union area. If both regions are empty, UnionRgn sets the destination to the empty region defined by the rectangle (0,0,0,0).

The UnionRgn function does not create the destination region; you must have already allocated memory for it by using the NewRgn function.

The destination region may be one of the source regions, if desired.

Discussion

The UnionRgn procedure calculates the union of the two regions whose handles you pass in the srcRgnA and srcRgnB parameters, and it places the union in the region whose handle you pass in the dstRgn parameter. If both regions are empty, UnionRgn sets the destination to the empty region defined by the rectangle (0,0,0,0).

Special Considerations

The UnionRgn function may temporarily use heap space that’s twice the size of the two input regions.

The UnionRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.h

XorRgn

Calculates the difference between the union and the intersection of two regions.

void XorRgn (
   RgnHandle srcRgnA,
   RgnHandle srcRgnB,
   RgnHandle dstRgn
);

Parameters

srcRgnA

A handle to the first of two regions to compare.

srcRgnB

A handle to the second of two regions to compare.

dstRgn

On return, a handle to the region holding the result.

This does not create the destination region; you must have already allocated memory for it by using the NewRgn function.

If the regions are coincident, XorRgn sets the destination region to the empty region defined by the rectangle (0,0,0,0).

Discussion

The XorRgn procedure calculates the difference between the union and the intersection of the regions whose handles you pass in the srcRgnA and srcRgnB parameters and places the result in the region whose handle you pass in the dstRgn parameter.

Special Considerations

The XorRgn function may temporarily use heap space that’s twice the size of the two input regions.

The XorRgn function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

QuickdrawAPI.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

ColorComplementUPP

typedef ColorComplementProcPtr ColorComplementUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

ColorSearchUPP

typedef ColorSearchProcPtr ColorSearchUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac 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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

ConstPatternParam

typedef const Pattern* ConstPatternParam;

Availability

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

CSpecArray

typedef ColorSpec CSpecArray[1];

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

X.h

CursorImageRec

struct CursorImageRec {
   UInt16 majorVersion;
   UInt16 minorVersion;
   PixMapHandle cursorPixMap;
   BitMapHandle cursorBitMask;
};
typedef struct CursorImageRec CursorImageRec;
typedef CursorImageRec * CursorImagePtr;

Availability

Available in Mac OS X v10.0 through Mac 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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

CWindowPtr

typedef WindowPtr CWindowPtr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

DeviceLoopDrawingUPP

typedef DeviceLoopDrawingProcPtr DeviceLoopDrawingUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

DeviceLoopFlags

typedef unsigned long DeviceLoopFlags;

Availability

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

DragConstraint

typedef UInt16 DragConstraint;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

DragGrayRgnUPP

typedef DragGrayRgnProcPtr DragGrayRgnUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac 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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

GrafVerb

typedef SInt8 GrafVerb;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QDOffscreen.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 Mac OS X v10.0 and later.

Declared In

QDOffscreen.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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

MacRegion

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

PixelType

typedef SInt8 PixelType;

Availability

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

PrinterFontStatus

struct PrinterFontStatus {
   SInt32 oResult;
   SInt16 iFondID;
   Style iStyle;
};
typedef struct PrinterFontStatus PrinterFontStatus;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

PrinterScalingStatus

struct PrinterScalingStatus {
   Point oScalingFactors;
};
typedef struct PrinterScalingStatus PrinterScalingStatus;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

PrinterStatusOpcode

typedef SInt32 PrinterStatusOpcode;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDArcUPP

typedef QDArcProcPtr QDArcUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDBitsUPP

typedef QDBitsProcPtr QDBitsUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDByte

typedef SignedByte QDByte;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDCommentUPP

typedef QDCommentProcPtr QDCommentUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDErr

typedef short QDErr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDGetPicUPP

typedef QDGetPicProcPtr QDGetPicUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDJShieldCursorUPP

typedef QDJShieldCursorProcPtr QDJShieldCursorUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDLineUPP

typedef QDLineProcPtr QDLineUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDOpcodeUPP

typedef QDOpcodeProcPtr QDOpcodeUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDOvalUPP

typedef QDOvalProcPtr QDOvalUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.1 and later.

Declared In

QDPictToCGContext.h

QDPolyUPP

typedef QDPolyProcPtr QDPolyUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDPrinterStatusUPP

typedef QDPrinterStatusProcPtr QDPrinterStatusUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDPutPicUPP

typedef QDPutPicProcPtr QDPutPicUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDRectUPP

typedef QDRectProcPtr QDRectUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDRegionBitsRef

typedef struct OpaqueQDRegionBitsRef * QDRegionBitsRef;

Availability

Available in Mac OS X v10.1 and later.

Declared In

QuickdrawAPI.h

QDRegionParseDirection

typedef SInt32 QDRegionParseDirection;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.h

QDRgnUPP

typedef QDRgnProcPtr QDRgnUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDRRectUPP

typedef QDRRectProcPtr QDRRectUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDStdGlyphsUPP

typedef QDStdGlyphsProcPtr QDStdGlyphsUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDTextUPP

typedef QDTextProcPtr QDTextUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

QDTxMeasUPP

typedef QDTxMeasProcPtr QDTxMeasUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

RegionToRectsUPP

typedef RegionToRectsProcPtr RegionToRectsUPP;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawAPI.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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

IOMacOSTypes.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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

xColorSpec

struct xColorSpec {
   short value;
   RGBColor rgb;
   short xalpha;
};
typedef struct xColorSpec xColorSpec;
typedef xColorSpec * xColorSpecPtr;

Availability

Available in Mac OS X v10.0 and later.

Declared In

QuickdrawTypes.h

xCSpecArray

typedef xColorSpec xCSpecArray[1];

Availability

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

whiteColor

Represents white.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

redColor

Represents red.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

greenColor

Represents green.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

blueColor

Represents blue.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

cyanColor

Represents cyan.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

magentaColor

Represents magenta.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

yellowColor

Represents yellow.

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

crossCursor

The crosshairs cursor; to draw graphics

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

plusCursor

The plus sign cursor; to select cells

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

watchCursor

The wristwatch cursor; to indicate a short operation in progress

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

ext32Device

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

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

ramInit

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

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

mainScreen

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

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

allInit

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

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

screenDevice

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

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

noDriver

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

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

screenActive

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

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

kVerticalConstraint

Constrain movement to horizontal axis only.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

kHorizontalConstraint

Constrain movement to vertical axis only.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.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 Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

fixedType

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

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

directType

Represents a device with direct RGB colors.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.3 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared in QuickdrawTypes.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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

paint

Specifies the paint action.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

erase

Specifies the erase action.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

invert

Specifies the invert action.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

fill

Specifies the fill action.

Available in Mac OS X v10.0 and later.

Declared in QuickdrawTypes.h.

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 Code	Value	Description
`updPixMemErr`	-125	Insufficient memory to update a pixmap. Available in Mac OS X v10.0 and later.
`noMemForPictPlaybackErr`	-145	Insufficient memory for drawing the picture. Available in Mac OS X v10.0 and later.
`pixMapTooDeepErr`	-148	Pixel map is deeper than 1 bit per pixel. Available in Mac OS X v10.0 and later.
`nsStackErr`	-149	Insufficient stack Available in Mac OS X v10.0 and later.
`cMatchErr`	-150	`Color2Index` failed to find an index. Available in Mac OS X v10.0 and later.
`cTempMemErr`	-151	Failed to allocate memory for temporary structures. Available in Mac OS X v10.0 and later.
`cNoMemErr`	-152	Failed to allocate memory for structures. Available in Mac OS X v10.0 and later.
`cRangeErr`	-153	Range error on color table requests. Available in Mac OS X v10.0 and later.
`cProtectErr`	-154	`ColorTable` structure entry protection violation. Available in Mac OS X v10.0 and later.
`cDevErr`	-155	Invalid type of graphics device. Available in Mac OS X v10.0 and later.
`cResErr`	-156	Invalid resolution for `MakeITable`. Available in Mac OS X v10.0 and later.
`cDepthErr`	-157	Invalid pixel depth. Available in Mac OS X v10.0 and later.
`rgnTooBigErr`	-500	Bitmap too large to convert to a region. Available in Mac OS X v10.0 and later.
`kQDNoPalette`	-3950	Available in Mac OS X v10.2 and later.
`kQDNoColorHWCursorSupport`	-3951	Available in Mac OS X v10.2 and later.
`kQDCursorAlreadyRegistered`	-3952	Available in Mac OS X v10.2 and later.
`kQDCursorNotRegistered`	-3953	Available in Mac OS X v10.2 and later.
`kQDCorruptPICTDataErr`	-3954	Available in Mac OS X v10.2 and later.

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.