Functions

Q3AttributeSet_Add

( TQ3Status ) Q3AttributeSet_Add (
    TQ3AttributeSet attributeSet,
    TQ3AttributeType theType,
    const void *data
);

Discussion

Add an attribute to an attribute set.

Copy attribute data into an attribute set. If the set already contains the specified type of attribute, it is replaced.

Parameter Descriptions

attributeSet
The attribute set.

theType
The attribute type.

data
Pointer to the attribute data.

function result: Success or failure of the operation.

Q3AttributeSet_Clear

( TQ3Status ) Q3AttributeSet_Clear (
    TQ3AttributeSet attributeSet,
    TQ3AttributeType theType
);

Discussion

Remove an attribute from an attribute set.

Parameter Descriptions

attributeSet
The attribute set.

theType
The attribute type.

function result: Success or failure of the operation.

Q3AttributeSet_Contains

( TQ3Boolean ) Q3AttributeSet_Contains (
    TQ3AttributeSet attributeSet,
    TQ3AttributeType attributeType
);

Discussion

Determine whether an attribute set contains a specified attribute.

Parameter Descriptions

attributeSet
The attribute set.

attributeType
The attribute type.

function result: kQ3True if the attribute type exists in the set.

Q3AttributeSet_Empty

( TQ3Status ) Q3AttributeSet_Empty (
    TQ3AttributeSet target
);

Discussion

Remove all attributes from an attribute set.

Parameter Descriptions

target
The attribute set.

function result: Success or failure of the operation.

Q3AttributeSet_Get

( TQ3Status ) Q3AttributeSet_Get (
    TQ3AttributeSet attributeSet,
    TQ3AttributeType theType,
    void *data
);

Discussion

Get attribute data from an attribute set.

Copies attribute data into a user-provided buffer which should be large enough for the given kind of attribute.

Parameter Descriptions

attributeSet
The attribute set.

theType
The attribute type.

data
Pointer to a buffer to receive the attribute data.

function result: Success or failure of the operation.

Q3AttributeSet_GetNextAttributeType

( TQ3Status ) Q3AttributeSet_GetNextAttributeType (
    TQ3AttributeSet source,
    TQ3AttributeType *theType
);

Discussion

Find the next attribute type in an attribute set.

If you pass kQ3AttributeTypeNone, it will return the first attribute type. After reaching the last element type, it returns kQ3AttributeTypeNone. Hence, you could iterate through all the attribute types as follows:


TQ3AttributeType	theType = kQ3AttributeTypeNone;
while ( Q3AttributeSet_GetNextAttributeType( set, &theType ) &&
 	(theType != kQ3AttributeTypeNone) )
{
 	DoSomething( theType );
}

Parameter Descriptions

source
The attribute set object.

theType
Given an attribute type, receives the next attribute type.

function result: Success or failure of the operation.

Q3AttributeSet_Inherit

( TQ3Status ) Q3AttributeSet_Inherit (
    TQ3AttributeSet parent,
    TQ3AttributeSet child,
    TQ3AttributeSet result
);

Discussion

Configures an attribute set by copying all attributes from one set (the child) and then copying any attributes that were not in the child from another attribute set (the parent).

The set you pass to receive the result must be an existing attribute set, but any existing attributes in it will be removed.

Parameter Descriptions

parent
An attribute set.

child
An attribute set.

result
An attribute set to be redefined.

function result: Success or failure of the operation.

Q3AttributeSet_New

( TQ3AttributeSet ) Q3AttributeSet_New (void);

Discussion

Create an attribute set object.

function result: A new empty attribute set, or NULL on failure.

Q3AttributeSet_Submit

( TQ3Status ) Q3AttributeSet_Submit (
    TQ3AttributeSet attributeSet,
    TQ3ViewObject view
);

Discussion

Submit an attribute set.

This should only be used within a submitting loop.

Parameter Descriptions

attributeSet
The attribute set object.

view
A view object.

function result: Success or failure of the operation.

Q3Attribute_Submit

( TQ3Status ) Q3Attribute_Submit (
    TQ3AttributeType attributeType,
    const void *data,
    TQ3ViewObject view
);

Discussion

Submit an attribute in immediate mode.

This should only be used within a submitting loop.

Parameter Descriptions

attributeType
The attribute type.

data
Pointer to attribute data.

view
The view object.

function result: Success or failure of the operation.

Q3Set_Add

( TQ3Status ) Q3Set_Add (
    TQ3SetObject theSet,
    TQ3ElementType theType,
    const void *data
);

Discussion

Add an element to a set.

This function copies an element into an existing set. If the set already contains an element of the given type, it is replaced. In the case of a custom element, the type is the type that was returned by Q3XElementClass_Register.

Parameter Descriptions

theSet
The set object.

theType
Type of the element.

data
Pointer to the element data.

function result: Success or failure of the operation.

Q3Set_Clear

( TQ3Status ) Q3Set_Clear (
    TQ3SetObject theSet,
    TQ3ElementType theType
);

Discussion

Remove an element of a given type from a set.

If the set did not contain an element of the specified type, the function returns kQ3Failure.

Parameter Descriptions

theSet
The set object.

theType
The element type.

function result: Success or failure of the operation.

Q3Set_Contains

( TQ3Boolean ) Q3Set_Contains (
    TQ3SetObject theSet,
    TQ3ElementType theType
);

Discussion

Determine whether a set contains an element of a given type.

Parameter Descriptions

theSet
The set object.

theType
The element type.

function result: kQ3True if the element exists in the set.

Q3Set_CopyElement

( TQ3Status ) Q3Set_CopyElement (
    TQ3SetObject sourceSet,
    TQ3ElementType theType,
    TQ3SetObject destSet
);

Discussion

Copies an element from one set to another.

If the destination set already contains an element of the specified type, the element will be replaced.

This function is not available in QD3D.

Parameter Descriptions

sourceSet
The set containing the element to be copied.

theType
Type of the element.

destSet
Set to receive the copied element.

function result: Success or failure of the operation.

Q3Set_Empty

( TQ3Status ) Q3Set_Empty (
    TQ3SetObject target
);

Discussion

Remove all elements from a set.

Parameter Descriptions

target
The set object.

function result: Success or failure of the operation.

Q3Set_Get

( TQ3Status ) Q3Set_Get (
    TQ3SetObject theSet,
    TQ3ElementType theType,
    void *data
);

Discussion

Copy the data of an element into a buffer you provide.

Parameter Descriptions

theSet
The set object.

theType
The element type.

data
Pointer to a buffer large enough to receive the element data.

function result: Success or failure of the operation.

Q3Set_GetNextElementType

( TQ3Status ) Q3Set_GetNextElementType (
    TQ3SetObject theSet,
    TQ3ElementType *theType
);

Discussion

Find the next element type in a set.

If you pass kQ3ElementTypeNone, it will return the first element type. After reaching the last element type, it returns kQ3ElementTypeNone. Hence, you could iterate through all the element types as follows:


TQ3ElementType	theType = kQ3ElementTypeNone;
while ( Q3Set_GetNextElementType( set, &theType ) &&
 	(theType != kQ3ElementTypeNone) )
{
 	DoSomething( theType );
}

Search results are undefined if the set is edited while a search is in progress. Q3Set_GetNextElementType will always return a valid element type or kQ3ElementTypeNone, however some elements may be skipped if the set is modified before the final kQ3ElementTypeNone is returned.

Parameter Descriptions

theSet
The set object.

theType
Given an element type, receives the next element type.

function result: Success or failure of the operation.

Q3Set_GetType

( TQ3ObjectType ) Q3Set_GetType (
    TQ3SetObject theSet
);

Discussion

Get the type of a set object.

Returns kQ3SetTypeAttribute or kQ3ObjectTypeInvalid.

Parameter Descriptions

theSet
The set object.

function result: The subtype of the set.

Q3Set_New

( TQ3SetObject ) Q3Set_New (void);

Discussion

Create a new set, initially empty.

Plain sets are less commonly used than attribute sets.

function result: The new set object, or NULL on failure.

Q3XAttributeClass_Register

( TQ3XObjectClass ) Q3XAttributeClass_Register (
    TQ3AttributeType *attributeType,
    const char *className,
    TQ3Uns32 sizeOfElement,
    TQ3XMetaHandler metaHandler
);

Discussion

Parameter Descriptions

attributeType
Receives the new attribute type.

className
Unique name for the new attribute.

sizeOfElement
Size in bytes of the attribute data.

metaHandler
Your metahandler, providing appropriate methods. It may return NULL in some cases.

function result: Pointer to the new class.

Q3XAttributeSet_GetMask

( TQ3XAttributeMask ) Q3XAttributeSet_GetMask (
    TQ3AttributeSet attributeSet
);

Discussion

Get a mask of the attributes contained in an attribute set.

This function should only be called from renderer plug-ins.

Parameter Descriptions

attributeSet
The attribute set to query.

function result: A mask indicating the attributes present in attributeSet.

Q3XAttributeSet_GetPointer

( void * ) Q3XAttributeSet_GetPointer (
    TQ3AttributeSet attributeSet,
    TQ3AttributeType attributeType
);

Discussion

Get a pointer to the internal data structure for an attribute.

For attributes of type kQ3AttributeTypeXXX, the internal attribute data is currently identical to the data structured passed to Q3AttributeSet_Add.

This function should only be called from renderer plug-ins.

Parameter Descriptions

attributeSet
The attribute set to query.

attributeType
The attribute type to locate.

function result: A pointer to the internal attribute data if present, or NULL.

Q3XElementClass_Register

( TQ3XObjectClass ) Q3XElementClass_Register (
    TQ3ElementType *elementType,
    const char *name,
    TQ3Uns32 sizeOfElement,
    TQ3XMetaHandler metaHandler
);

Discussion

Register a custom element class.

The custom class naming convention is to begin with your company name, then a colon, then a specific class name.

If your element's data contains indirect data, such as pointers to other data or references to Quesa objects, your metahandler should provide methods of the types kQ3XMethodTypeElementCopyAdd, kQ3XMethodTypeElementCopyGet, kQ3XMethodTypeElementCopyDuplicate, kQ3XMethodTypeElementCopyReplace, and kQ3XMethodTypeElementDelete. If you want to be able to write your element to a file and read it back, your metahandler should define methods of the types kQ3XMethodTypeObjectTraverse, kQ3XMethodTypeObjectWrite, and kQ3XMethodTypeObjectReadData.

See QuesaExtension.h for other operations on a custom class, such as Q3XObjectHierarchy_UnregisterClass.

Parameter Descriptions

elementType
Receives the element type assigned by Quesa.

name
The unique name of the new class.

sizeOfElement
Size of the data for the element.

metaHandler
Your metahandler function that returns element methods. You may return NULL for some methods.

function result: Opaque pointer to the new object class.

Q3XElementType_GetElementSize

( TQ3Status ) Q3XElementType_GetElementSize (
    TQ3ElementType elementType,
    TQ3Uns32 *sizeOfElement
);

Discussion

Return the size in bytes of an element type.

In the case of a custom element, this would be the same as the size you provided when you called Q3XElementClass_Register.

Parameter Descriptions

elementType
An element type.

sizeOfElement
Receives the size in bytes of the element.

function result: Success or failure of the operation.