# Delta Class Reference

Related Scripting Object: Delta | Supported Parameter List: model_delta

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

`#include <xsi_delta.h>`

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

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

## 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:

- xsi_delta.h