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

Debugging With GraphicsBug
GraphicsBug reads and verifies only graphics objects. It does not create objects, dispose of objects, or modify objects in any manner. GraphicsBug never interferes with an application and does not cause bugs to appear or disappear.
Table 4-11 summarizes the GraphicsBug commands. This list is available online by typing "?", "help", or "HELP" when in the command line of GraphicsBug. You can copy or save the brief explanations as a text file.
Table 4-11 GraphicsBug commands and responses
Command Response
DA
[bu(sy) di(rect) fr(ee) i(ndirect) t(emp) u(n)b(usy) u(n)l(oaded)] [<type>[type>...]] Display all blocks in the heap, or all that match parameters. Example: DA bu line layout polygon.
DM addr[n|t(ype)] Display memory from addr for n bytes or as a type. Example: DM 1b2358 t.
DV Display version.
ER number Display error name that matches this number.
F addr[number[start[end]]] [bu(sy) di(rect) fr(ee) i(ndirect) t(emp) u(n)b(usy) u(n)l(oaded)] [<type>[type>...]] Find references to addr in the heap blocks that match parameters. Example: F 0x4456A 3 ul picture.
FL addr[filename] Display the stream produced by flattening this shape. Example: FL 0x3321A "flat shapes".
GG Display graphics globals
HC Check the heap.
HD [bu(sy) di(rect) fr(ee) i(ndirect) t(emp) u(n)b(usy) u(n)l(oaded)] HD [<type> [<type>...]] Dump the heap or the heap parts that match parameters. Example: HD bu line layout polygon.

HT Total the heap.
HX addr|<heapname> Switch to the heap containing addr, or named <heapname>. Example: HX System.
HZ List the known heaps.
IG Display initialization globals.
LC (process) List the known graphics clients.
LP List the known processes that have a graphics client.
CG Display other (generic, nongraphic) globals.
Q Quit.
UF filename[page number] Display the contents of the file by flattening it. Use page number to specify a page of a print file.
V [addr] Validate all (no parameters) or validate specific block.
GG Graphics globals.
WH addr Display the block containing addr.
Operators: -, +, *, /, %, ^, |, &, [, @, *, ], ~, (, )
Numbers: .0x$#3 "strings: ""

In addition to the GraphicsBug commands above, you can Option-double-click (hold down the Option key and double-click) on a memory address to display memory as a type, use the up/down arrow keys to set the scrolling speed, use dot '.' to represent the last displayed address, and use shape as an argument to the DA, F, and HD commands to display all graphics client-owned shapes.

Analyzing a Picture Shape
The following sections demonstrate the use of GraphicsBug for the analysis of a picture containing seven shapes. The code that creates the picture and the analysis of the data stream for each flattened shape is given in the section "Analyzing the Data Streams of Flattened Shapes" in the chapter "QuickDraw GX Stream Format."

Determining the Heap Size for All Shapes in the Picture
You can use the GraphicsBug HT command to display the heap total in bytes for a specified graphics client heap. First run the application, then select the graphics client heap from the GraphicsBug heap menu, then apply the HT command. Listing 4-2 showsa sample output of the HT command: the GraphicsBug heap size in bytes. Note that the size of the graphics client and its heap is 86724 bytes. You can use this procedure to select the initial size of your application's graphics client heap or heaps. For additional information about specifying the size of your graphics client heap, see the section "Creating a Graphics Client and its Graphics Client Heap" in the chapter "QuickDraw GX Memory Management."
Listing 4-2 Totaling the graphics client and its heap
Totaling the heap at 00c07de8 (all shapes heap). 
          Total Blocks                 Total of Block Sizes 
Free      0000001b    #       27       0000fff8    #    65528 
Direct    00000044    #       68       00001dbc    #     7612 
Indirect  00000047    #       71       000031bc    #    12732 
Sub Heaps 00000000    #        0       00000000    #        0 
Heap Size 000000a6    #      166       000152c4    #    86724 
Analyzing the Shapes in the Picture
You can use the GraphicsBug HD PIC command to display the memory locations of the seven shapes in the picture. Listing 4-3 shows the GraphicsBug output for the picture shape created by the application "all shapes." User input is shown in boldface.
The GraphicsBug command lines shown in Listing 4-3 are used as follows:

hd pic command turns pic into picture.
dm 00c0886c t command displays default picture data.
dm 00c0a4a0 t displays the data for the picture with seven shapes. Note that there are multiple text shapes displayed because the gxUniqueItemsShape attribute was set.

Listing 4-3 Determining the memory locations of the shapes in the picture
hx "all shapes"
heap set to 00c07de8  "all shapes"
hd pic 
 Start    Length  \x90   Typ Busy Mstr Ptr Temp TBsy Disk   Object 
00c0886c 00000048+00   i       00c1d02c                picture 
00c0a4a0 00000108+00   i       00c1d010                picture 
          Total Blocks            Total of Block Sizes 
Blocks    00000002  #        2    00000150    #      336 
dm 00c0886c t
displaying picture gxShape from 00c0886c
  devShape        nil 
  owners            1 
  seed              0 
  flags      isDefaultShape  
  attributes gxMapTransformShape  
  gxStyle      00c083b0     
  gxInk        00c08460     
  gxTransform  00c088b4     
  tagList         nil 
  cacheList       nil 
  geo.flags         0
  fillType   evenOddFill 
  entries    0 
  references 00000000 
      gxShape        (type)       gxStyle           gxInk         gxTransform 
dm 00c0a4a0 t
displaying picture gxShape from 00c0a4a0
  devShape   00c0a98c 
  owners            1 
  seed              0 
  flags             0  
  attributes 
/* 
There are multiple text shapes because the gxUniqueItemsShape attribute was 
set.
*/
  gxStyle      00c083b0     
  gxInk        00c08460     
  gxTransform  00c088b4    
  tagList         nil 
  cacheList       nil 
geo.flags         0 
  fillType   evenOddFill 
  entries    12 
  references 00c08d1c 
      gxShape   (type)      gxStyle        gxInk      gxTransform 
    00c08dd0  (line)       00000000       00000000       00000000    
    00c0949c  (rectangle)  00000000       00000000       00000000     
    00c099e4  (curve)      00000000       00000000       00000000     
    00c09bd0  (path)       00000000       00000000       00000000
    00c0a220  (text)       00000000       00000000       00000000     
    00c0a220  (text)       00c0a268       00c08e1c       00c0997c     
    00c0a220  (text)       00c0a268       00c09b98       00c0a350     
    00c0a220  (text)       00c0a268       00c0a640       00c0bc30     
    00c0a220  (text)       00c0a268       00c0a678       00c0a6b0     
    00c0a220  (text)       00c0a268       00c0a750       00c0a788     
    00c0a828  (polygon)    00000000       00000000       00000000     
    00c0bc94  (bitmap)     00000000       00000000       00000000 
Analyzing the Rectangle in the Picture
You can use the dm command or Option-double-click command on the memory location of one of the seven shapes from Listing 4-3 to display information about the shape. Listing 4-4 shows the GraphicsBug output for the rectangle shape. The command line is shown in boldface.
Listing 4-4 Analyzing the rectangle shape in the picture
dm 00c0949c t
Displaying rectangle gxShape from 00c0949c 
  devShape        nil 
  owners            1 
  seed              0 
  flags             0  
  attributes no attributes  
  gxStyle      00c0984c     
  gxInk        00c098fc     
  gxTransform  00c0961c     
  tagList         nil 
  cacheList       nil 
  geo.flags         0 
  fillType   closedFrameFill 
{   150.0000,    25.0000}  {   200.0000,    75.0000} 
Analyzing the Ink in the Rectangle
You can select a memory location of one of the objects in the rectangle from Listing 4-4 and use the dm command or GraphicsBug Option-double click command to display information about the object. Listing 4-5 shows the GraphicsBug output for the ink in the rectangle shape. The command line is shown in boldface.
Listing 4-5 Analyzing the ink in the rectangle shape
dm 00c098fc t
Displaying gxInk from 00c098fc
  devInk       00c094e8 
  privateFlags        0  
  attributes          0  
  owners              1 
  seed                0 
  tagList           nil 
  space        gxRGBSpace 
  profile           nil 
  value(s)       1.0000 (ffff)  0.0000 0x0000  0.0000 0x0000   
  mode         gxCopyMode 

**Table 4-11 GraphicsBug commands and responses**
Command	Response
DA `[bu(sy) di(rect) fr(ee) i(ndirect) t(emp) u(n)b(usy) u(n)l(oaded)] [<type>[type>...]]`	Display all blocks in the heap, or all that match parameters. Example: `DA bu line layout polygon`.
DM addr[n\|t(ype)]	Display memory from `addr` for n bytes or as a type. Example: `DM 1b2358 t`.
DV	Display version.
ER number	Display error name that matches this number.
`F addr[number[start[end]]] [bu(sy) di(rect) fr(ee) i(ndirect) t(emp) u(n)b(usy) u(n)l(oaded)] [<type>[type>...]]`	Find references to `addr` in the heap blocks that match parameters. Example: `F 0x4456A 3 ul picture`.
FL addr[filename]	Display the stream produced by flattening this shape. Example: `FL 0x3321A "flat shapes"`.
GG	Display graphics globals
HC	Check the heap.
`HD [bu(sy) di(rect) fr(ee) i(ndirect) t(emp) u(n)b(usy) u(n)l(oaded)] HD [<type> [<type>...]]`	Dump the heap or the heap parts that match parameters. Example: `HD bu line layout polygon`.

HT	Total the heap.
HX addr\|<heapname>	Switch to the heap containing `addr`, or named `<heapname>`. Example: `HX System`.
HZ	List the known heaps.
IG	Display initialization globals.
LC (process)	List the known graphics clients.
LP	List the known processes that have a graphics client.
CG	Display other (generic, nongraphic) globals.
Q	Quit.
UF filename[page number]	Display the contents of the file by flattening it. Use page number to specify a page of a print file.
V [addr]	Validate all (no parameters) or validate specific block.
GG	Graphics globals.
WH addr	Display the block containing `addr`. Operators: -, +, , /, %, ^, \|, &, [, @, , ], ~, (, ) Numbers: .0x$#3 "strings: ""

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