AlCluster

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