Public Member Functions
Envelope Class Reference

## 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