Public Member Functions
Source Class Reference

## Detailed Description

Sources are references to data which are instantiated. For example, a shape source becomes a ShapeClip in the animation mixer when it is instantiated there.

There are several types of sources:

Action animation:
  Stores animation data with the RelativeName of a parameter. For example, an action animation source, when instantiated, may include an fcurve driving an object's position in space over time, etc. Action animation is a specialized kind of Source object called an ActionSource object--see the ActionSource documentation for more details.

Shape animation:
  Stores shape data on point clusters relative to the reference shape in ShapeKeys. Shape animation is a specialized kind of Source object called an ActionSource object--see the ActionSource documentation for more details.

Audio files:
  Audio sources add to the scene content when instantiated (rather than modifying scene data like action and shape animation). Audio sources contain references to audio files (supported formats: `*`.aiff/.aif, `*`.aifc, `*`.avi, `*`.mov, `*`.qt, and `*`.wav).

Image files:
  Image sources add to the scene content when instantiated (rather than modifying scene data like action and shape animation). Image sources contain references to image files (see the Image object for more details).

See also:
  Clip::GetSource, ActionSource, Model::GetSources, AddImageSource, ImportAudio

Since:
  4.0

Example:
  Illustrates how to retrieve the image file name used for the texture of an object. It also illustrates how to retrieve the x and y resolution of that image.

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

            // Create an image source and clip
            CValueArray shrArgs(5); CValue shrOut;
            shrArgs[1] = myCube.GetFullName();
            shrArgs[3] = CValue(3.0); //siUnspecified;
            shrArgs[4] = CValue(3.0); //siLetLocalMaterialsOverlap;
            app.ExecuteCommand( L"ApplyShader", shrArgs, shrOut );

            CValueArray prjArgs(8); CValue prjOut;
            prjArgs[0] = myCube.GetFullName();
            prjArgs[1] = CValue(4.0); //siTxtSpherical;
            prjArgs[2] = CValue(4.0); //siTxtDefaultSpherical;
            prjArgs[3] = L"Texture_Projection";
            prjArgs[5] = CValue(0.0); //siRelDefault;
            app.ExecuteCommand( L"CreateProjection", prjArgs, prjOut );

            CValueArray txtArgs(9); CValue txtOut;
            txtArgs[1] = myCube.GetFullName();
            txtArgs[2] = CValue(1.0);
            txtArgs[3] = true;
            txtArgs[3] = CValue(1.0); //siReplaceAndBlendInPreset;
            app.ExecuteCommand( L"BlendInTextureLayers", txtArgs, txtOut );

            // Get the source and the clip
            CRefArray mats = myCube.GetMaterials();
            Material mat( mats[0] );
            ImageClip2 imgClip = mat.GetCurrentImageClip2 ();
            Source imgsrc( imgClip.GetSource() );

            // Log some info
            app.LogMessage( L"Fullname of source: " + imgsrc.GetFullName() );
            Parameter filename = imgsrc.GetParameter( L"FileName" );
            Parameter xres = imgsrc.GetParameter( L"XRes" );
            Parameter yres = imgsrc.GetParameter( L"YRes" );
            app.LogMessage( L"The image filename is " + filename.GetValue().GetAsText() );
            app.LogMessage( L"The image x resolution is " + xres.GetValue().GetAsText() );
            app.LogMessage( L"The image y resolution is " + yres.GetValue().GetAsText() );

            // Expected result:
            //INFO : Fullname of source: Sources.noIcon_pic
            //INFO : The image filename is S:\Application\rsrc\noIcon.pic
            //INFO : The image x resolution is 256
            //INFO : The image y resolution is 256

Example:
  Demonstrates how to find all sources in the scene when there are several levels of models all with their own sources. Something to note is that only ActionSources are returned from the Model.

            using namespace XSI;

            // Forward declarations
            CRefArray SearchEveryModel( Model& in_model );
            CString GetRelativeNameForTarget( Parameter& in_param );
            void CreateShapeAction( Model& in_model );
            void CreateAudioSource( Model& in_model );
            void CreateImageSource( Model& in_model );

            Application app;

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

            // Set up the scene
            Model root = app.GetActiveSceneRoot();
            CRefArray dummy;
            Model m1; root.AddModel( dummy, L"Larry", m1 );
            Model m2; m1.AddModel( dummy, L"Curly", m2 );
            Model m3; m2.AddModel( dummy, L"Moe", m3 );
            CreateShapeAction( m2 );
            CreateImageSource( m1 );
            CreateAudioSource( m3 );

            // Start with the top level model (the Scene_Root) and the use the Models property
            // to search recursively. Since all action sources are stored under the model, once
            // we've visited each model, we will have found each source in the scene.
            CRefArray allsources = SearchEveryModel( root );
            if ( allsources.GetCount() > LONG(0) ) {
                app.LogMessage( L"SearchEveryModel results: " + allsources.GetAsText() );
            }

            // Expected Results:
            //INFO : MODEL: Scene_Root
            //INFO : MODEL: Larry
            //INFO : MODEL: Curly
            //INFO : MODEL: Moe
            //INFO : SearchEveryModel results: Curly.Mixer.ShapeKey,Curly.Mixer.Shape_ClusterClip_source,
            //Curly.Mixer.ShapeKey1,Curly.Mixer.ShapeKey2

            CRefArray SearchEveryModel( Model& in_model )
            {
                Application app;
                app.LogMessage( L"MODEL: " + in_model.GetFullName() );

                // Start with the top-level model
                // Get a CRefArray of all sources found under this model
                CRefArray results;
                CRefArray foundsrcs = in_model.GetSources();
                if ( foundsrcs.GetCount() > LONG(0) ) {
                    // We can just copy the whole array over
                    results = foundsrcs;
                }

                // For every model nested within this scene, check it for sources
                CRefArray modellist = in_model.GetModels( true );
                for ( LONG i=0; i<modellist.GetCount(); ++i ) {
                    Model mdl( modellist[i] );
                    app.LogMessage( L"MODEL: " + mdl.GetFullName() );

                    CRefArray morefound = mdl.GetSources();
                    if ( morefound.GetCount() > LONG(0) ) {
                        // We can append the whole array to the one we already have
                        results += morefound;
                    }
                }

                // Return the CRefArray
                return results;
            }

            // This is a handy function to have around if you're going to create an action
            // source or clip on a parameter that is in a nested model (ie., not directly
            // under the Scene_Root) because AddClip will force a mapping template if your
            // parameter is not relative.
            CString GetRelativeNameForTarget( 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;
                }
            }

            // Helper functions to create & instantiate sources
            void CreateShapeAction( Model& in_model )
            {
                Application app;
                X3DObject obj; in_model.AddGeometry( L"Sphere", L"NurbsSurface", L"MySphere", obj );

                // SetSelFilter command
                CValueArray args; CValue out;
                args.Add( L"Point" );
                app.ExecuteCommand( L"SetSelFilter", args, out );

                // CreateCluster command
                CValueArray args1; CValue out1;
                args1.Add( obj.GetFullName() + L".pnt[(5,4),(6,4),(7,4),(0,5),(1,5),(2,5),(3,5),(4,5),(5,5),(6,5),(7,5),(0,6),(1,6),(2,6),(3,6)]" );
                app.ExecuteCommand( L"CreateCluster", args1, out1 );

                // StoreShapeKey
                CValueArray args2(8); CValue out2;
                args2[0] = out1;
                args2[1] = L"MyShape";
                args2[2] = 1.0;         //siShapeObjectReferenceMode
                app.ExecuteCommand( L"StoreShapeKey", args2, out2 );
            }

            void CreateAudioSource( Model& in_model )
            {
                Application app;
                CString mdlname = in_model.GetFullName();

                // Get the mixer
                Mixer mixmaster;
                if ( in_model.HasMixer() ) {
                    mixmaster = in_model.GetMixer();
                } else {
                    mixmaster = in_model.AddMixer();
                }

                // AddTrack command
                CValueArray trkArgs; CValue trkOut;
                trkArgs.Add( mdlname );
                trkArgs.Add( mixmaster.GetFullName() );
                trkArgs.Add( CValue(2.0) );
                app.ExecuteCommand( L"AddTrack", trkArgs, trkOut );
                Track aud_track( trkOut );

                // ImportAudio command
                CValueArray impArgs; CValue impOut;
                impArgs.Add( mdlname );
                impArgs.Add( L"C:\\Program Files\\Messenger\\NEWALERT.WAV" );
                app.ExecuteCommand( L"ImportAudio", impArgs, impOut );
                Source aud_src( impOut );

                // AddAudioClip command
                CValueArray clpArgs; CValue clpOut;
                clpArgs.Add( mdlname );
                clpArgs.Add( aud_src.GetFullName() );
                clpArgs.Add( mixmaster.GetFullName() );
                clpArgs.Add( aud_track.GetFullName() );
                clpArgs.Add( CValue(22.0) );
                app.ExecuteCommand( L"AddAudioClip", clpArgs, clpOut );
            }

            void CreateImageSource( Model& in_model )
            {
                Application app;
                X3DObject cube; in_model.AddGeometry( L"Cube", L"MeshSurface", L"MyCube", cube );

                // ApplyShader command
                CValueArray shdrArgs(5); CValue shdrOut;
                shdrArgs[3] = 3.0;              //siUnspecified
                shdrArgs[4] = 3.0;              //siLetLocalMaterialsOverlap
                app.ExecuteCommand( L"ApplyShader", shdrArgs, shdrOut );

                // CreateProjection command
                CValueArray txtArgs(8); CValue txtOut;
                txtArgs[0] = cube.GetFullName();
                txtArgs[1] = 4.0;           //siTxtSpherical
                txtArgs[2] = 4.0;           //siTxtDefaultSpherical
                txtArgs[3] = L"";
                txtArgs[4] = L"Texture_Projection";
                txtArgs[6] = 0.0;           //siRelDefault
                app.ExecuteCommand( L"CreateProjection", txtArgs, txtOut );

                // BlendInTextureLayers command
                CValueArray blndArgs(9); CValue blndOut;
                blndArgs[0] = L"Image";
                blndArgs[1] = cube.GetFullName();
                blndArgs[2] = CValue(1.0);
                blndArgs[3] = false;
                blndArgs[4] = 1.0;          //siReplaceAndBlendInPreset
                blndArgs[5] = true;
                blndArgs[6] = true;
                blndArgs[7] = false;
                blndArgs[8] = false;
                app.ExecuteCommand( L"BlendInTextureLayers", blndArgs, blndOut );
            }

`#include <xsi_source.h>`

Inheritance diagram for Source:
[legend]

List of all members.

## Public Member Functions
| Source ()
| ~Source ()
| Source (const CRef &in_ref)
| Source (const Source &in_obj)
bool | IsA (siClassID in_ClassID) const
siClassID | GetClassID () const
Source & | operator= (const Source &in_obj)
Source & | operator= (const CRef &in_ref)
Property | AddProperty (const CString &in_preset, bool in_bBranch=false, const CString &in_name=CString())
CRefArray | GetProperties () const

## Constructor & Destructor Documentation

Source | ( |  | ) |

Default constructor.

~Source | ( |  | ) |

Default destructor.

Source | ( | const CRef & | in_ref | ) |

Constructor.

Parameters:

  in_ref | constant reference object.

Source | ( | const Source & | 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 Library, and MaterialLibrary.

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

Returns the type of the API class.

Returns:
  The class type.

Reimplemented from ProjectItem.

Reimplemented in Library, and MaterialLibrary.

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

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

Reimplemented from ProjectItem.

Reimplemented in Library, and MaterialLibrary.

Property AddProperty | ( | const CString & | in_preset,
|  | bool | in_bBranch = `false`,
|  | const CString & | in_name = `CString()`
| ) |  |

Adds a property such as a UserDataBlob or CustomProperty to the Source. This can be useful for storing custom user data inside the scene.

Note:
  Only CustomPropertyPresets CustomProperty Presets, UserDataBlobPresets UserDataBlob Presets, and UserDataMapPresets UserDataMap Presets are valid for sources.

Parameters:

  in_preset | Either the name of a PropPreset Property Preset or a string with the filename or full path to a Preset file. The type of property that is created is determined by this argument. For example, `"CustomProperty"` creates an empty CustomProperty and `"UserDataBlob"` creates a UserDataBlob.
  in_bBranch | False is the only supported value
  in_name | Represents the name of the new property (see SIObject::Name). If not specified the object is named based on the value specified for `in_preset`.

See also:
  Source::GetProperties, SceneItem::AddProperty

CRefArray GetProperties | ( |  | ) | const

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

See also:
  Source::AddProperty, SceneItem::GetProperties

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

- xsi_source.h