Playback Controls

Playback Controls are fundamentally a set of parameters that control how the user moves around in the timeline and how the scene is played back. This set of parameters is contained in the Play Control property set (its scripting name is PlayControl). Some of the most useful parameters include:

  • Current: Contains the current frame number (see Getting and Changing the Current Frame).
  • In and Out: Contain the first and last frame numbers (see Moving Around in the Timeline).
  • Loop: True for continuous playback (looping).
  • Step: Sets the interval at which frames are played back in the viewport. A value of 2 causes the viewports to display only every second frame in the viewport during playback.
  • Format and Rate: Control the frame rate for the PAL, NTSC, Film, and HDTV formats (see Controlling the Frame Rate and Format for more information).
  • KeepFrameTiming: Determines whether to save fcurve keys in frames (relative) or seconds (absolute).
  • OnFrameChangeCommand: Allows you to run simple VBScript code each time the frame changes (see Running Commands During Playback at Each Frame Change for more information).
NOTE: PlayControl does not have a special class implemented in the object model or C++ API. Most functionality is available via scripting commands, but you can also access it in the object model and the C++ API like any other Property object (or Property class), which is demonstrated in Accessing the PlayControl Property Set.


Table of contents

Accessing the PlayControl Property Set

The PlayControl property set is one of the scene-level properties; that is, it remembers how you want the scene to play back. Because it is scene-level, it can be identified by name directly, it does not need any other namespace (for example, GetValue("PlayControl") (http://softimage.wiki.avid.com/sdkdocs/GetValue.htm)).

TIP: The SIObject.Name (http://softimage.wiki.avid.com/sdkdocs/SIObject_Name.htm) (SIObject::GetName (http://softimage.wiki.avid.com/sdkdocs/sicppsdk/html/classXSI_1_1SIObject.html)) of the PlayControl property set is "Play Control" (with space) but its SIObject.FullName (http://softimage.wiki.avid.com/sdkdocs/SIObject_FullName.htm) (SIObject::GetFullName (http://softimage.wiki.avid.com/sdkdocs/sicppsdk/html/classXSI_1_1SIObject.html)) is "PlayControl" (without space). This distinction is important to remember when you are trying to access it because you use the Name to identify it from the list of properties but you use the FullName otherwise as explained below.

Like other properties in XSI, you can either read and write its parameter data values directly or get a pointer to the Property (http://softimage.wiki.avid.com/sdkdocs/Property.htm) object (Property (http://softimage.wiki.avid.com/sdkdocs/sicppsdk/html/classXSI_1_1Property.html) in the C++ API) and then use the Parameter (http://softimage.wiki.avid.com/sdkdocs/Parameter.htm) object (or Parameter (http://softimage.wiki.avid.com/sdkdocs/sicppsdk/html/classXSI_1_1Parameter.html) class) to get and set data.


Accessing Parameter Values Directly

You can get and set PlayControl parameter values directly using the GetValue (http://softimage.wiki.avid.com/sdkdocs/GetValue.htm) and SetValue (http://softimage.wiki.avid.com/sdkdocs/SetValue.htm) commands using the Name (PlayControl) of the PlayControl property set.


VBScript Example: Accessing a PlayControl Parameter Value Directly Using the GetValue and SetValue Commands

' VBScript (command access)
dim near_dist
near_dist = GetValue( "PlayControl.NearDist" ) ' GetValue only returns data values for Parameters

' Double the distance threshold value
SetValue "PlayControl.NearDist", near_dist*2
NOTE: The C++ API also provides functions that read and write data values directly, but you still need a pointer to the PlayControl property first.


Getting a Pointer to the PlayControl Property via Dictionary.GetObject (OM Only)

The Dictionary.GetObject (http://softimage.wiki.avid.com/sdkdocs/Dictionary.GetObject.htm) method uses the Name (PlayControl) of the PlayControl property set to identify which object to get. Because PlayControl is a scene-level property, there is always only one per scene, so there is no namespace needed.

Once you have a pointer to the Property you can use PlayControl.Parameters (http://softimage.wiki.avid.com/sdkdocs/PlayControl_Parameters.htm) to access each Parameter (http://softimage.wiki.avid.com/sdkdocs/Parameter.htm). You can get and set parameter values using the Parameter.Value (http://softimage.wiki.avid.com/sdkdocs/Parameter_Value.htm) property.


JScript Example: Getting a Pointer to PlayControl via Dictionary.GetObject

// JScript (object model access)
var remote_control = Dictionary.GetObject( "PlayControl" );
var curr_frame = remote_control.Parameters( "Current" ); ' Dictionary.GetObject returns a pointer to the specified Parameter

// Find out what the current frame is
Application.LogMessage( "Current frame: " + curr_frame.Value );

// Go to frame 10, and then the last frame
curr_frame.Value = 10.0;
curr_frame.Value = remote_control.Parameters( "Out" ).Value;


Getting a Pointer to the PlayControl Property via the Current Project's Properties

Both the C++ API and the object model provide access via the collection of scene-level properties from the current (active) project. The object model uses the XSIProject (http://softimage.wiki.avid.com/sdkdocs/XSIProject.htm) object and the C++ API uses the Project (http://softimage.wiki.avid.com/sdkdocs/sicppsdk/html/classXSI_1_1Project.html) class. The trick with this approach is that, unlike the other strategies, you identify the PlayControl property set by its FullName (Play Control), as the examples below demonstrate.

Using the object model, once you have a pointer to the Property you can use PlayControl.Parameters (http://softimage.wiki.avid.com/sdkdocs/PlayControl_Parameters.htm) to access each Parameter (http://softimage.wiki.avid.com/sdkdocs/Parameter.htm) and then get and set parameter values using the Parameter.Value (http://softimage.wiki.avid.com/sdkdocs/Parameter_Value.htm) property.

Using the C++ API, once you have a pointer to the Property you can use any of the functions available to the Property (http://softimage.wiki.avid.com/sdkdocs/sicppsdk/html/classXSI_1_1Property.html) class to get a pointer to the Parameter (http://softimage.wiki.avid.com/sdkdocs/sicppsdk/html/classXSI_1_1Parameter.html) class (GetParameter or GetParameters) or read and write parameter values (GetParameterValue and PutParameterValue).


Python Example: Getting a Pointer to Play Control via the Current Project's Properties

# Get the current project
app = Application
prj = app.ActiveProject

# The PlayControl property set is stored with scene data under the project
proplist = prj.Properties
playctrl = proplist("Play Control")

# Remember that the fullname of PlayControl is different from its name:
app.LogMessage( "PlayControl's Name: " + playctrl.Name );
app.LogMessage( "PlayControl's FullName: " + playctrl.FullName );

# Expected result
#INFO : PlayControl's Name: Play Control
#INFO : PlayControl's FullName: PlayControl


C++ API Example: Getting a Pointer to Play Control via the Current Project's Properties

// Get the current project
Application app;
Project prj = app.GetActiveProject();

// The PlayControl property set is stored with scene data under the project
CRefArray proplist = prj.GetProperties();
Property playctrl( proplist.GetItem(L"Play Control") );

// Remember that the fullname of PlayControl is different from its name:
app.LogMessage( L"PlayControl's Name: " + playctrl.GetName() );
app.LogMessage( L"PlayControl's FullName: " + playctrl.GetFullName() );

// Expected result
//INFO : PlayControl's Name: Play Control
//INFO : PlayControl's FullName: PlayControl


Getting and Changing the Current Frame

The current frame value is contained in a parameter named Current and can be accessed directly, via the GetValue (http://softimage.wiki.avid.com/sdkdocs/GetValue.htm) and SetValue (http://softimage.wiki.avid.com/sdkdocs/SetValue.htm) commands (as discussed in Accessing Parameter Values Directly) or through the OM Parameter (http://softimage.wiki.avid.com/sdkdocs/Parameter.htm) object and the C++ API Parameter (http://softimage.wiki.avid.com/sdkdocs/sicppsdk/html/classXSI_1_1Parameter.html) class, as demonstrated in the examples below.

Parameters are available from the Property object and the Property class (see Accessing the PlayControl Property Set for details on how to get a pointer to the PlayControl property).


VBScript Example: Getting the Current Frame

' VBScript (command access)
dim curr_frame
curr_frame = GetValue( "PlayControl.Current" ) ' GetValue only returns data values for Parameters

' Go to frame 10, and then the last frame
SetValue "PlayControl.Current", 10.0 
SetValue "PlayControl.Current", GetValue( "PlayControl.Out" )


JScript Example: Getting the Current Frame

// JScript (object model access)
var remote_control = ActiveProject.Properties( "PlayControl" );
var curr_frame = remote_control.Parameters( "Current" ); // returns a pointer to the specified Parameter

// Find out what the current frame is
Application.LogMessage( "Current frame: " + curr_frame.Value );

// Go to frame 10, and then the last frame
curr_frame.Value = 10.0;
curr_frame.Value = remote_control.Parameters( "Out" ).Value;


Moving Around in the Timeline

There are a series of commands that move to frames or keys. These are the scripting equivalent of the playback control buttons for moving to the next frame or key. These are:

  • FirstFrame (http://softimage.wiki.avid.com/sdkdocs/FirstFrame.htm)
  • PrevFrame (http://softimage.wiki.avid.com/sdkdocs/PrevFrame.htm)
  • NextFrame (http://softimage.wiki.avid.com/sdkdocs/NextFrame.htm)
  • LastFrame (http://softimage.wiki.avid.com/sdkdocs/LastFrame.htm)

Frame navigation buttons)

These commands are basically shortcuts for changing the PlayControl.Current parameter value to the target frame number. For example, assuming you are on frame 18 and you want to go to the next frame. You can either use the NextFrame command or set the PlayControl.Current parameter to 19.

There is another series of commands that do not represent a simple parameter change. These navigate through the timeline based on the fcurve keys set:

  • FirstKey (http://softimage.wiki.avid.com/sdkdocs/FirstKey.htm)
  • PrevKey (http://softimage.wiki.avid.com/sdkdocs/PrevKey.htm)
  • NextKey (http://softimage.wiki.avid.com/sdkdocs/NextKey.htm)
  • LastKey (http://softimage.wiki.avid.com/sdkdocs/LastKey.htm)

Key navigation buttons)


Starting the Playback in Any Direction

Playback controls also provide different options for how the scene should be played back. These commands reproduce the functionality of the playback control buttons on the Playback Panel in the UI:

  • PlayForwardsFromStart (http://softimage.wiki.avid.com/sdkdocs/PlayForwardsFromStart.htm)
  • PlayForwards (http://softimage.wiki.avid.com/sdkdocs/PlayForwards.htm)
  • PlayFrame (http://softimage.wiki.avid.com/sdkdocs/PlayFrame.htm)
  • PlaybackStop (http://softimage.wiki.avid.com/sdkdocs/PlaybackStop.htm)
  • PlayBackwards (http://softimage.wiki.avid.com/sdkdocs/PlayBackwards.htm)
  • PlayBackwardsFromEnd (http://softimage.wiki.avid.com/sdkdocs/PlayBackwardsFromEnd.htm)
  • PlayRealTime (http://softimage.wiki.avid.com/sdkdocs/PlayRealTime.htm)
  • PlayRealTimeFromStart (http://softimage.wiki.avid.com/sdkdocs/PlayRealTimeFromStart.htm)

Key navigation buttons)


Changing the PlayControl Options

There are four basic things you can change to fine-tune the playback:

  • the timing
  • the precision
  • how the fcurve keys are stored
  • the list of scene elements to draw

These options are simply parameters on the PlayControl (http://softimage.wiki.avid.com/sdkdocs/xsiparams/PlayControl.html) property and can therefore be changed using the same methods demonstrated in Playback Controls#Getting and Changing the Current Frame.


Controlling the Frame Rate and Format

The playback frame rate and format (The speed at which frames are displayed) are used only for the playback interaction in XSI. These playback options take the default settings made in the Output Format property, but you can change them as required for playback without affecting the default frame format and rate set for the scene.

There are four standard frame rate formats described by the numerical value contained in the Format parameter. Specifying the custom frame rate format allows the user to define a non-standard frame rate in the Rate parameter value:


Format parameter value Description Rate parameter value (frames per second)
7 FILM format 24 fps
8 PAL format 25 fps
10 NTSC format 29.97 fps
11 Custom format frame rate defined by user
19 HDTV format 30 fps


TIP: The Format parameter values correspond to the siDefaultTimeFormat (http://softimage.wiki.avid.com/sdkdocs/siDefaultTimeFormat.htm) enum, but these are the values that are logged when using the SetValue (http://softimage.wiki.avid.com/sdkdocs/SetValue.htm) command.


These can be accessed directly via the GetValue (http://softimage.wiki.avid.com/sdkdocs/GetValue.htm) and SetValue (http://softimage.wiki.avid.com/sdkdocs/SetValue.htm) commands (as discussed in Accessing Parameter Values Directly) or through the OM Parameter (http://softimage.wiki.avid.com/sdkdocs/Parameter.htm) object and the C++ API Parameter (http://softimage.wiki.avid.com/sdkdocs/sicppsdk/html/classXSI_1_1Parameter.html) class, as demonstrated in the examples below.

JScript Example: Finding the Current Frame Rate

// JScript (command access)
var format = GetValue( "PlayControl.Format" );
var results = "Current frame: ";

switch (format) {
   case 10 : results += " NTSC (29.97 fps)"; break;
   case 8 : results += " PAL (25 fps)"; break;
   case 7 : results += " FILM (24 fps)"; break;
   case 19 : results += " HDTV (30 fps)"; break;
   case 11 : results += " Custom (User ticks per second)";
   default : results = "Unknown format!";
}
Application.LogMessage( results );

// Expected results:
//INFO : Current frame:  FILM (24 fps)


Python Example: Setting a Custom Frame Rate

# Python (command access)
app = Application
app.SetValue( "PlayControl.Format", 11  # switch to custom format
app.SetValue( "PlayControl.Rate", 10 ) # set rate to 10 frames per second


C++ Example: Changing the Current Frame Rate

// Get the current project
Application app;
Project prj = app.GetActiveProject();

// The PlayControl property set is stored with scene data under the project
CRefArray proplist = prj.GetProperties();
Property playctrl( proplist.GetItem(L"Play Control") );

// Switch to PAL format (25 frames per second)
playctrl.PutParameterValue( L"Format", 8.0 );


Running Commands During Playback at Each Frame Change

You may need to run a quick command at every frame change during playback, such as logging some scene information based on the current animation. There is a parameter on the PlayControl property set which can hold a simple VBScript snippet that will run whenever the frame changes. This is the OnFrameChangeCommand parameter (see VBScript Example: Logging an Object’s Position at Each Frame Change).

NOTE: This parameter is only triggered during playback. If you are looking for an event that will be triggered by a frame change during rendering, you must implement an event handler for the OnBeginFrame or OnEndFrame event. For more information, see A Note About Event Handlers for Rendering.


VBScript Example: Logging an Object’s Position at Each Frame Change

This example logs the null's position in 3 separate calls to Application.LogMessage.

TIP: VBScript is the only supported language for this command. Note that since VBScript marks the end of lines with a return character, if you want to run more than a one-line command you must separate each line of code with vbCrLf (VBScript enum for the return character).


dim cmd2run
cmd2run = "Application.LogMessage GetValue(" & Chr(34) & "null.kine.local.posx" & Chr(34) & ")" & vbCrLf _
   & "Application.LogMessage GetValue(" & Chr(34) & "null.kine.local.posy" & Chr(34) & ")" & vbCrLf _
   & "Application.LogMessage GetValue(" & Chr(34) & "null.kine.local.posz" & Chr(34) & ")"
SetValue "PlayControl.OnFrameChangeCommand", cmd2run


A Note About Event Handlers for Rendering

If you need to run something at every frame update during rendering, you can use one of these events (for more information about how to implement these events, see Custom Events (http://softimage.wiki.avid.com/sdkdocs/cus_events.htm)):

  • OnBeginFrame--triggered before a frame gets rendered. These events are registered with the siOnBeginFrame enum (from the siEventID (http://softimage.wiki.avid.com/sdkdocs/siEventID.htm) enum).
  • OnEndFrame--triggered after a frame gets rendered. These events are registered with the siOnEndFrame enum (from the siEventID (http://softimage.wiki.avid.com/sdkdocs/siEventID.htm) enum).
TIP: If you want a frame change during rendering to trigger an event, you must use either the siOnBeginFrame or siOnEndFrame event handlers. The OnFrameChangeCommand parameter is only triggered during playback.



This page was last modified 14:10, 21 Oct 2008.
This page has been accessed 9802 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy