Envelope Class Reference

Related Scripting Object: Envelope

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. More...

#include <xsi_envelope.h>

Inheritance diagram for Envelope:

Detailed Description

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 and Envelope::SetDeformerWeights

Constructor & Destructor Documentation

Default destructor.

Constructor.

Parameters:

in_ref

constant reference object.

Copy constructor.

Parameters:

in_obj

constant class object.

Member Function Documentation

Returns the type of the API class.

Returns:

The class type.

Reimplemented from Operator.

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.

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.

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

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

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 );
        }

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

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

Sets the weights of the specified deformer.

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::SetDeformerWeights

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 );
            }
        }

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

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

• xsi_envelope.h