Inside Macintosh: 3D Graphics Programming With QuickDraw 3D /

Chapter 16 - Storage Objects / Storage Objects Reference

Storage Objects Routines / Creating and Accessing Memory Storage Objects

Q3MemoryStorage_NewBuffer

You can use the Q3MemoryStorage_NewBuffer function to create a new memory storage object. The data you provide is not copied into QuickDraw 3D memory.

TQ3StorageObject Q3MemoryStorage_NewBuffer (
unsigned char *buffer, 
unsigned long validSize, 
unsigned long bufferSize);

buffer

A pointer to a buffer in memory, or NULL.

validSize

The size, in bytes, of the valid metafile data contained in the specified buffer. If buffer is set to NULL, this parameter specifies the initial size and also the grow size of the buffer that QuickDraw 3D allocates internally.

bufferSize

The size, in bytes, of the specified buffer.

DESCRIPTION

The Q3MemoryStorage_NewBuffer function returns, as its function result, a new memory storage object associated with the buffer specified by the buffer and validSize parameters. The data in the specified buffer is not copied into internal QuickDraw 3D memory, so your application must not access that buffer until the associated storage object is closed or disposed of.

If you pass the value NULL in the buffer parameter, QuickDraw 3D allocates a buffer of validSize bytes, increases the buffer by that size whenever necessary, and later disposes of the buffer when the associated storage object is closed or disposed of. If buffer is set to NULL and validSize is set to 0, QuickDraw 3D uses a default initial buffer and grow size.

The bufferSize parameter specifies the size of the specified buffer. The validSize parameter specifies the size of the valid metafile data contained in the buffer. The value of the validSize parameter should always be less than or equal to the value of the bufferSize parameter. This allows you to maintain other data in the buffer following the valid metafile data.

If Q3MemoryStorage_NewBuffer cannot create a new storage object, it returns the value NULL.

ERRORS

kQ3ErrorOutOfMemory