Delta Class Reference
 
 
 
Delta Class Reference

#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:
ProjectItem SIObject CBase

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]

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]

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 )

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 )

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

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 )

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 )

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 )

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

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

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 )

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

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 )

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

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: