Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 2 - QuickDraw GX Memory Management / QuickDraw GX Memory Management Reference

Functions / Creating and Disposing of a Graphics Client

GXNewGraphicsClient

You can use the GXNewGraphicsClient function to create a new graphics client.

gxGraphicsClient GXNewGraphicsClient(void *memoryStart, 
                  long memoryLength, gxClientAttribute attribute);

memoryStart

A pointer to the memory location where the new graphics client will begin.

memoryLength

The requested size in bytes of the QuickDraw GX graphics client heap.

attribute

The attributes flag set for the new graphics client.

function result

A reference to the new graphics client object.

DESCRIPTION

The GXNewGraphicsClient function creates a new graphics client and makes it the active graphics client for this application. The graphics client specifies the memory location, the size in bytes, and the attributes of its graphics client heap. When additional memory blocks are allocated to the graphics client heap, their locations and sizes are also stored in the graphics client. The GXNewGraphicsClient function does not allocate memory for the graphics client heap. Calling the GXEnterGraphics functionallocates the heap.

If you are going to make a GXNewGraphicsClient call, it must be the first QuickDraw GX call in your application. Otherwise, a Quickdraw GX call may implicitly create the first graphics client and any subsequent GXNewGraphicsClient call creates another graphics client. If you want to create multiple graphics client objects, you can call this routine several times.

The memoryStart parameter specifies the starting location in memory for the graphics client and its graphics client heap. If you specify nil, QuickDraw GX selects the location for you. This is the most common selection. Since QuickDraw GX is managing memory, it selects what it believes is the optimum location in memory for the new graphics client. However, in the rare case in which you need to specify the memory location, you can use the memoryStart parameter to specify the exact location of the graphics client. If you specify the memoryStart parameter, you must also specify the memoryLength parameter.

The memoryLength parameter specifies the size of the heap in bytes. If you pass 0 and there is no 'gasz' resource, QuickDraw GX version 1.0 creates a graphics client with a default heap size of 600 KB. If there is a 'gasz' resource, QuickDraw GX uses its size value instead.

The attributes parameter is a flag from the gxClientAttributes enumeration that defines whether QuickDraw GX will or will not add additional memory blocks to the newly defined, but not allocated, graphics client heap. A flag of default value 0 indicates that QuickDraw GX may add memory blocks to the graphics client heap, as required. A flag of value 1 is the gxStaticHeapClient constant and indicates that QuickDraw GX will never add memory blocks to the initially allocated graphics client heap.

If QuickDraw GX is unable to create a graphics client, there probably is not sufficient memory. As a result, the function returns nil. Note that QuickDraw GX does not post an error since there is no graphics client to post the error to.

SPECIAL CONSIDERATIONS

If no error results, the GXNewGraphicsClient function creates a graphics client object; you are responsible for disposing of that object when you no longer need it.

SEE ALSO

The use of the GXNewGraphicsClient function to create a new graphics client is described in the section "Creating a Graphics Client and Its Graphics Client Heap" beginning on page 2-5.

To determine the correct size of the memory for your graphics client, see the section "Determining Memory Requirements for a Graphics Client Heap" beginning on page 2-8.

The gxClientAttribute enumeration is described in the section "Graphics Client Attributes" beginning on page 2-18.

QuickDraw GX functions that do not require a graphics client or a graphics client heap are described in the section "Functions That Do Not Require a Graphics Client or Heap" beginning on page 2-14.

If you need to specify the memory starting location of the graphics client and its graphics client heap, see the section "Specifying the Starting Location of a Graphics Client" beginning on page 2-14.