Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: QuickDraw GX Environment and Utilities /: Chapter 4 - QuickDraw GX Debugging / Using QuickDraw GX Debugging

Analyzing Drawing Problems
If you have run your application and a shape didn't draw as you anticipated, you can use the GXGetShapeDrawError function to have QuickDraw GX analyze why the shape didn't draw correctly. This function checks the content of a shape and all of the objects referenced by the shape for a condition that explains why the shape has no visible effect when drawn. As a result, GXGetShapeDrawError returns a single drawing error from the gxDrawErrors enumeration that may describe why the shape failed to draw correctly. The gxDrawErrors enumeration is listed in the section "Drawing Errors" beginning on page 4-29. The GXGetShapeDrawError function is described on page 4-33.These errors should not be confused with gxGraphicsErrors.
If the drawing was completed successfully, QuickDraw GX posts the NoDrawError drawing error. If you don't see the drawing, remember that it may have been drawn to a different view device or may have just redrawn over the previous shape that was drawn. The posting of a NoDrawError drawing error does not mean that the shape drawn is the one you expected or the correct shape. It just means that QuickDraw GX detected no drawing problems during the processing of the shape drawn.
The drawing error QuickDraw GX posts is selected from a special subset of the QuickDraw GX error codes. This set of drawing error codes is structured with respect to the stage in the drawing process sequence that the drawing failed. The earliest stage of failure will be described in the posted drawing error. The single error code posted attempts to indicate the reason that you do not see the drawing that you anticipated.
Drawing errors are grouped into categories that correspond to the approximate sequence of QuickDraw GX processing, as shown in Table 4-1.
Table 4-1 QuickDraw GX drawing process sequence
Drawing process
sequence Object processed
1 Shape type
2 Style
3 Ink
4 Transform
5 View port
6 View device

The processing sequence is also the sequence of drawing errors posted. QuickDraw GX posts the first drawing error that is detected. It does not post subsequent drawing errors until the error posted earlier in the process sequence is corrected. For example, if an application attempts to draw a defective shape with a defective view port, QuickDraw GX posts a single shape type drawing error and does not post a view port drawing error. This is because QuickDraw GX analyzes the integrity of the shape earlier in the drawing process. It analyzes the integrity of the view port toward the end of the process. Once you correct the defective shape, QuickDraw GX can detect the defective view port in subsequent analysis with the GXGetShapeDrawError function.
Table 4-2 shows the GXGetShapeDrawError function shape type drawing errors that QuickDraw GX may post.
Table 4-2 Shape type drawing errors
Error Description
shape_emptyType An empty type doesn't have an area to draw.
shape_inverse_fullType An inverse full type doesn't have an area to draw.
rectangle_zero_width The rectangle doesn't have an area to draw.
rectangle_zero_height The rectangle doesn't have an area to draw.
polygon_empty There is no contour to draw.
path_empty There is no contour to draw.
bitmap_zero_width The bitmap doesn't have an area to draw.
bitmap_zero_height The bitmap doesn't have an area to draw.
text_empty There is no character to draw.
glyph_empty There is no glyph to draw.
layout_empty There is no layout to draw.
picture_empty There is no shape in the picture.
shape_no_fill The shape fill is set to gxNoFill, which will not draw.
shape_no_enclosed_area There is no enclosed area to draw.
shape_no_enclosed_pixels There is an enclosed area, but it is so small that it does not cross any pixel centers.
shape_very_small There is a shape to draw, but it is extremely small (on the order of the size of a pixel).
shape_very_large Part of the shape may be drawn outside the bounds of the coordinate system (\xB132,768).
shape_contours_cancel The shapes contours overlap and cancel each other out.

Table 4-3 shows the GXGetShapeDrawError function style drawing errors.
Table 4-3 Style drawing errors
Error Description
pen_too_small The pen width is so small that it doesn't enclose any pixels and therefore doesn't draw.
text_size_too_small The text size is so small that it doesn't enclose any pixels and therefore doesn't draw.
dash_empty The dash shape was specified as an empty type shape.
start_cap_empty The start cap shape was specified as an empty type shape.
pattern_empty The pattern shape was specified as an empty type shape.
textFace_Empty Each layer of the text face has a shape fill equal to gxNoFill.
shape_primitive_empty The original shape enclosed an area. There is no stylized shape to draw. An example is a pattern shape that contains overlapping patterns that cancel.
shape_primitive_very_small There is a shape to draw, but it is extremely small (on the order of the size of a pixel). An example is a scaled transform that shrinks the shape.

Table 4-4 shows the GXGetShapeDrawError function ink drawing errors.
Table 4-4 Ink drawing errors
Error Description
transfer_equals_noMode The transfer mode gxNoMode suppresses drawing.
transfer_matrix_ignores_source The transfer mode's mapping scales all values greater than 1 or less than 0 and the overComponent flag is not set.
transfer_matrix_ignores_device The transfer mode's mapping scales all values greater than 1 or less than 0 and the overComponent flag is not set.
transfer_source_reject The color is not within the source minimum and the source maximum.
transfer_mode_ineffective The transfer mode has no effect on the device. An example is a blend with an operand of 0.
colorSet_no_entries There are no colors in the color set so there is nothing to draw.
bitmap_colorSet_one_entry The bitmap drew, but it is probably not the desired result, since all colors map to the one color of the entry. An example is when the colors are off the end of the color set.

Table 4-5 shows the GXGetShapeDrawError function transform drawing errors.
Table 4-5 Transform drawing errors
Error Description
transform_scale_too_small The transform has reduced the shape to less than 1/72 inch. You may see a few pixels drawn, depending on the resolution of your view port.
transform_map_too_largetransform_move_too_large
transform_scale_too_large
transform_rotate_too_large
transform_perspective_too_large
transform_skew_too_large The transform has moved all or part of the shape outside the bounds of the coordinate system (\xB132,768). This may be the result of a move, scale, rotate, perspective, or skew transformation.
transform_clip_no_intersection The clip shape does not intersect any view port.
transform_clip_empty The transform clip is an empty type shape.
transform_no_viewPorts The number of entries in the view port list is zero.

Table 4-6 shows the GXGetShapeDrawError function view port drawing errors.
Table 4-6 View port drawing errors
Error Description
viewPort_disposed The view port that was to be drawn to has already been disposed of. There is no view port to draw to.
viewPort_clip_empty The view port clip is an empty type shape.
viewPort_clip_no_intersection The view port clip does not intersect the view device.
viewPort_scale_too_small The map to global space has been completed. The object is less than 1/72 inch. You may see a few pixels drawn, depending on the resolution of your view port.
viewPort_map_too_largeviewPort_move_too_large
viewPort_scale_too_large
viewPort_rotate_too_large
viewPort_perspective_too_large
viewPort_skew_too_large, The view port mapping has moved all or part of the shape outside the bounds of the coordinate system (\xB132,768). This may be the result of a move, scale, rotate, perspective, or skew transformation.
viewPort_viewGroup_offscreen The shape is drawn to an off-screen view device. This may be normal. This error is returned to alert you in the event that the drawing result was unexpected.

Table 4-7 shows the GXGetShapeDrawError function view device drawing errors.
Table 4-7 View device drawing errors
Error Description
viewDevice_clip_no_intersection The view device clip does not intersect the bounds described by the view device bitmap shape.
viewDevice_scale_too_small The mapping to global space has been completed. The object is less than 1/72 inch. You may see a few pixels drawn, depending on the resolution of your draw view port.
viewDevice_map_too_largeviewDevice_move_too_large
viewDevice_scale_too_large
viewDevice_rotate_too_large
viewDevice_perspective_too_large
viewDevice_skew_too_large The view port mapping has moved the shape outside the bounds of the coordinate system (\xB132,768). This may be the result of a move, scale, rotate, perspective, or skew transformation.

**Table 4-1 QuickDraw GX drawing process sequence**
Drawing process sequence	Object processed
1	Shape type
2	Style
3	Ink
4	Transform
5	View port
6	View device

**Table 4-2 Shape type drawing errors**
Error	Description
`shape_emptyType`	An empty type doesn't have an area to draw.
`shape_inverse_fullType`	An inverse full type doesn't have an area to draw.
`rectangle_zero_width`	The rectangle doesn't have an area to draw.
`rectangle_zero_height`	The rectangle doesn't have an area to draw.
`polygon_empty`	There is no contour to draw.
`path_empty`	There is no contour to draw.
`bitmap_zero_width`	The bitmap doesn't have an area to draw.
`bitmap_zero_height`	The bitmap doesn't have an area to draw.
`text_empty`	There is no character to draw.
`glyph_empty`	There is no glyph to draw.
`layout_empty`	There is no layout to draw.
`picture_empty`	There is no shape in the picture.
`shape_no_fill`	The shape fill is set to `gxNoFill`, which will not draw.
`shape_no_enclosed_area`	There is no enclosed area to draw.
`shape_no_enclosed_pixels`	There is an enclosed area, but it is so small that it does not cross any pixel centers.
`shape_very_small`	There is a shape to draw, but it is extremely small (on the order of the size of a pixel).
`shape_very_large`	Part of the shape may be drawn outside the bounds of the coordinate system (\xB132,768).
`shape_contours_cancel`	The shapes contours overlap and cancel each other out.

**Table 4-3 Style drawing errors**
Error	Description
`pen_too_small`	The pen width is so small that it doesn't enclose any pixels and therefore doesn't draw.
`text_size_too_small`	The text size is so small that it doesn't enclose any pixels and therefore doesn't draw.
`dash_empty`	The dash shape was specified as an empty type shape.
`start_cap_empty`	The start cap shape was specified as an empty type shape.
`pattern_empty`	The pattern shape was specified as an empty type shape.
`textFace_Empty`	Each layer of the text face has a shape fill equal to `gxNoFill`.
`shape_primitive_empty`	The original shape enclosed an area. There is no stylized shape to draw. An example is a pattern shape that contains overlapping patterns that cancel.
`shape_primitive_very_small`	There is a shape to draw, but it is extremely small (on the order of the size of a pixel). An example is a scaled transform that shrinks the shape.

**Table 4-4 Ink drawing errors**
`Error`	Description
`transfer_equals_noMode`	The transfer mode `gxNoMode` suppresses drawing.
`transfer_matrix_ignores_source`	The transfer mode's mapping scales all values greater than 1 or less than 0 and the `overComponent` flag is not set.
`transfer_matrix_ignores_device`	The transfer mode's mapping scales all values greater than 1 or less than 0 and the `overComponent` flag is not set.
`transfer_source_reject`	The color is not within the source minimum and the source maximum.
`transfer_mode_ineffective`	The transfer mode has no effect on the device. An example is a blend with an operand of 0.
`colorSet_no_entries`	There are no colors in the color set so there is nothing to draw.
`bitmap_colorSet_one_entry`	The bitmap drew, but it is probably not the desired result, since all colors map to the one color of the entry. An example is when the colors are off the end of the color set.

**Table 4-5 Transform drawing errors**
Error	Description
`transform_scale_too_small`	The transform has reduced the shape to less than 1/72 inch. You may see a few pixels drawn, depending on the resolution of your view port.
`transform_map_too_large`transform_move_too_large transform_scale_too_large transform_rotate_too_large transform_perspective_too_large transform_skew_too_large	The transform has moved all or part of the shape outside the bounds of the coordinate system (\xB132,768). This may be the result of a move, scale, rotate, perspective, or skew transformation.
`transform_clip_no_intersection`	The clip shape does not intersect any view port.
`transform_clip_empty`	The transform clip is an empty type shape.
`transform_no_viewPorts`	The number of entries in the view port list is zero.

**Table 4-6 View port drawing errors**
Error	Description
`viewPort_disposed`	The view port that was to be drawn to has already been disposed of. There is no view port to draw to.
`viewPort_clip_empty`	The view port clip is an empty type shape.
`viewPort_clip_no_intersection`	The view port clip does not intersect the view device.
`viewPort_scale_too_small`	The map to global space has been completed. The object is less than 1/72 inch. You may see a few pixels drawn, depending on the resolution of your view port.
`viewPort_map_too_large`viewPort_move_too_large viewPort_scale_too_large viewPort_rotate_too_large viewPort_perspective_too_large viewPort_skew_too_large,	The view port mapping has moved all or part of the shape outside the bounds of the coordinate system (\xB132,768). This may be the result of a move, scale, rotate, perspective, or skew transformation.
`viewPort_viewGroup_offscreen`	The shape is drawn to an off-screen view device. This may be normal. This error is returned to alert you in the event that the drawing result was unexpected.

**Table 4-7 View device drawing errors**
Error	Description
`viewDevice_clip_no_intersection`	The view device clip does not intersect the bounds described by the view device bitmap shape.
`viewDevice_scale_too_small`	The mapping to global space has been completed. The object is less than 1/72 inch. You may see a few pixels drawn, depending on the resolution of your draw view port.
`viewDevice_map_too_large`viewDevice_move_too_large viewDevice_scale_too_large viewDevice_rotate_too_large viewDevice_perspective_too_large viewDevice_skew_too_large	The view port mapping has moved the shape outside the bounds of the coordinate system (\xB132,768). This may be the result of a move, scale, rotate, perspective, or skew transformation.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.