#include <xsi_delta.h>

Class Description

The Delta object represents a 'diff' or list of modifications to a reference model.

These are grouped into types of changes called ActionDelta objects, which have a unique type similar to the Parameter::GetSource type (see siModificationDeltaType) and changes to Overrides (which are stored in a parameter called 'PropertiesAddedToRefModel' under the Delta property), etc.

Modifications stored in an override are used to save static modifications, such as a new material.

Modifications stored in an ActionDelta are related to animation, such as FCurves, Constraints, etc.

Delta properties are stored under the model and each model can only have one delta associated to it, so to access a delta, use the SIObject::GetNestedObjects on the model. When the user makes a change to a value or source on a parameter in a reference model, a new Delta is automatically created containing an ActionDelta with the ActionDeltaItem to store the change.

To create a new delta you can use the AddDelta command. You can also import a delta using the ImportDelta or ImportReferencedDelta commands.

Since:: 6.0

Example:

Illustrates how to assign a new value to an ActionDeltaItem

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

                //Add cube geometry and create the reference model
                Model root = app.GetActiveSceneRoot();
                X3DObject myCube, myCone;
                root.AddGeometry( L"Cube", L"MeshSurface",L"",myCube);

                // CreateModelAndConvertToRef command
                CString strFactPath = app.GetInstallationPath(siProjectPath) ;
                        strFactPath += L"/Models/MyModel.emdl";
                cargs.Add( myCube.GetFullName() ); cargs.Add( strFactPath );
                app.ExecuteCommand( L"CreateModelAndConvertToRef", cargs, oarg );
                cargs.Clear();

                Delta myDelta;

                // AddDelta command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"AddDelta", cargs, oarg );
                cargs.Clear();
                myDelta = oarg;

                // Translate command
                cargs.Add(myCube.GetFullName()); cargs.Add(2.0); cargs.Add(1.3); cargs.Add(0.0);
                cargs.Add(L"siRelative"); cargs.Add(L"siView"); cargs.Add(L"siObj"); cargs.Add(L"siXYZ");
                app.ExecuteCommand( L"Translate", cargs, oarg );
                cargs.Clear();

                ActionDelta ActionDelta0 = myDelta.GetActionDeltas().GetItem(0);
                CRefArray ActionDeltaItems = ActionDelta0.GetItems();
                CString strmgs;
                for ( LONG i=0; i<ActionDeltaItems.GetCount(); ++i ) {

                        ActionDeltaItem item = ActionDeltaItems[i];

                        // Print info about the current ActionDeltaItem
                        strmgs = L"ActionSourceItem["; strmgs += CValue(i).GetAsText(); strmgs += L"]";
                        Application().LogMessage(strmgs);
                        strmgs = L"Name: "; strmgs += item.GetName();
                        Application().LogMessage(strmgs);
                        strmgs = L"Type: "; strmgs += item.GetType();
                        Application().LogMessage(strmgs);

                        //Print the current value
                        strmgs = L"Initiale Value: "; strmgs += item.GetValue();
                        Application().LogMessage(strmgs);

                        // Change the value of the item
                        item.PutValue ( 1.2 * i );

                        //Print the new value
                        strmgs = L"New value: "; strmgs += item.GetValue();
                        Application().LogMessage(strmgs);
                }
                // File to save delta
                CString deltaFile = app.GetInstallationPath(siProjectPath) + L"/Deltas/MyDelta.delta";
                myDelta.Save (deltaFile );

Inheritance diagram for Delta:

List of all members.

Public Member Functions
	Delta ()
	~Delta ()
	Delta (const CRef &in_ref)
	Delta (const Delta &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Delta &	operator= (const Delta &in_obj)
Delta &	operator= (const CRef &in_ref)
CStatus	Save (const CString &in_FileName)
CStatus	Load (const CString &in_FileName)
CStatus	Apply () const
ActionDelta	AddAction (siModificationDeltaType in_type)
CStatus	RemoveAction (siModificationDeltaType in_type)
CStatus	AddOverrideFromPreset (const CString &in_Preset)
CStatus	RemoveOverride ()
CString	GetTarget () const
CStatus	PutTarget (const CString &in_Target)
bool	GetMute () const
CStatus	PutMute (const bool in_Mute)
CRefArray	GetActionDeltas () const

Constructor & Destructor Documentation

Delta ( )

Default constructor.

~Delta ( )

Default destructor.

Delta ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

Delta ( const Delta & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

Search for all occurrences

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.

siClassID GetClassID ( ) const [virtual]

Search for all occurrences

Returns the type of the API class.

Returns:: The class type.

Reimplemented from ProjectItem.

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

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

Reimplemented from ProjectItem.

CStatus Save ( const CString & in_FileName )

Search for all occurrences

Saves the Delta (all modifications on the reference model) to the specified file. This file can be used later as external storage or when importing a delta.

Parameters:

in_FileName The filename to save.

Returns:: CStatus::OK success; CStatus::Fail is returned in case of failure

Example:: See Delta main example for an example of how to use this function.

CStatus Load ( const CString & in_FileName )

Search for all occurrences

Loads a Delta (all modifications on the reference model) from the specified file.

Parameters:

in_FileName The name of the file to load.

Returns:: CStatus::OK success; CStatus::Fail is returned in case of failure

Example:

This example demonstrates how to load a delta. Be sure to have a delta saved in Application.InstallationPath( siProjectPath) + "/Deltas/MyDelta.delta" ( you can run the main Delta example to do so ).

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

                //Add cube geometry and create the reference model
                Model root = app.GetActiveSceneRoot();
                X3DObject myCube;
                root.AddGeometry( L"Cube", L"MeshSurface",L"",myCube);

                // CreateModelAndConvertToRef command
                CString strFactPath = app.GetInstallationPath(siProjectPath) ;
                        strFactPath += L"/Models/MyModel.emdl";
                cargs.Add( myCube.GetFullName() ); cargs.Add( strFactPath );
                app.ExecuteCommand( L"CreateModelAndConvertToRef", cargs, oarg );
                cargs.Clear();

                Delta myDelta;

                // AddDelta command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"AddDelta", cargs, oarg );
                cargs.Clear();
                myDelta = oarg;

                // Add an action of type siModificationDeltaStaticValue
                ActionDelta myDeltaAction = myDelta.AddAction(siModificationDeltaStaticValue);

                // Add the Static value item
                ActionDeltaItem myActionDeltaItem = myDeltaAction.AddStaticValueItem ( myCube.GetFullName()
                                + L".kine.global.posx", 10.0);

                // ApplyShader command
                cargs.Add( CValue() ); cargs.Add( L"" );
                cargs.Add( CValue() ); cargs.Add( L"" ); cargs.Add( siLetLocalMaterialsOverlap );
                app.ExecuteCommand( L"ApplyShader", cargs, oarg );
                cargs.Clear();

                // File to load delta from
                CString deltaFile = app.GetInstallationPath(siProjectPath) + L"/Deltas/MyDelta.delta";
                myDelta.Load (deltaFile );

CStatus Apply ( ) const

Search for all occurrences

Applies the Delta to a reference model. Use this function when you add modifications to a delta (for example, using ActionDelta::AddFCurveItem) and you want to apply those changes back to the reference model.

Returns:: CStatus::OK success; CStatus::Fail is returned in case of failure

Example:: See Delta::AddAction for an example of how to use this function.

ActionDelta AddAction ( siModificationDeltaType in_type )

Search for all occurrences

Adds the specified ActionDelta to this Delta.

Note:: Only one ActionDelta for each type is permitted on the Delta. If you try to add an ActionDelta type that already exists, it returns an error with the message "ERROR : 'siModificationDelta' is undefined".

Parameters:

in_type The modification type (siModificationDeltaType)

Returns:: A reference to the new ActionDelta

Example:

This example demonstrates how to add an ActionDelta to a Delta.

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

                //Add cube geometry and create the reference model
                Model root = app.GetActiveSceneRoot();
                X3DObject myCube;
                root.AddGeometry( L"Cube", L"MeshSurface",L"",myCube);

                // CreateModelAndConvertToRef command
                CString strFactPath = app.GetInstallationPath(siProjectPath) ;
                        strFactPath += L"/Models/MyModel.emdl";
                cargs.Add( myCube.GetFullName() ); cargs.Add( strFactPath );
                app.ExecuteCommand( L"CreateModelAndConvertToRef", cargs, oarg );
                cargs.Clear();

                Delta myDelta;

                // AddDelta command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"AddDelta", cargs, oarg );
                cargs.Clear();
                myDelta = oarg;

                // Add an action of type siModificationDeltaStaticValue
                ActionDelta myDeltaAction = myDelta.AddAction(siModificationDeltaStaticValue);

                // Add the Static value item
                ActionDeltaItem myActionDeltaItem = myDeltaAction.AddStaticValueItem ( myCube.GetFullName()
                                + L".kine.global.posx",  10.0);

                // To apply the modification
                myDelta.Apply();

CStatus RemoveAction ( siModificationDeltaType in_type )

Search for all occurrences

Removes the specified ActionDelta from the Delta.

Parameters:

in_type The modification type (siModificationDeltaType)

Returns:: CStatus::OK success; CStatus::Fail is returned in case of failure

Example:: See Delta::RemoveOverride for an example of how to use this function.

CStatus AddOverrideFromPreset ( const CString & in_Preset )

Search for all occurrences

Adds an override to the Delta based on the specified preset.

Deprecated:: 6.5. This method is obsolete and is maintained for informational purposes only. Use AddAction instead.

Note:: If there already an override in the delta, remove it before running this method.

Parameters:

in_Preset Filename of preset

Returns:: CStatus::OK success; CStatus::Fail is returned in case of failure

Example:

Illustrates how to add an override property from a preset

                using namespace XSI;

                // Forward declaration
                void CreateOverridePreset ( const CString &in_presetFile, Application &in_App );

                Application app;

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

                // Preset file path
                CString presetFile = app.GetInstallationPath( siUserPath) +
                                                L"/Data/DSPresets/Properties/Override.Preset";

                // Create and save an override preset
                CreateOverridePreset(presetFile, app);

                //Add cube geometry and create the reference model
                Model root = app.GetActiveSceneRoot();
                X3DObject myCube, myCone;
                root.AddGeometry( L"Cube", L"MeshSurface",L"",myCube);

                // CreateModelAndConvertToRef command
                CString strFactPath = app.GetInstallationPath(siProjectPath) ;
                        strFactPath += L"/Models/MyModel.emdl";
                cargs.Add( myCube.GetFullName() ); cargs.Add( strFactPath );
                app.ExecuteCommand( L"CreateModelAndConvertToRef", cargs, oarg );
                cargs.Clear();

                Delta myDelta;

                // AddDelta command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"AddDelta", cargs, oarg );
                cargs.Clear();

                // Add the override from preset
                myDelta = oarg;
                myDelta.AddOverrideFromPreset ( presetFile );

                //This function create the preset that is going to be add to the Delta
                void CreateOverridePreset ( const CString &in_presetFile, Application &in_App )
                {
                        Model root = in_App.GetActiveSceneRoot();

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

                        // CreateModelAndConvertToRef command
                        CString strFactPath = in_App.GetInstallationPath(siProjectPath) ;
                                strFactPath += L"/Models/MyModel.emdl";
                        CValueArray cargs; CValue oarg;
                        cargs.Add( myCube.GetFullName() ); cargs.Add( strFactPath );
                        in_App.ExecuteCommand( L"CreateModelAndConvertToRef", cargs, oarg );
                        cargs.Clear();

                        // AddProp command
                        cargs.Add( L"Synoptic Property" );
                        cargs.Add( myCube.GetFullName() ); cargs.Add( L"" );
                        in_App.ExecuteCommand( L"AddProp", cargs, oarg );
                        cargs.Clear();

                        // SetValue command
                        cargs.Add( myCube.GetFullName() + L".Synoptic_Property.displayname"); cargs.Add( L"TestName" );
                        in_App.ExecuteCommand( L"SetValue", cargs, oarg );
                        cargs.Clear();

                        // SavePreset command
                        cargs.Add( L"Model.Delta.PropertiesAddedToRefModel" );
                        cargs.Add( in_presetFile );
                        in_App.ExecuteCommand( L"SavePreset", cargs, oarg );
                        cargs.Clear();

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

                }

CStatus RemoveOverride ( )

Search for all occurrences

Removes the stored override from the Delta. Only one override is stored with each Delta inside a property called "PropertiesAddedToRefModel".

Deprecated:: 6.5. This method is obsolete and is maintained for informational purposes only. Use RemoveAction instead.

Returns:: CStatus::OK success; CStatus::Fail is returned in case of failure

Example:

Illustrates how to remove override and action from the Delta.

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

                //Add cube geometry and create the reference model
                Model root = app.GetActiveSceneRoot();
                X3DObject myCube;
                root.AddGeometry( L"Cube", L"MeshSurface",L"",myCube);

                // CreateModelAndConvertToRef command
                CString strFactPath = app.GetInstallationPath(siProjectPath) ;
                        strFactPath += L"/Models/MyModel.emdl";
                cargs.Add( myCube.GetFullName() ); cargs.Add( strFactPath );
                app.ExecuteCommand( L"CreateModelAndConvertToRef", cargs, oarg );
                cargs.Clear();

                Delta myDelta;

                // AddDelta command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"AddDelta", cargs, oarg );
                cargs.Clear();
                myDelta = oarg;

                // Add an action of type siModificationDeltaStaticValue
                ActionDelta myDeltaAction = myDelta.AddAction(siModificationDeltaStaticValue);

                // Add the Static value item
                ActionDeltaItem myActionDeltaItem = myDeltaAction.AddStaticValueItem ( myCube.GetFullName()
                                + L".kine.global.posx",  10.0);

                // AddProp command
                cargs.Add( L"Synoptic Property" );
                cargs.Add( myCube.GetFullName() ); cargs.Add( L"" );
                in_App.ExecuteCommand( L"AddProp", cargs, oarg );
                cargs.Clear();

                myDelta.RemoveOverride();
                myDelta.RemoveAction(siModificationDeltaStaticValue);


                // UpdateReferencedModel command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"UpdateReferencedModel", cargs, oarg );
                cargs.Clear();
                myDelta = oarg;

CString GetTarget ( ) const

Search for all occurrences

Returns the name of the reference model associated to this Delta.

Returns:: The target reference model name.

Example:: See Delta::PutTarget for an example of how to use the GetTarget function.

CStatus PutTarget ( const CString & in_Target )

Search for all occurrences

Sets the name of the reference model associated to this Delta.

Parameters:

in_Target The name of the target reference model.

Returns:: CStatus::OK success; CStatus::Fail is returned in case of failure

Example:

Illustrates how to change the target reference model

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

                //Add cube geometry and create the reference model
                Model root = app.GetActiveSceneRoot();
                X3DObject myCube, myCone;
                root.AddGeometry( L"Cube", L"MeshSurface",L"Proxy3DObj",myCube);

                // CreateModelAndConvertToRef command
                CString strFactPath = app.GetInstallationPath(siProjectPath) ;
                        strFactPath += L"/Models/MyModel.emdl";
                cargs.Add( myCube.GetFullName() ); cargs.Add( strFactPath );
                app.ExecuteCommand( L"CreateModelAndConvertToRef", cargs, oarg );
                cargs.Clear();

                //Create a second reference model with the cone
                root.AddGeometry( L"Cone", L"MeshSurface",L"Proxy3DObj",myCone);
                // CreateModelAndConvertToRef command
                CString strFactPath1 = app.GetInstallationPath(siProjectPath) ;
                        strFactPath1 += L"/Models/MyModel1.emdl";
                app.LogMessage(strFactPath1);
                cargs.Add( myCone.GetFullName() ); cargs.Add( strFactPath1 );
                app.ExecuteCommand( L"CreateModelAndConvertToRef", cargs, oarg );
                cargs.Clear();

                Delta myDelta;

                // AddDelta command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"AddDelta", cargs, oarg );
                cargs.Clear();
                myDelta = oarg;

                // Add an action of type siModificationDeltaStaticValue
                ActionDelta myDeltaAction = myDelta.AddAction(siModificationDeltaStaticValue);

                // Add the Static value item
                ActionDeltaItem myActionDeltaItem = myDeltaAction.AddStaticValueItem ( myCube.GetFullName()
                                + L".kine.global.posx", 10.0);

                // Change the target reference model
                myDelta.PutTarget( myCone.GetModel().GetName() );

                // UpdateReferencedModel command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"UpdateReferencedModel", cargs, oarg );
                cargs.Clear();
                myDelta = oarg;

bool GetMute ( ) const

Search for all occurrences

Returns a boolean value indicating whether the Delta is muted or not.

Returns:: True if the delta is muted; false if it is active

Example:: See Delta::PutMute for an example of how to use the GetMute function.

CStatus PutMute ( const bool in_Mute )

Search for all occurrences

Sets a boolean value indicating whether the Delta is muted or not.

Parameters:

in_Mute True to mute the delta; false to make it active

Returns:: CStatus::OK success; CStatus::Fail is returned in case of failure

Example:

Illustrates how to mute a Delta

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

                //Add cube geometry and create the reference model
                Model root = app.GetActiveSceneRoot();
                X3DObject myCube, myCone;
                root.AddGeometry( L"Cube", L"MeshSurface",L"",myCube);

                // CreateModelAndConvertToRef command
                CString strFactPath = app.GetInstallationPath(siProjectPath) ;
                        strFactPath += L"/Models/MyModel.emdl";
                cargs.Add( myCube.GetFullName() ); cargs.Add( strFactPath );
                app.ExecuteCommand( L"CreateModelAndConvertToRef", cargs, oarg );
                cargs.Clear();

                Delta myDelta;

                // AddDelta command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"AddDelta", cargs, oarg );
                cargs.Clear();
                myDelta = oarg;

                myDelta.PutMute (true);

                app.LogMessage(L"muting " + myDelta.GetName());

                // UpdateReferencedModel command
                cargs.Add( L"Model" );
                app.ExecuteCommand( L"UpdateReferencedModel", cargs, oarg );
                cargs.Clear();

CRefArray GetActionDeltas ( ) const

Search for all occurrences

Returns an array containing each ActionDelta object in the Delta.

Returns:: Array of of references to all ActionDelta objects contained in the delta.

Example:: See Delta main example for an example of how to use the GetActionDeltas function.

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

xsi_delta.h

Class Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation