Functions

( TQ3Status ) Q3Bitmap_Empty (
    TQ3Bitmap *bitmap
);

Discussion

Release the memory used by a TQ3Bitmap.

Should be used to release the data used by TQ3Bitmaps returned by Quesa. You should not call Q3Bitmap_Empty on TQ3Bitmaps whose image data was allocated by you.

Parameter Descriptions

bitmap

The TQ3Bitmap whose image data should be released.

function result

Success or failure of the operation.

( TQ3Boolean ) Q3Bitmap_GetBit (
    const TQ3Bitmap *theBitmap,
    TQ3Uns32 x,
    TQ3Uns32 y
);

Discussion

Get the status of a bit within a bitmap.

This function is not available in QD3D.

Parameter Descriptions

theBitMap

The bitmap to query.

x

The x coordinate of the pixel to query.

y

The y coordinate of the pixel to query.

function result

The status of the bit.

( TQ3Uns32 ) Q3Bitmap_GetImageSize (
    TQ3Uns32 width,
    TQ3Uns32 height
);

Discussion

Determine how much image data would be required for a TQ3Bitmap.

Returns the smallest block of memory that could hold a bitmap with the specified dimensions.

Parameter Descriptions

width

The proposed width of the bitmap.

height

The proposed height of the bitmap.

function result

The number of bytes needed for the bitmap.

( TQ3Status ) Q3Bitmap_SetBit (
    TQ3Bitmap *theBitmap,
    TQ3Uns32 x,
    TQ3Uns32 y,
    TQ3Boolean theState
);

Discussion

Set the status of a bit within a bitmap.

This function is not available in QD3D.

Parameter Descriptions

theBitMap

The bitmap to update.

x

The x coordinate of the pixel to update.

y

The y coordinate of the pixel to update.

theState

The new state for the pixel.

function result

Success or failure of the operation.

( TQ3Status ) Q3Exit (void);

Discussion

Shuts down Quesa, and releases any resources allocated by the library.

function result

Success or failure of the operation.

( TQ3Status ) Q3GetReleaseVersion (
    TQ3Uns32 *releaseRevision
);

Discussion

Returns the revision of the installed Quesa software in the format of the first four bytes of a Macintosh 'vers' resource.

The four bytes contain 1) the major revision level, 2) the minor revision, 3) the development stage, and 4) the prerelease revision level, respectively. The three revision levels are each represented in binary coded decimal. The development stage can be development (0x20), alpha (0x40), beta (0x60) or release (0x80).

For example, if the revision is 1.61a23 (= 1.6.1a23), returns 0x01614023. For more information, see the description of the 'vers' resource in the book Inside Macintosh: Macintosh Toolbox Essentials.

Note that unlike QD3D, Quesa allows Q3GetReleaseVersion to be called outside of a Q3Initialize/Q3Exit block.

Parameter Descriptions

releaseRevision

Receives the revision of Quesa.

function result

Success or failure of the operation.

( TQ3Status ) Q3GetVersion (
    TQ3Uns32 *majorRevision,
    TQ3Uns32 *minorRevision
);

Discussion

Returns the major and minor revision levels of the installed Quesa software.

For example, if the revision is 1.6a23 (= 1.6.0a23), returns 1 as the major revision level and 6 as the minor revision level: The final 0 in the minor revision level is omitted. If the revision is 1.61a23 (= 1.6.1a23), returns 1 as the major revision level and 61 as the minor revision level.

Note that unlike QD3D, Quesa allows Q3GetVersion to be called outside of a Q3Initialize/Q3Exit block.

Parameter Descriptions

majorRevision

Receives the major revision level of Quesa.

minorRevision

Receives the minor revision level of Quesa.

function result

Success or failure of the operation.

( TQ3Status ) Q3Initialize (void);

Discussion

Initialises Quesa.

Only Q3IsInitialized, Q3GetVersion, and Q3GetReleaseVersion may be called before the Quesa library is initialised.

function result

Success or failure of the operation.

( TQ3Boolean ) Q3IsInitialized (void);

Discussion

Tests to see if Quesa has been initialised or not.

function result

True or false as Quesa has been initialised or not.

( TQ3Status ) Q3ObjectHierarchy_EmptySubClassData (
    TQ3SubClassData *subClassData
);

Discussion

Release the memory allocated by a previous call to Q3ObjectHierarchy_GetSubClassData.

Parameter Descriptions

subClassData

The sub-class data to release.

function result

Success or failure of the operation.

( TQ3Status ) Q3ObjectHierarchy_GetStringFromType (
    TQ3ObjectType objectClassType,
    TQ3ObjectClassNameString objectClassString
);

Discussion

Returns the class name string for a class identified by a class type.

Parameter Descriptions

objectClassType

The class type of the class to locate.

objectClassString

Receives the class name string of the class.

function result

Success or failure of the operation.

( TQ3Status ) Q3ObjectHierarchy_GetSubClassData (
    TQ3ObjectType objectClassType,
    TQ3SubClassData *subClassData
);

Discussion

Return the immediate sub-classes of a class.

The data returned must be released with a subsequent call to Q3ObjectHierarchy_EmptySubClassData.

Parameter Descriptions

objectClassType

The class type of the class to query.

subClassData

Receives the immediate sub-classes of the class.

function result

Success or failure of the operation.

( TQ3Status ) Q3ObjectHierarchy_GetTypeFromString (
    const TQ3ObjectClassNameString objectClassString,
    TQ3ObjectType *objectClassType
);

Discussion

Returns the class type for a class identified by a class name string.

Parameter Descriptions

objectClassString

The class name of the class to locate.

objectClassType

Receives the class type of the class.

function result

Success or failure of the operation.

( TQ3Boolean ) Q3ObjectHierarchy_IsNameRegistered (
    const char *objectClassName
);

Discussion

Check to see if a class is registered with Quesa.

Parameter Descriptions

majorRevision

The class name of the class to check.

function result

True or false as the class is registered or not.

( TQ3Boolean ) Q3ObjectHierarchy_IsTypeRegistered (
    TQ3ObjectType objectClassType
);

Discussion

Check to see if a class is registered with Quesa.

Parameter Descriptions

objectClassType

The class type of the class to check.

function result

True or false as the class is registered or not.

( TQ3Status ) Q3Object_AddElement (
    TQ3Object object,
    TQ3ElementType theType,
    const void *data
);

Discussion

Add an element to an object. Same as Q3Shape_AddElement, except that the object is not required to be a shape or set.

If the object is Shared, this operation will increment the object's edit index.

This function is not available in QD3D.

Parameter Descriptions

object

The object to update.

theType

The type of the element data.

data

The element data.

function result

Success or failure of the operation.

( TQ3Status ) Q3Object_CleanDispose (
    TQ3Object *theObject
);

Discussion

Cleanly disposes of a Quesa object.

If theObject is not NULL, invokes Q3Object_Dispose to decrement the object reference count then clears the supplied pointer to prevent stale references.

Equivalent to:

if (theObject != NULL) { Q3Object_Dispose(theObject); theObject = NULL; }

This function is not available in QD3D.

Parameter Descriptions

theObject

The object to dispose (may be NULL).

function result

Success or failure of the operation.

( TQ3Status ) Q3Object_ClearElement (
    TQ3Object object,
    TQ3ElementType theType
);

Discussion

Empty an object of a particular type of element. Same as Q3Shape_ClearElement, except that the object is not required to be a shape or set.

If the object is Shared, this operation will increment the object's edit index.

This function is not available in QD3D.

Parameter Descriptions

object

The object to update.

theType

The element type to remove.

function result

Success or failure of the operation.

( TQ3Boolean ) Q3Object_ContainsElement (
    TQ3Object object,
    TQ3ElementType theType
);

Discussion

Check to see if an object contains an element of a given type. Same as Q3Shape_ContainsElement, except that the object is not required to be a shape or set.

This function is not available in QD3D.

Parameter Descriptions

object

The object to query.

theType

The type of the element data to look for.

function result

Success or failure of the operation.

( TQ3Status ) Q3Object_Dispose (
    TQ3Object object
);

Discussion

Disposes of a Quesa object.

Most types of TQ3Object are reference-counted. This function decrements the reference count of the object. When the reference count falls to 0, the object is deleted.

When used on a non-reference-counted object such as a view or pick, the object is deleted immediately.

Parameter Descriptions

object

The object to dispose.

function result

Success or failure of the operation.

( TQ3Object ) Q3Object_Duplicate (
    TQ3Object object
);

Discussion

Duplicates a Quesa object.

Returns a new copy of the object, with a reference count of 1.

Parameter Descriptions

object

The object to duplicate.

function result

A new copy of the object.

( TQ3Status ) Q3Object_EmptyElements (
    TQ3Object object
);

Discussion

Empty an object of any elements it contains. Same as Q3Shape_EmptyElements, except that the object is not required to be a shape or set.

If the object is Shared, this operation will increment the object's edit index.

This function is not available in QD3D.

Parameter Descriptions

object

The object to update.

function result

Success or failure of the operation.

( TQ3Status ) Q3Object_GetElement (
    TQ3Object object,
    TQ3ElementType theType,
    void *data
);

Discussion

Get an element from an object. Same as Q3Shape_GetElement, except that the object is not required to be a shape or set.

This function is not available in QD3D.

Parameter Descriptions

object

The object to query.

theType

The type of the element data.

data

Receives the element data.

function result

Success or failure of the operation.

( TQ3ObjectType ) Q3Object_GetLeafType (
    TQ3Object object
);

Discussion

Returns the leaf type of an object.

Returns the most specific type that can be identified from the object (e.g., a camera object may have a leaf type of kQ3CameraTypeViewAngleAspect). Returns kQ3ObjectTypeInvalid if the object type is unknown.

Parameter Descriptions

object

The object to test.

function result

The leaf type of the object.

( TQ3Status ) Q3Object_GetNextElementType (
    TQ3Object object,
    TQ3ElementType *theType
);

Discussion

Iterate through the element types in an object. Same as Q3Shape_GetNextElementType, except that the object is not required to be a shape or set.

Pass in kQ3ElementTypeNone to start iterating through the element types in the object, and pass back the returned value to obtain the next type. The type is set to kQ3ElementTypeNone if there are no more elements in the shape.

This function is not available in QD3D.

Parameter Descriptions

object

The object to query.

theType

Receives the next element type.

function result

Success or failure of the operation.

( TQ3Status ) Q3Object_GetProperty (
    TQ3Object object,
    TQ3ObjectType propType,
    TQ3Uns32 bufferSize,
    TQ3Uns32* actualSize,
    void* buffer
);

Discussion

Get property data from an object.

The operation fails if the property does not exist or if you provide a buffer that is not large enough to hold the data.

If you do not know the size of the property, you may call Q3Object_GetProperty passing NULL for the buffer to find the size of the data, then allocate your buffer and call Q3Object_GetProperty again.

This function is not available in QD3D.

Parameter Descriptions

object

The object.

propType

Property type tag.

bufferSize

Size of provided buffer in bytes.

actualSize

Returns size of returned data in bytes. You may pass NULL if you do not need this information.

buffer

Buffer to receive the property data. May be NULL.

function result

Success or failure of the operation.

( TQ3Status ) Q3Object_GetSet (
    TQ3Object object,
    TQ3SetObject* set
);

Discussion

Get the element set of an object. This is not the same as the set returned by Q3Shape_GetSet.

This function is primarily for the use of file format plug-ins. Most applications will not need it.

This function is not available in QD3D.

Parameter Descriptions

object

The object.

set

Receives a set object, or NULL.

function result

Success or failure of the operation.

( TQ3ObjectType ) Q3Object_GetType (
    TQ3Object object
);

Discussion

Returns the top level type of an object.

Returns kQ3ObjectTypeElement, kQ3ObjectTypePick, kQ3ObjectTypeShared, or kQ3ObjectTypeView. Returns kQ3ObjectTypeInvalid if the object type is unknown.

Parameter Descriptions

object

The object to test.

function result

The top level type of the object.

( TQ3Boolean ) Q3Object_IsDrawable (
    TQ3Object object
);

Discussion

Tests to see if an object is drawable.

Only drawable objects may be submitted to a view's rendering loop.

Parameter Descriptions

object

The object to test.

function result

True or false as the object is drawable or not.

( TQ3Boolean ) Q3Object_IsType (
    TQ3Object object,
    TQ3ObjectType theType
);

Discussion

Tests to see if an object belongs to a given type.

Examines both the object supplied and its parents. E.g., a camera object would return true for a type of kQ3CameraTypeViewAngleAspect, kQ3ShapeTypeCamera, kQ3SharedTypeShape, and kQ3ObjectTypeShared but would return false for kQ3ObjectTypePick.

Parameter Descriptions

object

The object to test.

theType

The type to test the object against.

function result

True or false as the object belongs to the type or not.

( TQ3Boolean ) Q3Object_IsWritable (
    TQ3Object object,
    TQ3FileObject theFile
);

Discussion

Tests to see if an object is writable.

Only drawable objects may be submitted to a view's writing loop.

Parameter Descriptions

object

The object to test.

function result

True or false as the object is writable or not.

( TQ3Status ) Q3Object_RemoveProperty (
    TQ3Object object,
    TQ3ObjectType propType
);

Discussion

Remove a property from an object.

This function is not available in QD3D.

Parameter Descriptions

object

The object.

propType

Property type tag.

function result

Success or failure of the operation.

( TQ3Status ) Q3Object_SetProperty (
    TQ3Object object,
    TQ3ObjectType propType,
    TQ3Uns32 dataSize,
    const void* data
);

Discussion

Set a property of an object. If there was already a property of the same type, it is replaced.

Property type tags consisting of all lowercase ASCII letters are reserved for Quesa internal use.

This function is not available in QD3D.

Parameter Descriptions

object

The object.

propType

Property type tag.

dataSize

Size in bytes of the data.

data

Data to copy into the property.

function result

Success or failure of the operation.

( TQ3Status ) Q3Object_SetSet (
    TQ3Object object,
    TQ3SetObject set
);

Discussion

Assign to the element set of an object, disposing any previous set. This is not the same as the set element that is changed by Q3Shape_SetSet.

This function is primarily for the use of file format plug-ins. Most applications will not need it.

This function is not available in QD3D.

Parameter Descriptions

object

The object.

set

A set object.

function result

A set object, or NULL.

( TQ3Status ) Q3Object_Submit (
    TQ3Object object,
    TQ3ViewObject view
);

Discussion

Submit an object to a view.

The object is submitted to the view's current processing loop, e.g., for rendering, picking, or writing to a file.

Parameter Descriptions

object

The object to submit.

view

The view to submit the object to.

function result

Success or failure of the operation.

( TQ3Status ) Q3Shape_AddElement (
    TQ3ShapeObject shape,
    TQ3ElementType theType,
    const void *data
);

Discussion

Add an element to a shape.

Parameter Descriptions

shape

The object to update.

theType

The type of the element data.

data

The element data.

function result

Success or failure of the operation.

( TQ3Status ) Q3Shape_ClearElement (
    TQ3ShapeObject shape,
    TQ3ElementType theType
);

Discussion

Empty a shape of a particular type of element.

Parameter Descriptions

shape

The object to update.

theType

The element type to remove.

function result

Success or failure of the operation.

( TQ3Boolean ) Q3Shape_ContainsElement (
    TQ3ShapeObject shape,
    TQ3ElementType theType
);

Discussion

Check to see if a shape contains an element of a given type.

Parameter Descriptions

shape

The object to query.

theType

The type of the element data to look for.

function result

Success or failure of the operation.

( TQ3Status ) Q3Shape_EmptyElements (
    TQ3ShapeObject shape
);

Discussion

Empty a shape of any elements it contains.

Parameter Descriptions

shape

The object to update.

function result

Success or failure of the operation.

( TQ3Status ) Q3Shape_GetElement (
    TQ3ShapeObject shape,
    TQ3ElementType theType,
    void *data
);

Discussion

Get an element from a shape.

Parameter Descriptions

shape

The object to query.

theType

The type of the element data.

data

Receives the element data.

function result

Success or failure of the operation.

( TQ3Status ) Q3Shape_GetNextElementType (
    TQ3ShapeObject shape,
    TQ3ElementType *theType
);

Discussion

Iterate through the element types in a shape.

Pass in kQ3ElementTypeNone to start iterating through the element types in the shape, and pass back the returned value to obtain the next type. Is set to kQ3ElementTypeNone if there are no more elements in the shape.

Parameter Descriptions

shape

The object to query.

theType

Receives the next element type.

function result

Success or failure of the operation.

( TQ3Status ) Q3Shape_GetSet (
    TQ3ShapeObject shape,
    TQ3SetObject *theSet
);

Discussion

Get the set element currently associated with a shape. The function call Q3Shape_GetSet( o, &s ) is equivalent to Q3Shape_GetElement( o, kQ3ElementTypeSet, &s ).

Note that this is not the same as the attribute set of a geometry object, nor is in the internal set which holds elements on an object. That is, after adding elements or attributes to an object, this function may still return the NULL set.

Parameter Descriptions

shape

The object to query.

theSet

Receives the set of the object, or NULL.

function result

Success or failure of the operation.

( TQ3ObjectType ) Q3Shape_GetType (
    TQ3ShapeObject shape
);

Discussion

Get the type of a shape object.

Returns kQ3ObjectTypeInvalid if the object is not a shape object or the type can not be determined. Returns a kQ3ShapeTypeXXXX value for shape objects.

Parameter Descriptions

shape

The object to test.

function result

The type of the shape object.

( TQ3Status ) Q3Shape_SetSet (
    TQ3ShapeObject shape,
    TQ3SetObject theSet
);

Discussion

Set the set element currently associated with a shape. The function call Q3Shape_SetSet( o, s ) is equivalent to Q3Shape_SetElement( o, kQ3ElementTypeSet, &s ).

Note that this is not the same as the attribute set of a geometry object.

Parameter Descriptions

shape

The object to update.

theSet

The new set for the object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Shared_Edited (
    TQ3SharedObject sharedObject
);

Discussion

Change the edit index of a shared object.

Editing a shared object will change its edit index automatically: this function is typically used for shared plug-in objects who need to indicate to Quesa that their private data has changed.

Parameter Descriptions

sharedObject

The object to update.

function result

Success or failure of the operation.

( TQ3Uns32 ) Q3Shared_GetEditIndex (
    TQ3SharedObject sharedObject
);

Discussion

Get the edit index of a shared object.

An edit index is a unique number associated with a shared object, which changes each time the object is edited. By testing this number, you can determine when an object has been edited.

Parameter Descriptions

sharedObject

The object to query.

function result

The current edit index of the object.

( TQ3SharedObject ) Q3Shared_GetReference (
    TQ3SharedObject sharedObject
);

Discussion

Increment the reference count of a shared object.

Parameter Descriptions

sharedObject

The object whose reference count should be incremented.

function result

The object whose reference count has been incremented.

( TQ3Uns32 ) Q3Shared_GetReferenceCount (
    TQ3SharedObject sharedObject
);

Discussion

Return the reference count of a shared object.

This function should be used only for debugging. If you are tempted to use it for something else, then you probably don't understand the correct way to work with reference-counted objects.

This function is not available in QD3D.

Parameter Descriptions

sharedObject

The object to test.

function result

Reference count.

( TQ3ObjectType ) Q3Shared_GetType (
    TQ3SharedObject sharedObject
);

Discussion

Get the type of a shared object.

Returns kQ3ObjectTypeInvalid if the object is not a shared object or the type can not be determined. Returns a kQ3SharedTypeXXXX value for shared objects.

Parameter Descriptions

sharedObject

The object to test.

function result

The type of the shared object.

( TQ3Boolean ) Q3Shared_IsReferenced (
    TQ3SharedObject sharedObject
);

Discussion

Determine if a shared object has more than one reference to it.

Returns kQ3True if the object has more than one reference to it. Will return kQ3False if the object a reference count of one.

Parameter Descriptions

sharedObject

The object to test.

function result

True or false as the object has more than one reference.

( void ) Q3Shared_SetEditIndex (
    TQ3SharedObject inObject,
    TQ3Uns32 inEditIndex
);

Discussion

This function should be used even more rarely than Q3Shared_Edited. It was added to solve a specific problem: Caching information in a custom element attached to an object without changing the edit index of the object.

This function is not available in QD3D.

Parameter Descriptions

inObject

A shared object to update.

inEditIndex

New edit index.

© 1999-2008 Quesa Developers (Last Updated 5/10/2008)