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
