3D Graphics Programming with QuickDraw 3D
Q3File_SetStorage
function). If necessary, you can also get or set some of the information associated with a particular storage object. For example, you can determine the file reference number of the open file associated with a Macintosh storage object. This section describes how to perform these two tasks.Listing 16-1 Creating a Macintosh storage object
myErr = FSpOpenDF(&myFSSpec, fsCurPerm, &myFRefNum); if (!myErr) myStorageObj = Q3MacintoshStorage_New(myFRefNum);Listing 16-2 illustrates how to open a file and create a UNIX storage object connected to that open file.
Listing 16-2 Creating a UNIX storage object
myFile = fopen("..:teacup.eb", "r"); if (myFile) myStorageObj = Q3UnixStorage_New(myFile);Listing 16-3 illustrates how to allocate a block of memory and create a storage object connected to that block.
Listing 16-3 Creating a memory storage object
#define kBufferSize 256 myBuffer = malloc(kBufferSize); if (myBuffer) myStorageObj = Q3MemoryStorage_NewBuffer (myBuffer, 0, kBufferSize);In the code shown in Listing 16-1 through Listing 16-3, your application specifically reserves the desired piece of the physical storage device, either by opening a file or by allocating memory. In these cases, your application must also make sure to close the file or deallocate the memory block after you've closed or disposed of the associated storage object.
Note, however, that QuickDraw3D provides two types of memory storage functions. The function Q3MemoryStorage_NewBuffer
creates a new memory storage object using a specified buffer. The function Q3MemoryStorage_New
creates a new memory storage object but copies the data in the specified buffer into its own internal memory. If you create a storage object by calling Q3MemoryStorage_New
, you can dispose of the buffer once Q3MemoryStorage_New
returns.
Whenever you create a storage object associated with an open file or an allocated memory block, you must close
the file or dispose of the memory yourself. Whenever QuickDraw3D opens a file or allocates memory to create
a storage object, it closes the file or disposes of the
memory itself.<8bat>s
It's possible, however, to have QuickDraw3D create and manage a piece of storage for you. For example, you can create a memory storage object by calling Q3MemoryStorage_NewBuffer
as follows:
myStorageObj = Q3MemoryStorage_NewBuffer(NULL, 0, 0);Notice that the first parameter in this call is
NULL
; this value indicates that you want QuickDraw3D to allocate a buffer internally and automatically expand the buffer whenever necessary. (The initial size of the buffer and the grow size of the buffer are determined by internal QuickDraw3D settings.) In addition, when you close or dispose of the storage object, QuickDraw3D disposes of any memory it has allocated on your behalf.
You can also have QuickDraw3D open and close files on your behalf. On the Macintosh Operating System, you can call the Q3FSSpecStorage_New
function, passing a file system specification structure describing a closed file. The following line of code illustrates how to do this:
myStorageObj = Q3FSSpecStorage_New(&myFSSpec);QuickDraw3D opens the file and creates a storage object associated with
Q3UnixPathStorage_New
to have QuickDraw3D open a file described by a path name and create a new storage object associated with it. When you No matter whether you opened a piece of storage (that is, a file or a block of memory) yourself or allowed QuickDraw3D to open it for you, you must not access that piece of storage once you've created a storage object to represent it. QuickDraw3D assumes that it has exclusive access to all data in any part of a physical storage device associated with an open storage object.<8batcolor>s
Q3MacintoshStorage_Get
. Similarly, you can determine the starting address and size of a buffer associated with a memory storage object by calling Q3MemoryStorage_GetBuffer
.In general, the routines that get and set storage object information operate like the get and set routines for other types of QuickDraw3D objects, but with several important differences:
Q3MemoryStorage_NewBuffer
, the returned address is the address of the actual buffer associated with the storage object, not the address of a copy of that buffer. In addition, that buffer may change locations in memory (but only if QuickDraw3D allocated the buffer on your behalf and writing data to the storage object causes QuickDraw3D to resize the buffer).
Q3MemoryStorage_Get
or Q3MemoryStorage_Set
with a handle storage object (of type kQ3MemoryStorageTypeHandle
). Similarly, you cannot use Q3UnixStorage_Get
or Q3UnixStorage_Set
with a UNIX path name storage object (of type kQ3UnixStorageTypePath
).
Q3File_SetStorage
function and that file object has been opened by a call to the Q3File_OpenRead
or Q3File_OpenWrite
function.) A storage object is considered closed at all other times. (Note that a storage object can be closed even though the associated file on disk is open to the operating system.)
Let us know what you think of these prototype pages.
Generated with Harlequin WebMaker