QuesaGroup.h

Discussion

Functions

( TQ3Status ) Q3DisplayGroup_CalcAndUseBoundingBox (
    TQ3GroupObject group,
    TQ3ComputeBounds computeBounds,
    TQ3ViewObject view
);

Discussion

Calculate and use a bounding box on the given group.

This function computes a bounding box that contains all the geometry in the group. It then stores this box on the group, and sets the kQ3DisplayGroupStateMaskUseBoundingBox flag on the group state, telling Quesa that the bounding box should be used for culling.

The computed bounding box will be correct at the time of this call, but if the group contents change, the bounding box is not automatically updated. It is up to the application programmer to call this function again or otherwise update the bounding box when the group changes.

This function must not be called within a submitting loop.

Parameter Descriptions

group

Group for which a bounding box is to be calculated.

computeBounds

Either kQ3ComputeBoundsExact (precise) or kQ3ComputeBoundsApproximate (faster).

view

View in which the group will ultimately be rendered.

function result

Success or failure of the operation.

( TQ3Status ) Q3DisplayGroup_GetBoundingBox (
    TQ3GroupObject group,
    TQ3BoundingBox *bBox
);

Discussion

Get the bounding box of a group.

This function retrieves the bounding box of a group, if one has been set or calculated. If not, kQ3Failure is returned.

Parameter Descriptions

group

Group to inspect.

bBox

Address of bounding box to set with group's bounding box.

function result

Success or failure of the operation.

( TQ3Status ) Q3DisplayGroup_GetState (
    TQ3GroupObject group,
    TQ3DisplayGroupState *state
);

Discussion

Get the state flags of a display group.

The display group state flags affect its behavior with regard to rendering, picking, and computation of a bounding box or sphere.

kQ3DisplayGroupStateNone: no flags are set. kQ3DisplayGroupStateMaskIsDrawn: if set, the group is processed for rendering or picking; if clear, it is skipped. kQ3DisplayGroupStateMaskIsInline: if set, the group is processed without pushing and popping the graphics state. kQ3DisplayGroupStateMaskUseBoundingBox: if set, the bounding box of the group is used during rendering. kQ3DisplayGroupStateMaskUseBoundingSphere: if set, the bounding sphere of the group is used during rendering. kQ3DisplayGroupStateMaskIsPicked: if set, the group is eligible for picking. kQ3DisplayGroupStateMaskIsWritten: if set, the group is eligible for writing to a file.

The default state has the IsDrawn, IsPicked, and IsWritten flags set; other flags are clear.

Parameter Descriptions

group

Group to inspect.

state

Receives the group's state flags.

function result

Success or failure of the operation.

( TQ3ObjectType ) Q3DisplayGroup_GetType (
    TQ3GroupObject group
);

Discussion

Get the specific type of a display group.

The result will be kQ3DisplayGroupTypeOrdered for an ordered display group, kQ3DisplayGroupTypeIOProxy for an I/O Proxy group, and kQ3GroupTypeDisplay for a generic display group. kQ3ObjectTypeInvalid is returned if there is some error.

Parameter Descriptions

group

The group to query.

function result

The type of the group.

( TQ3GroupObject ) Q3DisplayGroup_New (void);

Discussion

Create a new display group.

A display group contains objects that are drawable: geometry, styles, transforms, attributes and attribute sets, and other display groups. A display group can be rendered by calling Q3DisplayGroup_Submit within the rendering loop.

This function returns a newly created, empty display group object. If some error occurs during creation, this returns NULL.

See also Q3OrderedDisplayGroup_New and Q3IOProxyDisplayGroup_New.

function result

Newly created group, or NULL.

( TQ3Status ) Q3DisplayGroup_RemoveBoundingBox (
    TQ3GroupObject group
);

Discussion

Remove the bounding box from a group.

If the given group had an assigned or calculated bounding box, this function removes it and clears the kQ3DisplayGroupStateMaskUseBoundingBox flag. If not, it does nothing (and returns kQ3Success anyway).

Parameter Descriptions

group

Group to remove the bounding box of.

function result

Success or failure of the operation.

( TQ3Status ) Q3DisplayGroup_SetAndUseBoundingBox (
    TQ3GroupObject group,
    const TQ3BoundingBox *bBox
);

Discussion

Sets a bounding box for a display group.

This function assigns the given bounding box to the display group. It also sets the kQ3DisplayGroupStateMaskUseBoundingBox flag on the group state, telling Quesa that the bounding box should be used for culling.

Parameter Descriptions

group

Group on which to set a bounding box.

bBox

Bounding box to use (must be non-empty).

function result

Success or failure of the operation.

( TQ3Status ) Q3DisplayGroup_SetState (
    TQ3GroupObject group,
    TQ3DisplayGroupState state
);

Discussion

Set the state flags of a display group.

The display group state flags affect its behavior with regard to rendering, picking, and computation of a bounding box or sphere.

kQ3DisplayGroupStateNone: no flags are set. kQ3DisplayGroupStateMaskIsDrawn: if set, the group is processed for rendering or picking; if clear, it is skipped. kQ3DisplayGroupStateMaskIsInline: if set, the group is processed without pushing and popping the graphics state. kQ3DisplayGroupStateMaskUseBoundingBox: if set, the bounding box of the group is used during rendering. kQ3DisplayGroupStateMaskUseBoundingSphere: if set, the bounding sphere of the group is used during rendering. kQ3DisplayGroupStateMaskIsPicked: if set, the group is eligible for picking. kQ3DisplayGroupStateMaskIsWritten: if set, the group is eligible for writing to a file.

The default state has the IsDrawn, IsPicked, and IsWritten flags set; other flags are clear.

Parameter Descriptions

group

Group on which to adjust state flags.

state

Desired state flags.

function result

Success or failure of the operation.

( TQ3Status ) Q3DisplayGroup_Submit (
    TQ3GroupObject group,
    TQ3ViewObject view
);

Discussion

Submit a display group.

This group is used within an appropriate submitting loop on a view to render, pick, bound, or write the contents of the group.

Note: QD3D would also let you get away with submitting a group for rendering by calling Q3Geometry_Submit. But this is not valid; a group (even a display group) is not a type of geometry. Quesa is less lenient in this regard, so you should collect your drawable objects in a display group, and submit them with this function.

Parameter Descriptions

group

Display group to submit.

view

View (which must be in a submitting loop).

function result

Success or failure of the operation.

( TQ3GroupPosition ) Q3Group_AddObject (
    TQ3GroupObject group,
    TQ3Object object
);

Discussion

Append an object to a group.

If the group is unordered (which really means unsorted), the object is appended to the end of the group. If it is ordered (i.e. sorted), it is appended to the end of the subset of objects in the group of the same type as the given object.

The group increments the object's reference count, so you can safely dispose of your own reference if you no longer need it.

If for some reason the object cannot be appended, this function returns NULL.

Parameter Descriptions

group

Group to add an object to.

object

Object to be added.

function result

Resulting position of object in group.

( TQ3GroupPosition ) Q3Group_AddObjectAfter (
    TQ3GroupObject group,
    TQ3GroupPosition position,
    TQ3Object object
);

Discussion

Insert an object into a group after a specified position.

This function adds an object to a group, just after the object at the specified position.

The group increments the object's reference count, so you can safely dispose of your own reference if you no longer need it.

If for some reason the object cannot be appended, this function returns NULL.

Parameter Descriptions

group

Group to add an object to.

position

Position after which to add the object.

object

Object to be added.

function result

Resulting position of object in group.

( TQ3GroupPosition ) Q3Group_AddObjectAndDispose (
    TQ3GroupObject theGroup,
    TQ3Object *theObject
);

Discussion

Add an object to a group, and then dispose of it.

If theObject is not NULL, invokes Q3Group_AddObject to add the object to the group, disposes of the object, then clears the supplied pointer to prevent stale references.

Equivalent to:

if (theObject != NULL) { Q3Group_AddObject(theGroup, theObject); Q3Object_Dispose(theObject); theObject = NULL; }

This function is not available in QD3D.

Parameter Descriptions

theGroup

The group to add the object to.

theObject

The object to add (may be NULL).

function result

Success or failure of the operation.

( TQ3GroupPosition ) Q3Group_AddObjectBefore (
    TQ3GroupObject group,
    TQ3GroupPosition position,
    TQ3Object object
);

Discussion

Insert an object into a group before a specified position.

This function adds an object to a group, before the object at the specified position.

The group increments the object's reference count, so you can safely dispose of your own reference if you no longer need it.

If for some reason the object cannot be appended, this function returns NULL.

Parameter Descriptions

group

Group to add an object to.

position

Position before which to add the object.

object

Object to be added.

function result

Resulting position of object in group.

( TQ3Status ) Q3Group_CountObjects (
    TQ3GroupObject group,
    TQ3Uns32 *nObjects
);

Discussion

Determine how many objects are in a group.

Note that subgroups (groups within the given group) count as only one object each; this function does not recurse into them to get the total number of objects in the hierarchy.

Parameter Descriptions

group

Group to inspect.

nObjects

Address of integer to receive the object count.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_CountObjectsOfType (
    TQ3GroupObject group,
    TQ3ObjectType isType,
    TQ3Uns32 *nObjects
);

Discussion

Determine how many objects of a certain type are in a group.

Note that subgroups (groups within the given group) count as only one object each; this function does not recurse into them to consider the entire hierarchy.

Parameter Descriptions

group

Group to inspect.

isType

Object type.

nObjects

Address of integer to receive the object count.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_EmptyObjects (
    TQ3GroupObject group
);

Discussion

Remove all object references from the group.

Call this function to dispose of all object references in the given group. (The group itself is not disposed of.)

Parameter Descriptions

group

Group to empty.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_EmptyObjectsOfType (
    TQ3GroupObject group,
    TQ3ObjectType isType
);

Discussion

Remove all objects of a particular type from a group.

Call this function to dispose of all object references of a certain type in the given group. (The group itself is not disposed of, even if this call leaves it empty.)

Parameter Descriptions

group

Group to operate on.

isType

Type of objects to dispose.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetFirstObjectPosition (
    TQ3GroupObject group,
    TQ3Object object,
    TQ3GroupPosition *position
);

Discussion

Get the first position of an object within a group.

An object may be referenced a group multiple times. Use this function to find the first position of the first reference to the given object. You could then use Q3Group_GetNextObjectPosition to iterate over all other references to the same object.

Parameter Descriptions

group

Group to inspect.

object

Desired object.

position

Receives first position of object in group.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetFirstPosition (
    TQ3GroupObject group,
    TQ3GroupPosition *position
);

Discussion

Get the first position in a group.

This can be used in conjunction with Q3Group_GetNextPosition to iterate over all members of a group.

Parameter Descriptions

group

Group of interest.

position

Receives the position of the first object in group.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetFirstPositionOfType (
    TQ3GroupObject group,
    TQ3ObjectType isType,
    TQ3GroupPosition *position
);

Discussion

Get the position of the first object of a given type.

This can be used in conjunction with Q3Group_GetNextPositionOfType to iterate over all group members of a certain type.

Parameter Descriptions

group

Group of interest.

isType

Desired object type.

position

Receives the position of the first object of that type.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetLastObjectPosition (
    TQ3GroupObject group,
    TQ3Object object,
    TQ3GroupPosition *position
);

Discussion

Get the last position of an object within a group.

An object may be referenced a group multiple times. Use this function to find the last position of the first reference to the given object. You could then use Q3Group_GetPreviousObjectPosition to iterate backwards over all other references to the same object.

Parameter Descriptions

group

Group to inspect.

object

Desired object.

position

Receives last position of object in group.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetLastPosition (
    TQ3GroupObject group,
    TQ3GroupPosition *position
);

Discussion

Get the last position in a group.

This can be used in conjunction with Q3Group_GetPreviousPosition to iterate backwards over all members of a group.

Parameter Descriptions

group

Group of interest.

position

Receives the position of the last object in group.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetLastPositionOfType (
    TQ3GroupObject group,
    TQ3ObjectType isType,
    TQ3GroupPosition *position
);

Discussion

Get the position of the last object of a given type.

This can be used in conjunction with Q3Group_GetPreviousPositionOfType to iterate backwards over all group members of a certain type.

Parameter Descriptions

group

Group of interest.

isType

Desired object type.

position

Receives the position of the last object of that type.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetNextObjectPosition (
    TQ3GroupObject group,
    TQ3Object object,
    TQ3GroupPosition *position
);

Discussion

Advance to the position of the next reference to a given object within a group. If the given object does not occur again within the group, *position is set to NULL.

Use this in conjunction with Q3Group_GetFirstObjectPosition to iterate over all occurrences of an object within a group.

Parameter Descriptions

group

Group to inspect.

object

Desired object.

position

Position to advance to the next occurrence of object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetNextPosition (
    TQ3GroupObject group,
    TQ3GroupPosition *position
);

Discussion

Advance to the next position in a group.

This function updates position to refer to the next position in the group. If there are no further objects in the group, *position is set to NULL.

Parameter Descriptions

group

Group of interest.

position

Address of position to advance.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetNextPositionOfType (
    TQ3GroupObject group,
    TQ3ObjectType isType,
    TQ3GroupPosition *position
);

Discussion

Advance to the position of the next object of a certain type.

This function updates position to refer to the next position in the group of an object of the given type. If there are no further objects of that type in the group, *position is set to NULL.

Parameter Descriptions

group

Group of interest.

isType

Desired object type.

position

Address of position to advance.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetPositionObject (
    TQ3GroupObject group,
    TQ3GroupPosition position,
    TQ3Object *object
);

Discussion

Get the object located at a certain position in a group.

This function obtains a reference to the group member at a specified position. Note that the reference count of the object is incremented, so you must dispose of this reference when you no longer need it.

Sets *object to NULL if there is no object at the given position.

Parameter Descriptions

group

Group to inspect.

position

Position of desired object.

object

Receives a reference to the indicated object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetPreviousObjectPosition (
    TQ3GroupObject group,
    TQ3Object object,
    TQ3GroupPosition *position
);

Discussion

Step back to the position of the previous reference to a given object within a group. If there is no previous reference to that object within the group, *position is set to NULL.

Use this in conjunction with Q3Group_GetLastObjectPosition to iterate in reverse over all occurrences of an object within a group.

Parameter Descriptions

group

Group to inspect.

object

Desired object.

position

Position to step back to the previous occurrence of object.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetPreviousPosition (
    TQ3GroupObject group,
    TQ3GroupPosition *position
);

Discussion

Step back to the previous position in a group.

This function updates position to refer to the previous position in the group. If the given position was already on the first object in the group, *position is set to NULL.

Parameter Descriptions

group

Group of interest.

position

Address of position to step back.

function result

Success or failure of the operation.

( TQ3Status ) Q3Group_GetPreviousPositionOfType (
    TQ3GroupObject group,
    TQ3ObjectType isType,
    TQ3GroupPosition *position
);

Discussion

Step back to the position of the previous object of a certain type.

This function updates position to refer to the previous position in the group of an object of the given type. If there are no previous objects of that type in the group, *position is set to NULL.

Parameter Descriptions

group

Group of interest.

isType

Desired object type.

position

Address of position to step back.

function result

Success or failure of the operation.

( TQ3ObjectType ) Q3Group_GetType (
    TQ3GroupObject group
);

Discussion

Return the type of a group.

This function returns the group type, as an enum such as kQ3GroupTypeDisplay, kQ3GroupTypeInfo, or kQ3GroupTypeLight. (Returns kQ3ObjectTypeInvalid if the type cannot be determined.)

Parameter Descriptions

group

Group to inspect.

function result

Type of that group.

( TQ3GroupObject ) Q3Group_New (void);

Discussion

Create a new generic group.

This function returns a newly created, empty Group object. If some error occurs during creation, this returns NULL.

function result

Newly created group, or NULL.

( TQ3Object ) Q3Group_RemovePosition (
    TQ3GroupObject group,
    TQ3GroupPosition position
);

Discussion

Remove an object from a group.

This function deletes an object reference from a group, returning it to the caller. Note that if you don't need the object, you must dispose of the returned reference; otherwise it will leak.

After this function successfully completes, position is invalid.

Parameter Descriptions

group

Group to remove an object from.

position

Position of object to remove.

function result

Object that was removed.

( TQ3Status ) Q3Group_SetPositionObject (
    TQ3GroupObject group,
    TQ3GroupPosition position,
    TQ3Object object
);

Discussion

Sets the object at a specified position in a group.

This function replaces a member of a group. The reference to the object previously at the specified position is disposed of, and a reference to the given object is stored in its place.

The group increments the object's reference count, so you can safely dispose of your own reference if you no longer need it.

If for some reason the object cannot be appended, this function returns NULL.

Parameter Descriptions

group

Group to replace an object in.

position

Position of object to replace.

object

Object to be stored.

function result

Success or failure of the operation.

( TQ3GroupObject ) Q3IOProxyDisplayGroup_New (void);

Discussion

Create a new generic group.

An I/O proxy display group is a group that contains several alternate representations of the same object, used for file input and output. For example, if your object contains some advanced type of geometry which some clients may not be able to support, you could use a proxy display group to also provide simpler representations of the model. You should put the alternate representations into the group in order of preference; client applications will use the first entry in the group which they can understand.

This function returns a newly created, empty Group object. If some error occurs during creation, this returns NULL.

function result

Newly created proxy display group, or NULL.

( TQ3GroupObject ) Q3InfoGroup_New (void);

Discussion

Create a new information group.

This function returns a newly created, empty information group object. If some error occurs during creation, this returns NULL.

function result

Newly created information group, or NULL.

( TQ3GroupObject ) Q3LightGroup_New (void);

Discussion

Create a new light group.

A light group is a group that contains only lights. These can then be attached to a view by Q3View_SetLightGroup.

This function returns a newly created, empty light group object. If some error occurs during creation, this returns NULL.

function result

Newly created light group, or NULL.

( TQ3GroupObject ) Q3OrderedDisplayGroup_New (void);

Discussion

Create a new ordered display group.

An ordered display group contains drawable objects (geometry, transforms, attributes, etc.), and keeps them always sorted by type. They are kept (and rendered) in this order:

1. transforms 2. styles 3. attribute sets 4. shaders 5. geometric objects 6. groups 7. unknown objects

This ordering ensures that transforms, styles, attributes, and shaders are applied to all of the geometric objects, groups, and unknown objects in the group.

This function returns a newly created, empty ordered display group. If some error occurs during creation, this returns NULL.

function result

Newly created ordered display group, or NULL.

( void * ) Q3XGroup_GetPositionPrivate (
    TQ3GroupObject group,
    TQ3GroupPosition position
);

Discussion

Get the private data stored in a group at the given position.

This function returns private data, in the form of an untyped pointer, which is stored in a group at the given position.

Parameter Descriptions

group

Group to inspect.

position

Position of desired data.

function result

Pointer to private data, or NULL.

Enumerations

typedef enum {
    kQ3DisplayGroupStateNone                    = 0,
    kQ3DisplayGroupStateMaskIsDrawn             = (1 << 0),
    kQ3DisplayGroupStateMaskIsInline            = (1 << 1),
    kQ3DisplayGroupStateMaskUseBoundingBox      = (1 << 2),
    kQ3DisplayGroupStateMaskUseBoundingSphere   = (1 << 3),
    kQ3DisplayGroupStateMaskIsPicked            = (1 << 4),
    kQ3DisplayGroupStateMaskIsWritten           = (1 << 5),
    
    kQ3DisplayGroupStateMaskIsNotForBounding  = (1 << 6),
#endif // QUESA_ALLOW_QD3D_EXTENSIONS

    kQ3DisplayGroupStateMaskSize32              = 0xFFFFFFFF
} TQ3DisplayGroupStateMasks;

Discussion

Group traversal state.

A group's traversal state is set with Q3DisplayGroup_SetState, and controls how the group is processed when submitted for rendering, picking, bounding, or writing.

Constants

kQ3DisplayGroupStateNone

No value.

kQ3DisplayGroupStateMaskIsDrawn

The group will be submitted during rendering or picking.

kQ3DisplayGroupStateMaskIsInline

The group will be submited without pushing/popping the view state stack around the group contents.

kQ3DisplayGroupStateMaskUseBoundingBox

The bounding box is used for culling when rendering.

kQ3DisplayGroupStateMaskUseBoundingSphere

The bounding sphere is used for culling when rendering.

kQ3DisplayGroupStateMaskIsPicked

The group will be eligible for returning during picking.

kQ3DisplayGroupStateMaskIsWritten

The group will be submitted during writing.

kQ3DisplayGroupStateMaskIsNotForBounding

The group will not be submitted during bounding. (Not in QD3D.)

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