Parameter Performance Optimization

Always get the parameters from the primary owner

Parameters are accessed in the Softimage SDK through the ProjectItem class. This class is the base for most of the SDK classes and allow writing generic and reusable code. While it always pay off to write generic code, it also comes with a performance cost when it comes down to parameter access. To optimize the performance we recommend to always get the parameters from their primary owner i.e the immediate parent of the parameters.

Consider the Camera object for instance which has several children objects where each have their own parameters. You can write some generic code like this to get the camera's X position:

Application app;
Model model = app.GetActiveSceneRoot();
ProjectItem camera = model.GetChild(L"Camera");
Parameter posx = camera.GetParameters().GetItem("posx");
app.LogMessage( posx.GetValue().GetAsText() );

The call to ProjectItem::GetParameters navigates the whole camera hierarchy and collects all the parameters nested under the camera including the primitive, camera display, kinematics, visibility, etc. It would be preferable to get the parameters directly from the camera's local KinematicState object instead which holds the posx parameter. Doing so, Softimage will not navigate all camera children objects but only the kinematic property where posx is defined.

Application app;
Model model = app.GetActiveSceneRoot();
Camera camera = model.GetChild(L"Camera");
KinematicState ks = camera.GetKinematics().GetLocal();
Parameter posx = ks.GetParameters().GetItem("posx");
app.LogMessage( posx.GetValue().GetAsText() );

Single parameter access

ProjectItem::GetParameterValue and Parameter::GetParameterValue are typically used for accessing a minimum number of parameters. As opposed to GetParameters which traverses the entire hierarchy of the target object in order to cache all visited node parameters, GetParameterValue only looks for a specific parameter and returns its value as soon as the parameter is located.

GetParameterValue doesn't use a cache, therefore the overhead that would be required to build the cache (potentially huge) is avoided since only one parameter value is requested. Use GetParameterValue only in scenarios when a very few number of parameters are involved.

Application app;
Model model = app.GetActiveSceneRoot();
Camera camera = model.GetChild(L"Camera");

// Wrong way of getting a single parameter value. This 
// will traverse the entire camera parameter hierarchy and 
// cache all parameters

Parameter fov = camera.GetParameters().GetItem(L"fov");
app.LogMessage( fov.GetValue().GetAsText() );

// Suggested way of getting a single parameter value.
CValue val = camera.GetParameterValue(L"fov");
app.LogMessage( val.GetAsText() );