Clip Class Reference
 
 
 
Clip Class Reference

This reference page is linked to from the following overview topics: Softimage 2013, What is an Output Argument?.


#include <xsi_clip.h>


Class Description

Clips are instances of animation and shape actions (ActionSource), audio and image sources (Source) and compound clips (ClipContainer).

You can check to see the clip type (such as an audio clip) using SIObject::GetType which returns one of the values contained in the ::siClipType enum.

This class also provides access to clip features such as its timing (TimeControl), any links to other clips (ClipRelation), and any applied effects (ClipEffect). In addition, you can get the underlying source on which this clip is instantiated (the Source object via Clip::GetSource) or the elements of that source (using either the MappedItem object via Clip::GetMappedItems or the AnimationSourceItem object via ActionSource::GetItems).

Attention:
While a Clip object represents compound, audio, and image clips, not all Clip members are available for these types. For example, the GetMappedItems function returns an empty array when called on audio and image clips.
Tip:
There is no function in the C++ API to create clips from sources, but you can use the AddClip command, which returns a Clip object. To access existing Clip objects, you can get a CRefArray of clips in the Mixer via ClipContainer::GetClips.
See also:
ClipContainer, Model::GetMixer, Source, AddClip, ClipContainer::GetClips, Track::GetClips, CopyClipToTrack, AddAudioClip, ImportAudioAndAddClip, ApplyShapeKey, SaveShapeKey
Since:
4.0
Example:
Demonstrates how to create a Clip using the AddClip command and how to find that clip in the mixer using ClipContainer::GetClips. The clip will contain the static values of the local position of a cube.
                using namespace XSI;

                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 and create a cube in it
                Model root = app.GetActiveSceneRoot();
                X3DObject myCube; root.AddGeometry( L"Cube", L"MeshSurface", L"MyCube", myCube );

                // We need the relative name of the pos parameters to set up a proper source
                Parameter posx = myCube.GetParameter( L"posx" ); CString rposx = GetRelativePath(posx);
                Parameter posy = myCube.GetParameter( L"posy" ); CString rposy = GetRelativePath(posy);
                Parameter posz = myCube.GetParameter( L"posz" ); CString rposz = GetRelativePath(posz);

                // Set up a source on the cube's pos parameters using static values
                ActionSource src = root.AddActionSource( L"MyStoredStaticSource" );
                src.AddSourceItem( rposx, double(1.0), true );
                src.AddSourceItem( rposy, double(0.0), true );
                src.AddSourceItem( rposz, double(-2.5), true );

                // Instantiate the source with the AddClip command
                CValueArray clpArgs(9); CValue clpOut;
                clpArgs[0] = root.GetFullName();
                clpArgs[1] = src.GetFullName();
                app.ExecuteCommand( L"AddClip", clpArgs, clpOut );

                // Now find the clip through the mixer
                Mixer mxr = root.GetMixer();
                CRefArray cliplist = mxr.GetClips();
                for ( LONG i=0; i<cliplist.GetCount(); ++i ) {
                        Clip clp( cliplist[i] );
                        app.LogMessage( clp.GetFullName() + L" is a " + clp.GetType() );

                        // Since a give clip may be a compound clip, it may be necessary to drill down
                        if ( clp.GetType() == siClipAnimCompoundType || clp.GetType() == siClipShapeCompoundType ) {
                                // First convert the clip to a clipcontainer
                                ClipContainer compoundclip( cliplist[i] );
                                CRefArray subclips = compoundclip.GetClips();
                                for ( LONG j=0; j<subclips.GetCount(); ++j ) {
                                        Clip clp2( subclips[j] );
                                        app.LogMessage( clp2.GetFullName() + L" is a " + clp2.GetType() );
                                        // ... and so on
                                }
                        }
                }

                // Expected result:
                //INFO : Clip # 1 is a mixeranimclip: Mixer.Mixer_Anim_Track.MyStoredStaticSource_Clip
Inheritance diagram for Clip:
ProjectItem SIObject CBase ClipContainer ImageClip2 Mixer

List of all members.

Public Member Functions

  Clip ()
  ~Clip ()
  Clip (const CRef &in_ref)
  Clip (const Clip &in_obj)
bool  IsA (siClassID in_ClassID) const
siClassID  GetClassID () const
Clip operator= (const Clip &in_obj)
Clip operator= (const CRef &in_ref)
TimeControl  GetTimeControl () const
Source  GetSource () const
CRefArray  GetMappedItems () const
ClipEffect  GetEffect () const
Property  AddProperty (const CString &in_preset, bool in_bBranch=false, const CString &in_name=CString())
CRefArray  GetProperties () const

Constructor & Destructor Documentation

Clip ( )

Default constructor.

~Clip ( )

Default destructor.

Clip ( const CRef in_ref )

Constructor.

Parameters:
in_ref constant reference object.
Clip ( const Clip 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 ProjectItem.

Reimplemented in ClipContainer, ImageClip2, and Mixer.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Reimplemented from ProjectItem.

Reimplemented in ClipContainer, ImageClip2, and Mixer.

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

Reimplemented from ProjectItem.

Reimplemented in ClipContainer, ImageClip2, and Mixer.

TimeControl GetTimeControl ( ) const

Returns the TimeControl property associated with this clip.

Returns:
The TimeControl property object.
Source GetSource ( ) const

Returns the Source object which is instantiated by this clip. For example, if the clip is an instance of an ActionSource (ie., an animation or shape AnimationSourceItem), then the ActionSource object is returned. If the clip is an instance of an audio or image source, the Source object is returned.

Note:
The source returned here stores animation, audio, or image data. This is not the same as the animation data that is driving the parameter, such as an FCurve or a ShapeKey. To access those DataSource elements, use MappedItem::GetAnimationSource on the Clip::GetMappedItems items.
Returns:
The Source or ActionSource instantiated by this clip.
CRefArray GetMappedItems ( ) const

Returns the array of MappedItem objects which are driven by this clip.

Warning:
If you try to use GetMappedItems on an audio source (siClipAudioType), you will get an error. You can test for the audio source type with SIObject::GetType.
Returns:
Array of MappedItem objects.
ClipEffect GetEffect ( ) const

Returns the ClipEffect associated with this clip.

Returns:
The ClipEffect associated with this clip.
See also:
GetMappingRule, SetMappingRule
Property AddProperty ( const CString in_preset,
bool  in_bBranch = false,
const CString in_name = CString() 
)

Adds a UserDataBlob or CustomProperty to the Clip. This can be useful for storing custom user data inside the scene.

Parameters:
in_preset Preset name or name of a self-installed CustomProperty. The type of property that is created is determined by this argument. For example, CustomProperty creates an empty CustomProperty and UserDataBlob creates a UserDataBlob. It is also possible to specify the name of a CustomProperty that is installed as a PluginItem.
in_bBranch False is the only supported value.
in_name Optional name for the new property (SIObject::GetName). If no name is specified the name is determined based on the value for in_preset.
Returns:
The new Property object.
See also:
SceneItem::AddProperty, Clip::GetProperties
CRefArray GetProperties ( ) const

Returns an array of all applied Property objects on the object. A Clip may have nested CustomProperty or UserDataBlob properties.

See also:
SceneItem::GetProperties, Clip::AddProperty

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