Encapsulates creation, deletion and manipulation of clusters.
Synopsis
#include <AlCluster.h>
class AlCluster : public AlObject
enum PercentEffectType { kInvalid, kLeafNode, kJoint };
AlCluster();
virtual ~AlCluster();
virtual statusCode deleteObject();
virtual AlObject* copyWrapper() const;
statusCode create();
AlObjectType type() const;
AlCluster* nextCluster() const;
statusCode nextClusterD();
AlCluster* prevCluster() const;
statusCode prevClusterD();
AlClusterNode* clusterNode() const;
boolean isEmpty() const;
int numberOfMembers() const;
AlClusterMember* firstMember() const;
statusCode applyIteratorToMembers( AlIterator*, int& ) const;
statusCode clusterRestrict( AlClusterRestrict& ) const;
statusCode setClusterRestrict( AlClusterRestrict );
statusCode originalTRS( double[3], double[3], double[3] ) const;
Description
This class encapsulates the functionality for creating, manipulating and deleting a cluster. A cluster is a group of DAG nodes
and/or curve and surface control points, which are grouped as such for deformation purposes. Every cluster has a cluster DAG
node which is in the universe’s DAG. Adding and removing nodes and control points to and from a cluster does not affect the
topology of the universe’s DAG. Transforming the cluster DAG node affects the transformations of the objects in the cluster.
Empty clusters are allowed. An object can be in more than one cluster at a time, provided that those clusters are of type
kMultiCluster. When an object is added to a cluster, it is given a weight that indicates how much of the cluster’s leaf transformation
is applied to the object. The default weight is 100%. If a DAG node is added to a cluster the percentages of each individual
CV may be manipulated separately without actually adding the CVs themselves to the cluster.
To create a cluster, the user must instantiate and call create on an AlCluster object. This also creates an AlClusterNode
which gets attached to the AlCluster and which is inserted into the universe’s DAG. The user may not instantiate an AlClusterNode
or an AlClusterMember directly.
There are two ways to delete a cluster object. When a cluster is deleted, its attached cluster node is deleted. Alternatively,
when AlClusterNode::deleteObject() is used, its cluster is deleted. The DAG nodes and control points in a cluster are not
deleted, however the AlClusterMember objects that represented the "in a cluster" relation are invalidated.
Clusters don’t have names. Any attempts to query for a name will return NULL.
AlCluster::AlCluster()
Description
Constructs an AlCluster wrapper object.
AlCluster::~AlCluster()
Description
Deletes an AlCluster wrapper object.
AlObject* AlCluster::copyWrapper() const
Description
Returns an exact duplicate of the current AlCluster wrapper.
statusCode AlCluster::deleteObject()
Description
Deletes the associated cluster node and for removes the cluster from the universe. This function also invalidates all of the
AlClusterMember objects associated with this cluster.
A cluster can be deleted in two ways. If AlCluster::deleteObject() is called, it deletes the associated cluster node. If AlClusterNode::deleteObject()
is called, it invalidates the associated AlCluster and AlClusterMembers.
Note that removing all members of a cluster will not destroy it. You must call the cluster deleteObject() to do this.
Return Codes
sSuccess - the data for the cluster was successfully deleted
sInvalidObject - the cluster was not valid
statusCode AlCluster::create()
Description
Creates a cluster and a cluster DAG node. The cluster DAG node is added to the current universe. The cluster by default is
given ’non-exclusive’ status - this means that a particular item can be in more than one cluster at a time.
Return Codes
sSuccess - everything was successful
sInsufficientMemory - not enough memory available
AlObjectType AlCluster::type() const
Description
Returns the class identifier ’kClusterType’.
AlCluster* AlCluster::nextCluster() const
Description
Returns a pointer to the cluster following this one in the global cluster list. If this is the last one then NULL is returned.
statusCode AlCluster::nextClusterD()
Description
Destructively sets the object to point to the next cluster in the global cluster list, if the next cluster can be found. If
not, the object is unaffected.
Return Codes
sSuccess - the AlCluster was successfully updated
sInvalidObject - the AlCluster was not valid
sFailure - the method failed
AlCluster* AlCluster::prevCluster() const
Description
Returns a pointer to the cluster preceding this one in the global cluster list. If this is the first one then NULL is returned.
statusCode AlCluster::prevClusterD()
Description
Destructively sets the object to point to the next cluster in the global cluster list, if the next cluster can be found. If
not, the object is unaffected.
Return Codes
sSuccess - the AlCluster was successfully updated
sInvalidObject - the AlCluster was not valid
sFailure - the method failed
AlClusterNode *AlCluster::clusterNode() const
Description
Returns a pointer to the attached (parent) cluster node. The cluster node must exist.
boolean AlCluster::isEmpty() const
Description
Returns TRUE if this cluster is empty (that is, doesn’t have any members). If the call fails, TRUE is returned.
AlClusterMember* AlCluster::firstMember() const
Description
Returns the head of the list of members in this cluster.
int AlCluster::numberOfMembers() const
Description
Returns the number of members in this cluster. Zero is returned if the call fails.
statusCode AlCluster::applyIteratorToMembers( AlIterator* iter, int &rc ) const
Description
Applies the given iterator to each member of this cluster. See the documentation for AlIterator.
Return Codes
sSuccess - the iterator completed successfully
sInvalidArgument - the iterator ’iter’ was NULL
sInvalidObject - the cluster was invalid
sFailure - the iterator completed abnormally
statusCode AlCluster::clusterRestrict( AlClusterRestrict& restrict ) const
Description
Puts the type of the current cluster, kMultiCluster or kExclusiveCluster, into the argument.
Arguments
> restrict - value to return
Return Codes
sSuccess - the cluster type was successfully set
sInvalidObject - the cluster was invalid
sFailure - the cluster type could not be determined
statusCode AlCluster::setClusterRestrict( AlClusterRestrict newRestrict )
Description
Sets the type of the current cluster, kMultiCluster or kExclusiveCluster
Arguments
< newRestrict - new cluster type
Return Codes
sSuccess - everything successful
sInvalidObject - the cluster was not valid
sFailure - if cluster could not take on the given type
sInvalidArgument - the argument was neither kMultiCluster nor kExclusiveCluster
statusCode AlCluster::originalTRS( double [3], double [3], double [3]) const
Description
Gets the original translate, rotate and scale of this cluster.
Return Codes
sSuccess - original TRS was get successfully
sInvalidObject - the cluster was not valid
sFailure - can’t get the original TRS
sInvalidArgument - if any of the arguments are NULL
