Functions like CParameterRefArray::GetValue are designed to improve the speed of C++ code that reads and writes Parameters. There has also been a fair amount of optimization within Softimage to provide fast access to Parameter values. However the SDK user also needs some knowledge about how to write fast parameter access code, so here are a few suggestions to help take advantage of parameters in the C++ API:
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() );
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() );