A function identified as deprecated has been superseded and may become unsupported in the future.
Adds a function to the head of the current device data structure’s list of complement functions. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void AddComp ( ColorComplementUPP compProc );
A pointer to your complement function, ColorComplementProcPtr
.
AddComp
creates and allocates a CProcRec
data structure.
QuickdrawAPI.h
Adds a function to the head of the current GDevice
data structure’s list of search functions. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void AddSearch ( ColorSearchUPP searchProc );
A pointer to your custom search function, ColorSearchProcPtr
.
AddSearch
creates and allocates an SProcRec
data structure.
QuickdrawAPI.h
Reallocates cursor memory. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void AllocCursor ( void );
Under normal circumstances, you should never need to use this function, since Color QuickDraw handles reallocation of cursor memory.
QuickdrawAPI.h
Makes the base address for an offscreen pixel image purgeable. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void AllowPurgePixels ( PixMapHandle pm );
A handle to an offscreen pixel map.
The AllowPurgePixels
function allows the Memory Manager to free the memory it occupies if available memory space becomes low. By default, NewGWorld
creates an unpurgeable base address for an offscreen pixel image.
To get a handle to an offscreen pixel map, first use the GetGWorldPixMap
function. Then supply this handle for the pm
parameter of AllowPurgePixels
.
Your application should call the LockPixels
function before drawing into or copying from an offscreen pixel map. If the Memory Manager has purged the base address for its pixel image, LockPixels
returns FALSE
. In that case either your application should use the UpdateGWorld
function to begin reconstructing the offscreen pixel image, or it should draw directly to an onscreen graphics port.
Only unlocked memory blocks can be made purgeable. If you use LockPixels
, you must use the UnlockPixels
function before calling AllowPurgePixels
.
The AllowPurgePixels
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QDOffscreen.h
Changes a basic graphics port’s background color. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void BackColor ( long color );
One of eight color values. See “Color Constants.”
The background color is the color of the pixels in the bitmap wherever no drawing has taken place. By default the background color of a GrafPort
is white.
The BackColor
function sets the background color for the current graphics port to the color that you specify in the color
parameter. When you draw with the patCopy
and srcCopy
transfer modes, for example, white pixels are drawn in the color you specify with BackColor
.
All nonwhite colors appear as black on black-and-white screens. Before you use BackColor
, use the DeviceLoop
function to determine the color characteristics of the current screen.
The BackColor
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
In System 7, use the Color QuickDraw function RGBBackColor
.
QuickdrawAPI.h
Changes the bit pattern used as the background pattern by the current graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void BackPat ( const Pattern *pat );
A bit pattern, as defined by a Pattern
structure.
The BackPat
function sets the bit pattern defined in the Pattern
structure, which you specify in the pat
parameter, to be the background pattern. (The standard bit patterns white
, black
, gray
, ltGray
, and dkGray
are predefined; the initial background pattern for the graphics port is white
.) This pattern is stored in the bkPat
field of a GrafPort
structure.
The BackPat
function also sets a bit pattern for the background color in a color graphics port. The BackPat
function creates a handle, of type PixPatHandle
, for the bit pattern and stores this handle in the bkPixPat
field of the CGrafPort
structure. As in basic graphics ports, Color QuickDraw draws patterns in color graphics ports at the time of drawing, not at the time you use PenPat
to set the pattern.
To define your own patterns, you typically create pattern, ‘PAT’, or pattern list, ‘PAT#’, resources.
The BackPat
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Assigns a pixel pattern as the background pattern. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void BackPixPat ( PixPatHandle pp );
A handle to the pixel pattern to use as the background pattern.
Setting the background pattern allows the ScrollRect
function and the shape-erasing functions (for example, EraseRect
) to fill the background with a colored patterned “ink.”
The BackPixPat
function is similar to the basic QuickDraw function BackPat
, except that you pass BackPixPat
a handle to a multicolored pixel pattern instead of a bit pattern.
The handle to the pixel pattern is stored in the bkPixPat
field of the CGrafPort
structure, therefore, you should not dispose of this handle since QuickDraw removes all references to your pattern from an existing graphics port when you dispose of it.
If you use BackPixPat
to set a background pixel pattern in a basic graphics port, the data in the pat1Data
field of the PixPat
structure is placed into the bkPat
field of the GrafPort
structure.
To define your own pixel pattern, create a pixel pattern resource, x is described on 'ppat'
, or use the NewPixPat
function. To set the background pattern to a bit pattern, you can also use the QuickDraw function, BackPat
.
The BackPixPat
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Converts a bitmap or pixel map to a region. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSErr BitMapToRegion ( RgnHandle region, const BitMap *bMap );
A handle to a region to hold the converted BitMap
or PixMap
structure. This must be a valid region handle created with the NewRgn
function. The old region contents are lost.
A pointer to a BitMap
or PixMap
structure to be converted. If you supply a PixMap
structure, its pixel depth must be 1.
A result code.
The BitMapToRegion
function converts a given BitMap
or PixMap
structure to a region. Pixels are added to the region where the corresponding entries in the bitmap have a value of 1. You would generally use this region later for drawing operations.
QuickdrawAPI.h
Determines where filling will not occur when filling from the outside of a rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void CalcCMask ( const BitMap *srcBits, const BitMap *dstBits, const Rect *srcRect, const Rect *dstRect, const RGBColor *seedRGB, ColorSearchUPP matchProc, long matchData );
The source image. If the image is in a pixel map, you must coerce its PixMap
structure to a BitMap
structure.
The destination image. The CalcCMask
function returns the generated bitmap mask in this parameter. You can then use this mask with the CopyBits
, CopyMask
, and CopyDeepMask
functions.
The rectangle of the source image.
The rectangle of the destination image.
An RGBColor
structure specifying the color for pixels that should not be filled.
An optional matching function.
Data for the optional matching function.
Specify a source image in the srcBits
parameter and in the srcRect
parameter, specify a rectangle within that source image. Starting from the edges of this rectangle, CalcCMask
calculates which pixels cannot be filled. By default, CalcCMask
returns 1’s in the mask to indicate which pixels have the exact color that you specify in the seedRGB
parameter and which pixels are enclosed by shapes whose outlines consist entirely of pixels with this color.
For instance, if the source image in srcBits
contains a dark blue rectangle on a red background, and your application sets seedRGB
equal to dark blue, then CalcCMask
returns a mask with 1’s in the positions corresponding to the edges and interior of the rectangle, and the 0’s outside of the rectangle.
If you set the matchProc
and matchData
parameters to 0, CalcCMask
uses the exact color specified in the RGBColor
structure that you supply in the seedRGB
parameter. You can customize CalcCMask
by writing your own color search function and pointing to it in the matchProc
parameter. As with SeedCFill
, you can then use the matchData
parameter in any manner useful for your application.
The CalcCMask
function does not scale so the source and destination rectangles must be the same size. Calls to CalcCMask
are not clipped to the current port and are not stored into QuickDraw pictures.
QuickdrawAPI.h
Determines where filling will not occur when filling from the outside of a rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void CalcMask ( const void *srcPtr, void *dstPtr, short srcRow, short dstRow, short height, short words );
A pointer to the source bit image.
A pointer to the destination bit image.
Row width of the source bitmap.
Row width of the destination bitmap.
Height (in pixels) of the fill rectangle.
Width (in words) of the fill rectangle.
The CalcMask
function produces a bit image with 1’s in all pixels to which paint could not flow from any of the outer edges of the rectangle. Use this bit image as a mask with the CopyBits
or CopyMask
function. A hollow object produces a solid mask, but an open object produces a mask of itself.
As with the SeedFill
function, point to the bit image you want to fill with the srcPtr
parameter, which can point to the image’s base address or a word boundary within the image. Specify a pixel height and word width with the height
and words
parameters to define a fill rectangle that delimits the area you want to fill. The fill rectangle can be the entire bit image or a subset of it. Point to a destination image with the dstPtr
parameter. Specify the row widths of the source and destination bitmaps (their rowBytes
values) with the srcRow
and dstRow
parameters. (The bitmaps can be different sizes, but they must be large enough to contain the fill rectangle at the origins specified by srcPtr
and dstPtr
.)
Calls to CalcMask
are not clipped to the current port and are not stored into QuickDraw pictures.
QuickdrawAPI.h
Sets the clipping path in a Quartz 2D graphics context, using a clipping region. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus ClipCGContextToRegion ( CGContextRef gc, const Rect *portRect, RgnHandle region );
A Quartz context associated with a graphics port. You can obtain such a context by calling QDBeginCGContext
.
The portRect
for the graphics port associated with the context.
A region that represents the desired clipping path.
A result code. If noErr
, the clipping path is now the region-based path.
This function sets the clipping path in the specified context to closely approximate the geometry of the specified region.
Unlike clipping in Quartz 2D, this function does not intersect the new region-based path with the current clipping path—the new path simply replaces the current clipping path.
You should use this function only when absolutely necessary—it’s relatively inefficient when compared to Quartz 2D clipping functions such as CGContextClipToRect
.
QuickdrawAPI.h
Changes the clipping region of the current graphics port (basic or color). (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ClipRect ( const Rect *r );
A pointer to a rectangle for the boundary of the new clipping region. The ClipRect
function changes the clipping region of the current graphics port to a region that’s equivalent to this rectangle. ClipRect
doesn’t change the region handle, but it affects the clipping region itself.
Since ClipRect
makes a copy of the given rectangle, any subsequent changes you make to that rectangle do not affect the clipping region of the port.
The ClipRect
function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSErr CloseCursorComponent ( ComponentInstance ci );
A result code.
QuickdrawAPI.h
Completes the collection of drawing commands and picture comments that define your picture. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ClosePicture ( void );
The ClosePicture
function stops collecting drawing commands and picture comments for the currently open picture. You should perform one and only one call to ClosePicture
for every call to the OpenCPicture
(or OpenPicture
) function.
The ClosePicture
function calls the ShowPen
function, balancing the call made by OpenCPicture
(or OpenPicture
) to the HidePen
function.
QuickdrawAPI.h
Completes the collection of lines that defines a polygon. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ClosePoly ( void );
The ClosePoly
function stops collecting line-drawing commands for the currently open polygon and computes the polyBBox
field of the Polygon
structure. You should call ClosePoly
only once for every call to the OpenPoly
function.
The ClosePoly
function uses the ShowPen
function, balancing the call to the HidePen
function made by the OpenPoly
function.
The ClosePoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Organizes a collection of lines and shapes into a region definition. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void CloseRgn ( RgnHandle dstRgn );
The handle to the region to close. This handle should be a region handle returned by the NewRgn
function.
The CloseRgn
function stops the collection of lines and framed shapes, organizes them into a region definition, and saves the result in the region whose handle you pass in the dstRgn
parameter.
The CloseRgn
function does not create the destination region; you must have already allocated space for it by using the OpenRgn
function. The CloseRgn
function calls the ShowPen
function, balancing the call to the HidePen
function made by OpenRgn.
When you no longer need the memory occupied by the region, use the DisposeRgn
function.
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.
Regions are limited to 32 KB in size in basic QuickDraw and 64 KB in Color QuickDraw. When you structure drawing operations in an open region, the resulting region description may overflow this limit. Should this happen in Color QuickDraw, the QDError
function returns the result code regionTooBigError
. Since the resulting region is potentially corrupt, the CloseRgn
function returns an empty region if it detects QDError
has returned regionTooBigError
.
The CloseRgn
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Obtains the index of the best available approximation for a given color in the color table of the current GDevice
data structure. This function is used only by system software. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
long Color2Index ( const RGBColor *myColor );
A pointer to the RGB color value to be approximated.
The index of the best approximation for the given color that is available in the color table of the current GDevice
data structure. Note that Color2Index
returns a long integer, in which the low-order word is the index value; the high-order word contains zeros.
You should not call Color2Index
from within a custom search function (described in ColorSearchProcPtr
).
QuickdrawAPI.h
Sets the foreground color for all printing in the current graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ColorBit ( short whichBit );
An integer specifying the plane to draw into.
The ColorBit
function is called by printing software for a color printer (or other color-imaging software) to set the GrafPort
structure’s colorBit
field to the value in the whichBit
parameter. This value tells QuickDraw which plane of the color picture to draw into. QuickDraw draws into the plane corresponding to the bit number specified by the whichBit
parameter. Since QuickDraw can support output devices that have up to 32 bits of color information per pixel, the possible range of values for whichBit
is 0 through 31. The initial value of the colorBit
field is 0.
QuickdrawAPI.h
Copies a portion of a bitmap or a pixel map from one graphics port or offscreen graphics world into another graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void CopyBits ( const BitMap *srcBits, const BitMap *dstBits, const Rect *srcRect, const Rect *dstRect, short mode, RgnHandle maskRgn );
The source BitMap
structure.
The destination BitMap
structure.
The source rectangle.
The destination rectangle.
One of the eight source modes in which the copy is to be performed. See “Source, Pattern, and Arithmetic Transfer Mode Constants.” The CopyBits
function always dithers images when shrinking them between pixel maps on direct devices.
When transferring pixels from a source pixel map to a destination pixel map, color QuickDraw interprets the source mode constants differently than basic QuickDraw does.
When you use CopyBits
on a computer running color QuickDraw, you can also specify one of the transfer modes in the mode
parameter.
A region to use as a clipping mask. You can pass a region handle to specify a mask region the resulting image is always clipped to this mask region and to the boundary rectangle of the destination bitmap. If the destination bitmap is the current graphics port’s bitmap, it is also clipped to the intersection of the graphics port’s clipping region and visible region. If you do not want to clip to a masking region, just pass NULL
for this parameter.
The CopyBits
function transfers any portion of a bitmap between two basic graphics ports, or any portion of a pixel map between two color graphics ports. Use CopyBits
to move offscreen graphic images into an onscreen window, to blend colors for the image in a pixel map, and to shrink and expand images.
Specify a source bitmap in the srcBits
parameter and a destination bitmap in the dstBits
parameter. When copying images between color graphics ports, you must coerce each CGrafPort
structure to a GrafPort
structure, dereference the portBits
fields of each, and then pass these “bitmaps” in the srcBits
and dstBits
parameters. If your application copies a pixel image from a color graphics port called MyColorPort
, for example, you could specify (* GrafPtr(MyColorPort)).portBits
in the srcBits
parameter. In a CGrafPort
structure, the high 2 bits of the portVersion
field are set. This field, which shares the same position in a CGrafPort
structure as the portBits.rowBytes
field in a GrafPort
structure, indicates to CopyBits
that you have passed it a handle to a pixel map rather than a bitmap.
Using the srcRect
and dstRect
parameters, you can specify identically or differently sized source and destination rectangles; for differently sized rectangles, CopyBits
scales the source image to fit the destination. If the bit image is a circle in a square source rectangle, and the destination rectangle is not square, the bit image appears as an oval in the destination. When you specify rectangles in the srcRect
and dstRect
parameters, use the local coordinate systems of, respectively, the source and destination graphics ports.
The CopyDeepMask
function combines the functions of the CopyBits
and CopyMask
functions.
When you use the CopyBits
function to transfer an image between pixel maps, the source and destination images may be of different pixel depths, of different sizes, and they may have different color tables. However, CopyBits
assumes that the destination pixel map uses the same color table as the color table for the current GDevice
structure. (This is because the Color Manager requires an inverse table for translating the color table from the source pixel map to the destination pixel map.)
The CopyBits
function applies the foreground and background colors of the current graphics port to the image in the destination pixel map (or bitmap), even if the source image is a bitmap. This causes the foreground color to replace all black pixels in the destination and the background color to replace all white pixels. To avoid unwanted coloring of the image, use the RGBForeColor
function to set the foreground to black and use the RGBBackColor
function to set the background to white before calling CopyBits
.
The source bitmap or pixel map must not occupy more memory than half the available stack space. The stack space required by CopyBits
is roughly five times the value of the rowBytes
field of the source pixel map: one rowBytes
value for the pixel map (or bitmap), an additional rowBytes
value for dithering, another rowBytes
value when stretching or shrinking the source pixel map into the destination, another rowBytes
value for any color map changing, and a fifth additional rowBytes
value for any color aliasing. If there is insufficient memory to complete a CopyBits
operation in Color QuickDraw, the QDError
function returns the result code –143.
If you use CopyBits
to copy between two graphics ports that overlap, you must first use the LocalToGlobal
function to convert to global coordinates, and then specify the global variable screenBits
for both the srcBits
and dstBits
parameters.
The CopyBits
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
If you are reading directly from a NuBus video card with a base address of Fs00000 and there is not a card in the slot (s–1) below it, CopyBits
reads addresses less than the base address of the pixel map. This causes a bus error. To work around the problem, remap the baseAddr
field of the pixel map in your video card to at least 20 bytes above the NuBus boundary; an address link of Fs000020 precludes the problem.
QuickdrawAPI.h
Uses a mask when copying bitmaps or pixel maps between graphics ports (or from an offscreen graphics world into a graphics port). (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void CopyDeepMask ( const BitMap *srcBits, const BitMap *maskBits, const BitMap *dstBits, const Rect *srcRect, const Rect *maskRect, const Rect *dstRect, short mode, RgnHandle maskRgn );
The source BitMap
structure.
The masking BitMap
structure.
The destination BitMap
structure. The result is clipped to the mask region that you specify in the maskRgn
parameter, and to the boundary rectangle that you specify in the dstRect
parameter.
The source rectangle.
The mask rectangle. This must be the same size as the rectangle passed in the srcRect
parameter. The rectangle you pass here selects the portion of the bitmap or pixel map that you specify in the maskBits
parameter to use as the mask.
The destination rectangle.
The source mode.
The mask clipping region. If you do not want to clip to the mask region, specify NULL
.
CopyDeepMask
combines the effects of the CopyBits
and CopyMask
functions. You specify a mask to CopyDeepMask
so that it transfers the source image to the destination image only where the bits of the mask are set to 1. Use CopyDeepMask
to move offscreen graphic images into an onscreen window, to blend colors for the image in a pixel map, and to shrink and expand images.
When copying images between color graphics ports, you must coerce each port’s CGrafPort
structure to a GrafPort
structure, dereference the portBits
fields of each, and then pass these “bitmaps” in the srcBits
and dstBits
parameters. If your application copies a pixel image from a color graphics port called MyColorPort
, for example, you could specify (* GrafPtr(MyColorPort)).portBits
in the srcBits
parameter. The transfer can be performed in any of the transfer modes—with or without adding the ditherCopy
constant—that are available to CopyBits
.
Using the srcRect
and dstRect
parameters, you can specify identically or differently sized source and destination rectangles; for differently sized rectangles, CopyDeepMask
scales the source image to fit the destination. When you specify rectangles in the srcRect
and dstRect
parameters, use the local coordinate systems of, respectively, the source and destination graphics ports.
If you specify pixel maps to CopyDeepMask
, they may range from 1 to 32 pixels in depth. The pixel depth of the mask that you specify in the maskBits
parameter is applied as a filter between the source and destination pixel maps that you specify in the srcBits
and dstBits
parameters. A black mask pixel value means that the copy operation is to take the source pixel a white value means that the copy operation is to take the destination pixel. Intermediate values specify a weighted average, which is calculated on a color component basis. For each pixel’s color component value, the calculation is
(1 – mask) x source + (mask) x destination
Thus high mask values for a pixel’s color component reduce that component’s contribution from the source PixMap
structure.
As with the CopyMask
function, calls to CopyDeepMask
are not recorded in pictures and do not print.
See the list of special considerations for CopyBits
; these considerations also apply to CopyDeepMask
.
The CopyDeepMask
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Copies a bit or pixel image from one graphics port or offscreen graphics world into another graphics port only where the bits in a mask are set to 1. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void CopyMask ( const BitMap *srcBits, const BitMap *maskBits, const BitMap *dstBits, const Rect *srcRect, const Rect *maskRect, const Rect *dstRect );
The source BitMap
structure.
The mask BitMap
structure.
The destination BitMap
structure.
The source rectangle.
The mask rectangle. This must be the same size as the rectangle passed in the srcRect
parameter. The rectangle you pass in this parameter selects the portion of the bitmap or pixel map that you specify in the maskBits
parameter to use as the mask.
The destination rectangle.
The CopyMask
function copies the source bitmap or pixel map that you specify in the srcBits
parameter to a destination bitmap or pixel map that you specify in the dstBits
parameter—but only where the bits of the mask bitmap or pixel map that you specify in the maskBits
parameter are set to 1. When copying images between color graphics ports, you must coerce each CGrafPort
structure to a GrafPort
structure, dereference the portBits
fields of each, and then pass these “bitmaps” in the srcBits
and dstBits
parameters. If your application copies a pixel image from a color graphics port called MyColorPort
, for example, you could specify (* GrafPtr(MyColorPort)).portBits
in the srcBits
parameter.
Using the srcRect
and dstRect
parameters, you can specify identically or differently sized source and destination rectangles; for differently sized rectangles, CopyMask
scales the source image to fit the destination. When you specify rectangles in the srcRect
and dstRect
parameters, use the local coordinate systems of, respectively, the source and destination graphics ports.
If you specify pixel maps to CopyMask
, they may range from 1 to 32 pixels in depth. The pixel depth of the mask that you specify in the maskBits
parameter is applied as a filter between the source and destination pixel maps that you specify in the srcBits
and dstBits
parameters. A black mask pixel value means that the copy operation is to take the source pixel a white value means that the copy operation is to take the destination pixel. Intermediate values specify a weighted average, which is calculated on a color component basis. For each pixel’s color component value, the calculation is
(1 – mask) x source + (mask) x destination
Thus high mask values for a pixel’s color component reduce that component’s contribution from the source PixMap
structure.
Use the bitmap returned by CalcMask
as the mask in order to implement a mask copy similar to that performed by the MacPaint lasso tool. In the same way, you can use the pixel map returned by the CalcCMask
function.
The CopyDeepMask
function combines the functions of the CopyMask
and CopyBits
functions.
Calls to CopyMask
are not recorded in pictures and do not print.
See the list of special considerations for CopyBits
; these considerations also apply to CopyMask
.
The CopyMask
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Duplicates a PixMap
structure. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void CopyPixMap ( PixMapHandle srcPM, PixMapHandle dstPM );
A handle to the PixMap
structure to be copied.
On return, a handle to the duplicated PixMap
structure.
Typically, you do not need to call this function in your application code, because the CopyPixMap
function copies the contents of the source PixMap
structure to the destination PixMap
structure. The contents of the color table are copied, so the destination PixMap
has its own copy of the color table. Because the baseAddr
field of the PixMap
structure is a pointer, the pointer, but not the image itself, is copied.
QuickdrawAPI.h
Copies the contents of one pixel pattern to another. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void CopyPixPat ( PixPatHandle srcPP, PixPatHandle dstPP );
A handle to a source pixel pattern, the contents of which you want to copy.
A handle to a destination pixel pattern, into which you want to copy the contents of the pixel pattern in the srcPP
parameter.
The CopyPixPat
function copies all of the fields in the source PixPat
structure, including the contents of the data handle, expanded data handle, expanded map, pixel map handle, and color table.
Generally, your application should create a pixel pattern in a 'ppat'
resource, instead of using this function.
QuickdrawAPI.h
Creates a Quartz 2D drawing environment associated with a graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Not Recommended
OSStatus CreateCGContextForPort ( CGrafPtr inPort, CGContextRef *outContext );
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. Printing ports are not supported—if you specify a printing port, this function does nothing and returns a non-zero result code.
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 release this context when you no longer need it.
A result code. If noErr
, the context was successfully created.
This function is not recommended in Mac OS X version 10.1 and later. For information about its replacement, see QDBeginCGContext
.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
CGrafPtr CreateNewPort ( void );
QuickdrawAPI.h
Creates a graphics port associated with a display. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
CGrafPtr CreateNewPortForCGDisplayID ( UInt32 inCGDisplayID );
A display identifier. If the identifier is not valid, the main display is used instead. For information about finding displays, see Quartz Display Services Reference.
A new display port. The portBounds
rectangle is the same size as the display. When you are finished using the port, you should call DisposePort
to release it.
This function returns a graphics port used to draw directly to a display. The pixel map for the new port is taken from the GDevice
record corresponding to the display. There is no back buffer associated with the port.
Before calling this function, you should capture the display. For information about capturing displays, see Quartz Display Services Reference.
You should not call this function and then attempt to create a Quartz drawing environment inside the port. Instead, applications using Quartz 2D can call CGDisplayGetDrawingContext
to obtain a context suitable for drawing directly to a captured display.
QuickdrawAPI.h
Signals QuickDraw that the content of a ColorTable
structure has been modified. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void CTabChanged ( CTabHandle ctab );
A handle to the ColorTable
structure changed by your application.
The CTabChanged
function calls the function GetCTSeed
and gets a new, unique identifier in the ctSeed
field of the ColorTable
structure, and notifies QuickDraw of the change.
Your application should never need to directly modify a ColorTable
structure and use the CTabChanged
function; instead, your application should use the QuickDraw functions provided for manipulating the values in a ColorTable
structure.
The CTabChanged
function may move or purge memory in the application heap; do not call the CTabChanged
function at interrupt time.
QDOffscreen.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSErr CursorComponentChanged ( ComponentInstance ci );
A result code.
This function is not implemented on Mac OS X.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSErr CursorComponentSetData ( ComponentInstance ci, long data );
A result code.
This function is not implemented on Mac OS X.
QuickdrawAPI.h
Removes a custom complement function from the current GDevice
data structure’s list of complement functions. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DelComp ( ColorComplementUPP compProc );
A pointer to the complement function, ColorComplementProcPtr
, to be deleted. DelComp
disposes of the chain element, but does nothing to the ProcPtr
data structure.
QuickdrawAPI.h
Removes a custom search function from the current GDevice
data structure’s list of search functions. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DelSearch ( ColorSearchUPP searchProc );
A pointer to the custom search function, ColorSearchProcPtr
to be deleted. DelSearch
disposes of the chain element, but does nothing to the ProcPtr
data structure.
QuickdrawAPI.h
Subtracts the coordinates of one point from another. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
long DeltaPoint ( Point ptA, Point ptB );
The first point.
The second point, the coordinates of which are to be subtracted from the coordinates of the first point.
A 32-bit value that contains the differences between the coordinates of the points p1
and p2
. The vertical difference is returned in the high 16 bits and the horizontal difference is returned in the low 16 bits.
You should not cast the result to a Point
data structure. Instead, use HiWord
and LoWord
to obtain the horizontal and vertical differences.
For example:
Point pointDiff; |
SInt32 difference = DeltaPoint(p1, p2); |
pointDiff.h = LoWord(difference); |
pointDiff.v = HiWord(difference); |
While DeltaPoint
is supported in Carbon, you can achieve the same result in a more direct manner using the function SubPt
.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use DeltaPoint
instead.)
long deltapoint ( Point *ptA, Point *ptB );
QuickdrawAPI.h
Draws images that are optimized for every screen they cross. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DeviceLoop ( RgnHandle drawingRgn, DeviceLoopDrawingUPP drawingProc, long userData, DeviceLoopFlags flags );
A handle to the region in which you will draw; this drawing region uses coordinates that are local to its graphics port.
A pointer to your own drawing function.
Any additional data that you wish to supply to your drawing function.
One or more members of the set of flags defined by the “ Device Loop Flags” data type. if you want to use the default behavior of DeviceLoop
, specify an empty set ([]) in this parameter.
The DeviceLoop
function searches for graphics devices that intersect your window’s drawing region, and it calls your drawing function for each dissimilar video device it finds.
Because DeviceLoop
provides your drawing function with the pixel depth and other attributes of each video device, your drawing function can optimize its drawing for each video device.
See DeviceLoopDrawingProcPtr
for a description of the drawing function you must provide for the drawingProc
parameter.
The DeviceLoop
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Disposes of all structures allocated by the GetCCursor
function. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeCCursor ( CCrsrHandle cCrsr );
A handle to the color cursor to be disposed of.
Use DisposeCCursor
for each call to the GetCCursor
function.
The DisposeCCursor
function is also available as the DisposCCursor
function.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeColorComplementUPP ( ColorComplementUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeColorSearchUPP ( ColorSearchUPP userUPP );
QuickdrawTypes.h
Disposes a ColorTable
structure. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeCTable ( CTabHandle cTable );
A handle to a ColorTable
structure to dispose of.
The DisposeCTable procedure disposes of the ColorTable record whose handle you pass in the cTable parameter.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeDeviceLoopDrawingUPP ( DeviceLoopDrawingUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeDragGrayRgnUPP ( DragGrayRgnUPP userUPP );
QuickdrawTypes.h
Disposes of a GDevice
structure, releases the space allocated for it, and disposes of all the data structures allocated for it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeGDevice ( GDHandle gdh );
A handle to the GDevice
structure.
Generally, you should never need to use this function. Color QuickDraw calls this function when appropriate. The DisposeGDevice
function is also available as the DisposGDevice
function.
When your application uses the DisposeGWorld
function to dispose of an offscreen graphics world, DisposeGDevice
disposes of its GDevice
structure.
QuickdrawAPI.h
Disposes of all the memory allocated for an offscreen graphics world. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeGWorld ( GWorldPtr offscreenGWorld );
A pointer to an offscreen graphics world. In this parameter, pass the pointer returned to your application by the NewGWorld
function when you created the offscreen graphics world.
The DisposeGWorld
function disposes of all the memory allocated for the specified offscreen graphics world, including the pixel map, color table, pixel image, and GDevice
structure (if one was created).
Call DisposeGWorld
only when your application no longer needs the pixel image associated with this offscreen graphics world. If this offscreen graphics world was the current device, the current device is reset to the device stored in the global variable MainDevice
.
QDOffscreen.h
Disposes a PixMap
structure and its color table. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposePixMap ( PixMapHandle pm );
A handle to the PixMap
structure to be disposed of.
The CloseCPort
function calls DisposePixMap
.
Your application typically does not need to call this function. This function is also available as DisposPixMap
.
If your application uses DisposePixMap
, take care that it does not dispose of a PixMap
structure whose color table is the same as the current device’s CLUT.
QuickdrawAPI.h
Releases the storage allocated to a pixel pattern. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposePixPat ( PixPatHandle pp );
A handle to the pixel pattern to be disposed of.
The DisposePixPat
function disposes of the data handle, expanded data handle, and pixel map handle allocated to the pixel pattern that you specify in the ppat
parameter.
The DisposePixPat
function is also available as the DisposPixPat
function.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposePort ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDArcUPP ( QDArcUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDBitsUPP ( QDBitsUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDCommentUPP ( QDCommentUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDGetPicUPP ( QDGetPicUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDJShieldCursorUPP ( QDJShieldCursorUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDLineUPP ( QDLineUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDOpcodeUPP ( QDOpcodeUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDOvalUPP ( QDOvalUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDPolyUPP ( QDPolyUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDPutPicUPP ( QDPutPicUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDRectUPP ( QDRectUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDRgnUPP ( QDRgnUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDRRectUPP ( QDRRectUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDStdGlyphsUPP ( QDStdGlyphsUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDTextUPP ( QDTextUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeQDTxMeasUPP ( QDTxMeasUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeRegionToRectsUPP ( RegionToRectsUPP userUPP );
QuickdrawAPI.h
Disposes an offscreen graphics world. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DisposeScreenBuffer ( PixMapHandle offscreenPixMap );
A handle to an existing offscreen PixMap
structure.
Generally, applications do not need to use DisposeScreenBuffer
. The DisposeGWorld
function uses the DisposeScreenBuffer
function when disposing of an offscreen graphics world.
The DisposeScreenBuffer
function disposes of the memory allocated for the base address of an offscreen pixel image.
QDOffscreen.h
Draws a picture on any type of output device. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void DrawPicture ( PicHandle myPicture, const Rect *dstRect );
A handle to the picture to be drawn. You must access a picture through its handle.
When creating pictures, the OpenCPicture
and OpenPicture
functions return their handles. You can use the GetPicture
function to get a handle to a QuickDraw picture stored in a 'PICT'
resource. To get a handle to a QuickDraw picture stored in a 'PICT'
file, you must use File Manager functions. To get a picture stored in the scrap, use the Scrap Manager function GetScrap
to get a handle to its data and then coerce this handle to one of type PicHandle
.
A destination rectangle, specified in coordinates local to the current graphics port, in which to draw the picture. The DrawPicture
function shrinks or expands the picture as necessary to align the borders of its bounding rectangle with the rectangle you specify in this parameter. To display a picture at a resolution other than that at which it was created, your application should compute an appropriate destination rectangle by scaling its width and height by the following factor:
scale factor = destination resolution / source resolution
For example, if a picture was created at 300 dpi and you want to display it at 75 dpi, then your application should compute the destination rectangle width and height as 1/4 of those of the picture’s bounding rectangle. Use the GetPictInfo
function to gather information about a picture. The PictInfo
structure returned by GetPictInfo
returns the picture’s resolution in its hRes
and vRes
fields. The sourceRect
field contains the bounding rectangle for displaying the image at its optimal resolution.
Within the rectangle that you specify in the dstRect
parameter, the DrawPicture
function draws the picture that you specify in the myPicture
parameter.
The DrawPicture
function passes any picture comments to the StdComment
function pointed to by the commentProc
field of the CQDProcs
or QDProcs
structure, which in turn is pointed to by the grafProcs
field of a CGrafPort
or GrafPort
structure. The default StdComment
function provided by QuickDraw does no comment processing whatsoever. If you want to process picture comments when drawing a picture, use the SetStdCProcs
function to assist you in changing the CQDProcs
structure and use the SetStdProcs
function to assist you in changing the QDProcs
structure.
Always use the ClipRect
function to specify a clipping region appropriate for your picture before defining it with the OpenCPicture
(or OpenPicture
) function. If you do not use ClipRect
to specify a clipping region, OpenCPicture
uses the clipping region specified in the current graphics port. If the clipping region is very large (as it is when a graphics port is initialized) and you want to scale the picture, the clipping region can become invalid when DrawPicture
scales the clipping region—in which case, your picture will not be drawn. On the other hand, if the graphics port specifies a small clipping region, part of your drawing may be clipped when DrawPicture
draws it. Setting a clipping region equal to the port rectangle of the current graphics port always sets a valid clipping region.
When it scales, DrawPicture
changes the size of the font instead of scaling the bits. However, the widths used by bitmap fonts are not always linear. For example, the 12-point width isn’t exactly 1/2 of the 24-point width. This can cause lines of text to become slightly longer or shorter as the picture is scaled. The difference is often insignificant, but if you are trying to draw a line of text that fits exactly into a box (a spreadsheet cell, for example), the difference can become noticeable to the user—most typically, at print time. The easiest way to avoid such problems is to specify a destination rectangle that is the same size as the bounding rectangle for the picture. Otherwise, your application may need to directly process the opcodes in the picture instead of using DrawPicture
.
You may also have disappointing results if the fonts contained in an image are not available on the user’s system. Before displaying a picture, your application may want to use the Picture Utilities to determine what fonts are contained in the picture, and then use Font Manager functions to determine whether the fonts are available on the user’s system. If they are not, you can use Dialog Manager functions to display an alert box warning the user of display problems.
If there is insufficient memory to draw a picture in Color QuickDraw, the QDError
function returns the result code noMemForPictPlaybackErr
.
The DrawPicture
function may move or purge memory.
QuickdrawAPI.h
Erases a wedge. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void EraseArc ( const Rect *r, short startAngle, short arcAngle );
The rectangle that defines an oval’s boundaries.
The angle indicating the start of the arc.
The angle indicating the arc’s extent.
Using the patCopy
pattern mode, the EraseArc
function draws a wedge of the oval bounded by the rectangle that you specify in the r
parameter with the background pattern for the current graphics port. As in FrameArc
, use the startAngle
and arcAngle
parameters to define the arc of the wedge.
This function leaves the location of the graphics pen unchanged.
The EraseArc
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Erases an oval. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void EraseOval ( const Rect *r );
The rectangle that defines the oval’s boundary.
Using the background pattern for the current graphics port and the patCopy
pattern mode, the EraseOval
function draws the interior of an oval just inside the bounding rectangle that you specify in the r
parameter. This effectively erases the oval bounded by the specified rectangle.
This function leaves the location of the graphics pen unchanged.
The EraseOval
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Erases a polygon. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ErasePoly ( PolyHandle poly );
A handle to the polygon to erase. The OpenPoly
function returns this handle when you first create the polygon.
Using the patCopy
pattern mode, the ErasePoly
function draws the interior of the polygon whose handle you pass in the poly
parameter with the background pattern for the current graphics port.
This function leaves the location of the graphics pen unchanged.
This function temporarily converts the polygon into a region to perform their operations. The amount of memory required for this temporary region may be far greater than the amount required by the polygon alone.
You can estimate the size of this region by scaling down the polygon with the MapPoly
, converting the polygon into a region, checking the region’s size with the Memory Manager function GetHandleSize
, and multiplying that value by the factor by which you scaled the polygon.
The result of this graphics operation is undefined whenever any horizontal or vertical line drawn through the polygon would intersect the polygon’s outline more than 50 times.
The ErasePoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Erases a rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void EraseRect ( const Rect *r );
The rectangle to erase.
Using the patCopy
pattern mode, the EraseRect
function draws the interior of the rectangle that you specify in the r
parameter with the background pattern for the current graphics port. This effectively erases the rectangle, making the shape blend into the background pattern of the graphics port. For example, use EraseRect
to erase the port rectangle for a window before redrawing into the window.
This function leaves the location of the graphics pen unchanged.
The EraseRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Erases a region. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void EraseRgn ( RgnHandle rgn );
The region to erase.
Using the patCopy
pattern mode, the EraseRgn
function draws the interior of the region whose handle you pass in the rgn
parameter with the background pattern for the current graphics port.
This function leaves the location of the graphics pen unchanged.
This function depends on the local coordinate system of the current graphics port. If you draw a region in a graphics port different from the one in which you defined the region, it may not appear in the proper position in the graphics port.
If any horizontal or vertical line drawn through the region would intersect the region’s outline more than 50 times, the results of this graphics operation are undefined.
The EraseRgn
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Erases a rounded rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void EraseRoundRect ( const Rect *r, short ovalWidth, short ovalHeight );
The rectangle that defines the rounded rectangle’s boundaries.
The width of the oval defining the rounded corner.
The height of the oval defining the rounded corner.
Using the patCopy
pattern mode, the EraseRoundRect
function draws the interior of the rounded rectangle bounded by the rectangle that you specify in the r
parameter with the background pattern of the current graphics port. This effectively erases the rounded rectangle. Use the ovalWidth
and ovalHeight
parameters to specify the diameters of curvature for the corners of the rounded rectangle.
This function leaves the location of the graphics pen unchanged.
The EraseRoundRect
function may move or purge memory blocks in the application; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a wedge with any available bit pattern. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillArc ( const Rect *r, short startAngle, short arcAngle, const Pattern *pat );
The rectangle that defines an oval’s boundaries.
The angle indicating the start of the arc.
The bit pattern to use for the fill.
The angle indicating the arc’s extent.
Using the patCopy
pattern mode and the pattern defined in the Pattern
structure that you specify in the pat
parameter, the FillArc
function draws a wedge of the oval bounded by the rectangle that you specify in the r
parameter. As in FrameArc
use the startAngle
and arcAngle
parameters to define the arc of the wedge.
This function leaves the location of the graphics pen unchanged.
Use GetPattern
and GetIndPattern
to get a pattern stored in a resource.
Use PaintArc
to draw a wedge with the pen pattern for the current graphics port.
To fill a wedge with a pixel pattern, use the FillCArc
function.
The FillArc
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a wedge with the given pixel pattern, using the patCopy
pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillCArc ( const Rect *r, short startAngle, short arcAngle, PixPatHandle pp );
The rectangle that defines the oval’s boundaries.
The angle indicating the start of the arc.
The angle indicating the arc’s extent.
A handle to the PixPat
structure for the pixel pattern to be used for the fill.
Use the startAngle
and arcAngle
parameters to define the arc of the wedge. This function ignores the pnPat
, pnMode
, and bkPat
fields of the current graphics port and leaves the pen location unchanged.
The FillCArc
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills an oval with the given pixel pattern, using the patCopy
pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillCOval ( const Rect *r, PixPatHandle pp );
The rectangle containing the oval to be filled.
A handle to the PixPat
structure for the pixel pattern to be used for the fill.
This function ignores the pnPat
, pnMode
, and bkPat
fields of the current graphics port and leaves the pen location unchanged.
The FillCOval
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a polygon with the given pixel pattern, using the patCopy
pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillCPoly ( PolyHandle poly, PixPatHandle pp );
A handle to the polygon to be filled.
A handle to the PixPat
structure for the pixel pattern to be used for the fill.
This function ignores the pnPat
, pnMode
, and bkPat
fields of the current graphics port and leaves the pen location unchanged.
The FillCPoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a rectangle with the given pixel pattern, using the patCopy
pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillCRect ( const Rect *r, PixPatHandle pp );
The rectangle to be filled.
A handle to the PixPat
structure for the pixel pattern to be used for the fill.
This function ignores the pnPat
, pnMode
, and bkPat
fields of the current graphics port and leaves the pen location unchanged.
The FillCRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a region with the given pixel pattern, using the patCopy
pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillCRgn ( RgnHandle rgn, PixPatHandle pp );
A handle to the region to be filled.
A handle to the PixPat
structure for the pixel pattern to be used for the fill.
This function ignores the pnPat
, pnMode
, and bkPat
fields of the current graphics port and leaves the pen location unchanged.
The FillCRgn
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a rounded rectangle with the given pixel pattern, using the patCopy
pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillCRoundRect ( const Rect *r, short ovalWidth, short ovalHeight, PixPatHandle pp );
The rectangle that defines the rounded rectangle’s boundaries.
The width of the oval defining the rounded corner.
The height of the oval defining the rounded corner.
A handle to the PixPat
structure for the pixel pattern to be used for the fill.
Use the ovalWidth
and ovalHeight
parameters to specify the diameters of curvature for the corners. This function ignores the pnPat
, pnMode
, and bkPat
fields of the current graphics port and leaves the pen location unchanged.
The FillCRoundRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills an oval with any available bit pattern. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillOval ( const Rect *r, const Pattern *pat );
The rectangle that defines the oval’s boundaries.
The bit pattern to use for the fill.
Using the patCopy
pattern mode and the bit pattern defined in the Pattern
structure that you specify in the pat
parameter, the FillOval
function draws the interior of an oval just inside the bounding rectangle that you specify in the r
parameter. The pen location does not change.
Use GetPattern
and GetIndPattern
, to get a pattern stored in a resource. Use the PaintOval
function to draw the interior of an oval with the pen pattern for the current graphics port.
To fill an oval with a pixel pattern, use the FillCOval
function.
The FillOval
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a polygon with any available bit pattern. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillPoly ( PolyHandle poly, const Pattern *pat );
A handle to the polygon to fill. The OpenPoly
function returns this handle when you first create the polygon.
The bit pattern to use for the fill.
Using the patCopy
pattern mode, the FillPoly
function draws the interior of the polygon whose handle you pass in the poly
parameter with the pattern defined in the Pattern
structure that you specify in the pat
parameter.
This function leaves the location of the graphics pen unchanged.
This function temporarily converts the polygon into a region to perform their operations. The amount of memory required for this temporary region may be far greater than the amount required by the polygon alone.
You can estimate the size of this region by scaling down the polygon with the MapPoly
, converting the polygon into a region, checking the region’s size with the Memory Manager function GetHandleSize
, and multiplying that value by the factor by which you scaled the polygon.
The result of this graphics operation is undefined whenever any horizontal or vertical line drawn through the polygon would intersect the polygon’s outline more than 50 times.
Use GetPattern
and GetIndPattern
to get a pattern stored in a resource.
Use PaintPoly
to draw the interior of a polygon with the pen pattern for the current graphics port. To fill a polygon with a pixel pattern, use the FillCPoly
function.
The FillPoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a rectangle with any available bit pattern. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillRect ( const Rect * r, const Pattern * pat );
The rectangle to fill.
The bit pattern to use for the fill.
Using the patCopy
pattern mode, the FillRect
function draws the interior of the rectangle that you specify in the r
parameter with the pattern defined in the Pattern
structure that you specify in the pat
parameter. This function leaves the pen location unchanged.
Use GetPattern
and GetIndPattern
, to get a pattern stored in a resource.
Use the PaintRect
to draw the interior of a rectangle with the pen pattern for the current graphics port. To fill a rectangle with a pixel pattern, use the FillCRect
function.
The FillRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a region with any available bit pattern. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillRgn ( RgnHandle rgn, const Pattern * pat );
A handle to the region to fill.
The bit pattern to use for the fill.
Using the patCopy
pattern mode, the FillRgn
function draws the interior of the region with the pattern defined in the Pattern
structure that you specify in the pat
parameter.
This function leaves the location of the graphics pen unchanged.
This function depends on the local coordinate system of the current graphics port. If you draw a region in a graphics port different from the one in which you defined the region, it may not appear in the proper position in the graphics port.
If any horizontal or vertical line drawn through the region would intersect the region’s outline more than 50 times, the results of this graphics operation are undefined.
Use GetPattern
and GetIndPattern
to get a pattern stored in a resource.
Use PaintRgn
to draw the interior of a region with the pen pattern for the current graphics port. To fill a region with a pixel pattern, use the FillCRegion
function.
The FillRgn
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Fills a rounded rectangle with any available bit pattern. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FillRoundRect ( const Rect *r, short ovalWidth, short ovalHeight, const Pattern *pat );
The rectangle that defines the rounded rectangle’s boundaries.
The width of the oval defining the rounded corner.
The height of the oval defining the rounded corner.
The bit pattern to use for the fill.
Using the patCopy
pattern mode, the FillRoundRect
function draws the interior of the rounded rectangle bounded by the rectangle that you specify in the r
parameter with the bit pattern defined in the Pattern
structure that you specify in the pat
parameter. Use the ovalWidth
and ovalHeight
parameters to specify the diameters of curvature for the corners. The pen location does not change.
To fill a rounded rectangle with a pixel pattern, use the FillCRoundRect
function.
Use GetPattern
and GetIndPattern
to get a pattern stored in a resource. Use PaintRoundRect
to draw the interior of a rounded rectangle with the pen pattern for the current graphics port.
The FillRoundRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Changes the color of the “ink” used for framing, painting, and filling on computers that support only basic QuickDraw. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ForeColor ( long color );
One of eight color values. See “Color Constants.”
By default, the foreground color of a GrafPort
is black.
The ForeColor
function sets the foreground color for the current graphics port to the color that you specify in the color
parameter. When you draw with the patCopy
and srcCopy
transfer modes, for example, black pixels are drawn in the color you specify with ForeColor
.
When printing, use the ColorBit
function to set the foreground color.
All nonwhite colors appear as black on black-and-white screens. Before you use ForeColor
, use the DeviceLoop
function to determine the color characteristics of the current screen.
The ForeColor
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
In System 7, you may instead use the color QuickDraw function RGBForeColor
.
QuickdrawAPI.h
Draws an arc of the oval that fits inside a rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FrameArc ( const Rect *r, short startAngle, short arcAngle );
The rectangle that defines an oval’s boundaries.
The angle indicating the start of the arc.
The angle indicating the arc’s extent.
Using the pattern, pattern mode, and size of the graphics pen for the current graphics port, the FrameArc
function draws an arc of the oval bounded by the rectangle that you specify in the r
parameter. Use the startAngle
parameter to specify where the arc begins as modulo 360. Use the arcAngle
parameter to specify how many degrees the arc covers. Specify whether the angles are in positive or negative degrees a positive angle goes clockwise, while a negative angle goes counterclockwise. Zero degrees is at 12 o’clock high, 90 (or –270) is at 3 o’clock, 180 (or –180) is at 6 o’clock, and 270 (or –90) is at 9 o’clock. Measure other angles relative to the bounding rectangle.
A line from the center of the rectangle through its upper-right corner is at 45, even if the rectangle is not square a line through the lower-right corner is at 135, and so on.
The arc is as wide as the pen width and as tall as the pen height. The pen location does not change.
The FrameArc
function differs from other QuickDraw functions that frame shapes in that the arc is not mathematically added to the boundary of a region that’s open and being formed.
The FrameArc
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Draws an outline inside an oval. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FrameOval ( const Rect *r );
The rectangle that defines the oval’s boundary.
Using the pattern, pattern mode, and size of the graphics pen for the current graphics port, the FrameOval
function draws an outline just inside the oval with the bounding rectangle that you specify in the r
parameter. The outline is as wide as the pen width and as tall as the pen height. The pen location does not change.
If a region is open and being formed, the outside outline of the new oval is mathematically added to the region’s boundary.
The FrameOval
function may move or purge memory blocks in the application; do not call this function at interrupt time.
QuickdrawAPI.h
Draws the outline of a polygon. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FramePoly ( PolyHandle poly );
A handle to the polygon to draw. The OpenPoly
function returns this handle when you first create the polygon.
Using the current graphics port’s pen pattern, pattern mode, and size, the FramePoly
function plays back the line-drawing commands that define the polygon whose handle you pass in the poly
parameter.
The graphics pen hangs below and to the right of each point on the boundary of the polygon. Thus, the drawn polygon extends beyond the right and bottom edges of the polygon’s bounding rectangle (which is stored in the polyBBox
field of the Polygon
structure) by the pen width and pen height, respectively. All other graphics operations, such as painting a polygon with the PaintPoly
function, occur strictly within the boundary of the polygon.
If a polygon is open and being formed, FramePoly
affects the outline of the polygon just as if the line-drawing functions themselves had been called. If a region is open and being formed, the outside outline of the polygon being framed is mathematically added to the region’s boundary.
The result of this function is undefined whenever any horizontal or vertical line through the polygon would intersect the polygon’s outline more than 50 times.
The FramePoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Draws an outline inside a rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FrameRect ( const Rect * r );
The rectangle to frame.
Using the pattern, pattern mode, and size of the graphics pen for the current graphics port, the FrameRect
function draws an outline just inside the rectangle that you specify in the r
parameter. The outline is as wide as the pen width and as tall as the pen height. The pen location does not change.
If a region is open and being formed, the outside outline of the new rectangle is mathematically added to the region’s boundary.
The FrameRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Draws an outline inside a region. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FrameRgn ( RgnHandle rgn );
A handle to the region to frame.
Using the current graphics port’s pen pattern, pattern mode, and pen size, the FrameRgn
function draws an outline just inside the region whose handle you pass in the rgn parameter. The outline never goes outside the region boundary. The pen location does not change.
If a region is open and being formed, the outside outline of the region being framed is mathematically added to that region’s boundary.
This function depends on the local coordinate system of the current graphics port. If you draw a region in a graphics port different from the one in which you defined the region, it may not appear in the proper position in the graphics port.
If any horizontal or vertical line drawn through the region would intersect the region’s outline more than 50 times, the results of this graphics operation are undefined. The FrameRgn
function in particular requires that there would be no more than 25 such intersections.
The FrameRgn
function calls the functions CopyRgn
, InsetRgn
, and DiffRgn
, so FrameRgn
may temporarily use heap space that’s three times the size of the original region.
The FrameRgn
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Draws an outline inside a rounded rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void FrameRoundRect ( const Rect *r, short ovalWidth, short ovalHeight );
The rectangle that defines the rounded rectangle’s boundaries.
The width of the oval defining the rounded corner.
The height of the oval defining the rounded corner.
Using the pattern, pattern mode, and size of the graphics pen for the current graphics port, the FrameRoundRect
function draws an outline just inside the rounded rectangle bounded by the rectangle that you specify in the r
parameter. The outline is as wide as the pen width and as tall as the pen height. The pen location does not change.
Use the ovalWidth
and ovalHeight
parameters to specify the diameters of curvature for the corners of the rounded rectangle.
If a region is open and being formed, the outside outline of the new rounded rectangle is mathematically added to the region’s boundary.
The FrameRoundRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Notifies QuickDraw that the content of a GDevice
structure has been modified. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GDeviceChanged ( GDHandle gdh );
If your application changes the pmTable
field of the PixMap
structure specified in a GDevice
structure, call GDeviceChanged
. If your application changes the content of the ColorTable
structure referenced by the PixMap
structure, call both GDeviceChanged
and CTabChanged
.
Your application should never need to directly modify a GDevice
structure and use the GDeviceChanged
function; instead, your application should use the QuickDraw functions described in this book for manipulating the values in a GDevice
structure.
The GDeviceChanged
function may move or purge memory in the application heap; do not call the GDeviceChanged
function at interrupt time.
QDOffscreen.h
Obtains the background color of the current graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GetBackColor ( RGBColor *color );
On return, the RGBColor
structure for the current background color.
This function operates for graphics ports defined by both the GrafPort
and CGrafPort
structures. If the current graphics port is defined by a CGrafPort
structure, the returned value is taken directly from the rgbBkColor
field.
If the current graphics port is defined by a GrafPort
structure, then only eight possible colors can be returned. These eight colors are determined by the values in a global variable named QDColors
, which is a handle to a color table containing the current QuickDraw colors.
Use the RGBBackColor
function to change the background color.
QuickdrawAPI.h
Loads a color cursor resource into memory. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
CCrsrHandle GetCCursor ( short crsrID );
The resource ID of the cursor that you want to display.
A handle to the new CCrsr
structure. To display this cursor on the screen, call SetCCursor
. If a resource with the specified ID isn’t found, then this function returns a NULL
handle.
The GetCCursor
function creates a new CCrsr
structure and initializes it using the information in the ‘crsr’ resource with the specified ID.
Since the GetCCursor
function creates a new CCrsr
structure each time it is called, do not call the GetCCursor
function before each call to the SetCCursor
function. Unlike the way GetCursor
and SetCursor
are normally used, GetCCursor
does not dispose of or detach the resource, so resources of type 'crsr'
should typically be purgeable. Call the DisposeCCursor
function when you are finished using the color cursor created with GetCCursor
.
QuickdrawAPI.h
Determines the color of an individual pixel specified in the h
and v
parameters. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GetCPixel ( short h, short v, RGBColor *cPix );
The horizontal coordinate of the point at the upper-left corner of the pixel.
The vertical coordinate of the point at the upper-left corner of the pixel.
On return, the RGBColor
structure for the pixel color.
Use the SetCPixel
function to change the color of this pixel.
QuickdrawAPI.h
Obtains a color table stored in a 'clut'
resource. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
CTabHandle GetCTable ( short ctID );
The resource ID of a 'clut'
resource.
A handle to the color table. If the 'clut'
resource with that ID is not found, GetCTable
returns NULL
. Before you place this handle in the pmTable
field of a PixMap
structure, first use the DisposeCTable
function to dispose of the handle already there.
Before you modify a ColorTable
structure, change its ctSeed
field to invalidate it. To do this, use the CTabChanged
function.
The GetCTable
function recognizes a number of standard 'clut'
resource IDs. You can obtain the default grayscale color table for a given pixel depth by calling GetCTable
, adding 32 (decimal) to the pixel depth, and passing these values in the ctID
parameter:
A pixel depth of 1. Pass a resource ID of 33. Color table composition: black, white.
A pixel depth of 2. Pass a resource ID of 34. Color table composition: black, 33% gray, 66% gray, white.
A pixel depth of 4. Pass a resource ID of 36. Color table composition: black, 14 shades of gray, white.
A pixel depth of 8. Pass a resource ID of 40. Color table composition: black, 254 shades of gray, white.
For full color, obtain the default color tables by adding 64 to the pixel depth and passing these values in the ctID
parameter:
A pixel depth of 2. Pass a resource ID of 66. Color table composition: black, 50% gray, highlight color, white.
A pixel depth of 4. Pass a resource ID of 68. Color table composition: black, 14 colors including the highlight color, white.
A pixel depth of 8. Pass a resource ID of 72. Color table composition: black, 254 colors including the highlight color, white.
The GetCTable
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Obtains a unique seed value for a color table created by your application. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
long GetCTSeed ( void );
A unique seed value that you can use in the ctSeed
field of a color table created by your application. It is greater than the value stored in the constant minSeed
.
The seed value guarantees that the color table is recognized as distinct from the destination, and that color table translation is performed properly.
QuickdrawAPI.h
Loads a cursor resource into memory. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
CursHandle GetCursor ( short cursorID );
The resource ID for the cursor you want to display. You can supply one of the “Cursor ID Constants” to get a handle to one of the standard cursors.
A handle to a Cursor
structure for the cursor with the resource ID that you specify in the cursorID
parameter. If the resource cannot be read into memory, GetCursor
returns NULL
.
To get a handle to a color cursor, use the GetCCursor
function.
QuickdrawAPI.h
Obtains a handle to the first GDevice
structure in the device list. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle GetDeviceList ( void );
A handle to the first GDevice
structure in the global variable DeviceList
.
All existing GDevice
structures are linked together in the device list. After using this function to obtain a handle to the current GDevice
structure, your application can use the GetNextDevice
function to obtain a handle to the next GDevice
structure in the list.
The GetDeviceList
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Obtains the color of the foreground color for the current graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GetForeColor ( RGBColor *color );
On return, the RGBColor
structure for the current foreground color.
This function operates for graphics ports defined by both the GrafPort
and CGrafPort
structures. If the current graphics port is defined by a CGrafPort
structure, the returned value is taken directly from the rgbFgColor
field.
If the current graphics port is defined by a GrafPort
structure, then only eight possible RGB values can be returned. These eight values are determined by the values in a global variable named QDColors
, which is a handle to a color table containing the current QuickDraw colors.
Use the RGBForeColor
function to change the foreground color.
QuickdrawAPI.h
Obtains a handle to the GDevice
structure for the current device. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle GetGDevice ( void );
A handle to the current device.
At any given time, exactly one video device is the current device—that is, the one on which drawing is actually taking place.
Color QuickDraw stores a handle to the current device in the global variable TheGDevice
.
All existing GDevice
structures are linked together in the device list. After using this function to obtain a handle to the current GDevice
structure, your application can use the GetNextDevice
function to obtain a handle to the next GDevice
structure in the list.
You can also use the GetGWorld
function to get a handle to the GDevice
structure for the current device.
The GetGDevice
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Obtains a handle to the GDevice
structure associated with an offscreen graphics world. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle GetGWorldDevice ( GWorldPtr offscreenGWorld );
A pointer to an offscreen graphics world. The pointer returned to your application by the NewGWorld
function.
A handle to the GDevice
structure associated with the offscreen graphics world specified by the offscreenGWorld
parameter.
If you created the offscreen world by specifying the noNewDevice
flag, the GDevice
structure is for one of the screen devices or is the GDevice
structure that you specified to NewGWorld
or UpdateGWorld
.
If you point to a GrafPort
or CGrafPort
structure in the offscreenGWorld
parameter, GetGWorldDevice
returns the current device.
The GetGWorldDevice
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QDOffscreen.h
Obtains the pixel map created for an offscreen graphics world. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PixMapHandle GetGWorldPixMap ( GWorldPtr offscreenGWorld );
A pointer to an offscreen graphics world. Pass the pointer returned to your application by the NewGWorld
function when you created the offscreen graphics world.
A handle to the pixel map created for an offscreen graphics world. Your application can, in turn, pass the handle returned by GetGWorldPixMap
as a parameter to other QuickDraw functions that accept a handle to a pixel map.
On a system running only basic QuickDraw, the GetGWorldPixMap
function returns the handle to a 1-bit pixel map that your application can supply as a parameter to the other functions related to offscreen graphics worlds. However, your application should not supply this handle to color QuickDraw functions.
To ensure compatibility on systems running basic QuickDraw instead of Color QuickDraw, use GetGWorldPixMap
whenever you need to gain access to the bitmap created for a graphics world—that is, do not dereference the GWorldPtr
structure for that graphics world.
The GetGWorldPixMap
function is not available in systems preceding System 7. You can make sure that the GetGWorldPixMap
function is available by using the Gestalt
function with the gestaltSystemVersion
selector. Test the low-order word in the response
parameter; if the value is $0700 or greater, then GetGWorldPixMap
is available.
QDOffscreen.h
Obtains a pattern stored in a pattern list ('PAT#'
) resource. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GetIndPattern ( Pattern *thePat, short patternListID, short index );
On return, a pointer to a Pattern
structure for the pattern stored in the specified pattern list resource.
The resource ID for a resource of type 'PAT#'
.
The index number for the desired pattern within the pattern list ('PAT#'
) resource. The index number can range from 1 to the number of patterns in the pattern list resource.
The GetIndPattern
function calls the following Resource Manager function with these parameters:
GetResource('PAT#', patternListID); |
There is a pattern list resource in the System file that contains the standard Macintosh patterns used by MacPaint. The resource ID is represented by the constant sysPatListID
.
The GetIndPattern
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Obtains a handle to the GDevice
structure for the main screen. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle GetMainDevice ( void );
A handle to the device for the main screen, which is the device containing the menu bar.
A handle to the main device is kept in the global variable MainDevice
.
All existing GDevice
structures are linked together in the device list. After using this function to obtain a handle to the current GDevice
structure, your application can use the GetNextDevice
function to obtain a handle to the next GDevice
structure in the list.
The GetMainDevice
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Ptr GetMaskTable ( void );
QuickdrawAPI.h
Obtains a handle to the GDevice
structure for the video device with the greatest pixel depth. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle GetMaxDevice ( const Rect *globalRect );
A rectangle, in global coordinates, that intersects the graphics devices that you are searching to find the one with the greatest pixel depth.
A handle to the device with the greatest pixel depth.
All existing GDevice
structures are linked together in the device list. After using this function to obtain a handle to the current GDevice
structure, your application can use the GetNextDevice
function to obtain a handle to the next GDevice
structure in the list.
The GetMaxDevice
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Returns a handle to the next GDevice
structure in the device list. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle GetNextDevice ( GDHandle curDevice );
A handle to the GDevice
structure at which you want the search to begin.
A handle to the next device. If there are no more GDevice
structures in the list, NULL
.
After using any of the functions GetDeviceList
, GetGDevice
, GetMainDevice
, or GetMaxDevice
to obtain a handle to a GDevice
structure, use the GetNextDevice
function to obtain a handle to the next GDevice
structure in the list.
The GetNextDevice
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Obtains a pattern ('PAT'
) resource stored in a resource file. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PatHandle GetPattern ( short patternID );
The resource ID for a resource of type ‘PAT’.
a handle to the pattern having the resource ID that you specify in the patID
parameter. If a pattern resource with the ID that you request does not exist, the GetPattern
function returns NULL
.
The GetPattern
function calls the following Resource Manager function with these parameters:
GetResource('PAT', patID);
When you are finished using the pattern, dispose of its handle with the Memory Manager function DisposeHandle
.
The GetPattern
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Determines the location of the graphics pen. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GetPen ( Point *pt );
On return, a pointer to the graphics pen’s current position in the current graphics port. The point returned is in the local coordinates of the current graphics port.
In the pt parameter, the GetPen procedure returns the current pen position. The point returned is in the local coordinates of the current graphics port.
QuickdrawAPI.h
Determines the graphics pen’s location, size, pattern, and pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GetPenState ( PenState *pnState );
On return, a pointer to a PenState
structure holding information about the graphics pen. The GetPenState
function saves the location, size, pattern, and pattern mode of the graphics pen for the current graphics port in this structure.
After changing the graphics pen as necessary, restore these pen states with the SetPenState
function.
This pen-manipulation function uses the local coordinate system of the current graphics port. Remember that each graphics port has its own pen, the state of which is stored in several fields of its GrafPort
or CGrafPort
structure. If you draw in one graphics port, change to another, and return to the first, the pen for the first graphics port has the same state as when you left it.
QuickdrawAPI.h
Obtains a handle to a picture stored in a 'PICT'
resource. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PicHandle GetPicture ( short pictureID );
The resource ID for a 'PICT'
resource.
A handle to the picture in the specified ‘PICT’ resource. To draw the picture stored in the resource, pass this handle to the DrawPicture
function. If the resource cannot be read, GetPicture
returns NULL
.
The GetPicture
function calls the Resource Manager function GetResource
as follows:
GetResource(‘PICT’, picID)
To release the memory occupied by a picture stored in a 'PICT'
resource, use the Resource Manager function ReleaseResource
.
The GetPicture
function may move or purge memory.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Rect * GetPixBounds ( PixMapHandle pixMap, Rect *bounds );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
short GetPixDepth ( PixMapHandle pixMap );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
Determines whether the pixel associated with a point is black or white. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean GetPixel ( short h, short v );
The horizontal coordinate of the point for the pixel to be tested.
The vertical coordinate of the point for the pixel to be tested.
Returns TRUE
if the pixel is black or FALSE
if it is white.
The selected pixel is immediately below and to the right of the point whose coordinates you supply in the h
and v
parameters, in the local coordinates of the current graphics port. There’s no guarantee that the specified pixel actually belongs to the current graphics port, however it may have been drawn in a graphics port overlapping the current one. To see if the point indeed belongs to the current graphics port, you could use the PtInRgn
function to test whether the point is in the current graphics port’s visible region.
QuickdrawAPI.h
Saves the current information about the memory allocated for an offscreen pixel image. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GWorldFlags GetPixelsState ( PixMapHandle pm );
A handle to an offscreen pixel map. To get a handle to an offscreen pixel map, use the GetGWorldPixMap
function.
Information about the memory allocated for the base address for an offscreen pixel image. This result can be either of the constants, pixelsPurgeable
or pixelsLocked
. If the pixelsPurgeable
flag is not returned, then the base address for the offscreen pixel image is unpurgeable. If the pixelsLocked
flag is not returned, then the base address for the offscreen pixel image is unlocked.
After using GetPixelsState
to save this state information, use the SetPixelsState
function to restore this state to the offscreen graphics world.
After using GetPixelsState
and before using SetPixelsState
, temporarily use the AllowPurgePixels
function to make the base address for an offscreen pixel image purgeable, the NoPurgePixels
function to make it unpurgeable, the LockPixels
function to prevent it from being moved, and the UnlockPixels
function to allow it to be moved.
The GetPixelsState
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QDOffscreen.h
Obtains a pixel pattern ('ppat'
) resource stored in a resource file. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PixPatHandle GetPixPat ( short patID );
The resource ID for a resource of type 'ppat'
.
A handle to the pixel pattern having the resource ID you specify in the patID
parameter. The GetPixPat
function calls the following Resource Manager function with these parameters:
GetResource('ppat', patID);
If a 'ppat'
resource with the ID that you request does not exist, the GetPixPat
function returns NULL
.
When you are finished with the pixel pattern, use the DisposePixPat
function. For more information on the pixel pattern resource, see 'ppat'
.
Pixel patterns can use colors at any pixel depth and can be of any width and height that’s a power of 2. To create a pixel pattern, you typically define it in a 'ppat'
resource, which you store in a resource file. To retrieve the pixel pattern stored in a 'ppat'
resource, you can use the GetPixPat
function.
The GetPixPat
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
SInt32 GetPixRowBytes ( PixMapHandle pm );
QDOffscreen.h
Saves the current graphics port (basic or color). (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GetPort ( GrafPtr *port );
On return, a pointer to a GrafPort
structure for the current graphics port. If the current graphics port is a color graphics port, GetPort
coerces its CGrafPort
structure into a GrafPort
structure.
When your application runs in Color QuickDraw or uses offscreen graphics worlds, it should use the GetGWorld
function instead of GetPort
. The GetGWorld
function saves the current graphics port for basic and color graphics ports as well as offscreen graphics worlds.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
RGBColor * GetPortBackColor ( CGrafPtr port, RGBColor *backColor );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PixPatHandle GetPortBackPixPat ( CGrafPtr port, PixPatHandle backPattern );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
const BitMap * GetPortBitMapForCopyBits ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Rect * GetPortBounds ( CGrafPtr port, Rect *rect );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
short GetPortChExtra ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
RgnHandle GetPortClipRegion ( CGrafPtr port, RgnHandle clipRgn );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4.)
Not recommended
OSErr GetPortCustomXFerProc ( CGrafPtr port, CustomXFerProcPtr *proc, UInt32 *flags, UInt32 *refCon );
A result code.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PixPatHandle GetPortFillPixPat ( CGrafPtr port, PixPatHandle fillPattern );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
RGBColor * GetPortForeColor ( CGrafPtr port, RGBColor *foreColor );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
short GetPortFracHPenLocation ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
CQDProcsPtr GetPortGrafProcs ( CGrafPtr port );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
RGBColor * GetPortHiliteColor ( CGrafPtr port, RGBColor *hiliteColor );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
RGBColor * GetPortOpColor ( CGrafPtr port, RGBColor *opColor );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Point * GetPortPenLocation ( CGrafPtr port, Point *penLocation );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
SInt32 GetPortPenMode ( CGrafPtr port );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PixPatHandle GetPortPenPixPat ( CGrafPtr port, PixPatHandle penPattern );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Point * GetPortPenSize ( CGrafPtr port, Point *penSize );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
short GetPortPenVisibility ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PixMapHandle GetPortPixMap ( CGrafPtr port );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Fixed GetPortSpExtra ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Style GetPortTextFace ( CGrafPtr port );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
short GetPortTextFont ( CGrafPtr port );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
short GetPortTextMode ( CGrafPtr port );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
short GetPortTextSize ( CGrafPtr port );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
RgnHandle GetPortVisibleRegion ( CGrafPtr port, RgnHandle visRgn );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Cursor * GetQDGlobalsArrow ( Cursor *arrow );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Pattern * GetQDGlobalsBlack ( Pattern *black );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Pattern * GetQDGlobalsDarkGray ( Pattern *dkGray );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Pattern * GetQDGlobalsGray ( Pattern *gray );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Pattern * GetQDGlobalsLightGray ( Pattern *ltGray );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
long GetQDGlobalsRandomSeed ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
BitMap * GetQDGlobalsScreenBits ( BitMap *screenBits );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
CGrafPtr GetQDGlobalsThePort ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Pattern * GetQDGlobalsWhite ( Pattern *white );
QuickdrawAPI.h
Searches one color table for the best matches to colors in another color table. Your application should not need to call this function; it is used by system software only. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GetSubTable ( CTabHandle myColors, short iTabRes, CTabHandle targetTbl );
A handle to a color table containing the colors for which you want matches.
The resolution of the inverse table to be used.
A handle to a color table whose colors are to be matched. If you supply NULL
for targetTbl
, then the Color Manager searches the current GDevice
data structure’s CLUT, and uses its inverse table. Otherwise a temporary inverse table is built, with a resolution of the value in the iTabRes
parameter.
The Color Manager uses the Color2Index
function for each RGBColor
data structure in the color table of the myColors
parameter. It determines the best match in the target table and stores that index value in the value
field of the color table of the myColors
parameter.
Depending on the requested resolution, building the inverse table can require large amounts of temporary space in the application heap: twice the size of the table itself, plus a fixed overhead of 3–15 KB for each inverse table resolution.
QuickdrawAPI.h
Converts the coordinates of a point from global coordinates to the local coordinates of the current graphics port (basic or color). (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GlobalToLocal ( Point *pt );
A pointer to a point expressed in global coordinates (where the upper-left corner of the main screen has coordinates [0,0]). On return, this point is converted to local coordinates.
The GlobalToLocal procedure takes a point expressed in global coordinates (where the upper-left corner of the main screen has coordinates [0,0]) and converts it into the local coordinates of the current graphics port.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void GrafDevice ( short device );
QuickdrawAPI.h
Makes the graphics pen invisible, so that pen drawing doesn’t show on the screen. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void HidePen ( void );
The HidePen
function is called by the OpenRgn
, OpenPicture
, and OpenPoly
functions so that you can create regions, pictures, and polygons without drawing on the screen.
The HidePen
function decrements the pnVis
field of the current graphics port. The pnVis
field is initialized to 0 by the OpenPort
function. Whenever pnVis
is negative, the pen does not draw on the screen. The pnVis
field keeps track of the number of times the pen has been hidden to compensate for nested calls to the HidePen
and ShowPen
functions.
Every call to HidePen
should be balanced by a subsequent call to ShowPen
.
This pen-manipulation function uses the local coordinate system of the current graphics port. Remember that each graphics port has its own pen, the state of which is stored in several fields of its GrafPort
or CGrafPort
structure. If you draw in one graphics port, change to another, and return to the first, the pen for the first graphics port has the same state as when you left it.
QuickdrawAPI.h
Changes the highlight color for the current color graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void HiliteColor ( const RGBColor *color );
An RGBColor
structure that defines the highlight color.
All drawing operations that use the hilite
transfer mode use the highlight color. When a color graphics port is created, its highlight color is initialized from the global variable HiliteRGB
.
If the current graphics port is a basic graphics port, HiliteColor
has no effect.
QuickdrawAPI.h
Obtains the RGBColor
data structure corresponding to an index value in the color table of the current GDevice
data structure. Your application should not need to call this function; it is used by system software only. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void Index2Color ( long index, RGBColor *aColor );
The index value whose color entry is sought; you should supply a long integer in which the high-order word is padded with zeros.
A pointer to the returned RGBColor
data structure.
QuickdrawAPI.h
Initializes a GDevice
structure. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InitGDevice ( short qdRefNum, long mode, GDHandle gdh );
Reference number of the graphics device. System software sets this number at system startup time for most graphics devices.
The device configuration mode. Used by the screen driver, this value sets the pixel depth and specifies color or black and white.
The handle, returned by the NewGDevice
function, to the GDevice
structure to be initialized.
The InitGDevice
function sets the graphics device whose driver has the reference number specified in the gdRefNum
parameter to the mode specified in the mode
parameter. The InitGDevice
function then fills out the GDevice
structure, previously created with the NewGDevice
function, to contain all information describing that mode.
The mode
parameter determines the configuration of the device. Possible modes for a device are determined by interrogating the video device’s ROM through Slot Manager functions. The information describing the device’s mode is primarily contained in the video device’s ROM. If the video device has a fixed color table, then that table is read directly from the ROM. If the video device has a variable color table, then InitGDevice
uses the default color table defined in a 'clut'
resource, contained in the System file, that has a resource ID equal to the video device’s pixel depth.
In general, your application should never need to call InitGDevice
. All video devices are initialized at start time, and users change modes through the Monitors control panel.
If your program uses NewGDevice
to create a graphics device without a driver, InitGDevice
does nothing; instead, your application must initialize all fields of the GDevice
structure. After your application initializes the color table for the GDevice
structure, call the Color Manager function MakeITable
to build the inverse table for the graphics device.
The InitGDevice
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Inverts the pixels of a wedge. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvertArc ( const Rect *r, short startAngle, short arcAngle );
The rectangle that defines an oval’s boundaries.
The angle indicating the start of the arc.
The angle indicating the arc’s extent.
The InvertArc
function inverts the pixels enclosed by a wedge of the oval bounded by the rectangle that you specify in the r
parameter. Every white pixel becomes black and every black pixel becomes white. As in FrameArc
, use the startAngle
and arcAngle
parameters to define the arc of the wedge.
This function leaves the location of the graphics pen unchanged.
The InvertArc
function was designed for 1-bit images in basic graphics ports. This function operates on color pixels in color graphics ports, but the results are predictable only with direct devices or 1-bit pixel maps. For indexed pixels, Color QuickDraw performs the inversion on the pixel indexes, which means the results depend entirely on the contents of the CLUT. The eight colors used in basic QuickDraw are stored in a color table represented by the global variable QDColors
. To display those eight basic QuickDraw colors on an indexed device, Color QuickDraw uses the Color Manager to obtain indexes to the colors in the CLUT that best map to the colors in the QDColors
color table. Because the index, not the color value, is inverted, the results are unpredictable.
Inversion works better for direct pixels. Inverting a pure green, for example, that has red, green, and blue component values of $0000, $FFFF, and $0000 results in magenta, which has component values of $FFFF, $0000, and $FFFF.
The InvertArc
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Finds the complement of an RGBColor
data structure. This function is used only by system software. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvertColor ( RGBColor *myColor );
A pointer to the RGBColor
data structure for which the complement is to be found. The InvertColor
function returns the complement of an absolute color, using the list of complement functions in the current device data structure. The default complement function uses the one’s complement of each component of the given color.
QuickdrawAPI.h
Inverts the pixels enclosed by an oval. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvertOval ( const Rect *r );
The rectangle that defines the oval’s boundary.
The InvertOval
function inverts the pixels enclosed by an oval just inside the bounding rectangle that you specify in the r
parameter. Every white pixel becomes black and every black pixel becomes white. The pen location does not change.
The InvertOval
function was designed for 1-bit images in basic graphics ports. This function operates on color pixels in color graphics ports, but the results are predictable only with direct devices or 1-bit pixel maps. For indexed pixels, Color QuickDraw performs the inversion on the pixel indexes, which means the results depend entirely on the contents of the CLUT. The eight colors used in basic QuickDraw are stored in a color table represented by the global variable QDColors
. To display those eight basic QuickDraw colors on an indexed device, Color QuickDraw uses the Color Manager to obtain indexes to the colors in the CLUT that best map to the colors in the QDColors
color table. Because the index, not the color value, is inverted, the results are unpredictable.
Inversion works better for direct pixels. Inverting a pure green, for example, that has red, green, and blue component values of $0000, $FFFF, and $0000 results in magenta, which has component values of $FFFF, $0000, and $FFFF.
The InvertOval
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Inverts the pixels enclosed by a polygon. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvertPoly ( PolyHandle poly );
A handle to a polygon, the pixels of which you want to invert. The OpenPoly
function returns this handle when you first create the polygon.
The InvertPoly
function inverts the pixels enclosed by the polygon whose handle you pass in the poly
parameter. Every white pixel becomes black and every black pixel becomes white.
This function leaves the location of the graphics pen unchanged.
InvertPoly
temporarily converts the polygon into a region to perform their operations. The amount of memory required for this temporary region may be far greater than the amount required by the polygon alone.
You can estimate the size of this region by scaling down the polygon with the MapPoly
, converting the polygon into a region, checking the region’s size with the Memory Manager function GetHandleSize
, and multiplying that value by the factor by which you scaled the polygon.
The result of this graphics operation is undefined whenever any horizontal or vertical line drawn through the polygon would intersect the polygon’s outline more than 50 times.
The InvertPoly
function was designed for 1-bit images in basic graphics ports. This function operates on color pixels in color graphics ports, but the results are predictable only with 1-bit or direct pixels. For indexed pixels, Color QuickDraw performs the inversion on the pixel indexes, which means the results depend entirely on the contents of the CLUT. The eight colors used in basic QuickDraw are stored in a color table represented by the global variable QDColors
. To display those eight basic QuickDraw colors on an indexed device, Color QuickDraw uses the Color Manager to obtain indexes to the colors in the CLUT that best map to the colors in the QDColors
color table. Because the index, not the color value, is inverted, the results are unpredictable.
Inversion works better for direct pixels. Inverting a pure green, for example, that has red, green, and blue component values of $0000, $FFFF, and $0000 results in magenta, which has component values of $FFFF, $0000, and $FFFF.
The InvertPoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Inverts the pixels enclosed by a rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvertRect ( const Rect * r );
The rectangle whose enclosed pixels are to be inverted.
The InvertRect
function inverts the pixels enclosed by the rectangle that you specify in the r
parameter. Every white pixel becomes black and every black pixel becomes white. The pen location does not change.
The InvertRect
function was designed for 1-bit images in basic graphics ports. This function operates on color pixels in color graphics ports, but the results are predictable only with direct pixels or 1-bit pixel maps. For indexed pixels, Color QuickDraw performs the inversion on the pixel indexes, which means the results depend entirely on the contents of the CLUT. The eight colors used in basic QuickDraw are stored in a color table represented by the global variable QDColors
. To display those eight basic QuickDraw colors on an indexed device, Color QuickDraw uses the Color Manager to obtain indexes to the colors in the CLUT that best map to the colors in the QDColors
color table. Because the index, not the color value, is inverted, the results are unpredictable.
Inversion works better for direct pixels. Inverting a pure green, for example, that has red, green, and blue component values of $0000, $FFFF, and $0000 results in magenta, which has component values of $FFFF, $0000, and $FFFF.
The InvertRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Inverts the pixels enclosed by a region. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvertRgn ( RgnHandle rgn );
A handle to the region whose pixels are to invert.
The InvertRgn
function inverts the pixels enclosed by the region whose handle you pass in the rgn
parameter. Every white pixel becomes black and every black pixel becomes white.
This function leaves the location of the graphics pen unchanged.
This function depends on the local coordinate system of the current graphics port. If you draw a region in a graphics port different from the one in which you defined the region, it may not appear in the proper position in the graphics port.
If any horizontal or vertical line drawn through the region would intersect the region’s outline more than 50 times, the results of this graphics operation are undefined.
The InvertRgn
function was designed for 1-bit images in basic graphics ports. This function operates on color pixels in color graphics ports, but the results are predictable only with 1-bit or direct pixels. For indexed pixels, Color QuickDraw performs the inversion on the pixel indexes, which means the results depend entirely on the contents of the CLUT. The eight colors used in basic QuickDraw are stored in a color table represented by the global variable QDColors
. To display those eight basic QuickDraw colors on an indexed device, Color QuickDraw uses the Color Manager to obtain indexes to the colors in the CLUT that best map to the colors in the QDColors
color table. Because the index, not the color value, is inverted, the results are unpredictable.
Inversion works better for direct pixels. Inverting a pure green, for example, that has red, green, and blue component values of $0000, $FFFF, and $0000 results in magenta, which has component values of $FFFF, $0000, and $FFFF.
The InvertRgn
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Inverts the pixels enclosed by a rounded rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvertRoundRect ( const Rect *r, short ovalWidth, short ovalHeight );
The rectangle that defines the rounded rectangle’s boundaries.
The width of the oval defining the rounded corner.
The height of the oval defining the rounded corner.
The InvertRoundRect
function inverts the pixels enclosed by the rounded rectangle bounded by the rectangle that you specify in the r
parameter. Every white pixel becomes black and every black pixel becomes white. The ovalWidth
and ovalHeight
parameters specify the diameters of curvature for the corners. The pen location does not change.
The InvertRoundRect
function was designed for 1-bit images in basic graphics ports. This function operates on color pixels in color graphics ports, but the results are predictable only with direct devices or 1-bit pixel maps. For indexed pixels, Color QuickDraw performs the inversion on the pixel indexes, which means the results depend entirely on the contents of the CLUT. The eight colors used in basic QuickDraw are stored in a color table represented by the global variable QDColors
. To display those eight basic QuickDraw colors on an indexed device, Color QuickDraw uses the Color Manager to obtain indexes to the colors in the CLUT that best map to the colors in the QDColors
color table. Because the index, not the color value, is inverted, the results are unpredictable.
Inversion works better for direct pixels. Inverting a pure green, for example, that has red, green, and blue component values of $0000, $FFFF, and $0000 results in magenta, which has component values of $FFFF, $0000, and $FFFF.
The InvertRoundRect
function may move or purge memory blocks in the application; do not call this function at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean InvokeColorComplementUPP ( RGBColor *rgb, ColorComplementUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean InvokeColorSearchUPP ( RGBColor *rgb, long *position, ColorSearchUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeDeviceLoopDrawingUPP ( short depth, short deviceFlags, GDHandle targetDevice, SRefCon userData, DeviceLoopDrawingUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeDragGrayRgnUPP ( DragGrayRgnUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDArcUPP ( GrafVerb verb, const Rect *r, short startAngle, short arcAngle, QDArcUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDBitsUPP ( const BitMap *srcBits, const Rect *srcRect, const Rect *dstRect, short mode, RgnHandle maskRgn, QDBitsUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDCommentUPP ( short kind, short dataSize, Handle dataHandle, QDCommentUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDGetPicUPP ( void *dataPtr, short byteCount, QDGetPicUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDJShieldCursorUPP ( short left, short top, short right, short bottom, QDJShieldCursorUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDLineUPP ( Point newPt, QDLineUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDOpcodeUPP ( const Rect *fromRect, const Rect *toRect, UInt16 opcode, SInt16 version, QDOpcodeUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDOvalUPP ( GrafVerb verb, const Rect *r, QDOvalUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDPolyUPP ( GrafVerb verb, PolyHandle poly, QDPolyUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDPutPicUPP ( const void *dataPtr, short byteCount, QDPutPicUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDRectUPP ( GrafVerb verb, const Rect *r, QDRectUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDRgnUPP ( GrafVerb verb, RgnHandle rgn, QDRgnUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDRRectUPP ( GrafVerb verb, const Rect *r, short ovalWidth, short ovalHeight, QDRRectUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus InvokeQDStdGlyphsUPP ( void *dataStream, ByteCount size, QDStdGlyphsUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void InvokeQDTextUPP ( short byteCount, const void *textBuf, Point numer, Point denom, QDTextUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
short InvokeQDTxMeasUPP ( short byteCount, const void *textAddr, Point *numer, Point *denom, FontInfo *info, QDTxMeasUPP userUPP );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus InvokeRegionToRectsUPP ( UInt16 message, RgnHandle rgn, const Rect *rect, void *refCon, RegionToRectsUPP userUPP );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean IsPortClipRegionEmpty ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean IsPortColor ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean IsPortOffscreen ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean IsPortPictureBeingDefined ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean IsPortPolyBeingDefined ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean IsPortRegionBeingDefined ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean IsPortVisibleRegionEmpty ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean IsValidPort ( CGrafPtr port );
QuickdrawAPI.h
Releases the memory occupied by a picture not stored in a 'PICT'
resource. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void KillPicture ( PicHandle myPicture );
A handle to the picture whose memory can be released.
Use this function only when you are completely finished with a picture.
If you use the Window Manager function SetWindowPic
to store a picture handle in the window structure, use the Window Manager function DisposeWindow
or CloseWindow
to release the memory allocated to the picture. These functions automatically call KillPicture
for the picture.
If the picture is stored in a 'PICT'
resource, use the Resource Manager function ReleaseResource
instead of KillPicture
. The Window Manager functions DisposeWindow
and CloseWindow
will not delete it. Instead, call ReleaseResource
before calling DisposeWindow
or CloseWindow
.
The KillPicture
function may move or purge memory.
QuickdrawAPI.h
Releases the memory occupied by a polygon. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void KillPoly ( PolyHandle poly );
A handle to the polygon to dispose of.
Use KillPoly
only when you are completely through with a polygon.
The KillPoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Draws a line a specified distance from the graphics pen’s current location in the current graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void Line ( short dh, short dv );
The horizontal distance of the graphics pen’s movement.
The vertical distance of the graphics pen’s movement.
Starting at the current location of the graphics pen, the Line
function draws a line the horizontal distance that you specify in the dh
parameter and the vertical distance that you specify in the dv
parameter. The Line
function calls
LineTo(h+dh,v+dv)
where (h,v)
is the current location in local coordinates. The pen location becomes the coordinates of the end of the line after the line is drawn. If you are using Line
to draw a region or polygon, its outline is infinitely thin and is not affected by the values of the pnSize
, pnMode
, and pnPat
fields of the graphics port.
The Line
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Draws a line from the graphics pen’s current location to a new location. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LineTo ( short h, short v );
The horizontal coordinate of the graphics pen’s new location.
The vertical coordinate of the graphics pen’s new location.
The LineTo
function draws a line from the graphics pen’s current location in the current graphics port to the new location (h,v)
, which you specify in the local coordinates of the current graphics port. If you are using LineTo
to draw a region or polygon, its outline is infinitely thin and is not affected by the values of the pnSize
, pnMode
, or pnPat
field of the graphics port.
The LineTo
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean LMGetCursorNew ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle LMGetDeviceList ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
UInt8 LMGetFractEnable ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
UInt8 LMGetHiliteMode ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMGetHiliteRGB ( RGBColor *hiliteRGBValue );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Handle LMGetLastFOND ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
SInt32 LMGetLastSPExtra ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle LMGetMainDevice ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Handle LMGetQDColors ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
SInt16 LMGetScrHRes ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
SInt16 LMGetScrVRes ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle LMGetTheGDevice ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Handle LMGetWidthListHand ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Ptr LMGetWidthPtr ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Handle LMGetWidthTabHandle ( void );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetCursorNew ( Boolean value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetDeviceList ( GDHandle value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetFractEnable ( UInt8 value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetHiliteMode ( UInt8 value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetHiliteRGB ( const RGBColor *hiliteRGBValue );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetLastFOND ( Handle value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetLastSPExtra ( SInt32 value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetMainDevice ( GDHandle value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetQDColors ( Handle value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetScrHRes ( SInt16 value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetScrVRes ( SInt16 value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetTheGDevice ( GDHandle value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetWidthListHand ( Handle value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetWidthPtr ( Ptr value );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LMSetWidthTabHandle ( Handle value );
QuickdrawAPI.h
Converts a point’s coordinates from the local coordinates of the current graphics port (basic or color) to global coordinates. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void LocalToGlobal ( Point *pt );
A pointer to a point in local coordinates. On return, this point is converted to global coordinates.
The LocalToGlobal
function converts the given point from the current graphics port’s local coordinate system into the global coordinate system (where the upper-left corner of the main screen has coordinates [0,0]). This global point can then be compared to other global points, or it can be changed into the local coordinates of another graphics port.
Because a rectangle is defined by two points, you can convert a rectangle into global coordinates with two calls to LocalToGlobal
. In conjunction with LocalToGlobal
, you can use the OffsetRect
, OffsetRgn
, or OffsetPoly
functions to convert a rectangle, region, or polygon into global coordinates.
QuickdrawAPI.h
Prevents the base address for an offscreen pixel image from being moved while you draw into or copy from its pixel map. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean LockPixels ( PixMapHandle pm );
A handle to an offscreen pixel map. To get a handle to an offscreen pixel map, use the GetGWorldPixMap
function .
If the base address for an offscreen pixel image hasn’t been purged by the Memory Manager or is not purgeable, LockPixels
returns TRUE
as its function result, and your application can draw into or copy from the offscreen pixel map. However, if the base address for an offscreen pixel image has been purged, LockPixels
returns FALSE
to indicate that you can perform no drawing to or copying from the pixel map. At that point, your application should either call the UpdateGWorld
function to reallocate the offscreen pixel image and then reconstruct it, or draw directly in a window instead of preparing the image in an offscreen graphics world.
You must call LockPixels
before drawing to or copying from an offscreen graphics world.
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). The LockPixels
function dereferences the PixMap
handle into a pointer. When you use the UnlockPixels
function the handle is recovered.
As soon as you are finished drawing into and copying from the offscreen pixel image, call the UnlockPixels
function.
The LockPixels
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QDOffscreen.h
Acquires an exclusive lock on the back buffer for a Carbon window. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSErr LockPortBits ( GrafPtr port );
A window port.
A result code. If noErr
, the window’s back buffer is locked and available for direct access.
In Mac OS X, a Carbon window’s port bits are in a back buffer shared by the application and the Quartz compositor (sometimes called the window server). When an application needs to update this buffer, the Quartz compositor must be locked out temporarily. You can use this function together with UnlockPortBits
to acquire and release an exclusive lock.
If you’re using QuickDraw or Quartz 2D to draw in a window, you do not need to call this function—buffer locks are handled for you automatically. If you’re writing code that reads or modifies the port bits directly, you should bracket your code with calls to this function and UnlockPortBits
.
Nested calls to this function for the same port are permitted. For a given port, if you call LockPortBits
n times, the lock is actually released after the nth balancing call to UnlockPortBits
.
You should not call any QuickTime functions while holding the lock. To avoid degrading the user experience, you should release the lock as quickly as possible.
In Mac OS 9, this function does nothing and returns noErr
.
QuickdrawAPI.h
Generates an inverse table for a color table. Your application should not need to call this function; it is used by system software only. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void MakeITable ( CTabHandle cTabH, ITabHandle iTabH, short res );
The color table for which an inverse table is to be generated. Passing NULL
substitutes an appropriate handle from the current GDevice
data structure.
The generated inverse table. Passing NULL
substitutes an appropriate handle from the current GDevice
data structure.
The resolution needed for the inverse table. Passing 0 substitutes the current GDevice
data structure’s inverse table resolution.
The MakeITable
function generates an inverse table based on the current contents of the color table pointed to by the cTabH
parameter, with a resolution specified by the value in the res
parameter. Reserved color table pixel values are not included in the resulting color table. MakeITable
tests its input parameters and returns an error in QDError
if the resolution is less than three or greater than five.
This function allows maximum precision in mapping colors, even if colors in the color table differ by less than the resolution of the inverse table. Five-bit inverse tables are not needed when drawing in normal Color QuickDraw modes. However, Color QuickDraw transfer modes such as add, subtract, and blend may require a 5-bit inverse table for best results with certain color tables. The 'mitq'
resource governs how much memory is allocated for temporary internal structures; this resource type is for internal use only.
Depending on the requested resolution, building the inverse table can require large amounts of temporary space in the application heap: twice the size of the table itself, plus a fixed overhead of 3–15 KB for each inverse table resolution.
QuickdrawAPI.h
Creates the appearance of otherwise unavailable colors on indexed devices. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void MakeRGBPat ( PixPatHandle pp, const RGBColor *myColor );
On return, a handle to the generated pixel pattern.
An RGBColor
structure that defines the color you want to approximate.
The MakeRGBPat
function generates a PixPat
structure that approximates the color you specify in the myColor
parameter. For example, if your application draws to an indexed device that supports 4 bits per pixel, you only have 16 colors available if you simply set the foreground color and draw. If you use MakeRGBPat
to create a pattern, and then draw using that pattern, you effectively get 125 different colors. If the graphics device has 8 bits per pixel, you effectively get 2197 colors. (More color are theoretically possible; this implementation opted for a fast pattern selection rather than the best possible pattern selection.)
For a pixel pattern, the (** patMap).bounds
field of the PixPat
structure always contains the values (0,0,8,8), and the (** patMap).rowbytes
field equals 2.
Because patterns produced with MakeRGBPat
aren’t usually solid—they provide a selection of colors by alternating between colors, with up to four colors in a pattern— lines that are only one pixel wide may not look good.
When MakeRGBPat
creates a ColorTable
structure, it fills in only the rgb
fields of its ColorSpec
structures; the value
fields are computed at the time the drawing actually takes place, using the current pixel depth for the system.
QuickdrawAPI.h
Maps and scales a polygon within one rectangle to another rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void MapPoly ( PolyHandle poly, const Rect *srcRect, const Rect *dstRect );
A handle to a polygon. Upon input, this is the polygon to map. Upon completion, this polygon is the one mapped to a new location.
The rectangle containing the polygon.
The rectangle in which the new region will be mapped.
The MapPoly
function takes a polygon within one rectangle and maps and scales it to another rectangle. In the poly
parameter, you specify a handle to a polygon that lies within the rectangle that you specify in the srcRect
parameter. By calling the MapPt
function to map all the points that define the polygon specified in the poly
parameter, MapPoly
maps and scales it to the rectangle that you specify in the dstRect
parameter. The MapPoly
function returns the result in the polygon whose handle you initially passed in the poly
parameter.
Similar to the MapRgn
function described in the previous section, the MapPoly
function is useful for determining whether a polygon operation will exceed available memory.
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.
QuickdrawAPI.h
Moves the graphics pen a particular distance. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void Move ( short dh, short dv );
The horizontal distance of the graphics pen’s movement.
The vertical distance of the graphics pen’s movement.
The Move
function moves the graphics pen from its current location in the current graphics port a horizontal distance that you specify in the dh
parameter and a vertical distance that you specify in the dv
parameter. The Move
function calls
MoveTo(h+dh,v+dv)
where (h,v)
is the graphics pen’s current location in local coordinates. The Move
function performs no drawing.
QuickdrawAPI.h
Changes the position of the port rectangle of the current graphics port (basic or color). (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void MovePortTo ( short leftGlobal, short topGlobal );
The horizontal distance to move the port rectangle.
The vertical distance to move the port rectangle.
The MovePortTo
function is normally called only by the Window Manager. The MovePortTo
function changes the position of the current graphics port’s port rectangle: the leftGlobal
and topGlobal
parameters set the distance between the upper-left corner of the boundary rectangle and the upper-left corner of the new port rectangle.
This does not affect the screen; it merely changes the location at which subsequent drawing inside the graphics port appears. Like the PortSize
function, MovePortTo
doesn’t change the clipping or visible region, nor does it affect the local coordinate system of the graphics port.
QuickdrawAPI.h
Moves the graphics pen to a particular location in the current graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void MoveTo ( short h, short v );
The horizontal coordinate of the graphics pen’s new position.
The vertical coordinate of the graphics pen’s new position.
The MoveTo
function changes the graphics pen’s current location to the new horizontal coordinate you specify in the h
parameter and the new vertical coordinate you specify in the v
parameter. Specify the new location in the local coordinates of the current graphics port. The MoveTo
function performs no drawing.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
ColorComplementUPP NewColorComplementUPP ( ColorComplementProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
ColorSearchUPP NewColorSearchUPP ( ColorSearchProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
DeviceLoopDrawingUPP NewDeviceLoopDrawingUPP ( DeviceLoopDrawingProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
DragGrayRgnUPP NewDragGrayRgnUPP ( DragGrayRgnProcPtr userRoutine );
QuickdrawTypes.h
Creates a new GDevice
structure. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GDHandle NewGDevice ( short refNum, long mode );
Reference number of the graphics device for which you are creating a GDevice
structure. For most video devices, this information is set at system startup.
The device configuration mode. Used by the screen driver, this value sets the pixel depth and specifies color or black and white.
A handle to the new GDevice
structure. If the request is unsuccessful, NewGDevice
returns NULL
.
Generally, you do not need to use NewGDevice
, because Color QuickDraw uses this function to create GDevice
structures for your application automatically. When the system starts up, it allocates and initializes one handle to a GDevice
structure for each video device it finds. When you use the NewGWorld
function, QuickDraw automatically creates a GDevice
structure for the new offscreen graphics world.
For the graphics device whose driver is specified in the refNum
parameter and whose mode is specified in the mode
parameter, the NewGDevice
function allocates a new GDevice
structure and all of its handles, and then calls the InitGDevice
function to initialize the structure.
NewGDevice
allocates the new GDevice
structure and all of its handles in the system heap, and the NewGDevice
function sets all attributes in the gdFlags
field of the GDevice
structure to FALSE
. If your application creates a GDevice
structure, use the SetDeviceAttribute
function to change the flag bits in the gdFlags
field of the GDevice
structure to TRUE
. Your application should never directly change the gdFlags
field of the GDevice
structure. Instead, use only the SetDeviceAttribute
function.
If your application creates a GDevice
structure without a driver, set the mode
parameter to –1. In this case, InitGDevice
cannot initialize the GDevice
structure, so your application must perform all initialization of the structure. A GDevice
structure’s default mode is defined as 128. This is assumed to be a black-and-white mode. If you specify a value other than 128 in the mode
parameter, the structure’s gdDevType
bit in the gdFlags
field of the GDevice
structure is set to TRUE
to indicate that the graphics device is capable of displaying color.
The NewGDevice
function does not automatically insert the GDevice
structure into the device list. In general, your application should not create GDevice
structures, and if it ever does, it should never add them to the device list.
If your program uses NewGDevice
to create a graphics device without a driver, InitGDevice
does nothing; instead, your application must initialize all fields of the GDevice
structure. After your application initializes the color table for the GDevice
structure, call the Color Manager function MakeITable
to build the inverse table for the graphics device.
The NewGDevice
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDErr NewGWorldFromPtr ( GWorldPtr *offscreenGWorld, UInt32 PixelFormat, const Rect *boundsRect, CTabHandle cTable, GDHandle aGDevice, GWorldFlags flags, Ptr newBuffer, SInt32 rowBytes );
QDOffscreen.h
Creates a new, initialized PixMap
structure. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PixMapHandle NewPixMap ( void );
A handle to the new PixMap
structure.
All fields of the PixMap
structure are copied from the current device’s PixMap
structure except the color table. In System 7, the hRes
and vRes
fields are set to 72 dpi, no matter what values the current device’s PixMap
structure contains. A handle to the color table is allocated but not initialized.
Typically, you do not need to call this function because PixMap
structures are created for you when you create a window using the Window Manager functions NewCWindow
and GetNewCWindow
and when you create an offscreen graphics world with the NewGWorld
function.
If your application creates a pixel map, your application must initialize the PixMap
structure’s color table to describe the pixels. Use the GetCTable
function to read such a table from a resource file. Use the DisposeCTable
function to dispose of the PixMap
structure’s color table and replace it with the one returned by GetCTable
.
The NewPixMap
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Creates a new pixel pattern. Generally, however, your application should create a pixel pattern in a 'ppat'
resource. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PixPatHandle NewPixPat ( void );
A handle to the new PixPat
structure created by the NewPixPat
function.
This function calls the NewPixMap
function to allocate the pattern’s PixMap
structure and initializes it to the same settings as the pixel map of the current GDevice
structure. NewPixPat
also sets the pat1Data
field of the new PixPat
structure to a 50 percent gray pattern. NewPixPat
allocates new handles for the PixPat
structure’s data, expanded data, expanded map, and color table but does not initialize them instead, your application must initialize them.
Set the rowBytes
, bounds
, and pixelSize
fields of the pattern’s PixMap
structure to the dimensions of the desired pattern. The rowBytes
value should be equal to
(width of bounds) x pixelSize/8
The rowBytes
value need not be even. The width and height of the bounds must be a power of 2. Each scan line of the pattern must be at least 1 byte in length—that is, ([width of bounds] x pixelSize
) must be at least 8.
Your application can explicitly specify the color corresponding to each pixel value with a color table. The color table for the pattern must be placed in the pmTable
field in the pattern’s PixMap
structure.
Including the PixPat
structure itself, NewPixPat
allocates a total of five handles. The sizes of the handles to the PixPat
and PixMap
structures are the sizes of their respective data structures. The other three handles are initially small in size. Once the pattern is drawn, the size of the expanded data is proportional to the size of the pattern data, but adjusted to the depth of the screen. The color table size is the size of the structure plus 8 bytes times the number of colors in the table.
When you are finished using the pixel pattern, use the DisposePixPat
function to make the memory used by the pixel pattern available again.
The NewPixPat
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDArcUPP NewQDArcUPP ( QDArcProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDBitsUPP NewQDBitsUPP ( QDBitsProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDCommentUPP NewQDCommentUPP ( QDCommentProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDGetPicUPP NewQDGetPicUPP ( QDGetPicProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDJShieldCursorUPP NewQDJShieldCursorUPP ( QDJShieldCursorProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDLineUPP NewQDLineUPP ( QDLineProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDOpcodeUPP NewQDOpcodeUPP ( QDOpcodeProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDOvalUPP NewQDOvalUPP ( QDOvalProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDPolyUPP NewQDPolyUPP ( QDPolyProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDPutPicUPP NewQDPutPicUPP ( QDPutPicProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDRectUPP NewQDRectUPP ( QDRectProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDRgnUPP NewQDRgnUPP ( QDRgnProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDRRectUPP NewQDRRectUPP ( QDRRectProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDStdGlyphsUPP NewQDStdGlyphsUPP ( QDStdGlyphsProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDTextUPP NewQDTextUPP ( QDTextProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDTxMeasUPP NewQDTxMeasUPP ( QDTxMeasProcPtr userRoutine );
QuickdrawTypes.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
RegionToRectsUPP NewRegionToRectsUPP ( RegionToRectsProcPtr userRoutine );
QuickdrawAPI.h
Creates an offscreen PixMap
structure and allocates memory for the base address of its pixel image. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDErr NewScreenBuffer ( const Rect *globalRect, Boolean purgeable, GDHandle *gdh, PixMapHandle *offscreenPixMap );
The boundary rectangle, in global coordinates, for the offscreen pixel map.
A value of TRUE
to make the memory block for the offscreen pixel map purgeable, or a value of FALSE
to make it unpurgeable.
On return, a pointer to the handle to the GDevice
structure for the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle specified in the globalRect
parameter.
On return, a pointer to a handle to the new offscreen PixMap
structure.
A result code.
Applications generally do not need to use NewScreenBuffer
. The NewGWorld
function uses the NewScreenBuffer
function to create and allocate memory for an offscreen pixel image.
The NewScreenBuffer
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QDOffscreen.h
Creates an offscreen PixMap
structure and allocate temporary memory for the base address of its pixel image applications generally don’t need to use NewTempScreenBuffer
. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDErr NewTempScreenBuffer ( const Rect *globalRect, Boolean purgeable, GDHandle *gdh, PixMapHandle *offscreenPixMap );
The boundary rectangle, in global coordinates, for the offscreen pixel map.
A value of TRUE
to make the memory block for the offscreen pixel map purgeable, or a value of FALSE
to make it unpurgeable.
On return, a pointer to the handle to the GDevice
structure for the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle specified in the globalRect
parameter.
On return, a pointer to the handle to the new offscreen PixMap
structure.
A result code.
The NewTempScreenBuffer
function performs the same functions as NewScreenBuffer
except that it creates the base address for the offscreen pixel image in temporary memory. When an application passes it the useTempMem
flag, the NewGWorld
function uses NewTempScreenBuffer
instead of NewScreenBuffer
.
Your application should not need to use this function.
The NewTempScreenBuffer
function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
QDOffscreen.h
Prevents the Memory Manager from purging the base address for an offscreen pixel image. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void NoPurgePixels ( PixMapHandle pm );
A handle to an offscreen pixel map.
The NoPurgePixels
function marks the base address for an offscreen pixel image as unpurgeable.
To get a handle to an offscreen pixel map, use the GetGWorldPixMap
function. Then supply this handle for the pm
parameter of NoPurgePixels
.
The NoPurgePixels
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QDOffscreen.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
SInt32 OffscreenVersion ( void );
QDOffscreen.h
Moves a polygon. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void OffsetPoly ( PolyHandle poly, short dh, short dv );
A handle to a polygon to move.
The horizontal distance to move the polygon.
The vertical distance to move the polygon.
The OffsetPoly
function moves the polygon whose handle you pass in the poly
parameter by adding the value you specify in the dh
parameter to the horizontal coordinates of its points, 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.
OffsetPoly
is an especially efficient operation, because the data defining a polygon is stored relative to the first point of the polygon and so is not actually changed by OffsetPoly
.
QuickdrawAPI.h
Sets the maximum color values for the addPin
and subPin
arithmetic transfer modes and the weight color for the blend
arithmetic transfer mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void OpColor ( const RGBColor *color );
An RGBColor
structure that defines a color.
Specify the red, green, and blue values in the RGBColor
structure and specify this structure in the color
parameter.
If the current graphics port is defined by a GrafPort
structure, OpColor
has no effect.
QuickdrawAPI.h
Begins defining a picture in extended version 2 format. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PicHandle OpenCPicture ( const OpenCPicParams *newHeader );
An OpenCPicParams
structure.
A handle to a new Picture
structure. OpenCPicture
collects your subsequent drawing commands in this structure. Use this handle when referring to the picture in subsequent functions, such as the DrawPicture
function.
When defining a picture, you can use all other QuickDraw drawing functions, with the exception of CopyMask
, CopyDeepMask
, SeedFill
, SeedCFill
, CalcMask
, and CalcCMask
. You can also use the PicComment
function to include picture comments in your picture definition.
The OpenCPicture
function creates a pictures in the extended version 2 format. This format permits your application to specify resolutions when creating images.
Use the OpenCPicParams
structure you pass in the newHeader
parameter to specify the horizontal and vertical resolution for the picture, and specify an optimal bounding rectangle for displaying the picture at this resolution. When you later call the DrawPicture
function to play back the saved picture, supply a destination rectangle, and DrawPicture
scales the picture so that it is completely aligned with the destination rectangle. To display a picture at a resolution other than that at which it was created, compute an appropriate destination rectangle by scaling its width and height by the following factor:
scale factor = destination resolution / source resolution
For example, if a picture was created at 300 dpi and you want to display it at 75 dpi, then your application should compute the destination rectangle width and height as 1/4 of those of the picture’s bounding rectangle.
The OpenCPicture
function calls the HidePen
function, so no drawing occurs on the screen while the picture is open (unless you call the ShowPen
function just after OpenCPicture
, or you called ShowPen
previously without balancing it by a call to HidePen
).
After defining the picture, close it by using the ClosePicture
function.
After creating the picture, use the GetPictInfo
function to gather information about it. The PictInfo
structure returned by GetPictInfo
returns the picture’s resolution and optimal bounding rectangle.
When creating a picture, use the ClosePicture
function to finish it before you open the Printing Manager with the PrOpen
function. There are two main reasons for this. First, you should allow the printing driver to use as much memory as possible. Second, the Printing Manager creates its own type of graphics port, one that replaces the standard QuickDraw drawing operations stored in the grafProcs
field of a CGrafPort
or GrafPort
structure. To avoid unexpected results when creating a picture, draw into a graphics port created with QuickDraw instead of drawing into a printing port created by the Printing Manager.
After calling OpenCPicture
, be sure to finish your picture definition by calling ClosePicture
before you call OpenCPicture
again. You cannot nest calls to OpenCPicture
.
Always use the ClipRect
procedure to specify a clipping region appropriate for your picture before you call OpenCPicture
. If you do not use ClipRect
to specify a clipping region, OpenCPicture
uses the clipping region specified in the current graphics port. If the clipping region is very large (as it is when a graphics port is initialized) and you scale the picture when drawing it, the clipping region can become invalid when DrawPicture
scales the clipping region—in which case, your picture will not be drawn.
The OpenCPicture
function may move or purge memory; do not call at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSErr OpenCursorComponent ( Component c, ComponentInstance *ci );
This function is not implemented on Mac OS X.
QuickdrawAPI.h
Creates a picture which allows you to specify resolutions for your pictures. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PicHandle OpenPicture ( const Rect *picFrame );
The bounding rectangle for the picture. The DrawPicture
function uses this rectangle to scale the picture if you draw it into a destination rectangle of a different size.
A handle to a new Picture
structure. OpenPicture
collects your subsequent drawing commands in this structure. Use this handle when referring to the picture in subsequent functions, such as the DrawPicture
function.
The OpenPicture
function, which was created for earlier versions of system software, is described here for completeness. Use the OpenPicture
function to begin defining a picture.
The OpenPicture
function calls the HidePen
function, so no drawing occurs on the screen while the picture is open (unless you call the ShowPen
function just after OpenPicture
or you called ShowPen
previously without balancing it by a call to HidePen
).
The OpenPicture
function creates pictures in the version 2 format on computers with Color QuickDraw when the current graphics port is a color graphics port. Pictures created in this format support color drawing operations at 72 dpi. On computers supporting only basic QuickDraw, or when the current graphics port is a basic graphics port, this function creates pictures in version 1 format. Pictures created in version 1 format support only black-and-white drawing operations at 72 dpi.
When defining a picture, you can use all other QuickDraw drawing functions, with the exception of CopyMask
, CopyDeepMask
, SeedFill
, SeedCFill
, CalcMask
, and CalcCMask
. You can also use the PicComment
function to include picture comments in your picture definition.
After defining the picture, close it by using the ClosePicture
function. To draw the picture, use the DrawPicture
function.
The version 2 and version 1 picture formats support only 72-dpi resolution. The OpenCPicture
function creates pictures in the extended version 2 format. The extended version 2 format, which is created by the OpenCPicture
function on all Macintosh computers running System 7, permits your application to specify additional resolutions when creating images.
Version 1 pictures are limited to 32 KB. You can determine the picture size while it is being formed by calling the Memory Manager function GetHandleSize
.
QuickdrawAPI.h
Begins defining a polygon. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
PolyHandle OpenPoly ( void );
A handle to a new polygon.
The OpenPoly
function starts saving lines for processing as a polygon definition. While a polygon is open, all calls to the Line
and LineTo
functions affect the outline of the polygon. Only the line endpoints affect the polygon definition; the pattern mode, pattern, and size do not affect it. The OpenPoly
function calls the HidePen
function, so no drawing occurs on the screen while the polygon is open (unless you call the ShowPen
function just after calling OpenPoly
, or you called ShowPen
previously without balancing it by a call to HidePen
).
A polygon should consist of a sequence of connected lines. The OpenPoly
function stores the definition for a polygon in a Polygon
structure.
When a polygon is open, the current graphics port’s polySave
field contains a handle to information related to the polygon definition. If you want to temporarily disable the polygon definition, you can save the current value of this field, set the field to NULL
, and later restore the saved value to resume the polygon definition.
Even though the onscreen presentation of a polygon is clipped, the definition of a polygon is not; you can define a polygon anywhere on the coordinate plane.
When you are finished calling the line-drawing functions that define your polygon, use the ClosePoly
function.
Do not call OpenPoly
while a region or another polygon is already open.
Polygons are limited to 64 KB. You can determine the polygon size while it is being formed by calling the Memory Manager function GetHandleSize
.
The OpenPoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Begins defining a region. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void OpenRgn ( void );
The OpenRgn
function allocates temporary memory to start saving lines and framed shapes for processing as a region definition. Call OpenRgn
only after initializing a region with the NewRgn
function.
The NewRgn
function stores the definition for a region in a Region
structure.
While a region is open, all calls to Line
, LineTo
, and the functions that draw framed shapes (except arcs) affect the outline of the region. Only the line endpoints and shape boundaries affect the region definition—the pattern mode, pattern, and size do not affect it.
When you are finished defining the region, call the CloseRgn
function.
The OpenRgn
function calls HidePen
, so no drawing occurs on the screen while the region is open (unless you call ShowPen
just after OpenRgn
, or you called ShowPen
previously without balancing it by a call to HidePen
). Since the pen hangs below and to the right of the pen location, drawing lines with even the smallest pen changes pixels that lie outside the region you define.
The outline of a region is mathematically defined and infinitely thin, and it separates the bit or pixel image into two groups of pixels: those within the region and those outside it.
A region should consist of one or more closed loops. Each framed shape itself constitutes a loop. Any lines drawn with the Line
or LineTo
function should connect with each other or with a framed shape. Even if the onscreen presentation of a region is clipped, the definition of a region is not; you can define a region anywhere on the coordinate plane with complete disregard for the location of various graphics port entities on that plane.
When a region is open, the current graphics port’s rgnSave
field contains a handle to information related to the region definition. If you want to temporarily disable the collection of lines and shapes, you can save the current value of this field, set the field to NULL
, and later restore the saved value to resume the region definition. Also, calling SetPort
while a region is being formed discontinues formation of the region until another call to SetPort
resets the region’s original graphics port.
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.
Regions are limited to 32 KB in size in basic QuickDraw and 64 KB in Color QuickDraw. You can determine the current size of an existing region by calling the Memory Manager function GetHandleSize
. When you structure 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
.
Do not call OpenRgn
while another region or a polygon is already open. When you are finished constructing the region, use the CloseRgn
function, which is described next.
The OpenRgn
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Compresses a data buffer stored in RAM. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PackBits ( Ptr *srcPtr, Ptr *dstPtr, short srcBytes );
On entry, a pointer to the first byte of a buffer of data to be compressed. On exit, a pointer to the first byte following the bytes compressed.
On entry, a pointer to the first byte in which to store compressed data. On exit, a pointer to the first byte following the compressed data.
The number of bytes of uncompressed data to be compressed. In versions of software prior to version 6.0.2, this number must be 127 or less.
You must allocate memory for the destination buffer itself. Allocate enough memory for a worst-case scenario where the destination buffer is 128 bytes long for each block of source data up to 127 bytes. Use the following formula to determine how much space to allocate for the destination buffer:
maxDstBytes := srcBytes + (srcBytes+126) DIV 127;
where maxDstBytes
stands for the maximum number of destination bytes.
The PackBits
algorithm is most effective on data buffers in which there are likely to be series of bytes containing the same value. For example, resources of many formats often contain many consecutive zeros. If you have a data buffer in which there are only likely to be a series of words or long words containing the same values, PackBits
is unlikely to be effective.
Because your application must allocate memory for the source and destination buffers, PackBits
does not move relocatable blocks. Thus, you can call it at interrupt time.
Because PackBits
changes the values of the srcPtr
and dstPtr
parameters, you should pass to PackBits
only copies of the pointers to the source and destination buffers. This allows you to access the beginning of the source and destination buffers after PackBits
returns. Also, if the source or destination buffer is stored in an unlocked, relocatable block, this technique prevents PackBits
from changing the value of a master pointer, which would make the original handle invalid.
QuickdrawAPI.h
Paints a wedge of the oval that fits inside a rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PaintArc ( const Rect *r, short startAngle, short arcAngle );
The rectangle that defines an oval’s boundaries.
The angle indicating the start of the arc.
The angle indicating the arc’s extent.
Using the pen pattern and pattern mode of the current graphics port, the PaintArc
function draws a wedge of the oval bounded by the rectangle that you specify in the r
parameter. As in the FrameArc
function, use the startAngle
and arcAngle
parameters to define the arc of the wedge.
The pen location does not change.
Use FillArc
, to draw a wedge with a pattern different from that specified in the pnPat
field of the current graphics port.
The PaintArc
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Paints an oval with the graphics pen’s pattern and pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PaintOval ( const Rect *r );
The rectangle that defines the oval’s boundary.
Using the pen pattern and pattern mode for the current graphics port, the PaintOval
function draws the interior of an oval just inside the bounding rectangle that you specify in the r
parameter. The pen location does not change.
Use FillOval
to draw the interior of an oval with a pen pattern different from that for the current graphics port.
The PaintOval
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Paints a polygon with the graphics pen’s pattern and pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PaintPoly ( PolyHandle poly );
A handle to the polygon to paint. The OpenPoly
function returns this handle when you first create the polygon.
Using the pen pattern and pattern mode for the current graphics port, the PaintPoly
function draws the interior of a polygon whose handle you pass in the poly
parameter. The pen location does not change.
This function temporarily converts the polygon into a region to perform their operations. The amount of memory required for this temporary region may be far greater than the amount required by the polygon alone.
You can estimate the size of this region by scaling down the polygon with the MapPoly
, converting the polygon into a region, checking the region’s size with the Memory Manager function GetHandleSize
, and multiplying that value by the factor by which you scaled the polygon.
The result of this graphics operation is undefined whenever any horizontal or vertical line drawn through the polygon would intersect the polygon’s outline more than 50 times.
Use the FillPoly
function to draw the interior of a polygon with a pattern different from that specified in the pnPat
field of the current graphics port.
Do not create a height or width for the polygon greater than 32,767 pixels, or PaintPoly
will crash.
The PaintPoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Paints a rectangle with the graphics pen’s pattern and pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PaintRect ( const Rect *r );
The rectangle to paint.
The PaintRect
function draws the interior of the rectangle that you specify in the r
parameter with the pen pattern for the current graphics port, according to the pattern mode for the current graphics port. The pen location does not change.
Use the FillRect
to draw the interior of a rectangle with a pen pattern different from that for the current graphics port.
The PaintRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Paints a region with the graphics pen’s pattern and pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PaintRgn ( RgnHandle rgn );
A handle to the region to paint.
Using the pen pattern and pattern mode for the current graphics port, the PaintRgn
function draws the interior of the region whose handle you pass in the rgn
parameter. The pen location does not change.
This function depends on the local coordinate system of the current graphics port. If you draw a region in a graphics port different from the one in which you defined the region, it may not appear in the proper position in the graphics port.
If any horizontal or vertical line drawn through the region would intersect the region’s outline more than 50 times, the results of this graphics operation are undefined.
Use FillRgn
to draw the interior of a region with a pen pattern different from that for the current graphics port.
The PaintRgn
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Paints a rounded rectangle with the graphics pen’s pattern and pattern mode. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PaintRoundRect ( const Rect *r, short ovalWidth, short ovalHeight );
The rectangle that defines the rounded rectangle’s boundaries.
The width of the oval defining the rounded corner.
The height of the oval defining the rounded corner.
Using the pattern and pattern mode of the graphics pen for the current graphics port, the PaintRoundRect
function draws the interior of the rounded rectangle bounded by the rectangle that you specify in the r
parameter. Use the ovalWidth
and ovalHeight
parameters to specify the diameters of curvature for the corners of the rounded rectangle.
The pen location does not change.
Use FillRoundRect
to draw the interior of a rounded rectangle with a pen pattern different from that for the current graphics port.
The PaintRoundRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Sets the pattern mode of the graphics pen in the current graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PenMode ( short mode );
The pattern mode. See “Source, Pattern, and Arithmetic Transfer Mode Constants.”
Using the pattern mode you specify in the mode
parameter, the PenMode
function sets the manner in which the pattern of the graphics pen is transferred onto the bitmap (or pixel map) when you draw lines or shapes in the current graphics port.
If you specify a source mode (such as one used with the CopyBits
function) instead of a pattern mode, no drawing is performed.
The current pattern mode is stored in the pnMode
field of the current graphics port. The initial pattern mode value is patCopy
, in which the pen pattern is copied directly to the bitmap.
To use highlighting, add the hilite
constant or its value to the source or pattern mode:
With highlighting, QuickDraw replaces the background color with the highlight color when your application draws or copies images between graphics ports. This has the visual effect of using a highlighting pen to select the object. (The global variable HiliteRGB
is read from parameter RAM when the machine starts. Basic graphics ports use the color stored in the HiliteRGB
global variable as the highlight color. Color graphics ports default to the HiliteRGB
global variable, but can be overridden by the HiliteColor
function.
This pen-manipulation function uses the local coordinate system of the current graphics port. Remember that each graphics port has its own pen, the state of which is stored in several fields of its GrafPort
or CGrafPort
structure. If you draw in one graphics port, change to another, and return to the first, the pen for the first graphics port has the same state as when you left it.
When your application draws with a pixel pattern, Color QuickDraw ignores the pattern mode and simply transfers the pattern directly to the pixel map without regard to the foreground and background colors.
The results of inverting a pixel are predictable only with direct pixels or 1-bit pixel maps. For indexed pixels, Color QuickDraw performs the inversion on the pixel indexes, which means the results depend entirely on the contents of the color table. The eight colors used in basic QuickDraw are stored in a color table represented by the global variable QDColors
. To display those eight basic QuickDraw colors on an indexed device, Color QuickDraw uses the Color Manager to obtain indexes to the colors in the CLUT that best map to the colors in the QDColors
color table. Because the index, not the color value, is inverted, the results are unpredictable.
QuickdrawAPI.h
Sets the size, pattern, and pattern mode of the graphics pen in the current graphics port to their initial values. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PenNormal ( void );
The PenNormal
function restores the size, pattern, and pattern mode of the graphics pen in the current graphics port to their initial values: a size of 1 pixel by 1 pixel, a pattern mode of patCopy
, and a pattern of black
. The pen location does not change.
The PenNormal
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Sets the bit pattern to be used by the graphics pen in the current graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PenPat ( const Pattern *pat );
A bit pattern, as defined by a Pattern
structure.
The PenPat
function sets the graphics pen to use the bit pattern defined in the Pattern
structure that you specify in the pat
parameter. (The standard patterns white
, black
, gray
, ltGray
, and dkGray
are predefined; the initial bit pattern for the pen is black
.) This pattern is stored in the pnPat
field of a GrafPort
structure. The QuickDraw painting functions (such as PaintRect
) also use the pen’s pattern when drawing a shape.
The PenPat
function also sets a bit pattern for the graphics pen in a color graphics port. The PenPat
function creates a handle, of type PixPatHandle
, for the bit pattern and stores this handle in the pnPixPat
field of the CGrafPort
structure. This pattern always uses the graphics port’s current foreground and background colors.
To define your own patterns, you typically create pattern, ‘PAT’, or pattern list, ‘PAT#’, resources.
The PenPat
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Sets the pixel pattern used by the graphics pen in the current color graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PenPixPat ( PixPatHandle pp );
A handle to the pixel pattern to use as the pen pattern.
The PenPixPat
function is similar to the basic QuickDraw function PenPat
, except that you pass PenPixPat
a handle to a multicolored pixel pattern rather than a bit pattern.
The PenPixPat
function stores the handle to the pixel pattern in the pnPixPat
field of the CGrafPort
structure, therefore, you should not dispose of this handle since QuickDraw removes all references to your pattern from an existing graphics port when you dispose of it.
If you use PenPixPat
to set a pixel pattern in a basic graphics port, the data in the pat1Data
field of the PixPat
structure is placed into the pnPat
field of the GrafPort
structure.
To define your own pixel pattern, you can create a pixel pattern resource, which is described in 'ppat'
, or you can use the NewPixPat
function. To set the pen to use a bit pattern, you can also use the QuickDraw function PenPat
.
The PenPixPat
function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
QuickdrawAPI.h
Sets the dimensions of the graphics pen in the current graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PenSize ( short width, short height );
The pen width, as an integer from 0 to 32,767. If you set the value to 0, the pen does not draw. Values less than 0 are undefined.
The pen height, as an integer from 0 to 32,767. If you set the value to 0, the pen does not draw. Values less than 0 are undefined.
The PenSize
function sets the width that you specify in the width
parameter and the height that you specify in the height
parameter for the graphics pen in the current graphics port. All subsequent calls to the Line
and LineTo
functions and to the functions that draw framed shapes in the current graphics port use the new pen dimensions.
You can get the current pen dimensions from the pnSize
field of the current graphics port, where the width and height are stored as a Point
structure.
This pen-manipulation function uses the local coordinate system of the current graphics port. Remember that each graphics port has its own pen, the state of which is stored in several fields of its GrafPort
or CGrafPort
structure. If you draw in one graphics port, change to another, and return to the first, the pen for the first graphics port has the same state as when you left it.
QuickdrawAPI.h
Inserts a picture comment into a picture that you are defining or into your printing code. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PicComment ( short kind, short dataSize, Handle dataHandle );
The type of comment.
Size of any additional data passed in the dataHandle
parameter. If no additional data is used, specify 0 in this parameter.
A handle to additional data, if used. If no additional data is used, specify NULL
in this parameter.
When used after your application begins creating a picture with the OpenCPicture
(or OpenPicture
) function, the PicComment
function inserts the specified comment into the Picture
structure. When sent to a printer driver after your application uses the PrOpenPage
function, PicComment
passes the data or commands in the specified comment directly to the printer.
Picture comments contain data or commands for special processing by output devices, such as printers.
Usually printer drivers process picture comments, but applications can also do so. For your application to process picture comments, it must replace the StdComment
function pointed to by the commentProc
field of the CQDProcs
or QDProcs
structure, which in turn is pointed to by the grafProcs
field of a CGrafPort
or GrafPort
structure. The default StdComment
function provided by QuickDraw does no comment processing whatsoever. You can use the SetStdCProcs
function to assist you in changing the CQDProcs
structure, and you can use the SetStdProcs
function to assist you in changing the QDProcs
structure.
If you create and process your own picture comments, you should define comments so that they contain information that identifies your application (to avoid using the same comments as those used by Apple or by other third-party products). You should define a comment as an ApplicationComment
comment type with a kind
value of 100. The first 4 bytes of the data for the comment should specify your application’s signature. You can use the next 2 bytes to identify the type of comment—that is, to specify a kind
value to your own application.
Suppose your application signature were 'WAVE'
, and you wanted to use the value 128 to identify a kind
value to your own application. You would supply values to the kind
and data
parameters to PicComment
as follows:
kind
= 100; data
= 'WAVE'
[4 bytes] + 128 [2 bytes] + additional data [n bytes]
Your application can then parse the first 6 bytes of the comment to determine whether and how to process the rest of the data in the comment. It is up to you to publish information about your comments if you wish them to be understood and used by other applications.
These former picture comments are now obsolete: SetGrayLevel
, ResourcePS
, PostScriptFile
, and TextIsPostScript
.
The PicComment
function may move or purge memory.
QuickdrawAPI.h
Determines whether a pixel map requires 32-bit addressing mode for access to its pixel image. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean PixMap32Bit ( PixMapHandle pmHandle );
A handle to an offscreen pixel map.
TRUE
if a pixel map requires 32-bit addressing mode for access to its pixel image. If your application is in 24-bit mode, you must change to 32-bit mode.
To get a handle to an offscreen pixel map, first use the GetGWorldPixMap
function. Then supply this handle for the pm
parameter of PixMap32Bit
.
QDOffscreen.h
Notifies QuickDraw that the content of a PixPat
structure, including its PixMap
structure or the image in its patData
field, has been modified. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PixPatChanged ( PixPatHandle ppat );
A handle to the changed pixel pattern.
The PixPatChanged
function sets the patXValid
field of the PixPat
structure specified in the ppat
parameter to –1 and notifies QuickDraw of the change.
If your application changes the pmTable
field of a pixel pattern’s PixMap
structure, it should call PixPatChanged
. However, if your application changes the content of the color table referenced by the PixMap
structure’s pmTable
field, it should call both the PixPatChanged
and the CTabChanged
functions.
Your application should never need to directly modify a PixPat
structure and use the PixPatChanged
function; instead, your application should use the QuickDraw functions for manipulating the values in a PixPat
structure.
The PixPatChanged
function may move or purge memory in the application heap; do not call the PixPatChanged
function at interrupt time.
QDOffscreen.h
Notifies QuickDraw that the content of a GrafPort
structure or CGrafPort
structure, including any of the data structures specified by handles within the structure, has been modified. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PortChanged ( GrafPtr port );
A pointer to the GrafPort
structure that you have changed.
If your application has changed a CGrafPort
structure, it must coerce the CGrafPtr
so it will point to a GrafPtr
before passing the pointer in the port
parameter.
You generally should not directly change any of the PixPat
structures specified in a CGrafPort
structure, but instead use the PenPixPat
and BackPixPat
functions. However, if your application does change the content of a PixPat
structure, it should call the PixPatChanged
function and the PortChanged
function.
If your application changes the pmTable
field of the PixMap
structure specified in the graphics port, your application should call PortChanged
. If your application changes the content of the ColorTable
structure referenced by the pmTable
field, it should call CTabChanged
also.
QDOffscreen.h
Changes the size of the port rectangle of the current graphics port (basic or color). (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void PortSize ( short width, short height );
The width of the reset port rectangle.
The height of the reset port rectangle.
The PortSize
function is normally called only by the Window Manager. The PortSize
function changes the size of the current graphics port’s port rectangle. The upper-left corner of the port rectangle remains at its same location the width and height of the port rectangle are set to the given width
and height
. In other words, PortSize
moves the lower-right corner of the port rectangle to a position relative to the upper-left corner.
The PortSize
function doesn’t change the clipping or visible region of the graphics port, nor does it affect the local coordinate system of the graphics port it changes only the width and height of the port rectangle. Remember that all drawing occurs only in the intersection of the boundary rectangle and the port rectangle, after being cropped to the visible region and the clipping region.
QuickdrawAPI.h
Adds protection to or removes protection from an entry in the current GDevice
data structure’s color table. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ProtectEntry ( short index, Boolean protect );
The index to the entry whose protection is to be changed.
A Boolean value: specify true
to protect the entry, false
to remove protection.
A protected entry can not be changed by other applications. ProtectEntry
returns a protection error in QDErr
if you attempt to protect an already protected entry. However, it can remove protection from any entry, even an already unprotected one.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDAddRectToDirtyRegion ( CGrafPtr inPort, const Rect *inBounds );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDAddRegionToDirtyRegion ( CGrafPtr inPort, RgnHandle inRegion );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void QDDisplayWaitCursor ( Boolean forceWaitCursor );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDDisposeRegionBits ( QDRegionBitsRef regionBits );
QuickdrawAPI.h
Determines whether QuickDraw has completed drawing in a given graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean QDDone ( GrafPtr port );
The GrafPort
structure for a graphics port in which your application has begun drawing; if you pass NULL
, QDDone
tests all open graphics ports.
TRUE
if all drawing operations have finished in the graphics port specified in the port
parameter, FALSE
if any remain to be executed. If you pass NULL
in the port
parameter, then QDDone
returns TRUE
only if drawing operations have completed in all ports.
The QDDone
function may be useful if a graphics accelerator is present and operating asynchronously. You can use it to ensure that all drawing is done before issuing new drawing commands, and to avoid the possibility that the new drawing operations might be overlaid by previously issued but unexecuted operations.
If a graphics port draws a clock or some other continuously operating drawing process, QDDone
may never return TRUE
.
To determine whether all drawing in a color graphics port has completed, you must coerce its CGrafPort
structure to a GrafPort
structure, which you pass in the port
parameter.
QDOffscreen.h
Obtains a result code from the last applicable QuickDraw function that you called. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
short QDError ( void );
The error result. On a system with only basic QuickDraw, QDError
always returns noErr
.
The QDError
function is helpful in determining whether insufficient memory caused a drawing operation - particularly those involving regions, polygons, pictures, and images copied with CopyBits
- to fail.
Basic QuickDraw uses stack space for work buffers. For complex operations such as depth conversion, dithering, and image resizing, stack space may not be sufficient. QuickDraw attempts to get temporary memory from other parts of the system. If that is still not enough, QDError
returns the nsStackErr
error. If your application receives this result, reduce the memory required by the operation.
When you structure drawing operations in an open region, the resulting region description may overflow the 64 KB limit. In this case, QDError
returns regionTooBigError
. Since the resulting region is potentially corrupt, the CloseRgn
function returns an empty region if it detects QDError
has returned regionTooBigError
. A similar error, rgnTooBigErr
, occurs when using the BitMapToRegion
function to convert a bitmap to a region.
The BitMapToRegion
function also generates the pixmapTooDeepErr
error if a PixMap
structure is supplied that is greater than 1 bit per pixel. You may be able to recover from this problem by coercing your PixMap
structure into a 1-bit PixMap
structure and calling the BitMapToRegion
function again.
The QDError
function does not report errors returned by basic QuickDraw.
QuickdrawAPI.h
Calls the Quartz compositor to flush all new drawing in a Carbon window to the display. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void QDFlushPortBuffer ( CGrafPtr port, RgnHandle region );
A window port. If the port has no back buffer, or if the port is an offscreen or printing port, this function does nothing.
An update region. Under normal conditions, you should pass NULL
to avoid the overhead of additional region operations.
In Mac OS X, drawing in a window port updates a back buffer associated with the window. Updates to this buffer are accumulated in a list called the dirty region.
The back buffer is automatically flushed to the display each time through the event loop. When the event loop does not get control soon enough—for example, during an animation sequence—you can call this function to flush the port buffer to the device immediately.
When you call this function, there are several different execution paths:
If the region
parameter is NULL
, the dirty region is flushed—along with any Quartz 2D drawing operations marked for update by calls to CGContextSynchronize
—and the dirty region is set to empty.
If the region
parameter specifies an update region, the intersection of the dirty region and the update region is flushed—along with any Quartz 2D drawing operations marked for update by calls to CGContextSynchronize
—and the flushed region is subtracted from the dirty region.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDGetCursorData ( Boolean contextCursor, PixMapHandle *crsrData, Point *hotSpot );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDGetDirtyRegion ( CGrafPtr port, RgnHandle rgn );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void QDGetPatternOrigin ( Point *origin );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Rect * QDGetPictureBounds ( PicHandle picH, Rect *outRect );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Point * QDGlobalToLocalPoint ( CGrafPtr port, Point *point );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Rect * QDGlobalToLocalRect ( CGrafPtr port, Rect *bounds );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
RgnHandle QDGlobalToLocalRegion ( CGrafPtr port, RgnHandle region );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean QDIsNamedPixMapCursorRegistered ( const char name[128] );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean QDIsPortBufferDirty ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean QDIsPortBuffered ( CGrafPtr port );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Point * QDLocalToGlobalPoint ( CGrafPtr port, Point *point );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Rect * QDLocalToGlobalRect ( CGrafPtr port, Rect *bounds );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
RgnHandle QDLocalToGlobalRegion ( CGrafPtr port, RgnHandle region );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDRegisterNamedPixMapCursor ( PixMapHandle crsrData, PixMapHandle crsrMask, Point hotSpot, const char name[128] );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDRestoreRegionBits ( RgnHandle region, QDRegionBitsRef regionBits );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
QDRegionBitsRef QDSaveRegionBits ( RgnHandle region );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDSetCursorScale ( float scale );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDSetDirtyRegion ( CGrafPtr port, RgnHandle rgn );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDSetNamedPixMapCursor ( const char name[128] );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void QDSetPatternOrigin ( Point origin );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean QDSwapPort ( CGrafPtr inNewPort, CGrafPtr *outOldPort );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
UInt32 QDSwapPortTextFlags ( CGrafPtr port, UInt32 newFlags );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
UInt32 QDSwapTextFlags ( UInt32 newFlags );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus QDUnregisterNamedPixMapCursor ( const char name[128] );
QuickdrawAPI.h
Obtains a pseudorandom integer. (Deprecated in Mac OS X v10.4. Use the Standard C Library random(3)
function instead.)
short Random ( void );
A pseudorandom integer, uniformly distributed in the range -32767 to 32767.
The value Random
returns depends solely on the global variable randSeed
, which the QuickDraw InitGraf
function initializes to 1. Each time the Random
function executes, it uses a numerical algorithm to change the value of randSeed
to prevent it from returning the same value each time it is called.
To prevent your application from generating the same sequence of pseudo-random numbers each time it is executed, initialize the randSeed
global variable, when your application starts up, to a volatile long word variable such as the current date and time. If you would like to generate the same sequence of pseudo-random numbers twice, on the other hand, simply set randSeed
to the same value before calling Random
for each sequence.
QuickdrawAPI.h
Determines whether a given RGBColor
data structure exists in the current device’s color table. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean RealColor ( const RGBColor *color );
The RGBColor
data structure to be tested.
The RealColor
function determines whether the color is available in the current GDevice
data structure’s CLUT, basing its search on the current resolution of the inverse table. For example, if the current value of the iTabRes
field is 4, RealColor
returns true
if there exists a color that exactly matches the top 4 bits of red, green, and blue. (See the iTabRes
field of the inverse table, ITab
.)
QuickdrawAPI.h
Reserves or removes reservation from an entry in the current GDevice
data structure’s color table. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ReserveEntry ( short index, Boolean reserve );
The index to the entry.
True
to reserve the entry, false
to remove the reservation.
A reserved entry cannot be matched by another application’s search function, and Color2Index
(or other functions that depend on it such as RGBForeColor
, RGBBackColor
, and SetCPixel
) never return that entry to another client. You could use this function to selectively protect a color for color table animation.
The ReserveEntry
function copies the low byte of the gdID
field of the current GDevice
data structure into the low byte of the ColorSpec.value
field of the color table when reserving an entry, and leaves the high byte alone. ReserveEntry
acts like selective protection and does not allow any changes if the current gdID
field is different than the one in the ColorSpec.value
field of the reserved entry. If a requested match is already reserved, ReserveEntry
returns a protection error. It can remove reservation from any entry, even if a requested match is already not reserved.
This function does nothing useful on Mac OS X.
QuickdrawAPI.h
Restores a selection of color table entries. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void RestoreEntries ( CTabHandle srcTable, CTabHandle dstTable, ReqListRec *selection );
The color table containing entries to be restored.
The color table in which to restore the entries. If dstTable
is NULL
, or points to the current GDevice
data structure’s color table, RestoreEntries
changes the device’s color table and the hardware CLUT to these new colors.
A pointer to the ReqListRec
data structure. The entries to be restored are enumerated as offsets into a ColorTable
data structure, not the contents of the ColorSpec.value
field.
The RestoreEntries
function does not rebuild the inverse table.
If a request is beyond the end of the destination color table, RestoreEntries
sets that position in the requestList
data structure to colReqErr
, and returns an error. RestoreEntries
assumes that the color table specified by the srcTable
parameter and the request list specified by the selection
parameter have the same number of entries.
RestoreEntries
does not change the color table’s seed, so no invalidation occurs (which may cause RGBForeColor
to act strangely). RestoreEntries
ignores protection and reservation of color table entries.
You generally should use the Palette Manager to give your application its own set of colors; use of RestoreEntries
should be limited to special-purpose applications. RestoreEntries
allows you to change a color table without changing its ctSeed
field. You can execute the application code and then use RestoreEntries
to put the original colors back in. However, in some cases things in the background may appear in the wrong colors, since they were never redrawn. To avoid this, your application must build its own new inverse table and redraw the background. If you then use RestoreEntries
, you should call the CTabChanged
function to clean up correctly.
This function does nothing useful on Mac OS X.
QuickdrawAPI.h
Changes the background color. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void RGBBackColor ( const RGBColor *color );
An RGBColor
structure.
If the current port is defined by a CGrafPort
structure, QuickDraw supplies its rgbBkColor
field with the RGB value that you specify in the color
parameter, and places the pixel value most closely matching that color in the bkColor
field. For indexed devices, the pixel value is an index to the current device’s CLUT. F or direct devices, the value is the 16-bit or 32-bit equivalent to the RGB value.
If the current port is defined by a GrafPort
structure, basic QuickDraw supplies its fgColor
field with a color value determined by taking the high bit of each of the red, green, and blue components of the color that you supply in the color
parameter. Basic QuickDraw uses that 3-bit number to select a color from its eight-color system.
You can also use Palette Manager functions to set the background color.
To determine the current background color, use the GetBackColor
function.
Because a pixel pattern already contains color, QuickDraw ignores the background color and foreground colors when your application draws with a pixel pattern. Use the PenPixPat
function to assign a pixel pattern to the foreground pattern used by the graphics pen. Use the BackPixPat
function to assign a pixel pattern as the background pattern for the current color graphics port. Use the FillCRect
, FillCOval
, FillCRoundRect
, FillCArc
, FillCRgn
, and FillCPoly
functions to fill shapes with a pixel pattern.
The RGBBackColor
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Changes the color of the “ink” used for framing and painting. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void RGBForeColor ( const RGBColor *color );
An RGBColor
structure.
If the current port is defined by a CGrafPort
structure, QuickDraw supplies its rgbFgColor
field with the RGB value that you specify in the color
parameter, and places the pixel value most closely matching that color in the fgColor
field. For indexed devices, the pixel value is an index to the current device’s CLUT. For direct devices, the value is the 16-bit or 32-bit equivalent to the RGB value.
If the current port is defined by a GrafPort
structure, basic QuickDraw supplies its fgColor
field with a color value determined by taking the high bit of each of the red, green, and blue components of the color that you supply in the color
parameter. Basic QuickDraw uses that 3-bit number to select a color from its eight-color system.
You can also use Palette Manager functions to set the foreground color.
To determine the current foreground color, use the GetForeColor
function.
QuickDraw ignores the foreground and background colors when your application draws with a pixel pattern. Assign a pixel pattern to the foreground pattern used by the graphics pen; by using the BackPixPat
function to assign a pixel pattern as the background pattern for the current color graphics port; and by using the FillCRect
, FillCOval
, FillCRoundRect
, FillCArc
, FillCRgn
, and FillCPoly
functions to fill shapes with a pixel pattern.
The RGBForeColor
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Saves a selection of color table entries. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SaveEntries ( CTabHandle srcTable, CTabHandle resultTable, ReqListRec *selection );
The color table containing entries to be saved. If you supply NULL
, SaveEntries
uses the current device’s color table as the source.
The color table in which to save the entries.
A pointer to the ReqListRec
data structure. The entries to be set are enumerated as offsets into a ColorTable
data structure, not the contents of the ColorSpec.value
field.) If an entry is not present in srcTable
, then SaveEntries
sets that position of the selection
parameter to colReqErr
, and that position of resultTable
contains random values.
If SaveEntries
can not find one or more entries, then it posts an error code to QDError
; however, for every entry in selection which is not colReqErr
, the values in resultTable
are valid. SaveEntries
assumes that the color table specified by the srcTable
parameter and the request list specified by the selection
parameter have the same number of entries.
The output of SaveEntries
is the same as the input for RestoreEntries
, except for the order.
QuickdrawAPI.h
Determines the resolution of the main device. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ScreenRes ( short *scrnHRes, short *scrnVRes );
On return, the number of horizontal pixels per inch displayed by the current device.
On return, the number of vertical pixels per inch displayed by the current device.
To determine the resolutions of all available graphics devices, examine their GDevice
structures. The horizontal and vertical resolutions for a graphics device are stored in the hRes
and vRes
fields, respectively, of the PixMap
structure for the device’s GDevice
structure.
Currently, QuickDraw and the Printing Manager always assume a screen resolution of 72 dpi.
Do not use the actual screen resolution as a scaling factor when drawing into a printing graphics port. Instead, always use 72 dpi as the scaling factor. See the Printing Manager documentation for more information about drawing into a printing graphics port.
QuickdrawAPI.h
Scroll the pixels of a specified portion of a basic graphics port’s bitmap (or a color graphics port’s pixel map). (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ScrollRect ( const Rect *r, short dh, short dv, RgnHandle updateRgn );
The pointer to the rectangle defining the area to be scrolled.
The horizontal distance to be scrolled.
The vertical distance to be scrolled.
A handle to the region of the window that needs to be updated.
The ScrollRect
function shifts pixels that are inside the specified rectangle of the current graphics port. No other pixels or the bits they represent are affected. The pixels are shifted a distance of dh
horizontally and dv
vertically. The positive directions are to the right and down. The pixels that are shifted out of the specified rectangle are not displayed, and the bits they represent are not saved. It is up to your application to save this data.
The empty area created by the scrolling is filled with the graphics port’s background pattern, and the update region is changed to this filled area.
The ScrollRect
function doesn’t change the local coordinate system of the graphics port it simply moves the rectangle specified in the r
parameter to different coordinates. Notice that ScrollRect
doesn’t move the graphics pen or the clipping region. However, because the document has moved, they’re in different positions relative to the document.
By creating an update region for the window, ScrollRect
forces an update event. After using ScrollRect
, your application should use its own window-updating code to draw into the update region of the window.
The ScrollRect
function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SectRegionWithPortClipRegion ( CGrafPtr port, RgnHandle ioRegion );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SectRegionWithPortVisibleRegion ( CGrafPtr port, RgnHandle ioRegion );
QuickdrawAPI.h
Determines how far filling will extend to pixels matching the color of a particular pixel. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SeedCFill ( const BitMap *srcBits, const BitMap *dstBits, const Rect *srcRect, const Rect *dstRect, short seedH, short seedV, ColorSearchUPP matchProc, long matchData );
The source image. If the image is in a pixel map, you must coerce its PixMap
structure to a BitMap
structure.
On return, the destination mask.
The rectangle of the source image.
The rectangle of the destination image.
The horizontal position of the seed point.
The vertical position of the seed point.
An optional color search function.
Data for the optional color search function.
The SeedCFill
function generates a mask showing where the pixels in an image can be filled from a starting point, like the paint pouring from the MacPaint paint-bucket tool. This mask is a bitmap filled with 1’s to indicate all pixels adjacent to a seed point whose colors do not exactly match the RGBColor
structure for the pixel at the seed point. You can then use this mask with the CopyBits
, CopyMask
, and CopyDeepMask
functions.
You specify a source image in the srcBits
parameter and, in the srcRect
parameter, specify a rectangle within that source image. You specify where to begin seeding in the seedH
and seedV
parameters, which must be the horizontal and vertical coordinates of a point in the local coordinate system of the source bitmap. By default, the 1’s returned in the mask indicate all pixels adjacent to the seed point whose pixel values do not exactly match the pixel value of the pixel at the seed point. To use this default, set the matchProc
and matchData
parameters to 0.
In generating the mask, SeedCFill
uses the CopyBits
function to convert the source image to a 1-bit mask. The SeedCFill
function installs a default color search function that returns 0 if the pixel value matches that of the seed point all other pixel values return 1’s.
The SeedCFill
function does not scale so the source and destination rectangles must be the same size. Calls to SeedCFill
are not clipped to the current port and are not stored into QuickDraw pictures.
To customize SeedCFill,
write your own color search function and point to it in the matchProc
parameter; SeedCFill
will then use your function instead of the default.
QuickdrawAPI.h
Determines how far filling will extend from a seeding point. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SeedFill ( const void *srcPtr, void *dstPtr, short srcRow, short dstRow, short height, short words, short seedH, short seedV );
A pointer to the source bit image.
On input, a pointer to the destination bit image; upon return, a pointer to the bitmap containing the resulting mask.
Row width of the source bitmap.
Row width of the destination bitmap.
Height (in pixels) of the fill rectangle.
Width (in words) of the fill rectangle.
The horizontal offset (in pixels) at which to begin filling the destination bit image.
The vertical offset (in pixels) at which to begin filling the destination bit image.
The SeedFill
function produces a mask showing where bits in an image can be filled from a starting point, like the paint pouring from the MacPaint paint-bucket tool. The SeedFill
returns this mask in the dstPtr
parameter. This mask is a bitmap filled with 1’s only where the pixels in the source image can be filled. You can then use this mask with the CopyBits
, CopyMask
, and CopyDeepMask
functions.
Point to the bit image you want to fill with the srcPtr
parameter, which can point to the image’s base address or a word boundary within the image. Specify a pixel height and word width with the height
and words
parameters to define a fill rectangle that delimits the area you want to fill. The fill rectangle can be the entire bit image or a subset of it. Point to a destination image with the dstPtr
parameter. Specify the row widths of the source and destination bitmaps (their rowBytes
values) with the srcRow
and dstRow
parameters. (The bitmaps can be different sizes, but they must be large enough to contain the fill rectangle at the origins specified by the srcPtr
and dstPtr
parameters.)
You specify where to begin filling with the seedH
and seedV
parameters: they specify a horizontal and vertical offset in pixels from the origin of the image pointed to by the srcPtr
parameter. The SeedFill
function calculates contiguous pixels from that point out to the boundaries of the fill rectangle, and it stores the result in the bit image pointed to by the dstPtr
parameter.
Calls to SeedFill
are not clipped to the current port and are not stored into QuickDraw pictures.
QuickdrawAPI.h
Specifies a color cursor for display on the screen. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetCCursor ( CCrsrHandle cCrsr );
A handle to the color cursor to be displayed.
At the time the cursor is set, it is expanded to the current screen depth so that it can be drawn rapidly. You must call GetCCursor
before you call SetCCursor
; however, you can make several subsequent calls to SetCCursor
once GetCCursor
creates the CCrsr
structure.
If your application has changed the cursor’s data or its color table, it must also invalidate the crsrXValid
and crsrID
fields of the CCrsr
structure before calling SetCCursor
.
QuickdrawAPI.h
Sets the gdID
field in the current GDevice
data structure to identify this client program to its search and complement functions. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetClientID ( short id );
The ID to be set in the device data structure.
QuickdrawAPI.h
Sets the color of an individual pixel to the color that most closely matches the RGB color that you specify in the cPix
parameter. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetCPixel ( short h, short v, const RGBColor *cPix );
The horizontal coordinate of the point at the upper-left corner of the pixel.
The vertical coordinate of the point at the upper-left corner of the pixel.
An RGBColor
structure.
On an indexed color system, the SetCPixel
function sets the pixel value to the index of the best-matching color in the current device’s CLUT. In a direct environment, the SetCPixel
function sets the pixel value to a 16-bit or 32-bit direct pixel value.
To determine the color of an individual pixel, use the GetCPixel
function.
The SetCPixel
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Sets the current cursor. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetCursor ( const Cursor * crsr );
A Cursor
structure for the cursor to be displayed.
If the cursor is hidden, it remains hidden and attains its new appearance only when it’s uncovered. If the cursor is already visible, it changes to the new appearance immediately.
You need to use the InitCursor
function to initialize the standard arrow cursor and make it visible on the screen before you call SetCursor
to change the cursor’s appearance.
To display a color cursor, use the SetCCursor
function.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSErr SetCursorComponent ( ComponentInstance ci );
This function is not implemented on Mac OS X.
QuickdrawAPI.h
Sets the attribute bits of a GDevice
structure. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetDeviceAttribute ( GDHandle gdh, short attribute, Boolean value );
A handle to a GDevice
structure.
One of the specific constants, which represent bits in the gdFlags
field of a GDevice
structure. See GDevice for the values you can use in this parameter.
A value of either 0 or 1 for the flag bit specified in the attribute
parameter.
For the graphics device specified in the gdh
parameter, the SetDeviceAttribute
function sets the flag bit specified in the attribute
parameter to the value specified in the value
parameter.
Your application should never directly change the gdFlags
field of the GDevice
structure; instead, use only the SetDeviceAttribute
function.
The SetDeviceAttribute
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Sets a group of color table entries for the current GDevice
data structure. This function is used by system software and your application should not need to call it. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetEntries ( short start, short count, CSpecArray aTable );
The index of the first entry to be changed.
The number of entries to be changed. Note that all values are zero-based; for example, to set three entries, pass 2 in the count parameter.
An array of ColorSpec
data structures containing the colors to be used. Directly specify a cSpecArray
structure, not the beginning of a color table. The ColorSpec.value
fields of the entries must be in the logical range for the target device’s assigned pixel depth. Thus, with a 4-bit pixel size, the ColorSpec.value
fields should be in the range 1 to 15. With an 8-bit pixel size, the range is 0 to 255.
Instead of using SetEntries
, you should use the Palette Manager function SetEntryColor
to allow your application to run in a multiscreen or multitasking environment.
The SetEntries
positional information works in logical space rather than in the actual memory space used by the hardware. Requesting a change at the fourth position in the color table may not modify the fourth color table entry in the hardware, but it does correctly change the color on the screen for any pixels with a value of 4 in the video card. The SetEntries
mode characterized by a start position and a length is called sequence mode. In this case, SetEntries
sequentially loads new colors into the hardware in the same order as they appear in the aTable
parameter, copies the clientID
fields for changed color table entries from the current GDevice
data structure’s gdID
field, and ignores the ColorSpec.value
fields.
The other SetEntries
mode is called index mode. It allows the cSpecArray
structure to specify where the data will be installed on an entry-by-entry basis. To use this mode, pass –1 for the start position, with a valid count and a pointer to the cSpecArray
data structure. Each entry is installed into the color table at the position specified by the ColorSpec.value
field of each entry in the cSpecArray
data structure. In the current GDevice
data structure’s color table, the ColorSpec.value
fields of all changed entries are assigned the GDevice
data structure’s gdID
value.
When the Color Manager changes color table entries, it invalidates all cached fonts, and changes the color table’s seed number so that the next drawing operation triggers the Color Manager to rebuild the inverse table. If any of the requested entries are protected or out of range, the Color Manager returns a protection error, and nothing happens. The Color Manager changes a reserved entry only if the current gdID
field of the current GDevice
data structure matches the low byte of the intended ColorSpec.value
field in the color table.
QuickdrawAPI.h
Sets a GDevice
structure as the current device. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetGDevice ( GDHandle gd );
A handle to a GDevice
structure.
Your application won’t generally need to use this function, because when your application draws into a window on one or more screens, Color QuickDraw automatically switches GDevice
structures as appropriate; and when your application needs to draw into an offscreen graphics world, it can use the SetGWorld
function to set the graphics port as well as the GDevice
structure for the offscreen environment. However, if your application uses the SetPort
function instead of the SetGWorld
function to set the graphics port to or from an offscreen graphics world, then your application must use SetGDevice
in conjunction with SetPort
.
A handle to the currently active device is kept in the global variable TheGDevice
.
The SetGDevice
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Changes the coordinates of the window origin of the port rectangle of the current graphics port (basic or color). (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetOrigin ( short h, short v );
The horizontal coordinate of the upper-left corner of the port rectangle.
The vertical coordinate of the upper-left corner of the port rectangle.
The SetOrigin
function changes the coordinates of the upper-left corner of the current graphics port’s port rectangle to the values supplied by the h
and v
parameters. All other points in the current graphics port’s local coordinate system are calculated from this point. All subsequent drawing and calculation functions use the new coordinate system.
The SetOrigin
function does not affect the screen; it does, however, affect where subsequent drawing inside the graphics port appears. The SetOrigin
function does not offset the coordinates of the clipping region or the graphics pen, which therefore change position on the screen (unlike the boundary rectangle, port rectangle, and visible region, which don’t change position onscreen).
Because SetOrigin
does not move the window’s clipping region, use the GetClip
function to store your clipping region immediately after your first call to SetOrigin
—if you use clipping regions in your windows. Before calling your own window-drawing function, use the ClipRect
function to define a new clipping region—to avoid drawing over your scroll bars, for example. After calling your own window-drawing function, use the SetClip
function to restore the original clipping region. You can then call SetOrigin
again to restore the window origin to a horizontal coordinate of 0 and a vertical coordinate of 0 with your original clipping region intact.
All other functions in the Macintosh Toolbox and Operating System preserve the local coordinate system of the current graphics port. The SetOrigin
function is useful for readjusting the coordinate system after a scrolling operation.
Note that the Window Manager and Control Manager always assume the window’s upper-left point has a horizontal coordinate of 0 and a vertical coordinate of 0 when they draw in a window. Therefore, if you use SetOrigin
to change the window origin, be sure to use SetOrigin
again to return the window origin to a horizontal coordinate of 0 and a vertical coordinate of 0 before using any Window Manager or Control Manager functions.
QuickdrawAPI.h
Restores the state of the graphics pen that was saved with the GetPenState
function. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPenState ( const PenState *pnState );
A PenState
structure previously created with the GetPenState
function. The SetPenState
function sets the graphics pen’s location, size, pattern, and pattern mode in the current graphics port to the values stored in this structure.
This pen-manipulation function uses the local coordinate system of the current graphics port. Remember that each graphics port has its own pen, the state of which is stored in several fields of its GrafPort
or CGrafPort
structure. If you draw in one graphics port, change to another, and return to the first, the pen for the first graphics port has the same state as when you left it.
QuickdrawAPI.h
Restores an offscreen pixel image to the state that you saved with the GetPixelsState
function. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPixelsState ( PixMapHandle pm, GWorldFlags state );
A handle to an offscreen pixel map.
Flags, which you usually save with the GetPixelsState
function. You can use either of the constants pixelsPurgeable
or pixelsLocked here.
Because only an unlocked memory block can be purged, SetPixelsState
calls the UnlockPixels
and AllowPurgePixels
functions if the state
parameter specifies the pixelsPurgeable
flag. If the state
parameter does not specify the pixelsPurgeable
flag, SetPixelsState
makes the base address for the offscreen pixel image unpurgeable.
If the state
parameter does not specify the pixelsLocked
flag, SetPixelsState
allows the base address for the offscreen pixel image to be moved.
The SetPixelsState
function changes the state of the memory allocated for an offscreen pixel image to the state indicated in the state
parameter.
After using GetPixelsState
and before using SetPixelsState
, your application can temporarily alter the offscreen graphics world by using the AllowPurgePixels
function to temporarily mark the memory block for its offscreen pixel map as purgeable, the NoPurgePixels
function to make it unpurgeable, the LockPixels
function to prevent it from being moved, and the UnlockPixels
function to unlock it.
The SetPixelsState
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QDOffscreen.h
Changes the current graphics port (basic or color). (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
virtual void SetPort ( void *port );
A pointer to a GrafPort
structure. Typically, you pass a pointer to a GrafPort
structure that you previously saved with the GetPort
function. The SetPort
function sets this structure to be the current graphics port.
All QuickDraw drawing functions affect the bitmap of, and use the local coordinate system of, the current graphics port. Each graphics port has its own graphics pen and text characteristics, which remain unchanged when the graphics port isn’t selected as the current graphics port.
When your application runs in Color QuickDraw or uses offscreen graphics worlds, it should use the SetGWorld
function instead of SetPort
. The SetGWorld
function restores the current graphics port for basic and color graphics ports as well as offscreen graphics worlds.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortBackPixPat ( CGrafPtr port, PixPatHandle backPattern );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
Sets the bitmap for the current basic graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortBits ( const BitMap *bm );
A pointer to the BitMap
structure to set for the current graphics port. Be sure to prepare all fields of the BitMap
structure before you call SetPortBits
.
You should never need to use this function. This function, created for early versions of QuickDraw, allows you to perform all normal drawing and calculations on a buffer other than the screen—for example, copying a small offscreen image onto the screen with the CopyBits
function. However, instead of using SetPortBits
, you should use the more powerful offscreen graphics capabilities.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortBounds ( CGrafPtr port, const Rect *rect );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortClipRegion ( CGrafPtr port, RgnHandle clipRgn );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4.)
Not recommended
OSErr SetPortCustomXFerProc ( CGrafPtr port, CustomXFerProcPtr proc, UInt32 flags, UInt32 refCon );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortFillPixPat ( CGrafPtr port, PixPatHandle penPattern );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortFracHPenLocation ( CGrafPtr port, short pnLocHFrac );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortGrafProcs ( CGrafPtr port, CQDProcsPtr procs );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortOpColor ( CGrafPtr port, const RGBColor *opColor );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortPenMode ( CGrafPtr port, SInt32 penMode );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortPenPixPat ( CGrafPtr port, PixPatHandle penPattern );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortPenSize ( CGrafPtr port, Point penSize );
Use this new accessor function in place of direct access to structures.
QuickdrawAPI.h
Sets the pixel map for the current color graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortPix ( PixMapHandle pm );
A handle to the PixMap
structure.
The SetPortPix
function replaces the portPixMap
field of the current CGrafPort
structure with the handle you specify in the pm
parameter.
Typically, your application does not need to call this function.
The SetPortPix
function is analogous to the basic QuickDraw function SetPortBits
, which sets the bitmap for the current basic graphics port. The SetPortPix
function has no effect when used with a basic graphics port. Similarly, SetPortBits
has no effect when used with a color graphics port.
Both SetPortPix
and SetPortBits
allow you to perform drawing and calculations on a buffer other than the screen. However, instead of using these functions, use the offscreen graphics capabilities.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortTextFace ( CGrafPtr port, StyleParameter face );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortTextFont ( CGrafPtr port, short txFont );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortTextMode ( CGrafPtr port, short mode );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortTextSize ( CGrafPtr port, short txSize );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetPortVisibleRegion ( CGrafPtr port, RgnHandle visRgn );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetQDError ( OSErr err );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetQDGlobalsArrow ( const Cursor *arrow );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetQDGlobalsRandomSeed ( long randomSeed );
QuickdrawAPI.h
Obtains a CQDProcs
structure with fields that point to QuickDraw’s standard low-level functions, which you can modify to change QuickDraw’s standard low-level behavior. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetStdCProcs ( CQDProcs *procs );
Upon completion, a CQDProcs
structure with fields that point to QuickDraw’s standard low-level functions. You can change one or more fields to point to your own functions and then set the color graphics port to use this modified CQDProcs
structure.
For each shape that QuickDraw can draw, certain functions perform basic graphics operations on the shape: framing, painting, erasing, inverting, and filling. These functions, in turn, call a low-level drawing function for the shape.
The grafProcs
field determines which low-level functions are called. If that field contains a value of NULL
, the standard functions are called. You can set the grafProcs
field to point to a structure of pointers to your own functions, and either completely override the standard ones or call them after your functions have modified their parameters as necessary.
The SetStdCProcs
function sets all the fields of the CQDProcs
structure to point to the standard functions. You can then reset the ones with which you are concerned.
The functions you install in the CDQProcs
structure must have the same calling sequences as the standard basic QuickDraw functions.
When drawing in a color graphics port, your application must always use SetStdCProcs
instead of SetStdProcs
.
QuickdrawAPI.h
Obtains a QDProcs
structure with fields that point to basic QuickDraw’s standard low-level functions, which you can modify to point to your own functions. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void SetStdProcs ( QDProcs *procs );
On return, a pointer to a QDProcs
structure with fields that point to basic QuickDraw’s standard low-level functions. You can change one or more fields of this structure to point to your own functions and then set the basic graphics port to use this modified QDProcs
structure. By changing these pointers, you can install your own functions, and either completely override the standard ones or call them after your functions have modified their parameters as necessary.
The functions you install in this QDProcs
structure must have the same calling sequences as the standard functions.
The Color QuickDraw function SetStdCProcs
is analogous to the SetStdProcs
function, which you should use with computers that support only basic QuickDraw. When drawing in a color graphics port, your application must always use SetStdCProcs
instead of SetStdProcs
.
QuickdrawAPI.h
Changes the ink of a graphics pen from invisible to visible, making pen drawing appear on the screen. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void ShowPen ( void );
ShowPen
is called by the functions CloseRgn
, ClosePoly
, and ClosePicture
.
The ShowPen
function increments the pnVis
field of the current graphics port. For 0 or positive values, the pen drawing shows on the screen.
For example, if you have used the HidePen
function to decrement the pnVis
field from 0 to –1, use the ShowPen
function to make its value 0 so that QuickDraw resumes drawing on the screen. Subsequent calls to ShowPen
increment pnVis
beyond 0, so every call to ShowPen
should be balanced by a call to HidePen
.
This pen-manipulation function uses the local coordinate system of the current graphics port. Remember that each graphics port has its own pen, the state of which is stored in several fields of its GrafPort
or CGrafPort
structure. If you draw in one graphics port, change to another, and return to the first, the pen for the first graphics port has the same state as when you left it.
QuickdrawAPI.h
QuickDraw’s standard low-level function for drawing an arc or a wedge. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdArc ( GrafVerb verb, const Rect *r, short startAngle, short arcAngle );
The action to perform. See “Verb Constants.”
The rectangle to contain the arc.
The beginning angle.
The ending angle.
Using the action specified in the verb
parameter, the StdArc
function draws an arc or wedge of the oval that fits inside the rectangle specified in the r
parameter. The arc or wedge is bounded by the radii specified in the startAngle
and arcAngle
parameters.
You should only call this low-level function from your customized QuickDraw functions.
The StdArc
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
QuickDraw’s standard low-level function for transferring bits and pixels. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdBits ( const BitMap *srcBits, const Rect *srcRect, const Rect *dstRect, short mode, RgnHandle maskRgn );
A pointer to a bitmap or pixel map containing the image to copy.
A pointer to the source rectangle.
The destination rectangle.
The source mode for the copy.
A handle to a region acting as a mask for the transfer.
The StdBits
function transfers a bit or pixel image between the bitmap or pixel map specified in the srcBits
parameter and bitmap of the current graphics port, just as if the CopyBits
function were called with the same parameters and with a destination bitmap equal to (* thePort).portBits
.
You should only call this low-level function from your customized QuickDraw functions.
See CopyBits
for a discussion of the destination bitmap and of the srcBits
, srcRect
, dstRect
, mode
, and maskRgn
parameters
The StdBits
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
QuickDraw’s standard low-level function for processing a picture comment. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdComment ( short kind, short dataSize, Handle dataHandle );
The type of comment.
The size of additional data, in bytes.
A handle to additional data.
If there’s no additional data for the comment, the value of the dataHandle
parameter is NULL
and the value of the dataSize
parameter is 0. The StdComment
function simply ignores the comment.
You should only call this low-level function from your customized QuickDraw functions.
The StdComment
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
QuickDraw’s standard low-level function for retrieving information from the definition of a picture. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdGetPic ( void *dataPtr, short byteCount );
On return, a pointer to the collected picture data.
The size of the picture data.
The StdGetPic
function retrieves from the definition of the currently open picture the next number of bytes as specified in the byteCount
parameter.
You should only call this low-level function from your customized QuickDraw functions.
QuickdrawAPI.h
QuickDraw’s standard low-level function for drawing a line. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdLine ( Point newPt );
The point to which to draw the line.
The StdLine
function draws a line from the current pen location to the location (in local coordinates) specified in the newPt
parameter.
You should only call this low-level function from your customized QuickDraw functions.
The StdLine
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdOpcode ( const Rect *fromRect, const Rect *toRect, UInt16 opcode, SInt16 version );
QuickdrawAPI.h
QuickDraw’s standard low-level function for drawing an oval. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdOval ( GrafVerb verb, const Rect *r );
The action to perform. See “Verb Constants.”
The rectangle to contain the oval.
The StdOval
function draws an oval inside the given rectangle specified in the r
parameter according to the action specified in the verb
parameter.
You should only call this low-level function from your customized QuickDraw functions.
The StdOval
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
QuickDraw’s standard low-level function for drawing a polygon. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdPoly ( GrafVerb verb, PolyHandle poly );
The action to perform. See “Verb Constants.”
A handle to the polygon data.
The StdPoly
function draws the polygon specified in the poly
parameter according to the action specified in the verb
parameter.
You should only call this low-level function from your customized QuickDraw functions.
The StdPoly
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
QuickDraw’s standard low-level function for saving information as the definition of a picture. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdPutPic ( const void *dataPtr, short byteCount );
A pointer to the collected picture data.
The size of the picture data.
The StdPutPic
function saves as the definition of the currently open picture the drawing commands stored in the data structure pointed to by the dataPtr
parameter, starting with the first byte and continuing for the next number of bytes as specified in the byteCount
parameter.
You should only call this low-level function from your customized QuickDraw functions.
The StdPutPic
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
QuickDraw’s standard low-level function for drawing a rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdRect ( GrafVerb verb, const Rect *r );
The action to perform. See “Verb Constants.”
The rectangle to draw.
The StdRect
function draws the rectangle specified in the r
parameter according to the action specified in the verb
parameter.
You should only call this low-level function from your customized QuickDraw functions.
The StdRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
QuickDraw’s standard low-level function for drawing a region. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdRgn ( GrafVerb verb, RgnHandle rgn );
The action to perform. See “Verb Constants.”
A handle to the region data.
The StdRgn
function draws the region specified in the rgn
parameter according to the action specified in the verb
parameter.
You should only call this low-level function from your customized QuickDraw functions.
The StdRgn
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
QuickDraw’s standard low-level function for drawing a rounded rectangle. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StdRRect ( GrafVerb verb, const Rect *r, short ovalWidth, short ovalHeight );
The action to perform. See “Verb Constants.”
The rectangle to draw.
The width diameter for the corner oval.
The height diameter for the corner oval.
The StdRRect
function draws the rounded rectangle specified in the r
parameter according to the action specified in the verb
parameter. The ovalWidth
and ovalHeight
parameters specify the diameters of curvature for the corners.
You should only call this low-level function from your customized QuickDraw functions.
The StdRRect
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Sets byte values into memory. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void StuffHex ( void *thingPtr, ConstStr255Param s );
A pointer to any data structure in memory. If thingPtr
is an odd address, then thingPtr
is interpreted as pointing to the next word boundary.
A string of characters representing hexadecimal digits. All characters in this string must be hexadecimal digits (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F). Otherwise, StuffHex
may set bytes in the data structure pointed to by thingPtr
to arbitrary values. If there are an odd number of characters in the string, the last character is ignored.
The StuffHex
function sets bytes in memory beginning with that byte specified by the parameter thingPtr
. The total number of bytes set is equivalent to half the length of the string, ignoring the last character if the number of characters is odd.
Each byte to be set corresponds to two characters in the string. These characters should represent hexadecimal digits. For example, the string ‘ D41A
’ results in 2 bytes being set to the values $D4 and $1A, respectively.
To copy a range of bytes from one memory location to another, you should ordinarily use the Memory Manager function, BlockMove
.
The StuffHex
function does no range checking to ensure that bytes being set are within the bounds of a certain data structure. If you do not use StuffHex
carefully, you may change memory in the partition of your application or another application in unpredictable ways.
Although the StuffHex
function sets the value of individual bytes, it does not move relocatable blocks. Thus, you can call it at interrupt time.
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Handle SwapPortPicSaveHandle ( CGrafPtr port, Handle inPicSaveHdl );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Handle SwapPortPolySaveHandle ( CGrafPtr port, Handle inPolySaveHdl );
QuickdrawAPI.h
(Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Handle SwapPortRegionSaveHandle ( CGrafPtr port, Handle inRegionSaveHdl );
QuickdrawAPI.h
Synchronizes the origin in a Quartz context with the lower-left corner of the associated graphics port. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSStatus SyncCGContextOriginWithPort ( CGContextRef inContext, CGrafPtr port );
A Quartz context associated with a graphics port. You can obtain such a context by calling QDBeginCGContext
.
The graphics port associated with the context.
A result code. If noErr
, the context’s origin was successfully changed.
If you’re using Quartz 2D to draw in a graphics port and SetOrigin
is called to change the port’s origin, you can call this function to maintain the correspondence between the context’s origin and the lower-left corner of the portBounds
rectangle.
When you call this function:
The current transformation matrix (CTM) is reset to its default values. Any changes you made to the CTM prior to calling this function are lost.
The CTM is translated to establish the new origin, taking the port’s current origin into account.
QuickdrawAPI.h
Determines whether the flag bit for an attribute has been set in the gdFlags
field of a GDevice
structure. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
Boolean TestDeviceAttribute ( GDHandle gdh, short attribute );
A handle to a GDevice
structure.
One of the specific constants, which represent bits in the gdFlags
field of a GDevice
structure. See “Device Attribute Constants” for a description of the values you can use in this parameter.
TRUE
if the bit of the graphics device attribute specified in the attribute
parameter is set to 1. Otherwise, TestDeviceAttribute
returns FALSE
.
Use the SetDeviceAttribute
function to change any of the flags tested by the TestDeviceAttribute
function.
The TestDeviceAttribute
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QuickdrawAPI.h
Allows the Memory Manager to move the base address for the offscreen pixel map that you specify in the pm
parameter. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void UnlockPixels ( PixMapHandle pm );
A handle to an offscreen pixel map. Pass the same handle that you passed previously to the LockPixels
function.
To ensure the integrity of the data in a pixel image, call LockPixels
before drawing into or copying from a pixel map; then, to prevent heap fragmentation, call UnlockPixels
as soon as your application finishes drawing to and copying from the offscreen pixel map.
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). The LockPixels
function dereferences the PixMap
handle into a pointer. When you use the UnlockPixels
function, the handle is recovered.
You don’t need to call UnlockPixels
if LockPixels
returns FALSE
, because LockPixels
doesn’t lock the memory for a pixel image if that memory has been purged. However, calling UnlockPixels
on purged memory does no harm.
The UnlockPixels
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QDOffscreen.h
Releases a previously acquired lock on the back buffer for a Carbon window. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
OSErr UnlockPortBits ( GrafPtr port );
A window port specified in a previous call to LockPortBits
.
A result code. If noErr
, the corresponding lock is released.
For more information about this function, see LockPortBits
.
In Mac OS 9, this function does nothing and returns noErr
.
QuickdrawAPI.h
Decompresses a data buffer containing data compressed by PackBits
. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
void UnpackBits ( Ptr *srcPtr, Ptr *dstPtr, short dstBytes );
On entry, a pointer to the first byte of a buffer of data to be decompressed. On exit, a pointer to the first byte following the compressed data.
On entry, a pointer to the first byte in which to store decompressed data. On exit, a pointer to the first byte following the decompressed data.
The number of bytes of the data before compression. Use PackBits
to compress data structures of a fixed size that you can then pass in this parameter to UnpackBits
, or store with the compressed data the original size of the uncompressed data.
Because your application must allocate memory for the source and destination buffers, UnpackBits
does not move relocatable blocks. Thus, you can call it at interrupt time.
Because UnpackBits
changes the values of the srcPtr
and dstPtr
parameters, you should pass to UnpackBits
only copies of the pointers to the source and destination buffers. This allows you to access the beginning of the source and destination buffers after UnpackBits
returns. Also, if the source or destination buffer is stored in an unlocked, relocatable block, this technique prevents UnpackBits
from changing the value of a master pointer, which would make the original handle invalid.
QuickdrawAPI.h
Changes the pixel depth, boundary rectangle, or color table for an existing offscreen graphics world. (Deprecated in Mac OS X v10.4. Use Quartz 2D instead; see Quartz Programming Guide for QuickDraw Developers.)
GWorldFlags UpdateGWorld ( GWorldPtr *offscreenGWorld, short pixelDepth, const Rect *boundsRect, CTabHandle cTable, GDHandle aGDevice, GWorldFlags flags );
On input, a pointer to an existing offscreen graphics world; upon completion, the pointer to the updated offscreen graphics world.
The pixel depth of the offscreen world; possible depths are 1, 2, 4, 8, 16, and 32 bits per pixel. If you specify 0 in this parameter, UpdateGWorld
rescans the device list and uses the depth of the screen with the greatest pixel depth among all screens whose boundary rectangles intersect the rectangle that you specify in the boundsRect
parameter. If you specify 0 in this parameter, UpdateGWorld
also copies the GDevice
structure from this device to create an offscreen GDevice
structure. The UpdateGWorld
function ignores the value you supply for this parameter if you specify a GDevice
structure in the aGDevice
parameter.
The boundary rectangle and port rectangle for the offscreen pixel map. This also 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, with which it determines 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.
A handle to a ColorTable
structure. If you pass NULL
in this parameter, UpdateGWorld
uses the default color table for the pixel depth that you specify in the pixelDepth
parameter; if you set the pixelDepth
parameter to 0, UpdateGWorld
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. The UpdateGWorld
function ignores the value you supply for this parameter if you specify a GDevice
structure in the aGDevice
parameter.
As an option, a handle to a GDevice
structure whose pixel depth and color table you want to use for the offscreen graphics world. To use the pixel depth and color table that you specify in the pixelDepth
and cTable
parameters, set this parameter to NULL
.
Options available to your application. You can set a combination of the flags clipPix
, stretchPix
, and ditherPix
. If you don’t wish to use any of these flags, specify 0. However, you should pass either clipPix
or stretchPix
to ensure that the pixel map is updated to reflect the new color table. See GWorldFlags for a description of the values you can use here.
UpdateGWorld
returns the gwFlagErr
flag if UpdateGWorld
was unsuccessful; in this case, the offscreen graphics world is left unchanged. Use the QDError
function to help you determine why UpdateGWorld
failed.
You should call UpdateGWorld
after every update event and whenever your windows move or change size.
If the LockPixels
function reports that the Memory Manager has purged the base address for the offscreen pixel image, use UpdateGWorld
to reallocate its memory. Then, reconstruct the pixel image or draw directly in a window instead of preparing the image in an offscreen graphics world.
The UpdateGWorld
function uses the following algorithm when updating the offscreen pixel image:
If the color table that you specify in the cTable
parameter is different from the previous color table, or if the color table associated with the GDevice
structure that you specify in the aGDevice
parameter is different, Color QuickDraw maps the pixel values in the offscreen pixel map to the new color table.
If the value you specify in the pixelDepth
parameter differs from the previous pixel depth, Color QuickDraw translates the pixel values in the offscreen pixel image to those for the new pixel depth.
If the rectangle you specify in the boundsRect
parameter differs from, but has the same size as, the previous boundary rectangle, QuickDraw realigns the pixel image to the screen for optimum performance for the CopyBits
function.
If the rectangle you specify in the boundsRect
parameter is smaller than the previous boundary rectangle and you specify the clipPix
flag, the pixel image is clipped along the bottom and right edges.
If the rectangle you specify in the boundsRect
parameter is bigger than the previous boundary rectangle and you specify the clipPix
flag, the bottom and right edges of the pixel image are undefined.
If the rectangle you specify in the boundsRect
parameter is smaller than the previous boundary rectangle and you specify the stretchPix
flag, the pixel image is reduced to the new size.
If the rectangle you specify in the boundsRect
parameter is bigger than the previous boundary rectangle and you specify the stretchPix
flag, the pixel image is stretched to the new size.
If the Memory Manager purged the base address for the offscreen pixel image, UpdateGWorld
reallocates the memory, but the pixel image is lost. You must reconstruct it.
The UpdateGWorld
function may move or purge memory blocks in the application heap; do not call this function at interrupt time.
QDOffscreen.h
© 2001, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-06-29)