Public Member Functions
AnimationSourceItem Class Reference

## Detailed Description

An ActionSource contains a collection of animation source items, which you can get at using ActionSource::GetItems. The AnimationSourceItem class provides access to the animation DataSource (for example, an FCurve) and a target entity such as the Parameter or Cluster which the animation source drives.

One way to create action animation is to create an empty ActionSource and then populate it afterwards using ActionSource::AddSourceItem. In that case you can add a StaticSource as the animation source using AnimationSourceItem::SetAsStatic.

In order to know exactly which type of AnimationSourceItem you are dealing with you can use SIObject::GetType which returns one of the values contained in the ::siAnimationSourceItemType enum.

See also:
  ActionSource::GetItems, FCurve, StaticSource, Expression, Constraint, ShapeKey, Model::AddActionSource, ActionSource::AddSourceItem, AnimationSourceItem::SetAsStatic

Since:
  4.0

Example:
  Illustrates creating a source and accessing the source items contained in it.

            using namespace XSI;

            Application app;
            Model root = app.GetActiveSceneRoot();

            X3DObject myCube;
            root.AddGeometry( L"Cube", L"MeshSurface", L"", myCube );

            //Creating the first animation source
            CValueArray args(9);
            CValue      outArg;
            args[0] = root;
            args[1] = L"cube.kine.local.posx,cube.kine.local.posy,cube.kine.local.posz";
            args[2] = 1l;
            args[3] = L"StoredStaticPose";
            args[4] = true;
            args[5] = 1l;
            args[6] = 5l;
            args[7] = false;
            args[8] = false;
            app.ExecuteCommand( L"StoreAction", args, outArg );

            ActionSource mySource(outArg);
            CRefArray aSourceItems = mySource.GetItems();

            for(LONG i = 0; i < aSourceItems.GetCount();++i)
            {
                SourceItem currItem(aSourceItems[i]);
                app.LogMessage(L" The animated target is " + currItem.GetTarget());
                app.LogMessage(L" The type of animation is " + currItem.GetType());
                //In this case its a static value
                //you can switch on type.
                StaticValue myVal = currItem.GetSource();
                app.LogMessage(L" The value is " + myVal.GetValue().GetAsText());
            }

Example:
  Illustrates how to create an empty ActionSource using Model::AddActionSource, populate it with 2 static values and 1 fcurve using ActionSource::AddSourceItem, and then replace the fcurvesource with a static value for the 2nd and change the static value for the 3rd using AnimationSourceItem::SetAsStatic.

            using namespace XSI;

            // Forward declarations
            CString GetRelativeName( Parameter& in_param );
            FCurve MakeAnFCurve( Null& in_obj, CString in_param );

            Application app;

            // NewScene command
            CValueArray cargs; CValue oarg;
            cargs.Add( L"" ); cargs.Add( false );
            app.ExecuteCommand( L"NewScene", cargs, oarg );
            cargs.Clear();

            // Get the scene root
            Model root = app.GetActiveSceneRoot();

            // Create a null and get pointers to the pos parameters
            Null n; root.AddNull( L"null", n );

            Parameter posx = n.GetParameter( L"posx" ); CString rposx = GetRelativeName(posx);
            Parameter posy = n.GetParameter( L"posy" ); CString rposy = GetRelativeName(posy);
            Parameter posz = n.GetParameter( L"posz" ); CString rposz = GetRelativeName(posz);

            // Create an empty actionsource and then populate it with static values
            ActionSource src = root.AddActionSource( L"StaticActionSource" );
            FCurve fc = MakeAnFCurve( n, L"posy" );
            src.AddSourceItem( rposx, 2.0 );    // static value
            src.AddSourceItem( rposy, fc );     // fcurve
            src.AddSourceItem( rposz );     // default static value = 0.0

            // Now change the value on the posz parameter using SetAsStatic and change
            // the posy parameter source to an fcurve
            CRefArray animsrcitems = src.GetItems();
            for ( LONG i=0; i<animsrcitems.GetCount(); ++i ) {
                AnimationSourceItem srcitem(animsrcitems[i]);

                // Get a pointer to the source item (it can be either a StaticSource or an FCurve)
                CRef ref = srcitem.GetSource();
                if ( ref.IsA(siFCurveID) ) {
                    FCurve datasrc(ref);

                    // Print the FCurve type
                    app.LogMessage( L"AnimationSourceItem[" + CString(i) + L"] (" + srcitem.GetTarget()
                        + L") has " + CString(datasrc.GetNumKeys()) + L" keys" );
                }

                if ( ref.IsA(siStaticSourceID) ) {
                    StaticSource datasrc(ref);

                    // Print the current value
                    app.LogMessage( L"AnimationSourceItem[" + CString(i) + L"] (" + srcitem.GetTarget()
                        + L") has this static value: " + CString( datasrc.GetValue() ) );
                }

                // AnimationSourceItem::GetTarget returns the \xl RelativeName
                if ( srcitem.GetTarget() == rposy ) {
                    StaticSource staticvalue;
                    srcitem.SetAsStatic( CValue(1.0), staticvalue );

                    // Check for the new value (we know it's a StaticSource because we just set it)
                    StaticSource datasrc( srcitem.GetSource() );    // refresh
                    app.LogMessage( L"New static value = " + CString( datasrc.GetValue() ) );
                }

                if ( srcitem.GetTarget() == rposz ) {
                    StaticSource staticvalue;
                    srcitem.SetAsStatic( CValue(1.5), staticvalue );

                    // Check for the new value (we know it's a StaticSource because we just set it)
                    StaticSource datasrc( srcitem.GetSource() );    // refresh
                    app.LogMessage( L"New static value = " + CString( datasrc.GetValue() ) );
                }
            }

            //INFO : AnimationSourceItem[0] (null.kine.local.posx) has this static value: 2
            //INFO : AnimationSourceItem[1] (null.kine.local.posy) has 4 keys
            //INFO : New static value = 1
            //INFO : AnimationSourceItem[2] (null.kine.local.posz) has this static value: 0
            //INFO : New static value = 1.5

            // Function to remove the name of the model from the FullName of the specified parameter.
            // This is necessary when setting up a source that will later be used to instantiate a
            // clip when the parameter lives under a model other than the Scene_Root.
            CString GetRelativeName( Parameter& in_param )
            {
                Model mdl = in_param.GetModel();
                CString mdlname = mdl.GetFullName();
                if ( mdlname.IsEqualNoCase(L"Scene_Root") ) {
                    return in_param.GetFullName();
                } else {
                    CString tmp = in_param.GetFullName();
                    CString lookfor = mdlname + L".";
                    CString foundsofar = L"";
                    CString relpath = L"";
                    for ( ULONG i=0; i<tmp.Length(); ++i ) {
                        if ( foundsofar.IsEqualNoCase(lookfor) ) {
                            relpath += tmp[i];
                        } else {
                            foundsofar += tmp[i];
                        }
                    }
                    return relpath;
                }
            }

            // Convenience function
            FCurve MakeAnFCurve( Null& in_obj, CString in_param )
            {
                Parameter p = in_obj.GetParameter( in_param );
                FCurve fc; p.AddFCurve( siStandardFCurve, fc );
                fc.AddKey( CTime(1.0), CValue(1.25) );
                fc.AddKey( CTime(25.0), CValue(2.0) );
                fc.AddKey( CTime(40.0), CValue(2.75) );
                fc.AddKey( CTime(85.0), CValue(0.0) );

                return fc;
            }

`#include <xsi_animationsourceitem.h>`

Inheritance diagram for AnimationSourceItem:
[legend]

List of all members.

## Public Member Functions
| AnimationSourceItem ()
| ~AnimationSourceItem ()
| AnimationSourceItem (const CRef &in_ref)
| AnimationSourceItem (const AnimationSourceItem &in_obj)
bool | IsA (siClassID in_ClassID) const
siClassID | GetClassID () const
AnimationSourceItem & | operator= (const AnimationSourceItem &in_obj)
AnimationSourceItem & | operator= (const CRef &in_ref)
bool | GetIsActive () const
CStatus | PutIsActive (bool in_bActiveState)
CRef | GetSource () const
CStatus | PutSource (CRef in_source)
CString | GetTarget () const
CStatus | PutTarget (CString &in_target)
CStatus | SetAsStatic (CValue &in_vValue, StaticSource &out_static)

## Constructor & Destructor Documentation

AnimationSourceItem | ( |  | ) |

Default constructor.

~AnimationSourceItem | ( |  | ) |

Default destructor.

AnimationSourceItem | ( | const CRef & | in_ref | ) |

Constructor.

Parameters:

  in_ref | constant reference object.

AnimationSourceItem | ( | const AnimationSourceItem & | 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 SIObject.

siClassID GetClassID | ( |  | ) | const `[virtual]`

Returns the type of the API class.

Returns:
  The class type.

Reimplemented from SIObject.

AnimationSourceItem& operator= | ( | const AnimationSourceItem & | 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 AnimationSourceItem object.

AnimationSourceItem& 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 AnimationSourceItem object.

Reimplemented from SIObject.

bool GetIsActive | ( |  | ) | const

Returns true if the animation source item is active.

Returns:
  true if the animation source item is active.

Example:
  This example illustrates how to create a simple actionsource, access the actionsource from the model and mute one of the source items. The modified actionsource is then used to create an action clip.

            using namespace XSI;

            // Forward declaration
            void MakeFCActionSource( Null& in_null );

            Application app;

            // NewScene command
            CValueArray cargs; CValue oarg;
            cargs.Add( L"" ); cargs.Add( false );
            app.ExecuteCommand( L"NewScene", cargs, oarg );
            cargs.Clear(); oarg.Clear();

            Model root = app.GetActiveSceneRoot();

            // Create a simple actionsource from some animation on the null's position
            Null n; root.AddNull( L"null", n );
            MakeFCActionSource( n );

            // Get the actionsource from the model
            CRefArray sources = root.GetSources();
            app.LogMessage( L"Number of sources on " + root.GetFullName() + L": " + CString(sources.GetCount()) );
            ActionSource src( sources.GetItem(0) );

            // Find animation source item with posx and mute it
            CRefArray srcitems = src.GetItems();
            for ( LONG i=0; i<srcitems.GetCount(); ++i ) {
                AnimationSourceItem animsrcitm( srcitems[i] );

                // Find the right target by looking for 'posx' with the StringSearch command
                cargs.Add( animsrcitm.GetTarget() );
                cargs.Add( L"posx" );
                cargs.Add( false );
                app.ExecuteCommand( L"StringSearch", cargs, oarg );
                if ( oarg.GetAsText() != L"-1" ) {
                    app.LogMessage( L"muting " + animsrcitm.GetTarget() );
                    animsrcitm.PutIsActive( false );
                    break;          // Quit looking once it's found
                }
                cargs.Clear(); oarg.Clear();
            }

            // Apply actionsource with muted posx
            CValueArray args; CValue outarg;
            args.Add( root.GetFullName() );
            args.Add( src.GetFullName() );
            args.Add( root.GetFullName() );         // Simple clips take the model as compound owner
            app.ExecuteCommand( L"AddClip", args, outarg );

            // Find the clip
            Mixer mxr = root.GetMixer();
            CRefArray cliplist = mxr.GetClips();
            Clip clp( cliplist[0] );

            // Test the source items
            src  = clp.GetSource();
            srcitems = src.GetItems();
            for ( i=0; i<srcitems.GetCount(); ++i ) {
                AnimationSourceItem animsrcitm( srcitems[i] );
                app.LogMessage( animsrcitm.GetFullName() + L" " + animsrcitm.GetTarget() + L" is active: "
                    + CString(animsrcitm.GetIsActive()) );
            }

            // Expected results:
            //INFO : Number of sources on Scene_Root: 1
            //INFO : muting null.kine.local.posx
            //INFO : AnimationSourceItem null.kine.local.posx is active: false
            //INFO : AnimationSourceItem null.kine.local.posy is active: true
            //INFO : AnimationSourceItem null.kine.local.posz is active: true

            // Function to remove the name of the model from the FullName of the specified parameter.
            // This is necessary when setting up a source that will later be used to instantiate a
            // clip when the parameter lives under a model other than the Scene_Root.
            CString GetRelativeName( Parameter& in_param )
            {
                Model mdl = in_param.GetModel();
                CString mdlname = mdl.GetFullName();
                if ( mdlname.IsEqualNoCase(L"Scene_Root") ) {
                    return in_param.GetFullName();
                } else {
                    CString tmp = in_param.GetFullName();
                    CString lookfor = mdlname + L".";
                    CString foundsofar = L"";
                    CString relpath = L"";
                    for ( ULONG i=0; i<tmp.Length(); ++i ) {
                        if ( foundsofar.IsEqualNoCase(lookfor) ) {
                            relpath += tmp[i];
                        } else {
                            foundsofar += tmp[i];
                        }
                    }
                    return relpath;
                }
            }

            // Create a simple actionsource from animation on the null's position
            void MakeFCActionSource( Null& in_null )
            {
                Application app;

                CTimeArray time; time.Add( CTime(1.000) ); time.Add( CTime(50.000) ); time.Add( CTime(100.000) );
                CValueArray vals;

                // X
                Parameter posx = in_null.GetParameter( L"posx" ); CString rposx = GetRelativeName(posx);
                FCurve fcx; posx.AddFCurve( siStandardFCurve, fcx );
                vals.Add( CValue(-8.153) ); vals.Add( CValue(0.197) ); vals.Add( CValue(9.413) );
                fcx.SetKeys( time, vals ); vals.Clear();

                // Y
                Parameter posy = in_null.GetParameter( L"posy" ); CString rposy = GetRelativeName(posy);
                FCurve fcy; posy.AddFCurve( siStandardFCurve, fcy );
                vals.Add( CValue(7.015) ); vals.Add( CValue(-1.92) ); vals.Add( CValue(7.015) );
                fcy.SetKeys( time, vals ); vals.Clear();

                // Z
                Parameter posz = in_null.GetParameter( L"posz" ); CString rposz = GetRelativeName(posz);
                FCurve fcz; posz.AddFCurve( siStandardFCurve, fcz );
                vals.Add( CValue(-0.702) ); vals.Add( CValue(0.192) ); vals.Add( CValue(-0.702) );
                fcz.SetKeys( time, vals );

                // StoreAction command
                CValueArray args; CValue outarg;
                args.Add( app.GetActiveSceneRoot().GetFullName() );
                args.Add( rposx + L"," + rposy + L"," + rposz );
                args.Add( CValue(2.0) );
                args.Add( L"StoredFcvAction" );
                args.Add( true );
                args.Add( CValue(1.0) );
                args.Add( CValue(100.0) );
                app.ExecuteCommand( L"StoreAction", args, outarg );
            }

CStatus PutIsActive | ( | bool | in_bActiveState | ) |

Sets the activeness of the animation source item (true = active; false = muted).

Parameters:

  in_bActiveState | activation state.

Returns:
  CStatus::OK success
  CStatus::Fail failure

Example:
  See AnimationSourceItem::GetIsActive for an example of how to use the PutIsActive function.

CRef GetSource | ( |  | ) | const

Returns the animation source (FCurve, StaticSource or ShapeKey).

Returns:
  The animation source reference.

Example:
  See AnimationSourceItem::PutSource (under the PrintSourceInfo function) for an example of how to use the GetSource function

CStatus PutSource | ( | CRef | in_source | ) |

Sets the animation source (FCurve or StaticSource).

Parameters:

  in_source | The animation source reference.

See also:
  AnimationSourceItem::SetAsStatic

Example:
  Demonstrates how to overwrite an existing FCurve animation source item with a new FCurve using the PutSource function.

            using namespace XSI;

            // Forward declarations
            CString GetRelativeName( Parameter& in_param );
            void MakeNewFCrvSource();
            void MakeNewFCrv( FCurve& out_fc );
            void PrintClipInfo( Clip& in_clip );
            void PrintSourceInfo( ActionSource& in_src );

            Application app;

            // NewScene command
            CValueArray cargs; CValue oarg;
            cargs.Add( L"" ); cargs.Add( false );
            app.ExecuteCommand( L"NewScene", cargs, oarg );
            cargs.Clear(); oarg.Clear();

            // Get the SceneRoot
            Model root = app.GetActiveSceneRoot();
            CString rootName = root.GetFullName();

            // New fcurve ActionSource
            MakeNewFCrvSource();
            Null n = root.FindChild( L"", siNullPrimType, CStringArray() );

            // Get the ActionSource from the model & instantiate it as a clip
            CRefArray sources = root.GetSources();
            ActionSource src( sources.GetItem(0) );

            // AddClip command
            CValueArray clipArgs; CValue outClip;
            clipArgs.Add( rootName );
            clipArgs.Add( src.GetRef().GetAsText() );
            clipArgs.Add( rootName );                               // Simple clips take the model as compound owner
            app.ExecuteCommand( L"AddClip", clipArgs, outClip );

            // Set up another fc (external to a source)
            FCurve fc; MakeNewFCrv( fc );

            // Find the clip
            Mixer mxr = root.GetMixer();
            CRefArray cliplist = mxr.GetClips();
            Clip clp(cliplist[0]);
            app.LogMessage( L"BEFORE source modifications:" );
            PrintClipInfo( clp );

            // Copy the fc onto the fc-based source
            CRefArray srcitems = src.GetItems();
            AnimationSourceItem oldSrcItem( srcitems.GetItem(0) );
            oldSrcItem.PutSource( fc.GetRef() );

            // Print the values on the action source after modifications to the source
            // (the instanced action in the clip and its underlying source have the same values)
            app.LogMessage( L"AFTER source modifications:" );
            PrintClipInfo( clp );

            // Expected results:
            //INFO : BEFORE source modifications:
            //INFO : Reporting on Mixer.Mixer_Anim_Track.StoredFcvAction_Clip clip:
            //INFO :  - Source used = Sources.Scene_Root.StoredFcvAction
            //INFO :  --- SrcItem #0 target = MyAnimatedNull.kine.local.posx and its datasource is a FCurve
            //INFO :             (evaluates to -2.84068 at frame 30)
            //INFO :  --- SrcItem #1 target = MyAnimatedNull.kine.local.posy and its datasource is a FCurve
            //INFO :             (evaluates to 1.3305 at frame 30)
            //INFO :  --- SrcItem #2 target = MyAnimatedNull.kine.local.posz and its datasource is a FCurve
            //INFO :             (evaluates to -0.133232 at frame 30)
            //INFO :
            //INFO : AFTER source modifications:
            //INFO : Reporting on Mixer.Mixer_Anim_Track.StoredFcvAction_Clip clip:
            //INFO :  - Source used = Sources.Scene_Root.StoredFcvAction
            //INFO :  --- SrcItem #0 target = MyAnimatedNull.kine.local.posx and its datasource is a FCurve
            //INFO :             (evaluates to 2.84068 at frame 30)
            //INFO :  --- SrcItem #1 target = MyAnimatedNull.kine.local.posy and its datasource is a FCurve
            //INFO :             (evaluates to 1.3305 at frame 30)
            //INFO :  --- SrcItem #2 target = MyAnimatedNull.kine.local.posz and its datasource is a FCurve
            //INFO :             (evaluates to -0.133232 at frame 30)
            //INFO :

            // Function to remove the name of the model from the FullName of the specified parameter.
            // This is necessary when setting up a source that will later be used to instantiate a
            // clip when the parameter lives under a model other than the Scene_Root.
            CString GetRelativeName( Parameter& in_param )
            {
                Model mdl = in_param.GetModel();
                CString mdlname = mdl.GetFullName();
                if ( mdlname.IsEqualNoCase(L"Scene_Root") ) {
                    return in_param.GetFullName();
                } else {
                    CString tmp = in_param.GetFullName();
                    CString lookfor = mdlname + L".";
                    CString foundsofar = L"";
                    CString relpath = L"";
                    for ( ULONG i=0; i<tmp.Length(); ++i ) {
                        if ( foundsofar.IsEqualNoCase(lookfor) ) {
                            relpath += tmp[i];
                        } else {
                            foundsofar += tmp[i];
                        }
                    }
                    return relpath;
                }
            }

            // Create a simple (fcurve) actionsource based on a null's position
            void MakeNewFCrvSource()
            {
                Application app;
                Model root = app.GetActiveSceneRoot();
                Null n; root.AddNull( L"MyAnimatedNull", n );

                CTimeArray time; time.Add( CTime(1.000) ); time.Add( CTime(50.000) ); time.Add( CTime(100.000) );
                CValueArray vals;

                // X
                Parameter posx = n.GetParameter( L"posx" ); CString rposx = GetRelativeName(posx);
                FCurve fcx; posx.AddFCurve( siStandardFCurve, fcx );
                vals.Add( CValue(-8.153) ); vals.Add( CValue(0.197) ); vals.Add( CValue(9.413) );
                fcx.SetKeys( time, vals ); vals.Clear();

                // Y
                Parameter posy = n.GetParameter( L"posy" ); CString rposy = GetRelativeName(posy);
                FCurve fcy; posy.AddFCurve( siStandardFCurve, fcy );
                vals.Add( CValue(7.015) ); vals.Add( CValue(-1.92) ); vals.Add( CValue(7.015) );
                fcy.SetKeys( time, vals ); vals.Clear();

                // Z
                Parameter posz = n.GetParameter( L"posz" ); CString rposz = GetRelativeName(posz);
                FCurve fcz; posz.AddFCurve( siStandardFCurve, fcz );
                vals.Add( CValue(-0.702) ); vals.Add( CValue(0.192) ); vals.Add( CValue(-0.702) );
                fcz.SetKeys( time, vals );

                // StoreAction command
                CValueArray args; CValue outArg;
                args.Add( CRef(root) );
                args.Add( rposx + L"," + rposy + L"," + rposz );
                args.Add( 2.0 );
                args.Add( L"StoredFcvAction" );
                args.Add( true );
                args.Add( 1.0 );
                args.Add( 100.0 );
                app.ExecuteCommand( L"StoreAction", args, outArg );
            }

            // Convenience function to create an fcurve
            void MakeNewFCrv( FCurve& out_fc )
            {
                Application app;
                Model root = app.GetActiveSceneRoot();
                Null n; root.AddNull( L"MyDummyNull", n );
                CRefArray kids; kids.Add( n );
                Model m; root.AddModel( kids, L"MyDummyModel", m );

                CTimeArray time; time.Add( CTime(1.000) ); time.Add( CTime(50.000) ); time.Add( CTime(100.000) );
                CValueArray vals; vals.Add( CValue(8.153) ); vals.Add( CValue(-0.197) ); vals.Add( CValue(-9.413) );

                // X
                Parameter posx = n.GetParameter( L"posx" );
                posx.AddFCurve( siStandardFCurve, out_fc );
                out_fc.SetKeys( time, vals );
            }

            // Convenience function to print out information about the clip's source
            void PrintClipInfo( Clip& in_clip )
            {
                Application app;

                // Clip
                app.LogMessage( L"Reporting on " + in_clip.GetFullName() + L" clip:" );

                // Clip's source
                PrintSourceInfo( ActionSource(in_clip.GetSource()) );
            }

            // Convenience function to print out information about the source
            void PrintSourceInfo( ActionSource& in_src )
            {
                Application app;

                // Source
                app.LogMessage( L" - Source used = " + in_src.GetFullName() );

                // Source's items
                CRefArray itemsRef = in_src.GetItems();
                for ( LONG i=0; i<itemsRef.GetCount(); ++i ) {
                    AnimationSourceItem animsrcitm( itemsRef[i] );
                    app.LogMessage( L" --- SrcItem #" + CString(i) + L" target = " + animsrcitm.GetTarget()
                        + L" and its datasource is a " + animsrcitm.GetSource().GetClassIDName() );

                    // Underlying data source is an FCurve
                    if ( animsrcitm.GetSource().GetClassID() == siFCurveID ) {
                        FCurve fc( animsrcitm.GetSource() );
                        app.LogMessage( L"            (evaluates to " + fc.Eval( CTime(30.0) ).GetAsText() + L" at frame 30)" );
                    }

                    // Underlying data source is a StaticSource
                    if ( animsrcitm.GetSource().GetClassID() == siStaticSourceID ) {
                        StaticSource sv( animsrcitm.GetSource() );
                        app.LogMessage( L"            (evaluates to " + sv.GetValue().GetAsText() + L")" );
                    }
                }

                // Extra blank line
                app.LogMessage( L"" );
            }

CString GetTarget | ( |  | ) | const

Returns the complete name of the animation target (the Parameter to which the animation has been applied) as a RelativeName.

Note:
  ActionSources store the relative name instead of the FullName of a parameter so actions can be easily copied from one Model to another.

Tip:
  In the mixer, you can see this name ("Item Name") by opening the property page of the source (for example, Mixer > Sources > Shape > Point_ClusterClip_source. In the case of a shape source, you need to access Clip::GetMappedItems when you need a current cluster name changed by a designer, because this function returns the original cluster name stored in a Shape Source in the Mixer.

Returns:
  The RelativeName (SIObject::GetFullName without the modelname prefix).

Example:
  This example illustrates how to create a simple actionsource from some position animation. AnimationSourceItem::Source property is used to get the fcurve source and modify the keys.

            using namespace XSI;

            // Forward declarations
            CString GetRelativeName( Parameter& in_param );
            void MakeNewFCrvSource( Null& in_null );
            void PrintClipInfo( Clip& in_clip );
            void PrintSourceInfo( ActionSource& in_src );

            Application app;

            // NewScene command
            CValueArray cargs; CValue oarg;
            cargs.Add( L"" ); cargs.Add( false );
            app.ExecuteCommand( L"NewScene", cargs, oarg );
            cargs.Clear(); oarg.Clear();

            // Get the SceneRoot
            Model root = app.GetActiveSceneRoot();

            // Create a new model and add a null
            Model m; root.AddModel( CRefArray(), L"MyModel", m );
            Null n; m.AddNull( L"MyNull", n );

            // Add an fcurve ActionSource based on the new null
            MakeNewFCrvSource( n );

            // Get the ActionSource from the model
            CRefArray sources = m.GetSources();
            ActionSource src( sources.GetItem(0) );
            app.LogMessage( L"BEFORE source modifications:" );
            PrintSourceInfo( src );

            // Get the relative name for the posx parameter
            Parameter posx = n.GetParameter( L"posx" );
            CString rp = GetRelativeName( posx );

            // Find animation source item with posx
            CRefArray srcitems = src.GetItems();
            for ( LONG i=0; i<srcitems.GetCount(); ++i ) {
                AnimationSourceItem itm( srcitems.GetItem(i) );
                if ( itm.GetTarget() == rp ) {
                    // Change the fcurve keys on the posx source
                    FCurve fc( itm.GetSource() );
                    CTimeArray t; t.Add( CTime(1) ); t.Add( CTime(50) ); t.Add( CTime(100) );
                    CValueArray v; v.Add( CValue(-8.0) ); v.Add( CValue(8.0) ); v.Add( CValue(9.0) );
                    fc.SetKeys( t, v );

                    break;
                }
            }

            // Print modified info
            app.LogMessage( L"AFTER source modifications:" );
            PrintSourceInfo( src );

            // Expected results:
            //INFO : BEFORE source modifications:
            //INFO :  - Source used = Sources.MyModel.StoredFcvAction
            //INFO :    Underlying fc evaluates to -2.84068 at frame 30) on MyNull.kine.local.posx
            //INFO :
            //INFO : AFTER source modifications:
            //INFO :  - Source used = Sources.MyModel.StoredFcvAction
            //INFO :    Underlying fc evaluates to 2.1793 at frame 30) on MyNull.kine.local.posx
            //INFO :

            // Function to remove the name of the model from the FullName of the specified parameter.
            // This is necessary when setting up a source that will later be used to instantiate a
            // clip when the parameter lives under a model other than the Scene_Root.
            CString GetRelativeName( Parameter& in_param )
            {
                Model mdl = in_param.GetModel();
                CString mdlname = mdl.GetFullName();
                if ( mdlname.IsEqualNoCase(L"Scene_Root") ) {
                    return in_param.GetFullName();
                } else {
                    CString tmp = in_param.GetFullName();
                    CString lookfor = mdlname + L".";
                    CString foundsofar = L"";
                    CString relpath = L"";
                    for ( ULONG i=0; i<tmp.Length(); ++i ) {
                        if ( foundsofar.IsEqualNoCase(lookfor) ) {
                            relpath += tmp[i];
                        } else {
                            foundsofar += tmp[i];
                        }
                    }
                    return relpath;
                }
            }

            // Create a simple (fcurve) actionsource based on a null's position
            void MakeNewFCrvSource( Null& in_null )
            {
                Application app;
                Model mdl = in_null.GetModel();

                CTimeArray time; time.Add( CTime(1.000) ); time.Add( CTime(50.000) ); time.Add( CTime(100.000) );
                CValueArray vals;

                // X
                Parameter posx = in_null.GetParameter( L"posx" ); CString rposx = GetRelativeName(posx);
                FCurve fcx; posx.AddFCurve( siStandardFCurve, fcx );
                vals.Add( CValue(-8.153) ); vals.Add( CValue(0.197) ); vals.Add( CValue(9.413) );
                fcx.SetKeys( time, vals ); vals.Clear();

                // Y
                Parameter posy = in_null.GetParameter( L"posy" ); CString rposy = GetRelativeName(posy);
                FCurve fcy; posy.AddFCurve( siStandardFCurve, fcy );
                vals.Add( CValue(7.015) ); vals.Add( CValue(-1.92) ); vals.Add( CValue(7.015) );
                fcy.SetKeys( time, vals ); vals.Clear();

                // Z
                Parameter posz = in_null.GetParameter( L"posz" ); CString rposz = GetRelativeName(posz);
                FCurve fcz; posz.AddFCurve( siStandardFCurve, fcz );
                vals.Add( CValue(-0.702) ); vals.Add( CValue(0.192) ); vals.Add( CValue(-0.702) );
                fcz.SetKeys( time, vals );

                // Build an action with the fcurves as source items
                ActionSource src = mdl.AddActionSource( L"StoredFcvAction" );
                src.AddSourceItem( rposx, fcx, true );
                src.AddSourceItem( rposy, fcy, true );
                src.AddSourceItem( rposz, fcz, true );
            }

            // Convenience function to print out information about the source
            void PrintSourceInfo( ActionSource& in_src )
            {
                Application app;
                app.LogMessage( L" - Source used = " + in_src.GetFullName() );

                // Get the Source's first item
                CRefArray itemsRef = in_src.GetItems();
                AnimationSourceItem animsrcitm( itemsRef[0] );

                // Get underlying fcurve
                FCurve fc( animsrcitm.GetSource() );
                app.LogMessage( L"   Underlying fc evaluates to " + fc.Eval( CTime(30.0) ).GetAsText()
                    + L" at frame 30 on " + animsrcitm.GetTarget() );

                // Extra blank line
                app.LogMessage( L"" );
            }

CStatus PutTarget | ( | CString & | in_target | ) |

Sets the complete name of the object to be animated by this animation source item as a RelativeName.

Note:
  ActionSources store the relative name instead of the FullName of a parameter so actions can be easily copied from one Model to another.

Parameters:

  in_target | The RelativeName (SIObject::GetFullName without the modelname prefix)

Returns:
  CStatus::OK success
  CStatus::Fail failure

CStatus SetAsStatic | ( | CValue & | in_vValue,
|  | StaticSource & | out_static
| ) |  |

Sets the source of the source item as a StaticSource (static value).

Parameters:

  in_vValue | The value of the AnimationSourceItem.

Return values:

  out_static | The newly created StaticSource.

Returns:
  CStatus::OK success
  CStatus::Fail failure

Example:
  Illustrates some of the different ways you can work with the value of an AnimationSourceItem's StaticSource, from creating using AddSourceItem and SetAsStaticValue to editing an existing static value using the GetSournce/PutSource combo.

            using namespace XSI;

            // Forward declarations
            CString GetRelativeName( Parameter& in_param );
            void MakeStaticActionSource();
            void PrintClipInfo( Clip& in_clip );
            void PrintSourceInfo( ActionSource& in_src );

            Application app;

            // NewScene command
            CValueArray cargs; CValue oarg;
            cargs.Add( L"" ); cargs.Add( false );
            app.ExecuteCommand( L"NewScene", cargs, oarg );
            cargs.Clear(); oarg.Clear();

            // Get the SceneRoot
            Model root = app.GetActiveSceneRoot();
            CString rootName = root.GetFullName();

            // New static ActionSource
            MakeStaticActionSource();
            Null n = root.FindChild( L"", siNullPrimType, CStringArray() );

            // Get the ActionSource from the model & instantiate it as a clip
            CRefArray sources = root.GetSources();
            ActionSource src( sources.GetItem(0) );

            // AddClip command
            CValueArray clipArgs; CValue outClip;
            clipArgs.Add( rootName );
            clipArgs.Add( src.GetRef().GetAsText() );
            clipArgs.Add( rootName );                               // Simple clips take the model as compound owner
            app.ExecuteCommand( L"AddClip", clipArgs, outClip );

            // Find the clip
            Mixer mxr = root.GetMixer();
            CRefArray cliplist = mxr.GetClips();
            Clip clp(cliplist[0]);
            app.LogMessage( L"BEFORE source modifications:" );
            PrintClipInfo( clp );

            // Get the AnimationSourceItem
            CRefArray srcitems = src.GetItems();
            AnimationSourceItem oldSrcItem( srcitems.GetItem(0) );

            // Use the AnimationSourceItem::GetSource function to get the StaticSource and then change its value
            StaticSource sv( oldSrcItem.GetSource() );
            sv.PutValue( CValue(2.5) );

            // Print the values on the action source after modifications to the source
            app.LogMessage( L"AFTER source modifications:" );
            PrintClipInfo( clp );

            // Expected results:
            //INFO : BEFORE source modifications:
            //INFO : Reporting on Mixer.Mixer_Anim_Track.Action_Clip clip:
            //INFO :  - Source used = Sources.Scene_Root.Action
            //INFO :  --- SrcItem #0 target = MyAnimatedNull.kine.local.posx and its datasource is a StaticSource
            //INFO :             (evaluates to 0)
            //INFO :  --- SrcItem #1 target = MyAnimatedNull.kine.local.posy and its datasource is a StaticSource
            //INFO :             (evaluates to 1)
            //INFO :  --- SrcItem #2 target = MyAnimatedNull.kine.local.posz and its datasource is a StaticSource
            //INFO :             (evaluates to 2)
            //INFO :
            //INFO : AFTER source modifications:
            //INFO : Reporting on Mixer.Mixer_Anim_Track.Action_Clip clip:
            //INFO :  - Source used = Sources.Scene_Root.Action
            //INFO :  --- SrcItem #0 target = MyAnimatedNull.kine.local.posx and its datasource is a StaticSource
            //INFO :             (evaluates to 2.5)
            //INFO :  --- SrcItem #1 target = MyAnimatedNull.kine.local.posy and its datasource is a StaticSource
            //INFO :             (evaluates to 1)
            //INFO :  --- SrcItem #2 target = MyAnimatedNull.kine.local.posz and its datasource is a StaticSource
            //INFO :             (evaluates to 2)
            //INFO :

            // Function to remove the name of the model from the FullName of the specified parameter.
            // This is necessary when setting up a source that will later be used to instantiate a
            // clip when the parameter lives under a model other than the Scene_Root.
            CString GetRelativeName( Parameter& in_param )
            {
                Model mdl = in_param.GetModel();
                CString mdlname = mdl.GetFullName();
                if ( mdlname.IsEqualNoCase(L"Scene_Root") ) {
                    return in_param.GetFullName();
                } else {
                    CString tmp = in_param.GetFullName();
                    CString lookfor = mdlname + L".";
                    CString foundsofar = L"";
                    CString relpath = L"";
                    for ( ULONG i=0; i<tmp.Length(); ++i ) {
                        if ( foundsofar.IsEqualNoCase(lookfor) ) {
                            relpath += tmp[i];
                        } else {
                            foundsofar += tmp[i];
                        }
                    }
                    return relpath;
                }
            }

            // Create a simple actionsource based on static values
            void MakeStaticActionSource()
            {
                Application app;
                Model root = app.GetActiveSceneRoot();
                Null n; root.AddNull( L"MyAnimatedNull", n );

                // Get the relative names for the parameter targets
                Parameter posx = n.GetParameter( L"posx" ); CString rposx = GetRelativeName(posx);
                Parameter posy = n.GetParameter( L"posy" ); CString rposy = GetRelativeName(posy);
                Parameter posz = n.GetParameter( L"posz" ); CString rposz = GetRelativeName(posz);

                // Create an empty action source
                ActionSource src = root.AddActionSource();

                // Populate it with a static value using ActionSource::AddSourceItem (default=0.0)
                src.AddSourceItem( rposx );

                // Populate it with a specified static value using ActionSource::AddSourceItem
                src.AddSourceItem( rposy, double(1.0), true );

                // Populate it with the default static value, then set a real value later with AnimationSourceItem::SetAsStatic
                AnimationSourceItem animsrcitem = src.AddSourceItem( rposz );
                animsrcitem.SetAsStatic( CValue(2.0), StaticSource() );
            }

            // Convenience function to print out information about the clip's source
            void PrintClipInfo( Clip& in_clip )
            {
                Application app;

                // Clip
                app.LogMessage( L"Reporting on " + in_clip.GetFullName() + L" clip:" );

                // Clip's source
                PrintSourceInfo( ActionSource(in_clip.GetSource()) );
            }

            // Convenience function to print out information about the source
            void PrintSourceInfo( ActionSource& in_src )
            {
                Application app;

                // Source
                app.LogMessage( L" - Source used = " + in_src.GetFullName() );

                // Source's items
                CRefArray itemsRef = in_src.GetItems();
                for ( LONG i=0; i<itemsRef.GetCount(); ++i ) {
                    AnimationSourceItem animsrcitm( itemsRef[i] );
                    app.LogMessage( L" --- SrcItem #" + CString(i) + L" target = " + animsrcitm.GetTarget() + L" and its datasource is a " + animsrcitm.GetSource().GetClassIDName() );

                    // Underlying data source is an FCurve
                    if ( animsrcitm.GetSource().GetClassID() == siFCurveID ) {
                        FCurve fc( animsrcitm.GetSource() );
                        app.LogMessage( L"            (evaluates to " + fc.Eval( CTime(30.0) ).GetAsText() + L" at frame 30)" );
                    }

                    // Underlying data source is a StaticSource
                    if ( animsrcitm.GetSource().GetClassID() == siStaticSourceID ) {
                        StaticSource sv( animsrcitm.GetSource() );
                        app.LogMessage( L"            (evaluates to " + sv.GetValue().GetAsText() + L")" );
                    }
                }

                // Extra blank line
                app.LogMessage( L"" );
            }

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

- xsi_animationsourceitem.h