QuesaExtension.h

Discussion

Declares the Quesa extension interface.

Functions

Q3XError_Post

( void ) Q3XError_Post (
    TQ3Error error
);

Discussion

Post an error to the error manager.

Although intended only for use by extensions in QD3D, this call is also available to general application clients in Quesa.

Parameter Descriptions

error
The error to post.

Q3XMacintoshError_Post

( void ) Q3XMacintoshError_Post (
    OSErr macOSErr
);

Discussion

Post a Mac OS-specific error to the error manager.

Although intended only for use by extensions in QD3D, this call is also available to general application clients in Quesa.

Note that this call is equivalent to a call to Q3Error_PlatformPost, which is the preferred method for posting platform-specific errors.

Parameter Descriptions

macOSErr
The Mac OS error to post.

Q3XNotice_Post

( void ) Q3XNotice_Post (
    TQ3Notice notice
);

Discussion

Post a notice to the error manager.

Although intended only for use by extensions in QD3D, this call is also available to general application clients in Quesa.

Parameter Descriptions

notice
The notice to post.

Q3XObjectClass_GetLeafType

( TQ3ObjectType ) Q3XObjectClass_GetLeafType (
    TQ3XObjectClass objectClass
);

Discussion

Get the leaf type of a class.

The leaf type is the type returned by Q3XObjectHierarchy_RegisterClass when the class was registered.

Parameter Descriptions

objectClass
The class to query.

function result: The leaf type of the class.

Q3XObjectClass_GetMethod

( TQ3XFunctionPointer ) Q3XObjectClass_GetMethod (
    TQ3XObjectClass objectClass,
    TQ3XMethodType methodType
);

Discussion

Get a method of a class.

Parameter Descriptions

objectClass
The class to query.

methodType
The method type to retrieve.

function result: The function pointer for the method.

Q3XObjectClass_GetPrivate

( void * ) Q3XObjectClass_GetPrivate (
    TQ3XObjectClass objectClass,
    TQ3Object targetObject
);

Discussion

Get the private instance data of an object.

If no instance data space was reserved for the object, a NULL pointer will be returned.

Parameter Descriptions

objectClass
The class of the object.

targetObject
The object to query.

function result: A pointer to the private instance data.

Q3XObjectClass_GetType

( TQ3Status ) Q3XObjectClass_GetType (
    TQ3XObjectClass objectClass,
    TQ3ObjectType *theType
);

Discussion

Get the type of a class.

Parameter Descriptions

objectClass
The class to query.

theType
Receives the type of the class.

function result: Success or failure of the operation.

Q3XObjectHierarchy_FindClassByType

( TQ3XObjectClass ) Q3XObjectHierarchy_FindClassByType (
    TQ3ObjectType theType
);

Discussion

Locate a class within the class tree.

Parameter Descriptions

theType
The class type.

function result: The class registered under theType, or NULL.

Q3XObjectHierarchy_GetClassVersion

( TQ3Status ) Q3XObjectHierarchy_GetClassVersion (
    TQ3ObjectType objectClassType,
    TQ3XObjectClassVersion *version
);

Discussion

Get the version of a class.

The class version is returned by the class ClassVersion method.

Parameter Descriptions

objectClassType
The class to query.

version
Receives the version of the class.

function result: Success or failure of the operation.

Q3XObjectHierarchy_NewObject

( TQ3Object ) Q3XObjectHierarchy_NewObject (
    TQ3XObjectClass objectClass,
    void *parameters
);

Discussion

Instantiate a class.

Parameter Descriptions

objectClass
The class to instantiate.

parameters
The parameter data for the NewMethod method.

function result: A new instance of the class.

Q3XObjectHierarchy_RegisterClass

( TQ3XObjectClass ) Q3XObjectHierarchy_RegisterClass (
    TQ3ObjectType parentType,
    TQ3ObjectType *objectType,
    const char *objectName,
    TQ3XMetaHandler metaHandler,
    TQ3XMetaHandler virtualMetaHandler,
    TQ3Uns32 methodsSize,
    TQ3Uns32 instanceSize
);

Discussion

Register a new object class in the class tree.

Quesa does not support the virtualMetaHandler or methodsSize parameters, and these should be set to NULL and 0 respectively.

Virtual methods are inherited from the parent class metahandler in the Quesa class tree, and the QD3D docs are unclear on the purpose of methodsSize.

Parameter Descriptions

parentType
The object type of the parent the new class should be derived from. To derive new classes from the root TQ3Object class, pass in kQ3ObjectTypeInvalid.

objectType
Receives the new object type for the new class. This value is used as the class identifier in binary 3DMF files, and is returned by the _GetType and Q3Object_GetLeafType class. It may also be passed to Q3Object_IsType to identify objects of this class.

objectName
A C string which acts as a unique textual identifier for the new class. This value is used as the class identifier in text 3DMF files.

metaHandler
The metahandler for the class.

virtualMetaHandler
The virtual metahandler for the class (should be NULL).

methodsSize
The size of the private class data (shoudld be 0).

instanceSize
The size of the instance data for the class, if any.

function result: The new class reference.

Q3XObjectHierarchy_UnregisterClass

( TQ3Status ) Q3XObjectHierarchy_UnregisterClass (
    TQ3XObjectClass objectClass
);

Discussion

Unregister a object class from the class tree.

Only classes registered by Q3XObjectHierarchy_RegisterClass should be unregistered by this routine.

Parameter Descriptions

objectClass
The class to unregister.

function result: Success or failure of the operation.

Q3XObject_GetClass

( TQ3XObjectClass ) Q3XObject_GetClass (
    TQ3Object object
);

Discussion

Get the class of an object.

Parameter Descriptions

object
The object to query.

function result: The class of the object.

Q3XSharedLibrary_Register

( TQ3Status ) Q3XSharedLibrary_Register (
    TQ3XSharedLibraryInfo *sharedLibraryInfo
);

Discussion

Register a shared library with Quesa.

Can be called from within a shared library entry point to register a callback with Quesa. The callback will be invoked by Q3Initialize during initialisation, to allow it to register custom classes with the Quesa class tree.

Parameter Descriptions

sharedLibraryInfo
The shared library registration state.

function result: Success or failure of the operation.

Q3XSharedLibrary_Unregister

( TQ3Status ) Q3XSharedLibrary_Unregister (
    TQ3Uns32 sharedLibrary
);

Discussion

Unregister a shared library with Quesa.

The sharedLibrary parameter should match the sharedLibrary field within the TQ3XSharedLibraryInfo that was passed to Q3XSharedLibrary_Register.

Parameter Descriptions

sharedLibrary
The shared library reference.

function result: Success or failure of the operation.

Q3XWarning_Post

( void ) Q3XWarning_Post (
    TQ3Warning warning
);

Discussion

Post a warning to the error manager.

Although intended only for use by extensions in QD3D, this call is also available to general application clients in Quesa.

Parameter Descriptions

warning
The warning to post.

Typedefs

TQ3XObjectClassVersion

Pseudo-method that returns the version of a class.

typedef TQ3Uns32 TQ3XObjectClassVersion;

TQ3XSharedLibraryInfo

typedef struct TQ3XSharedLibraryInfo {
    TQ3XSharedLibraryRegister       registerFunction;
    TQ3Uns32                        sharedLibrary;
} TQ3XSharedLibraryInfo;

Discussion

Parameter data for Q3XSharedLibrary_Register.

The sharedLibrary field is often used to hold a platform-specific shared library reference. It has no meaning for Quesa, and is used as an identifier to match up calls to Q3XSharedLibrary_Unregister with the appropriate call to Q3XSharedLibrary_Register.

Field Descriptions

registerFunction
Shared library registration method.

sharedLibrary
Platform-specific shared library reference.

TQ3XViewSubmitImmediateMethod

Method type that a view object uses when an immediate object is submitted.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XViewSubmitImmediateMethod) ( TQ3ViewObject theView, TQ3ObjectType objectType, const void *objectData );

Parameter Descriptions

theView
A view object.

objectType
An object type.

objectData
The data of the object.

function result: Success or failure of the operation.

TQ3XViewSubmitRetainedMethod

Method type that a view object uses when a retained object is submitted.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XViewSubmitRetainedMethod) ( TQ3ViewObject theView, TQ3Object theObject );

Parameter Descriptions

theView
A view object.

theObject
An object.

function result: Success or failure of the operation.

Enumerations

Class method types

Codes identifying methods of Quesa objects.

enum {
    kQ3XMethodTypeObjectClassVersion            = Q3_METHOD_TYPE('v', 'r', 's', 'n'),
    kQ3XMethodTypeObjectClassRegister           = Q3_METHOD_TYPE('r', 'g', 's', 't'),
    kQ3XMethodTypeObjectClassReplace            = Q3_METHOD_TYPE('r', 'g', 'r', 'p'),
    kQ3XMethodTypeObjectClassUnregister         = Q3_METHOD_TYPE('u', 'n', 'r', 'g'),
    kQ3XMethodTypeObjectNew                     = Q3_METHOD_TYPE('n', 'e', 'w', 'o'),
    kQ3XMethodTypeObjectDelete                  = Q3_METHOD_TYPE('d', 'l', 't', 'e'),
    kQ3XMethodTypeObjectDuplicate               = Q3_METHOD_TYPE('d', 'u', 'p', 'l'),
    kQ3XMethodTypeViewSubmitRetainedRender      = Q3_METHOD_TYPE('s', 'v', 'r', 'r'),
    kQ3XMethodTypeViewSubmitRetainedPick        = Q3_METHOD_TYPE('s', 'v', 'r', 'p'),
    kQ3XMethodTypeViewSubmitRetainedBound       = Q3_METHOD_TYPE('s', 'v', 'r', 'b'),
    kQ3XMethodTypeViewSubmitRetainedWrite       = Q3_METHOD_TYPE('s', 'v', 'r', 'w'),
    kQ3XMethodTypeViewSubmitImmediateRender     = Q3_METHOD_TYPE('s', 'v', 'i', 'r'),
    kQ3XMethodTypeViewSubmitImmediatePick       = Q3_METHOD_TYPE('s', 'v', 'i', 'p'),
    kQ3XMethodTypeViewSubmitImmediateBound      = Q3_METHOD_TYPE('s', 'v', 'i', 'b'),
    kQ3XMethodTypeViewSubmitImmediateWrite      = Q3_METHOD_TYPE('s', 'v', 'i', 'w')
};

Discussion

These values should be considered to be of type TQ3XMethodType.

Constants

kQ3XMethodTypeObjectClassVersion
This is the type of a pseudo-method, really just a value of type TQ3XObjectClassVersion rather than a function pointer.

kQ3XMethodTypeObjectClassRegister
Currently unused by Quesa.

kQ3XMethodTypeObjectClassReplace
Currently unused by Quesa.

kQ3XMethodTypeObjectClassUnregister
Currently unused by Quesa.

kQ3XMethodTypeObjectNew
Method of type TQ3XObjectNewMethod that is called when an object is created.

kQ3XMethodTypeObjectDelete
Method of type TQ3XObjectDeleteMethod that is called when an object is deleted.

kQ3XMethodTypeObjectDuplicate
Method of type TQ3XObjectDuplicateMethod that is called when an object is duplicated.

kQ3XMethodTypeViewSubmitRetainedRender
Method of type TQ3XViewSubmitRetainedMethod belonging to a View object that is called when a retained object is submitted to the View for rendering.

kQ3XMethodTypeViewSubmitRetainedPick
Method of type TQ3XViewSubmitRetainedMethod belonging to a View object that is called when a retained object is submitted to the View for picking.

kQ3XMethodTypeViewSubmitRetainedBound
Method of type TQ3XViewSubmitRetainedMethod belonging to a View object that is called when a retained object is submitted to the View for bounding.

kQ3XMethodTypeViewSubmitRetainedWrite
Method of type TQ3XViewSubmitRetainedMethod belonging to a View object that is called when a retained object is submitted to the View for writing.

kQ3XMethodTypeViewSubmitImmediateRender
Method of type TQ3XViewSubmitImmediateMethod belonging to a View object that is called when an immediate object is submitted to the View for rendering.

kQ3XMethodTypeViewSubmitImmediatePick
Method of type TQ3XViewSubmitImmediateMethod belonging to a View object that is called when an immediate object is submitted to the View for picking.

kQ3XMethodTypeViewSubmitImmediateBound
Method of type TQ3XViewSubmitImmediateMethod belonging to a View object that is called when an immediate object is submitted to the View for bounding.

kQ3XMethodTypeViewSubmitImmediateWrite
Method of type TQ3XViewSubmitImmediateMethod belonging to a View object that is called when an immediate object is submitted to the View for writing.