Basic Interface to Alias DAG node objects.
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
statusCode AlDagNode::getSurfaceOrientation( boolean )
Description
For the given DAG node, detect whether the surface orientation has been flipped.
Returns TRUE if the surface orientation for the DAG node has not been flipped.
Returns FALSE if the orientation has been flipped.
statusCode AlDagNode::setSurfaceOrientation( boolean )
Description
For the given DAG node, set the surface orientation flag.
Arguments
< boolean - Set the argument to TRUE to maintain the surface orientation; set it to FALSE to flip the orientation
Return Codes
sSuccess - the orientation flag was set successfully
sInvalidObject - the DAG node was invalid
sInvalidArgument - the given argument is not valid
