Legacy Document

Inside Macintosh: Imaging With QuickDraw /

Chapter 4 - Color QuickDraw / Color QuickDraw Reference

Color QuickDraw Routines / Retrieving Color QuickDraw Result Codes

QDError

To get a result code from the last applicable Color QuickDraw or Color Manager routine that you called, use the QDError function.

FUNCTION QDError: Integer;

DESCRIPTION

The QDError function returns the error result from the last applicable Color QuickDraw or Color Manager routine. 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 in Color QuickDraw.

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. Color 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--for example, divide the image into left and right halves--and try again.

When you record drawing operations in an open region, the resulting region description may overflow the 64 KB limit. Should this happen, QDError returns regionTooBigError. Since the resulting region is potentially corrupt, the CloseRgn procedure (described in the chapter "QuickDraw Drawing" in this book) returns an empty region if it detects QDError has returned regionTooBigError. A similar error, rgnTooBigErr, can occur when using the BitMapToRegion function (described in the chapter "Basic QuickDraw" in this book) to convert a bitmap to a region.

The BitMapToRegion function can also generate the pixmapTooDeepErr error if a PixMap record is supplied that is greater than 1 bit per pixel. You may be able to recover from this problem by coercing your PixMap record into a 1-bit PixMap record and calling the BitMapToRegion function again.

RESULT CODES

noErr	0	No error
paramErr	-50	Illegal parameter to NewGWorld
	-143	CopyBits couldn't allocate required temporary memory
	-144	Ran out of stack space while drawing polygon
noMemForPictPlaybackErr	-145	Insufficient memory for drawing the picture
regionTooBigError	-147	Region too big or complex
pixmapTooDeepErr	-148	Pixel map is deeper than 1 bit per pixel
nsStackErr	-149	Insufficient stack
cMatchErr	-150	Color2Index failed to find an index
cTempMemErr	-151	Failed to allocate memory for temporary structures
cNoMemErr	-152	Failed to allocate memory for structure
cRangeErr	-153	Range error on color table request
cProtectErr	-154	ColorTable record entry protection violation
cDevErr	-155	Invalid type of graphics device
cResErr	-156	Invalid resolution for MakeITable
cDepthErr	-157	Invalid pixel depth specified to NewGWorld
rgnTooBigErr	-500	Bitmap would convert to a region greater than 64 KB

In addition to these result codes, QDErr also returns result codes from the Memory Manager.

SECIAL CONSIDERATIONS

The QDError function does not report errors returned by basic QuickDraw.

SEE ALSO

Listing 3-8 on page 3-24, Listing 3-10 on page 3-26, and Listing 3-11 on page 3-29 in the chapter "QuickDraw Drawing" in this book--and Listing 7-8 on page 7-19 in the chapter "Pictures" in this book--illustrate how to use QDError to report insufficient memory conditions for various drawing operations.

The NewGWorld function is described in the chapter "Offscreen Graphics Worlds" in this book. The Color2Index function and the MakeITable procedure are described in the chapter "Color Manager" in Advanced Color Imaging on the Mac OS. Graphics devices are described in the chapter "Graphics Devices" in this book. Memory Manager result codes are listed in Inside Macintosh: Memory.