Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 2 - QuickDraw GX Memory Management / Using Graphics Clients and Graphics Client Heaps

Creating a Graphics Client and Its Graphics Client Heap

Either QuickDraw GX or you can create a new graphics client and its heap. This section discusses how you can control these tasks.

Implicit Creation

If your application does not explicitly create a graphics client or a graphics client heap, QuickDraw GX creates them for you when needed. QuickDraw GX calls the GXNewGraphicsClient and the GXEnterGraphics functions when the first function call is made in your application that requires a graphics client heap. Almost all QuickDraw GX functions require a graphics client heap. The few exceptions are listed in the section "Functions That Do Not Require a Graphics Client or Heap" beginning on page 2-14.

When QuickDraw GX calls the GXNewGraphicsClient function, it selects the starting memory location for the heap and creates a graphics client to provide the bookkeeping for the heap. When QuickDraw GX calls the GXEnterGraphics function, it uses the memory location and heap size stored in the graphics client to create the new heap.

QuickDraw GX looks for a resource of type 'gasz' with an ID of 0 and uses the first long word of that resource as the number of bytes to be allocated to the graphics client heap. If your application does not provide this resource, QuickDraw GX version 1.0 uses a default memory size value of 600 KB. For additional information, see the description of the GXNewGraphicsClient routine beginning on page 2-19.

A 'gasz' resource can only provide one graphics client heap size in a single application. QuickDraw GX uses this size for every graphics client with a memoryLength parameter of zero. Listing 2-1 shows how to create a type 'gasz' resource for a 512 KB graphics client heap.

Listing 2-1 Creating a 'gasz' resource

resource 'gasz' (0) {
    0x00080000        /* 512KB graphics client heap */
};

The GXNewGraphicsClient function is described on page 2-19. The GXEnterGraphics function is described on page 2-22.

Explicit Creation

If you want to specify the characteristics of the graphics client heap, you can use the GXNewGraphicsClient function explicitly to create a graphics client.

The GXNewGraphicsClient function has parameters that specify the heap's starting memory location, memory size in bytes, and whether or not QuickDraw GX is permitted to later increase the heap's size by allocating additional memory blocks. The graphics client stores the data passed by the GXNewGraphicsClient function, but does not allocate memory to the heap. This requires the GXEnterGraphics function call.

Most applications should allow QuickDraw GX to select the memory starting location by passing nil for the memoryStart parameter. If you need to specify the memory starting location, see the section "Specifying the Starting Location of a Graphics Client" beginning on page 2-14.

If you pass zero for the memoryLength parameter, QuickDraw GX looks for a resource of type 'gasz' with an ID of 0 and uses the first long word of that resource as the heap size (the number of bytes to allocate). If your application does not provide this resource, QuickDraw GX version 1.0 uses a default size of 600 KB. Alternatively, you can specify the requested heap size in bytes. To determine how many bytes to specify for your graphics client heap, see the next section. The 'gasz' resource is described in the previous section.

If you pass zero for the attribute parameter, QuickDraw GX can later add additional memory blocks to the heap when more memory is required. If the attribute parameter has value 1, indicating the gxStaticHeapConstant constant, QuickDraw GX cannot add more memory blocks to the graphics client heap allocated.

Once a graphics client is created, you use the GXEnterGraphics function to allocate memory for its heap. If you don't explicitly make the call, QuickDraw GX implicitly calls the GXEnterGraphics function for you when it executes the next function that requires a graphics client heap. Almost all QuickDraw GX functions require a graphics client heap. The exceptions are given in the section "Functions That Do Not Require a Graphics Client or Heap" beginning on page 2-14.

Listing 2-2 shows how to explicitly create a graphics client and allocate 10 KB of memory for its heap. Since the attribute parameter is 0, QuickDraw GX performs its default behavior to add memory blocks to the graphics client heap created, as required. For example, additional memory may be required as your application creates new objects. You should allocate your graphics client at the beginning of your application and poll for errors to ensure that the graphics client is allocated.

Listing 2-2 Explicitly creating a graphics client and its heap

gxGraphicsClient  newClient;
long              graphicsHeapSizeRequested = 50K; // 50K GX heap

newClient = GXNewGraphicsClient(nil, graphicsHeapSizeRequested 
                                 * 1024,OL );

   // After we attempted to create the graphics client, we need to 
   // determine if the call succeeded. If the call did not (as in 
   // the case for all GX functions), "newClient" will be nil. If
   // it is, we alert the user to the problem, Otherwise, we will
   // attempt to allocate the GX heap.

if ( newClient ) {
   GXEnterGraphiccs();
   // Calling GXEnterGraphics allocates the memory within the GX
   // heap. The call would fail only if there is not enough
   // memory. In this case, the graphics error posted is -27999
   // (out of memory). At this point, we have not installed an 
   // error handler, so we check for the error number
   // corresponding to the out-of-memory error.
if ( GXGetGraphicsError( nil ) == -27999 ) {

   // Because we cannot allocate the requested size for our GX
   // heap, we need to throw away the client we created and alert
   // the user that there is not enough memory to continue.

   GXDisposeGraphicsClient( newClient);

   >> application code to alert user and shut down app

} else {
   // Application error code to tell the user there is not enough 
   // memory to create the graphics client. No error is
   // posted from GX because a graphics client does not
   // exist. The only reason you would not be able to create
   // a graphics client is if there is not enough memory.

   >> application code to alert user and shut down app