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;