Detailed Description

An envelope is an object or hierarchy that is assigned as a skin to a set of deformers such as IK chains. Envelopes move and deform in response to the movement of their deformers. In this way, for example, a character moves as you animate its skeleton.

Every point in an envelope is assigned to one or more deformers. Weights determine the relative influence of a deformer on a given point of the envelope.

Although it is common to use skeletons as deformers, you can actually use any object. The geometry of a deformer does not matter because the points of the envelope are assigned to its center. Bones are the exception; in this case, points are deformed by the whole length of the bone).

See also:: ChainBone, X3DObject, SceneItem

Example:: For examples that demonstrate how to access and set deformer weights, see Envelope::GetWeights, Envelope::GetDeformerWeights, Envelope::SetDeformerWeights and Envelope::SetDeformerWeights2.

#include <xsi_envelope.h>

Inheritance diagram for Envelope:

[legend]

List of all members.

Public Member Functions
	Envelope ()
	~Envelope ()
	Envelope (const CRef &in_ref)
	Envelope (const Envelope &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Envelope &	operator= (const Envelope &in_obj)
Envelope &	operator= (const CRef &in_ref)
CRefArray	GetDeformers () const
CClusterPropertyElementArray	GetWeights (double in_dFrame) const
CClusterElementArray	GetElements (double in_dFrame) const
CDoubleArray	GetDeformerWeights (const X3DObject &in_Deformer, double in_dFrame) const
CStatus	SetDeformerWeights (X3DObject &in_Deformer, const CDoubleArray &in_Array)
CStatus	GetDeformerColor (const X3DObject &in_Deformer, CColor &io_Color) const
CStatus	SetDeformerColor (const X3DObject &in_Deformer, const CColor &in_Color)
CStatus	SetDeformerWeights2 (X3DObject &in_Deformer, const CDoubleArray &in_Array)

Constructor & Destructor Documentation

Envelope ( )

Default constructor.

~Envelope ( )

Default destructor.

Envelope ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

Envelope ( const Envelope & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID class type.

Returns:: true if the class is compatible, false otherwise.

Reimplemented from Operator.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:: The class type.

Reimplemented from Operator.

Envelope& operator= ( const Envelope & in_obj )

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

in_obj constant class object.

Returns:: The new Envelope object.

Envelope& operator= ( const CRef & in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref constant class object.

Returns:: The new Envelope object.

Reimplemented from Operator.

CRefArray GetDeformers ( ) const

Returns an array of references to the deformer objects of this envelope.

Note:: You can convert a CRefArray element to an X3DObject (to use with envelope functions such as Envelope::GetDeformerWeights) as follows:

 myEnvelope.GetDeformerWeights( X3DObject( myCRefArray[someIndex] ) );

Returns:: Array of references to deformer objects

See also:: Envelope::GetWeights, Envelope::GetDeformerWeights, Envelope::SetDeformerWeights, Envelope::SetDeformerWeights2

CClusterPropertyElementArray GetWeights ( double in_dFrame ) const

Returns the weights for every deformer at a given frame.

Note:: The returned array contains, for every cluster element of the envelope, a list of the weights of all deformers. For instance, if an envelope is composed of two cluster elements and two deformers, the two first elements of the array are the weights for the deformers of the first cluster element. The third and fourth values represent the entries for the second cluster element.

Array Layout:

     ________________________________________________
    |  Index 0  |  Index 1  ||  Index 2  |  Index 3  |
    |-----------+-----------++-----------+-----------|
    |   Cluster element 0   ||   Cluster element 1   |
    |===========+===========++===========+===========|
    | Weight of | Weight of || Weight of | Weight of |
    |deformer 0 |deformer 1 ||deformer 0 |deformer 1 |
     ------------------------------------------------

Parameters:

in_dFrame Frame at which to get the deformers

Returns:: An array of weights.

See also:: CClusterPropertyElementArray::GetArray, CClusterPropertyElementArray::GetValueSize, Envelope::GetDeformerWeights, Envelope::SetDeformerWeights, Envelope::SetDeformerWeights2

Example:

        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        Null myDeformer1;
        root.AddNull( L"", myDeformer1 );
        Null myDeformer2;
        root.AddNull( L"", myDeformer2 );

        KinematicState nullGlobalKineState(myDeformer1.GetKinematics().GetGlobal());
        Parameter param(nullGlobalKineState.GetParameters().GetItem(L"posx"));
        param.PutValue( (double)4.0 );

        param = nullGlobalKineState.GetParameters().GetItem(L"posy");
        param.PutValue( (double)3.0 );

        X3DObject mySphere;
        root.AddGeometry( L"Sphere", L"MeshSurface", L"", mySphere );
        param = mySphere.GetKinematics().GetGlobal().GetParameters().GetItem(L"posz");
        param.PutValue( (double)2.0 );

        CRefArray deformers(2);
        deformers[0] = myDeformer1;
        deformers[1] = myDeformer2;

        Envelope myEnvelope;
        mySphere.ApplyEnvelope( deformers, siUnspecified, siUnspecified, myEnvelope );

        // get the weights at the current frame
        CTime time;
        CClusterPropertyElementArray weights = myEnvelope.GetWeights( time.GetTime() );
        CDoubleArray weightArray = weights.GetArray();

        wchar_t msg[30];
        LONG weightArrayCount = weightArray.GetCount();
        LONG deformerCount = weights.GetValueSize();

        // for each cluster element in the envelope
        for ( register LONG i = 0L; i < weightArrayCount; i += deformerCount )
        {
            swprintf( msg, L"Element #%d weights:", i / deformerCount  );
            CString csMsg( msg );

            // for each deformer of the current cluster element
            for ( register LONG j = 0L; j < deformerCount; j++ )
            {
                // show weight for current deformer
                swprintf( msg, L"\n\t\tDeformer #%d = %f", j, weightArray[i + j] );
                csMsg += msg;
            }
            app.LogMessage( csMsg );
        }

CClusterElementArray GetElements ( double in_dFrame ) const

Returns the cluster elements composing this envelope at a given frame.

Parameters:

in_dFrame Frame at which to get the cluster elements.

Returns:: An array of cluster elements

CDoubleArray GetDeformerWeights	(	const X3DObject &	in_Deformer,
		double	in_dFrame
	)		const

Returns the weights of a specific deformer at a given frame.

Parameters:

in_Deformer	The deformer to get
in_dFrame	Frame at which to get the deformer

Returns:: An array of weights

See also:: Envelope::GetWeights, Envelope::GetDeformers, Envelope::SetDeformerWeights, Envelope::SetDeformerWeights2

CStatus SetDeformerWeights	(	X3DObject &	in_Deformer,
		const CDoubleArray &	in_Array
	)

Sets the weights of the specified deformer and normalizes the weights.

Parameters:

in_Deformer	The deformer to set
in_Array	Array of weight values to apply

Returns:: CStatus::OK; CStatus::Fail

See also:: Envelope::GetDeformers, Envelope::GetWeights, Envelope::GetDeformerWeights, Envelope::SetDeformerWeights2

Example:

        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        Null myDeformer1;
        root.AddNull( L"", myDeformer1 );
        Null myDeformer2;
        root.AddNull( L"", myDeformer2 );

        KinematicState nullGlobalKineState(myDeformer1.GetKinematics().GetGlobal());
        Parameter param(nullGlobalKineState.GetParameters().GetItem(L"posx"));
        param.PutValue( (double)4.0 );

        param = nullGlobalKineState.GetParameters().GetItem(L"posy");
        param.PutValue( (double)3.0 );

        X3DObject mySphere;
        root.AddGeometry( L"Sphere", L"MeshSurface", L"", mySphere );
        param = mySphere.GetKinematics().GetGlobal().GetParameters().GetItem(L"posz");
        param.PutValue( (double)2.0 );

        CRefArray deformers(2);
        deformers[0] = myDeformer1;
        deformers[1] = myDeformer2;

        Envelope myEnvelope;
        mySphere.ApplyEnvelope( deformers, siUnspecified, siUnspecified, myEnvelope );

        // get the first deformer
        X3DObject firstDeformer( myEnvelope.GetDeformers()[0] );

        // Get its weights at frame 0
        CDoubleArray weights = myEnvelope.GetDeformerWeights( firstDeformer, 0.0 );

        // Set the weights to 75 for the current frame
        LONG weightCount = weights.GetCount();
        register LONG i = 0L;
        for ( ; i < weightCount; i++ ) weights[i] = 75.0;
        myEnvelope.SetDeformerWeights( firstDeformer, weights );

        wchar_t msg[128];
        CRefArray myDeformers = myEnvelope.GetDeformers();
        LONG deformerCount = myDeformers.GetCount();
        CTime frame;

        // for each deformer
        for ( i = 0L; i < deformerCount; i ++ )
        {
            swprintf( msg, L"Deformer #%d:", i );
            app.LogMessage( msg );

            // display the weights for the envelope at the current frame
            weights = myEnvelope.GetDeformerWeights( X3DObject(myDeformers[i]), frame.GetTime() );
            LONG elementCount = weights.GetCount();
            for ( register LONG i = 0L; i < elementCount; i++ )
            {
                swprintf( msg, L"Element %d = %f", i, weights[i] );
                app.LogMessage( msg );
            }
        }

CStatus GetDeformerColor	(	const X3DObject &	in_Deformer,
		CColor &	io_Color
	)		const

Returns the color of the specified deformer.

Parameters:

in_Deformer	The deformer to get
io_Color	Color of the deformer (as a CColor)

Returns:: CStatus::OK; CStatus::Fail

See also:: CColor

CStatus SetDeformerColor	(	const X3DObject &	in_Deformer,
		const CColor &	in_Color
	)

Sets the color of a given deformer.

Parameters:

in_Deformer	The deformer to set
in_Color	New color of the deformer

Returns:: CStatus::OK; CStatus::Fail

See also:: CColor

CStatus SetDeformerWeights2	(	X3DObject &	in_Deformer,
		const CDoubleArray &	in_Array
	)

Sets the weights of the specified deformer without normalizing the weights.

Parameters:

in_Deformer	The deformer to set
in_Array	Array of weight values to apply

Returns:: CStatus::OK; CStatus::Fail

Since:: 10.5 (2012)

See also:: Envelope::GetDeformers, Envelope::GetWeights, Envelope::GetDeformerWeights, Envelope::SetDeformerWeights

Example:

        // This example shows how to set vertex envelope weights
        // on a deformer without normalizing the weights

        // Create the scene made of a cube and 2 nulls
        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        X3DObject myCube;
        root.AddGeometry( L"Cube", L"MeshSurface", L"", myCube );
        Parameter param( myCube.GetKinematics().GetGlobal().GetParameters().GetItem( L"posz" ) );
        param.PutValue( (double)2.0 );

        Null myDeformer1;
        root.AddNull( L"", myDeformer1 );
        Null myDeformer2;
        root.AddNull( L"", myDeformer2 );

        KinematicState nullGlobalKineState( myDeformer1.GetKinematics().GetGlobal() );
        param = nullGlobalKineState.GetParameters().GetItem( L"posx" );
        param.PutValue( (double)4.0 );

        param = nullGlobalKineState.GetParameters().GetItem( L"posy" );
        param.PutValue( (double)3.0 );

        // Create a deformer array made of the 2 nulls
        CRefArray deformers( 2 );
        deformers[ 0 ] = myDeformer1;
        deformers[ 1 ] = myDeformer2;

        // Create a Envelope Weight on the grid with the 2 nulls
        Envelope myEnvelope;
        myCube.ApplyEnvelope( deformers, siUnspecified, siUnspecified, myEnvelope );

        // Get the first deformer and its weights at frame 0
        X3DObject firstDeformer( myEnvelope.GetDeformers()[ 0 ] );
        CDoubleArray weightsFirstDeformer = myEnvelope.GetDeformerWeights( firstDeformer, 0.0 );

        // Set the first deformer weights to 10 for the current frame
        // without normalizing the weights
        LONG weightCount = weightsFirstDeformer.GetCount();
        for( LONG i = 0; i < weightCount; i++ )
            weightsFirstDeformer[ i ] = 10.0;
        myEnvelope.SetDeformerWeights2( firstDeformer, weightsFirstDeformer );

        wchar_t msg[ 1024 ];
        CRefArray myDeformers = myEnvelope.GetDeformers();
        LONG deformerCount = myDeformers.GetCount();
        CTime frame;

        // Get the second deformer
        X3DObject secondDeformer( myEnvelope.GetDeformers()[ 1 ] );

        // Get the weights of both deformers
        weightsFirstDeformer = myEnvelope.GetDeformerWeights( firstDeformer, frame.GetTime() );
        CDoubleArray weightsSecondDeformer = myEnvelope.GetDeformerWeights( secondDeformer, frame.GetTime() );

        for( LONG i = 0; i < weightCount; i ++ )
        {
            swprintf( msg, L"Vertex %i: Deformer 1: %4.1f, Deformer 2: %4.1f",
                           i, weightsFirstDeformer[ i ], weightsSecondDeformer[ i ] );
            app.LogMessage( msg );
        }

The documentation for this class was generated from the following file:

xsi_envelope.h

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation