QuesaSet.h

Discussion

Functions

( 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.

( 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.

( 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.

( 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.

( 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.

( 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.

( 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.

( TQ3AttributeSet ) Q3AttributeSet_New (void);

Discussion

Create an attribute set object.

function result

A new empty attribute set, or NULL on failure.

( 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.

( 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.

( 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.

( 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.

( 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.

( 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.

( 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.

( 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.

( 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 );
}

Parameter Descriptions

theSet

The set object.

theType

Given an element type, receives the next element type.

function result

Success or failure of the operation.

( 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.

( 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.

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

Discussion

Register a custom attribute class.

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.

( 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.

( 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.

( 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.

( 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.

Typedefs

typedef TQ3ElementType                          TQ3AttributeType;

Discussion

This is a 32-bit value identifying a particular attribute.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XAttributeCopyInheritMethod) (
    const void *fromInternalAttribute,
    void *toInternalAttribute
);

Discussion

If your custom attribute supports inheritance, this method is called to copy attribute data from a parent set to a child set.

Parameter Descriptions

fromInternalAttribute

Attribute data to copy, in internal form.

toInternalAttribute

Destination of the copy, in internal form.

function result

Success or failure of the method.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XAttributeDefaultMethod) (
    void *internalAttribute
);

Discussion

This method does not appear to be mentioned in the QuickDraw 3D documentation, and is not currently used in Quesa.

typedef TQ3Boolean                          TQ3XAttributeInheritMethod;

Discussion

This is not literally a method. Your metahandler returns kQ3True or kQ3False to report whether a custom attribute supports inheritance.

typedef Q3_CALLBACK_API_C (TQ3Boolean, TQ3XAttributeIsDefaultMethod) (
    void *internalAttribute
);

Discussion

This method does not appear to be mentioned in the QuickDraw 3D documentation, and is not currently used in Quesa.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XElementCopyAddMethod) (
    const void *fromAPIElement,
    void *toInternalElement
);

Discussion

This method is called to add a new element to a set, as by Q3Set_Add or Q3Shape_AddElement. On entry, toInternalElement points to an uninitialized block of sizeOfElement bytes, where sizeOfElement is the size you provided when registering the class.

Parameter Descriptions

fromAPIElement

Data to be copied, in its external form.

toInternalElement

Destination of the copy, in internal form.

function result

Success or failure of the method.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XElementCopyDuplicateMethod) (
    const void *fromInternalElement,
    void *toInternalElement
);

Discussion

This method is called when Q3Object_Duplicate is used on a set or attribute set.

Parameter Descriptions

fromInternalElement

Data to be copied, in its internal form.

toInternalElement

Destination of the copy, in internal form.

function result

Success or failure of the method.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XElementCopyGetMethod) (
    const void *fromInternalElement,
    void *toAPIElement
);

Discussion

This method is called to copy element data out of a set, as by Q3Set_Get or Q3Shape_GetElement. If you do not provide this method, the default action is a memory copy of sizeOfElement bytes.

Parameter Descriptions

fromInternalElement

Data to be copied, in its internal form.

toAPIElement

Destination of the copy, in external form.

function result

Success or failure of the method.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XElementCopyReplaceMethod) (
    const void *fromAPIElement,
    void *toInternalElement
);

Discussion

This method is called to replace an existing element in a set, as by Q3Set_Add or Q3Shape_AddElement. On entry, toInternalElement points to existing element data, which you may need to dispose before replacing by new data.

Parameter Descriptions

fromAPIElement

Data to be copied, in its external form.

toInternalElement

Destination of the copy, in internal form.

function result

Success or failure of the method.

typedef Q3_CALLBACK_API_C (TQ3Status, TQ3XElementDeleteMethod) (
    void *internalElement
);

Discussion

This method is called to delete element data from a set or attribute set.

Parameter Descriptions

internalElement

Data to be deleted, in its internal form.

function result

Success or failure of the method.

Enumerations

enum {
    kQ3XMethodTypeAttributeInherit              = Q3_METHOD_TYPE('i', 'n', 'h', 't'),
    kQ3XMethodTypeAttributeCopyInherit          = Q3_METHOD_TYPE('a', 'c', 'p', 'i'),
    kQ3XMethodTypeAttributeDefault              = Q3_METHOD_TYPE('a', 's', 'd', 'f'),
    kQ3XMethodTypeAttributeIsDefault            = Q3_METHOD_TYPE('a', 'i', 'd', 'f')
};

Discussion

These are method types that apply particularly to custom attributes. Note that a custom element may also need to provide more general custom element or custom class methods, such as kQ3XMethodTypeObjectTraverse.

Constants

kQ3XMethodTypeAttributeInherit

See TQ3XAttributeInheritMethod.

kQ3XMethodTypeAttributeCopyInherit

See TQ3XAttributeCopyInheritMethod.

kQ3XMethodTypeAttributeDefault

See TQ3XAttributeDefaultMethod.

kQ3XMethodTypeAttributeIsDefault

See TQ3XAttributeIsDefaultMethod.

enum {
    kQ3XMethodTypeElementCopyAdd                = Q3_METHOD_TYPE('e', 'c', 'p', 'a'),
    kQ3XMethodTypeElementCopyReplace            = Q3_METHOD_TYPE('e', 'c', 'p', 'r'),
    kQ3XMethodTypeElementCopyGet                = Q3_METHOD_TYPE('e', 'c', 'p', 'g'),
    kQ3XMethodTypeElementCopyDuplicate          = Q3_METHOD_TYPE('e', 'c', 'p', 'd'),
    kQ3XMethodTypeElementDelete                 = Q3_METHOD_TYPE('e', 'd', 'e', 'l')
};

Discussion

These are method types that apply particularly to custom elements. Note that a custom element may also need to provide more general custom class methods, such as kQ3XMethodTypeObjectTraverse.

Constants

kQ3XMethodTypeElementCopyAdd

See TQ3XElementCopyAddMethod.

kQ3XMethodTypeElementCopyReplace

See TQ3XElementCopyReplaceMethod.

kQ3XMethodTypeElementCopyGet

See TQ3XElementCopyGetMethod.

kQ3XMethodTypeElementCopyDuplicate

See TQ3XElementCopyDuplicateMethod.

kQ3XMethodTypeElementDelete

See TQ3XElementDeleteMethod.

typedef enum TQ3AttributeTypes {
    kQ3AttributeTypeNone                        = 0,            // N/A
    kQ3AttributeTypeSurfaceUV                   = 1,            // TQ3Param2D
    kQ3AttributeTypeShadingUV                   = 2,            // TQ3Param2D
    kQ3AttributeTypeNormal                      = 3,            // TQ3Vector3D
    kQ3AttributeTypeAmbientCoefficient          = 4,            // float
    kQ3AttributeTypeDiffuseColor                = 5,            // TQ3ColorRGB
    kQ3AttributeTypeSpecularColor               = 6,            // TQ3ColorRGB
    kQ3AttributeTypeSpecularControl             = 7,            // float
    kQ3AttributeTypeTransparencyColor           = 8,            // TQ3ColorRGB
    kQ3AttributeTypeSurfaceTangent              = 9,            // TQ3Tangent2D
    kQ3AttributeTypeHighlightState              = 10,           // TQ3Switch
    kQ3AttributeTypeSurfaceShader               = 11,           // TQ3SurfaceShaderObject
    kQ3AttributeTypeEmissiveColor               = 12,           // TQ3ColorRGB
    kQ3AttributeTypeNumTypes                    = 13,           // N/A
    kQ3AttributeTypeSize32                      = 0xFFFFFFFF
} TQ3AttributeTypes;

Discussion

Type numbers for standard attributes. See QuesaView.h for default values of some of these attributes. For instance you will find that if you do not specify any attributes, an object will be white, opaque, and somewhat shiny.

Constants

kQ3AttributeTypeNone

No type. See Q3AttributeSet_GetNextAttributeType.

kQ3AttributeTypeSurfaceUV

Surface UV coordinates (TQ3Param2D) for texture mapping.

kQ3AttributeTypeShadingUV

Shading UV coordinates (TQ3Param2D) (originally intended for procedural shaders, but effectively interchangable with surface UV).

kQ3AttributeTypeNormal

Normal vector (TQ3Vector3D)

kQ3AttributeTypeAmbientCoefficient

Ambient coefficient (float)

kQ3AttributeTypeDiffuseColor

Diffuse color (TQ3ColorRGB)

kQ3AttributeTypeSpecularColor

Specular color (TQ3ColorRGB)

kQ3AttributeTypeSpecularControl

Specular control (float). Larger values make smaller specular highlights.

kQ3AttributeTypeTransparencyColor

Transparency color (TQ3ColorRGB). { 0, 0, 0 } is completely transparent, and { 1, 1, 1 } is completely opaque.

kQ3AttributeTypeSurfaceTangent

Surface tangent (TQ3Tangent2D)

kQ3AttributeTypeHighlightState

Highlight state (TQ3Switch)

kQ3AttributeTypeSurfaceShader

Surface shader (TQ3SurfaceShaderObject)

kQ3AttributeTypeEmissiveColor

Emissive color (TQ3ColorRGB) (This attribute did not exist in QuickDraw 3D, and may not be recognized by all renderers.)

kQ3AttributeTypeNumTypes

Number of standard attribute types.

enum {
    kQ3XAttributeMaskNone                       = 0,
    kQ3XAttributeMaskSurfaceUV                  = (1 << (kQ3AttributeTypeSurfaceUV          - 1)),
    kQ3XAttributeMaskShadingUV                  = (1 << (kQ3AttributeTypeShadingUV          - 1)),
    kQ3XAttributeMaskNormal                     = (1 << (kQ3AttributeTypeNormal             - 1)),
    kQ3XAttributeMaskAmbientCoefficient         = (1 << (kQ3AttributeTypeAmbientCoefficient - 1)),
    kQ3XAttributeMaskDiffuseColor               = (1 << (kQ3AttributeTypeDiffuseColor       - 1)),
    kQ3XAttributeMaskSpecularColor              = (1 << (kQ3AttributeTypeSpecularColor      - 1)),
    kQ3XAttributeMaskSpecularControl            = (1 << (kQ3AttributeTypeSpecularControl    - 1)),
    kQ3XAttributeMaskTransparencyColor          = (1 << (kQ3AttributeTypeTransparencyColor  - 1)),
    kQ3XAttributeMaskSurfaceTangent             = (1 << (kQ3AttributeTypeSurfaceTangent     - 1)),
    kQ3XAttributeMaskHighlightState             = (1 << (kQ3AttributeTypeHighlightState     - 1)),
    kQ3XAttributeMaskSurfaceShader              = (1 << (kQ3AttributeTypeSurfaceShader      - 1)),
    kQ3XAttributeMaskEmissiveColor              = (1 << (kQ3AttributeTypeEmissiveColor      - 1)),
    kQ3XAttributeMaskCustomAttribute            = 0x80000000,
    kQ3XAttributeMaskAll                        = 0x80000FFF,
    kQ3XAttributeMaskInherited                  = 0x000003FF,
    kQ3XAttributeMaskInterpolated               = kQ3XAttributeMaskSurfaceUV          |
                                                  kQ3XAttributeMaskShadingUV          |
                                                  kQ3XAttributeMaskNormal             |
                                                  kQ3XAttributeMaskAmbientCoefficient |
                                                  kQ3XAttributeMaskDiffuseColor       |
                                                  kQ3XAttributeMaskSpecularControl    |
                                                  kQ3XAttributeMaskTransparencyColor  |
                                                  kQ3XAttributeMaskEmissiveColor      |
                                                  kQ3XAttributeMaskSurfaceTangent,
    kQ3XAttributeMaskSize32                     = 0xFFFFFFFF
};

Discussion

Attribute mask flags.

Constants

kQ3XAttributeMaskNone

No attributes.

kQ3XAttributeMaskSurfaceUV

Surface UV attribute mask.

kQ3XAttributeMaskShadingUV

Shading UV attribute mask.

kQ3XAttributeMaskNormal

Normal attribute mask.

kQ3XAttributeMaskAmbientCoefficient

Ambient coefficent attribute mask.

kQ3XAttributeMaskDiffuseColor

Diffuse color attribute mask.

kQ3XAttributeMaskSpecularColor

Specular color attribute mask.

kQ3XAttributeMaskSpecularControl

Specular control attribute mask.

kQ3XAttributeMaskTransparencyColor

Transparency color attribute mask.

kQ3XAttributeMaskSurfaceTangent

Surface tangent attribute mask.

kQ3XAttributeMaskHighlightState

Highlight state attribute mask.

kQ3XAttributeMaskSurfaceShader

Surface shader attribute mask.

kQ3XAttributeMaskEmissiveColor

Emissive color attribute mask.

kQ3XAttributeMaskCustomAttribute

Custom attribute mask.

kQ3XAttributeMaskAll

All attributes.

kQ3XAttributeMaskInherited

Inherited attributes mask.

kQ3XAttributeMaskInterpolated

Interpolated attributes mask.

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