AlDagNode

Synopsis

#include <AlDagNode.h>

class AlDagNode : public AlObject , public AlClusterable , public AlAnimatable , public AlSettable , public AlPickable

virtual	~AlDagNode();

virtual statusCode	deleteObject();

virtual AlObject*	copyWrapper() const;

AlDagNode*	copyObject( AlCopyOptions* = NULL );

AlDagNode*	copyObject( AlCopyOptions*, int, int * );

virtual AlObjectType	type() const;

virtual const char*	name() const;

virtual statusCode	setName( const char* );

AlGroupNode*	parentNode() const;

AlDagNode*	nextNode() const;

AlDagNode*	prevNode() const;

virtual boolean	isInstanceable();

statusCode	addSiblingNode( AlDagNode* );

statusCode	comment( long&, const char*& );

statusCode	setComment( long, const char* );

statusCode	removeComment( void );

statusCode	blindData( int, long&, const char*& );

statusCode	setBlindData( int, long, const char* );

statusCode	removeBlindData( int );

statusCode	persistentID( AlPersistentID *&, int );

statusCode	hasPersistentID( int );

statusCode	localTransformationMatrix( double[4][4] ) const;

statusCode	globalTransformationMatrix( double[4][4] ) const;

statusCode	inverseGlobalTransformationMatrix( double[4][4] ) const;

statusCode	affectedTransformationMatrix( const AlTM&, double[4][4] ) const;

statusCode	localTransformationMatrix( AlTM& ) const;

statusCode	globalTransformationMatrix( AlTM& ) const;

statusCode	inverseGlobalTransformationMatrix( AlTM& ) const;

statusCode	affectedTransformationMatrix( const AlTM&, AlTM& ) const;

statusCode	translation( double&, double&, double& ) const;

statusCode	rotation( double&, double&, double& ) const;

statusCode	scale( double&, double&, double& ) const;

statusCode	rotatePivot( double&, double&, double& ) const;

statusCode	scalePivot( double&, double&, double& ) const;

statusCode	rotatePivotIn( double &x, double &y, double &z ) const;

statusCode	rotatePivotOut( double &x, double &y, double &z ) const;

statusCode	scalePivotIn( double &x, double &y, double &z ) const;

statusCode	scalePivotOut( double &x, double &y, double &z ) const;

statusCode	setTranslation( double, double, double );

statusCode	setWorldTranslation( double, double, double );

statusCode	setRotation( double, double, double );

statusCode	setScale( double, double, double );

statusCode	setRotatePivot( double, double, double );

statusCode	setScalePivot( double, double, double );

statusCode	localRotationAxes( double[3], double[3], double[3] ) const;

statusCode	setLocalRotationAxes(double[3], double[3], double[3]);

statusCode	localRotationAngles( double&, double&, double& ) const;

statusCode	setLocalRotationAngles( double, double, double );

statusCode	localRotateBy(double , double ,double );

statusCode	localTranslateBy(double , double ,double );

statusCode	boundingBox( double[8][4] ) const;

boolean	isDisplayModeSet( AlDisplayModeType ) const;

statusCode	setDisplayMode( AlDisplayModeType, boolean );

AlJoint*	joint() const;

statusCode	addJoint();

statusCode	removeJoint();

AlDagNode*	searchBelow( const char * ) const;

AlDagNode*	searchAcross( const char * ) const;

statusCode	updateDrawInfo( void ) const;

statusCode	sendGeometryModifiedMessage();

statusCode	doUpdates( boolean newState = TRUE );

AlConstraint*	firstConstraint( void ) const;

AlLayer*	layer() const;

statusCode	setLayer( const AlLayer * );

boolean	isAConstructionPlane();

AlList*	clusterPreTransformationMatrices() const;

statusCode	createSymmetricGeometry();

statusCode createSymmetricGeometry( AlDagNode *& );

unsigned int version( void ) const;

class AlCopyOptions

AlCopyOptions();

virtual	~AlCopyOptions();

boolean	instanceCopy() const;

statusCode	setInstanceCopy( boolean );

boolean	copyAnimation() const;

statusCode	setCopyAnimation( boolean );

boolean	copyClusters() const;

statusCode	setCopyClusters( boolean );

int	numCopies() const;

statusCode	setNumCopies( int );

AlParamControlType	parameterControl() const;

statusCode	setParameterControl( AlParamControlType );

AlHierarchyType	hierarchy() const;

statusCode	setHierarchy( AlHierarchyType );

double	timeOffset() const;

statusCode	setTimeOffset( double );

statusCode	translation( double&, double&, double& ) const;

statusCode	setTranslation( double, double, double );

statusCode	rotation( double&, double&, double& ) const;

statusCode	setRotation( double, double, double );

statusCode	scale( double&, double&, double& ) const;

statusCode	setScale( double, double, double );

Description

This class encapsulates the basic functionality for creating, manipulating and deleting a DAG node. A DAG node is part of a tree-like hierarchical structure known as a directed acyclic graph or DAG. All DAG nodes belong to a single DAG which is contained in the current universe. The head of the DAG is accessible by calling the AlUniverse::firstDagNode() static method.

Each DAG node can be mutually attached to a previous and next DAG node to form a list of DAG nodes. This list can belong to a group (or parent) DAG node. This list of DAG nodes that belong to a group node are called "children" of the group node.

A DAG node contains information that defines particular affine transformations such as scale, rotation and translation. There is a specific fixed order in which the transformations are combined. There are methods for accessing each particular transformation and a method exists for obtaining the local transformation matrix built from these transformations. For more information, see the description for the method localTransormationMatrix().

Classes derived from this class will refer to a particular type of object. For example, the AlCameraNode class is derived from AlDagNode and refers to AlCamera objects only. The shape, position and/or orientation of the object referred to is defined by combining the transformations for the DAG node with all the transformations inherited from the DAG nodes above it in the DAG. There is a method for obtaining the global transformation matrix, which is built from the local transformations and all inherited transformations. For example, if DAG node A is a parent of DAG node B which is a parent of DAG node C, then the global transformation of C is the matrix product [C]*[B]*[A], where [C], [B], and [A] are local transformations of each DAG node.

A DAG node can have some user-defined text associated with it and so there are methods for getting and setting the text.

Users cannot instantiate an AlDagNode directly. A derived class of an AlDagNode must be instantiated and then if required the create() method of the class must be called. This will insert the DAG node into the DAG as a parent-less node. A DAG node can be moved so that it is a sibling of any DAG node in the DAG. Deleting a DAG node removes the node from its list of siblings. For derived classes, deletion of a DAG node will cause the deletion of the object that it refers to.

Since an AlDagNode simply contains transformations but does not refer to any transformable object, this class is of little practical use on its own. It is primarily an abstract base class from which other DAG node classes are derived. Note that NULL DAG nodes created in the Alias Interactive package are retrieved by this library as group nodes without children.

What does a transformation matrix mean? This matrix is the product of matrices for scale, rotate and translate. One useful piece of information from this matrix is the POSITION of an object. The first three values in the bottom row of the matrix (indices (3,0), (3,1), and (3,2)) represent the translation of the origin (0,0,0) in the x, y, and z directions. For instance, if you placed a sphere at (20, 30, 16) in the Alias interactive package, then moved it to (-30, 16, 28), you would notice that its global transformation matrix would have (-30, 16, 28) in the bottom row.

Additionally, AlDagNode includes AlCopyOptions as a nested class. This class allows for the querying and setting of options for AlDagNode::copyObject(). When first instantiated, an instance of AlCopyOptions will have its values set according to the values in Edit->Duplicate Object option box. It is not possible to set the values in this option box through this class.

AlDagNode::~AlDagNode()

Description

Deletes an AlDagNode wrapper object.

statusCode AlDagNode::deleteObject()

Description

Destructor for AlDagNode. The entire DAG branch rooted at this node will be deleted. For each delete DAG node its animation will be deleted and the DAG node will be removed from all clusters or sets it is in. Some DAG nodes cannot be deleted (for example, AlTextureNodes), in which case this method will return sFailure.

Return Codes

sSuccess - the DAGnode and all associated objects were deleted

sFailure - the DAG node could not be deleted

sInvalidObject - the DAG node was not valid

AlObject *AlDagNode::copyWrapper() const

Description

Returns an exact duplicate of this AlDagNode wrapper.

AlDagNode *AlDagNode::copyObject( AlCopyOptions* options )

Description

Copies this AlDagNode returning a pointer to the new copy. If "options" is not NULL then the given copy options will be used in making copies, otherwise the options as they exist in the Duplicate object option box will be used. If multiple copies are made, a reference to the last copy will be returned. AlUniverse::redrawScreen() must be called once the copy is complete to see the results.

AlObjectType AlDagNode::type() const

Description

Returns the class identifier ’kDagNodeType’.

const char* AlDagNode::name() const

Description

Returns the name of the object.

statusCode AlDagNode::setName( const char *newName)

Description

Changes the name of the DAG node to a new name. If the given name is not unique, then a unique name is generated based on the given name and assigned to the DAG node. In this case, a status code of sNameChangedToUniqueOne is returned. It is illegal for the new name to be NULL.

Arguments

< newName - new name of the object

Return Codes

sSuccess - name was changed

sInvalidArgument - newName was NULL

sFailure - the request could not be completed

sInvalidObject - the DAG node was invalid

sNameChangedToUniqueOne - name was changed to be a unique version of the given name

AlGroupNode* AlDagNode::parentNode() const

Description

Returns a pointer to the parent AlGroupNode or NULL if there is no parent.

AlDagNode* AlDagNode::nextNode() const

Description

Returns a pointer to the object’s next sibling AlDagNode or NULL if there is no next sibling.

AlDagNode* AlDagNode::prevNode() const

Description

Returns a pointer to the object’s previous sibling AlDagNode or NULL if there is no previous sibling.

statusCode AlDagNode::addSiblingNode( AlDagNode *sibling )

Description

Inserts an AlDagNode as the next sibling of this AlDagNode object. If the AlDagNode is already a sibling of this object, then nothing is done and the AlDagNode is left where it is in the list of siblings. Otherwise, the AlDagNode is removed from the list of siblings it belongs to and added to the list of siblings for this object. If the AlDagNode is an AlGroupNode and it has siblings which are instanced AlGroupNodes, those instanced siblings are also made siblings of this object.

Arguments

< sibling - the AlDagNode to be inserted

Return Codes

sSuccess - the AlDagNode is now a sibling of this object

sInvalidArgument - ’sibling’ was invalid or NULL

sFailure - the AlDagNode could not be made a sibling of this object

sInvalidObject - the DAG node was invalid

boolean AlDagNode::isInstanceable()

Description

Returns TRUE. An AlDagNode is instanceable but derived classes that are not instanceable DAG nodes will redefine this method.

statusCode AlDagNode::comment( long &size, const char* &data )

Description

Obtains the size and address of a block of textual data associated with the object. If there is no textual data, then the size will be zero and the address of the data is NULL.

Note that the comment is NOT a null terminated string.

Arguments

> size - number of characters in the block of text

> data - address of the block of text

Return Codes

sSuccess - normal completion

sInvalidObject - the given object is not valid

statusCode AlDagNode::blindData( int user_type, long &size, const char* &data )

Description

Obtains the size and address of a block of data associated with the object. If there is no data, then the size will be zero and the address of the data is NULL. User_types must be reserved. If you would like to reserve a block of "user_types" please contact us. User_types less than zero indicate that the blind data is not persistent. As such, when the model is stored, blind data with a negative user_type will not be stored.

Arguments

< user_type - user type of the data desired

> size - number of characters in the block of text

> data - address of the block of text

Return Codes

sSuccess - normal completion

sInvalidObject - the given object is not valid

statusCode AlDagNode::persistentID( AlPersistentID *&id, int userType )

Description

Returns a copy of the AlPersistentID associated with this node. If one does not exist one is created. User_types between 0 and 9999 are reserved. If you would like to reserve a block of "user_types" please contact us.

Arguments

> id - a copy of the AlPersistentID

< userType - user type of the persistent ID desired

Return Codes

sSuccess - normal completion

sInvalidObject - the given object is not valid

sFailure - the ID did not exist or could not be created

statusCode AlDagNode::setPersistentID( AlPersistentID &id, int userType )

Description

Sets the values of the AlPersistentID associated with this node. This method only allows you to create persistent IDs with user types other than 1. If the persistent ID does not exist, it will be created.

User types between 0 and 9999 are reserved. If you would like to reserve a block of user types please contact us.

Arguments

< userType - user type of the persistent ID desired

> id - a copy of the AlPersistentID

Return Codes

sSuccess - normal completion

sInvalidObject - the given object is not valid

sInvalidArgument - the given userType is not valid

sFailure - the ID did not exist or could not be created

statusCode AlDagNode::hasPersistentID( int userType )

Description

Checks to see if the DagNode has a persistent ID associated with it.

Arguments

< userType - user type of the persistent ID desired

Return Codes

sSuccess - node has a persistent ID

sFailure - node does not have a persistent ID

sInvalidObject - the given object is not valid

statusCode AlDagNode::setComment( long size, const char* data )

Description

Associates a block of textual data with the object. If a block of text is already associated with the object, the reference to the old block of text is replaced by a reference to the new block of text. The old block of text is not deleted. It is up to the user to manage the deletion of the old block of text.

Arguments

< size - number of characters in the block of text

< data - address of the block of text

Return Codes

sSuccess - operation was successful

sInsufficientMemory - not enough memory sInvalidObject - the given object is not valid

statusCode AlDagNode::setBlindData( int user_type, long size, const char* data )

Description

Associates a block of data with the object. If a block of data is already associated with the object, the reference to the old block of data is replaced by a reference to the new block of data. The old block of data is not deleted. It is up to the user to manage the deletion of the old block of data. The user_type may be user defined to add more than one blind data block to any one object (see blindData() above for additional information).

Arguments

< user_type - desired user type of the blind data

< size - number of characters in the block of text

< data - address of the block of text

Return Codes

sSuccess - the blind data was set

sInsufficientMemory - there is not enough memory

sInvalidObject - the given object is not valid

statusCode AlDagNode::removeComment( void )

Description

Removes the block of text associated with this object from the object itself. Note that the user is still responsible for the memory associated with the block of text.

Return Codes

sSuccess - text was removed

sFailure - there was no comment to remove sInvalidObject - the given object is not valid

statusCode AlDagNode::removeBlindData( int user_type )

Description

Removes the block of data of the given type from the object. Note that the user is still responsible for the memory associated with this block of data.

Arguments

< user_type - user type of the blind desired

Return Codes

sSuccess - data was removed

sFailure - no such blind data existed sInvalidObject - the given object is not valid

statusCode AlDagNode::localTransformationMatrix( AlTM& matrix ) const

Description

Computes the local transformation matrix for the object. This version of the function takes an AlTM matrix instead of a 4x4 matrix of doubles.

Arguments

> matrix - the matrix to contain the local transformation

Return Codes

sSuccess - the transformation was successfully computed

sInvalidArgument - the matrix was NULL

sFailure - the request could not be completed

sInvalidObject - the DAG node was invalid

statusCode AlDagNode::localTransformationMatrix( double matrix[4][4] ) const

Description

Computes the local transformation matrix for the object. The matrix is oriented such that to transform a point, the point must be pre-multiplied by the matrix. The local transformation matrix is defined by seven triples which specify components for scale, rotation, and translation transformations. It is computed by doing the following transformations:

local transform = T1 * T2 * T3 * T4 * T5 * T6 * T7 * T8 * T9

- (T1) translation by x,y,z of scalePivotIn vector

- (T2) scale by x,y,z of scale vector

- (T3) translation by x,y,z of scalePivotOut vector

- (T4) translation by x,y,z of rotatePivotIn vector

- (T5) x-axis rotation by x component of rotation vector

- (T6) y-axis rotation by y component of rotation vector

- (T7) z-axis rotation by z component of rotation vector

- (T8) translation by x,y,z of rotatePivotOut vector

- (T9) translation by x,y,z of translation vector

This order reflects the order in which a point would be transformed by each transformation. When setting and querying the rotate pivot and the scale pivot, you only need to worry about setting the pivot in world space. The methods setRotatePivot() and setScalePivot() will calculate the corresponding In and Out transformations (T1,T3,T4,T8).

Arguments

> matrix - the matrix to contain the local transformation

Return Codes

sSuccess - the transformation was successfully computed

sInvalidArgument - matrix was NULL

sFailure - the request could not be completed

sInvalidObject - the DAG node was invalid

statusCode AlDagNode::globalTransformationMatrix( AlTM& matrix ) const

Description

Computes the global transformation matrix for the object, which is obtained by post multiplying the local transformation matrix with the global transformation matrix of the parent AlGroupNode. This version of the function takes an AlTM matrix instead of a 4x4 matrix of doubles.

Arguments

> matrix - the matrix to contain the global transformation

Return Codes

sSuccess - the global transformation matrix was computed

sInvalidArgument - matrix was NULL

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::globalTransformationMatrix( double matrix[4][4] ) const

Description

Computes the global transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the global transformation matrix of the parent AlGroupNode. For more information, see the AlDagNode class description.

Arguments

> matrix - the matrix to contain the global transformation

Return Codes

sSuccess - the global transformation matrix was computed

sInvalidArgument - matrix was NULL

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::inverseGlobalTransformationMatrix( AlTM& matrix ) const

Description

Computes the inverse of the global transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the global transformation matrix of the parent AlGroupNode. This version of the function takes an AlTM matrix instead of a 4x4 matrix of doubles. You will want to use this method to transform normals. There is a routine in AlTM called AlTM::transNormal, however it may not be numerically stable. Normals are transformed by the equation n’ = n * trans(inv(M)). To transform a normal (nx,ny,nz), the following code fragment can be used:

AlTM invTM;

dagNode->inverseGlobalTransformMatrix( invTM );

invTM.transpose().transVector( nx, ny, nz );

Arguments

> matrix - the matrix to contain the global transformation

Return Codes

sSuccess - the global transformation matrix was computed

sInvalidArgument - matrix was NULL

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::inverseGlobalTransformationMatrix( double matrix[4][4] ) const

Description

Computes the inverse of the global transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the global transformation matrix of the parent AlGroupNode. For more information, see the AlDagNode class description.

Arguments

> matrix - the matrix to contain the global transformation

Return Codes

sSuccess - the global transformation matrix was computed

sInvalidArgument - matrix was NULL

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::affectedTransformationMatrix( const AlTM& tm, AlTM& matrix ) const

Description

Computes the transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the given AlTM ’tm’.

Arguments

< tm - the transformation matrix generated while walking the DAG

> matrix - the matrix to contain the affected transformation

Return Codes

sSuccess - the transformation matrix was computed

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::affectedTransformationMatrix( const AlTM& tm, double matrix[4][4] ) const

Description

Computes the transformation matrix for the object, which is obtained by post-multiplying the local transformation matrix with the given AlTM.

Arguments

< tm - the transformation matrix generated while walking the DAG

> matrix - the matrix to contain the affected transformation

Return Codes

sSuccess - the transformation matrix was computed

sInvalidArgument - matrix was NULL

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::translation( double &x, double &y, double &z ) const

Description

Gets the final local translation vector.

Arguments

> x, y, z - components of the translation vector

Return Codes

sSuccess - the final local translation vector was returned

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::rotation( double &x, double &y, double &z ) const

Description

Gets the amount of rotation (in degrees ) about the x, y, and z axes.

Arguments

> x, y, z - amount of rotation about the x, y, z axis

Return Codes

sSuccess - the rotation was returned

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::scale( double &x, double &y, double &z ) const

Description

Gets the amount of scale in the x, y, and z direction.

Arguments

> x, y, z - components of the scale transformation

Return Codes

sSuccess - the scale amount was returned

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::rotatePivot( double &x, double &y, double &z ) const

Description

Returns the rotate pivot position in world space. The rotate pivot is the point about which rotations take place. For more information, see the description for the method localTransformationMatrix().

Arguments

> x, y, z - components of the translation vector

Return Codes

sSuccess - the rotate pivot was returned

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::scalePivot( double &x, double &y, double &z ) const

Description

Returns the scale pivot position in world space. The scale pivot is the point about which scaling take place. For more information, see the description for the method localTransformationMatrix().

Arguments

> x, y, z - components of the translation vector

Return Codes

sSuccess - the scale pivot was returned

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::doUpdates( boolean newState )

Description

Notifies the system that you are finished performing. If this flag is true, it is equivalent to sending out a ’geometry modified’ message to the rest of the system. When the system receives the update message, operations such as construction history, and so on, are done. This feature is important when using construction history plug-ins. Construction history plug-ins should always set the doUpdate flag to FALSE when doing updates (otherwise an infinite update loop will result, usually ending in a core dump). The update can be explicitly forced using the AlDagNode::sendGeometryModifiedMessage() method. This flag DOES NOT UPDATE THE SCREEN. Use the AlUniverse::redrawScreen to do the screen refresh. If the previous state of the flag was FALSE and the new state is TRUE, an update will be done at this point and on each subsequent DAG modification.

Return Codes

sSuccess - the new state was set

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setTranslation( double x, double y, double z )

Description

Sets the final local translation vector. The translation transformation is done after rotations.

This method takes advantage of the doUpdate mechanism to control whether updates happen immediately or are batched until the end of an operation.

NOTE: If this DAG node is a surface made from construction history, then the construction history will be broken. To find out if this surface is created by construction history, cast this DAG node to a surface. If it is a surface, call the method AlSurface::isConstructionHistoryResultingSurface().

Arguments

< x, y, z - components of the translation vector

Return Codes

sSuccess - the final local translation vector was set

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setWorldTranslation( double x, double y, double z )

Description

Sets the final world translation vector (by appropriately modifying the local translation).

See setTranslation() for notes on construction history.

See setTranslation() for notes on doUpdates().

Arguments

< x, y, z - components of the translation vector

Return Codes

sSuccess - the final local translation vector was set

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::sendGeometryModifiedMessage()

Description

Sends out an update message notifying that the geometry of this dagNode has been modified. This function is intended to be used after a series of geometry changes have been done with the ’doUpdate’ parameter set to FALSE. Note that updates should not be done during construction history plug-ins (an infinite loop will result).

Return Codes

sSuccess - the message was sent

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setRotation( double x, double y, double z )

Description

Sets the amount of rotation (in degrees) about the x, y, and z axes. The rotations will be done after the scale transformation and before the final local translation. See setTranslation for notes on doUpdate.

See setTranslation() for notes on construction history and on doUpdates().

Arguments

< x, y, z - amount of rotation about the x, y, z axis

Return Codes

sSuccess - the amount of rotation was set

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setScale( double x, double y, double z )

Description

Sets the local scale vector. The scale transformation will be done before the local rotations. There is no restriction on the values of the components of the scale vector.

See setTranslation() for notes on construction history and on doUpdates().

Arguments

< x, y, z - components of the scale transformation

Return Codes

sSuccess - the local scale vector was set

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setRotatePivot( double x, double y, double z )

Description

Changes the rotate pivot to the world space position given by x, y, and z. The rotate pivot is the point about which rotations take place.

Arguments

< x, y, z - components of the translation vector

Return Codes

sSuccess - the rotate pivot was set

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setScalePivot( double x, double y, double z)

Description

Changes the scale pivot to the world space position given by x, y, and z. The scale pivot is the point about which scaling take place.

Arguments

< x, y, z - components of the translation vector

Return Codes

sSuccess - the scale pivot was set

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::localRotationAxes( double x[3], double y[3], double z[3] ) const

Description

Returns vectors representing the local rotation axes for this node. These axes are the three axes vectors in world space co-ordinates.

Arguments

> x, y, z - three vectors representing the 3 axes

Return Codes

sSuccess - the local rotation axes were returned

sInvalidArgument - x, y or z was NULL

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setLocalRotationAxes(double x[3], double y[3], double z[3])

Description

Sets the local rotation axes of this DAG node to the given world space vectors. Note that you must ensure that the three vectors x, y and z are orthogonal, otherwise you may get unpredictable results. Also, note that if they are orthogonal, that all three axes are not needed, and in fact this method does not use the z vector.

Arguments

> x, y, z - three vectors representing the 3 axes

Return Codes

sSuccess - the local rotation axes were returned

sInvalidArgument - x, y or z was NULL

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::localRotationAngles( double& x, double& y, double& z ) const

Description

These angles allow you to determine how the local rotation axis have been rotated from their initial position. For example the x value indicates how much the y and z axes have been rotated about the x axis.

Arguments

> x, y, z - rotation angles about the three axes

Return Codes

sSuccess - the local rotation angles were returned

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::setLocalRotationAngles( double x, double y, double z )

Description

Setting the local rotation angles is the only means by which the local rotations axes can be modified. Each angle represents how much the other two axes are rotated about itself from their initial position. For example the value for x will determine how much the y and z axes are rotated about the x axis.

Arguments

> x, y, z - rotation angles about the three axes

Return Codes

sSuccess - the local rotation angles were set

sInvalidObject - this DagNode is invalid

sFailure - the local rotation angle could not be set

statusCode AlDagNode::localRotateBy(double x, double y,double z)

Description

Does a DAG node rotation based on the setting of the local axes. This function is additive or relative. Rotations are applied against previous rotations. The current rotation in world space is returned by AlDagNode::rotation().

Parameters:

> x,y,z - amount to rotate by

Return Codes

sSuccess - the method succeeded

sFailure - the method failed

sInvalidObject - the DAG node was invalid

statusCode AlDagNode::localTranslateBy(double x, double y,double z)

Description

Does a DAG node translation based on the setting of the local axes. This function is additive or relative. Translations are applied against previous translations. The current translation in world space is returned by AlDagNode::translation().

Parameters

> x,y,z - amount to translate by

Return Codes

sSuccess - the method succeeded

sFailure - the method failed

sInvalidObject - the DAG node was invalid

statusCode AlDagNode::boundingBox( double corners[8][4] ) const

Description

Returns the eight corners of the bounding box in world space. These corners are exactly like the bounding boxes drawn in the interactive Alias package. This DAG node must be in bounding box mode before this method is called.

Arguments

> corners - a matrix to hold the eight corners of the bounding box. Each corner has an x, y, z and homogeneous component.

Return Codes

sSuccess - the bounding box was returned

sInvalidArgument - ’corners’ was NULL

sFailure - the display mode was set or the box could not be determined

sInvalidObject - the DAG node was invalid

boolean AlDagNode::isDisplayModeSet( AlDisplayModeType mode ) const

Description

Returns TRUE if the specified display mode is toggled on for the DAG node. Returns FALSE otherwise.

The only valid AlDisplayModeTypes for an AlDagNode are

kDisplayModeBoundingBox
kDisplayModeInvisible
kDisplayModeTemplate
kDisplayModeDashed
kDisplayModeConstructionPlane
kDisplayModeCompressedSbd

Arguments

< mode - display mode of interest

statusCode AlDagNode::setDisplayMode( AlDisplayModeType mode, boolean on_or_off)

Description

For the given display mode, if the flag is TRUE then the display mode for the DAG node is set; otherwise it is unset.

The only valid AlDisplayModeTypes for an AlDagNode are

kDisplayModeBoundingBox
kDisplayModeInvisible
kDisplayModeTemplate
kDisplayModeDashed
kDisplayModeConstructionPlane
kDisplayModeCompressedSbd

Arguments

< mode - display mode of interest

< on_or_off - TRUE means that this DAG node will have the display mode set. FALSE means it will be unset.

Return Codes

sSuccess - operation was successful

sInvalidArgument - invalid display type

sInvalidObject - the DAG node was invalid

sFailure - the display mode could not be set

statusCode AlDagNode::rotatePivotIn( double &x, double &y, double &z ) const

Description

Gets the local pre-rotation translation vector.

Arguments

> x, y, z - components of the translation vector

Return Codes

sSuccess - the local pre-rotation translation vector was returned

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::rotatePivotOut( double &x, double &y, double &z ) const

Description

Gets the local post-rotation translation vector.

Arguments

> x, y, z - components of the translation vector

Return Codes

sSuccess - the local post-rotation translation vector was returned

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::scalePivotIn( double &x, double &y, double &z ) const

Description

Gets the local pre-scale translation vector.

Arguments

> x, y, z - components of the translation vector

Return Codes

sSuccess - the local pre-scale translation vector was returned

sInvalidObject - this DagNode is invalid

statusCode AlDagNode::scalePivotOut( double &x, double &y, double &z ) const

Description

Gets the local post-scale translation vector.

Arguments

> x, y, z - components of the translation vector

Return Codes

sSuccess - the local post-scale translation vector was returned

sInvalidObject - this DagNode is invalid

AlJoint* AlDagNode::joint() const

Description

Gets the IK joint node if one exists.

statusCode AlDagNode::addJoint()

Description

Adds an AlJoint to this DAG node to maintain IK information. Note that an AlDagNode may have only one AlJoint. If the AlDagNode already has an AlJoint when this method is called nothing will be done, and sSuccess will be returned.

Return Codes

sSuccess - the operation succeeded

sInvalidObject - the DAG node was invalid

sFailure - it was not possible to add an AlJoint

statusCode AlDagNode::removeJoint()

Description

Removes the AlJoint to this DAG node to maintain IK information.

Return Codes

sSuccess - the operation succeeded

sInvalidObject - the DAG node was invalid

sFailure - it was not possible to remove the AlJoint

AlDagNode * AlDagNode::searchBelow( const char * name ) const

Description

Searches the DAG tree (rooted at the child of the current node) for a DAG node with a specific name. A pointer to the DAG node is returned if it is found. NULL is returned if no such DAG node exists.

Arguments

name - the name to look for

AlDagNode * AlDagNode::searchAcross( const char * name ) const

Description

Searches across the DAG tree (starting at the current node), for a DAG node with a specific name. A pointer to the DAG node is returned if it is found. NULL is returned if no such DAG node exists.

Arguments

name - the name to look for

statusCode AlDagNode::updateDrawInfo( void ) const

Description

Forces the internal draw information to be updated to match the DagNode’s geometry.

Return Codes

sSuccess - the draw information was updated

sInvalidObject - the DAG node was invalid

sFailure - this call is not valid in OpenModel

AlLayer* AlDagNode::layer() const

Description

Gets the layer of an AlDagNode.

statusCode AlDagNode::setLayer(const AlLayer *layerObj)

Description

Sets the layer on a DAG node. When a layer is set to an AlDagNode, the following settings are assigned:

All the child nodes of the current node are assigned to the layerObj layer.
All the parent nodes are assigned to the default layer.
All the sibling nodes are unaffected.

Arguments

< layerObj - the layer object to be assigned to the AlDagNode

Return Codes

sSuccess - the layer was assigned successfully

sInvalidArgument - the layer is invalid

sInvalidObject - the DAG node was invalid

AlConstraint* AlDagNode::firstConstraint( void ) const

Description

Returns a pointer to the first constraint on this DAG node.

boolean AlDagNode::isAConstructionPlane()

Description

Returns TRUE if the DAG node is a construction plane.

AlList* AlDagNode::clusterPreTransformationMatrices() const

Description

Returns a list of AlClusterPreTMItem, which contains the transformation matrices of the geometry DAG node for clusters.

NULL is returned for non_leaf or null DAG nodes, or if a DAG node does not involve with any cluster.

Note: you must delete the AlList object.

AlDagNode *AlDagNode::copyObject( AlCopyOptions* options, int numOfBlindDataIDsToCopy, int *blindDataIDsToCopy )

Description

This method is similar to the ::copyObject() method above. In addition, blind data IDs to be copied are specified with this method.

Arguments

< - numOfBlindDataIDsToCopy contains the number of elements of array blindDataIDsToCopy[]

< - blindDataIDsToCopy is an array of IDs to copy

NULL will be returned if numOfBlindDataIDsToCopy < 1 or blindDataIDsToCopy is NULL.

Warning: we suggest only copying blind data IDs that are managed by your code. Copying blind data IDs out of your range may lead to program errors.

statusCode AlDagNode::createSymmetricGeometry( )

Description

Creates the symmetric geometry for this node if it is on a symmetric plane.

Return code

sSuccess - the method succeeded

sFailure - the method failed

sInvalidObject - invalid dag node

statusCode AlDagNode::createSymmetricGeometry( AlDagNode *&symmGeomDag )

Description

Creates the symmetric geometry for this node if it is on a symmetric plane.

Return code

sSuccess - the method succeeded

sFailure - the method failed

sInvalidObject - invalid dag node

unsigned int AlDagNode::version( void ) const

Description

Returns the version of the DagNode

AlDagNode::AlCopyOptions::AlCopyOptions()

Description

This constructor initializes the instance to the current Duplicate options, or in OpenModel to the defaults for the Duplicate operation.

copyAnimation set to FALSE.
instanceCopy set to FALSE
copyClusters set to TRUE.
numCopies set to 1.
parameters set to ALL.
hierarchy set to BOTH.
timeOffset set to 0.
translate, rotate set to 0.
scale set to 1.

By default, copies will be grouped with the original AlDagNode.

AlDagNode::AlCopyOptions::~AlCopyOptions()

Description

Deletes this instance of the AlDagNode::AlCopyOptions class.

boolean AlDagNode::AlCopyOptions::copyAnimation() const

Description

Returns TRUE if copying of an AlDagNode’s animation is enabled.

statusCode AlDagNode::AlCopyOptions::setCopyAnimation( boolean animation )

Description

If "animation" is TRUE, animation data on the AlDagNode will be copied.

Return Codes

sSuccess - the flag was correctly set

sInvalidObject - the AlCopyOptions object was not properly created

boolean AlDagNode::AlCopyOptions::instanceCopy() const

Description

Returns TRUE if the copies are to be instances of the AlDagNode rather than new objects.

statusCode AlDagNode::AlCopyOptions::setInstanceCopy( boolean instance )

Description

If "instance" is TRUE, instances of the AlDagNode will be created rather than new objects.

Return Codes

sSuccess - the flag was correctly set

sInvalidObject - the AlCopyOptions object was not properly created

boolean AlDagNode::AlCopyOptions::copyClusters() const

Description

Returns TRUE if new copies of clusters should be made of clusters that reference geometry below the AlDagNode.

statusCode AlDagNode::AlCopyOptions::setCopyClusters( boolean clusters )

Description

If "clusters" is TRUE, new copies of clusters will be created for clusters that reference geometry below the AlDagNode.

Return Codes

sSuccess - the flag was correctly set

int AlDagNode::AlCopyOptions::numCopies() const

Description

Returns the number of copies to be created. Zero will be returned if the AlDagNode::AlCopyOptions object wasn’t properly created.

statusCode AlDagNode::AlCopyOptions::setNumCopies( int copies )

Description

Sets the number of copies to create.

Return Codes

sSuccess - the flag was correctly set

sInvalidObject - the AlCopyOptions object was not properly created

AlParamControlType AlDagNode::AlCopyOptions::parameterControl() const

Description

Returns the current parameter control setting. This will be one of kPARAMETER_ALL, kPARAMETER_GLOBAL, or kPARAMETER_LOCAL as defined in AlAnim.h.

statusCode AlDagNode::AlCopyOptions::setParameterControl( AlParamControlType control )

Description

Sets the parameter control to one of kPARAMETER_ALL, kPARAMETER_GLOBAL, or kPARAMETER_LOCAL as defined in AlAnim.h.

Return Codes

sSuccess - the flag was successfully set

sInvalidArgument - control was not one of the three possibilities

sInvalidObject - the AlCopyOptions object was not properly created

AlHierarchyType AlDagNode::AlCopyOptions::hierarchy() const

Description

Returns the current hierarchy setting. This will be one of kHIERARCHY_NONE, kHIERARCHY_ABOVE, kHIERARCHY_BELOW, or kHIERARCHY_BOTH as defined in AlAnim.h.

statusCode AlDagNode::AlCopyOptions::setHierarchy( AlHierarchyType hier )

Description

Sets the hierarchy to one of kHIERARCHY_NONE, kHIERARCHY_ABOVE, kHIERARCHY_BELOW, or kHIERARCHY_BOTH as defined in AlAnim.h.

Return Codes

sSuccess - the flag was successfully set

sInvalidArgument - control was not one of the three possibilities

sInvalidObject - the AlCopyOptions object was not properly created

double AlDagNode::AlCopyOptions::timeOffset() const

Description

Returns the time offset for the copies if animation is being copied.

statusCode AlDagNode::AlCopyOptions::setTimeOffset( double offset )

Description

Sets the time offset for copies when copying animation

Return Codes

sSuccess - the offset was correctly set

sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::translation( double& x, double& y, double& z ) const

Description

Returns the translation which will be applied to copies of the AlDagNode.

Return Codes

sSuccess - the translation was successfully determined

sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::setTranslation( double x, double y, double z )

Description

Sets the translation, which will be applied to copies of the AlDagNode.

Return Codes

sSuccess - the translation was successfully set

sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::rotation( double& x, double& y, double& z ) const

Description

Returns the rotation, which will be applied to copies of the AlDagNode.

Return Codes

sSuccess - the rotation was successfully determined

sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::setRotation( double x, double y, double z )

Description

Sets the rotation, which will be applied to copies of the AlDagNode.

Return Codes

sSuccess - the rotation was successfully set

sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::scale( double& x, double& y, double& z ) const

Description

Returns the scale, which will be applied to copies of the AlDagNode.

Return Codes

sSuccess - the scale was successfully determined

sInvalidObject - the AlCopyOptions object was not properly created

statusCode AlDagNode::AlCopyOptions::setScale( double x, double y, double z )

Description

Sets the scale, which will be applied to copies of the AlDagNode.

Return Codes

sSuccess - the scale was successfully set

sInvalidObject - the AlCopyOptions object was not properly created