Loading and Saving

  1. QuesaIO.h
  2. QuesaStorage.h
  3. QuesaView.h

Quesa provides support for reading and writing arbitrary hierarchies of Quesa objects to and from files or memory buffers.

To read objects from a buffer or file, first create a TQ3FileObject that represents the input stream. Then, call Q3File_OpenRead to open the file for reading. While Q3File_IsEndOfFile is not true, call Q3File_ReadObject to read each object from the stream. What you do with the TQ3Object returned is up to you; but a typical application is to store this in a display group, so that the entire file contents can be treated elsewhere as a single object.

The C++ sample code below illustrates reading the contents of a memory buffer into a TQ3DisplayGroup.

Example: Loading a model from a memory buffer

	// Create a place to store the geometry.
	TQ3GeometryObject geom = Q3DisplayGroup_New();

	// create a File object
	TQ3FileObject fileObj = Q3File_New();

	// create a Storage object, and associate it with the File
	TQ3StorageObject storageObj = Q3MemoryStorage_NewBuffer(buffer, bytes, bytes);

	Q3File_SetStorage(fileObj, storageObj);
	Q3Object_Dispose(storageObj);

	// open the file, read the model
	TQ3FileMode fileMode = 0;
	Q3File_OpenRead(fileObj, &fileMode);

	while (not Q3File_IsEndOfFile(fileObj)) {
		TQ3Object tempObj = Q3File_ReadObject(fileObj);
		if (tempObj) {
			Q3Group_AddObject(geom, tempObj);
			Q3Object_Dispose(tempObj);
		}
	}
Saving a model or other scene to a file or buffer is similar: you start by creating a File object associated with some Storage. The Storage object represents the disk file or memory buffer in which the data should be saved. But to actually write the data, you use a submit loop on a view object. This is just like what you would use to render the scene, except that you precede the loop with a call to Q3View_StartWriting, and end the loop with Q3View_EndWriting.

The following example shows C code for writing an object (which would typically represent a model or a scene) to an arbitrary storage object. Note that while the submit loop in this example submits just the one object, additional objects could be submitted as well, just as when rendering.

Example: Saving a scene to a storage object

TQ3Status SaveToStorage( TQ3Object object, TQ3ViewObject view, TQ3StorageObject storage )
{
	TQ3Status       status;
	TQ3ViewStatus   viewStatus;
	TQ3FileObject   file;

	// check parameters
	if (NULL == object || NULL == storage) return kQ3Failure;

	// create a file object, and attach it to the given storage
	file = Q3File_New();
	if (NULL == file) return kQ3Failure;
	status = Q3File_SetStorage(file, storage);

	if (kQ3Success == status) {
		// open the file for writing
		status = Q3File_OpenWrite(file, kQ3FileModeNormal);

		// start writing, then use a submit loop to write data
		if (kQ3Success == status) {
			status = Q3View_StartWriting(view, file);
			viewStatus = kQ3ViewStatusRetraverse;
			while (kQ3Success == status && kQ3ViewStatusRetraverse == viewStatus) {
				Q3Object_Submit(object, view);
				viewStatus = Q3View_EndWriting(view);
			}
		}
	
		Q3File_Close(file);
	}
	Q3Object_Dispose(file);

	return status;
}