Auto DOP Nodes

Introduction

Most DOP nodes create and modify option data attached to SIM_Object and SIM_Data instances during the network pass of DOP processing. The DOP_Auto class can construct DOP node interfaces for these operators.

When defining custom Auto DOP nodes several steps must be performed.

• Derive from SIM_Data or one of its subclasses and SIM_OptionsUser. This provides storage for option data and methods for DOP_Auto to discover the individual fields of the option data.
• Define GETSET_DATA_FUNCS_S style macros for the parameters you wish to support.
• Write a static function to create the SIM_DopDescription that will be used by the auto node. The token names in the the PRM_Name of the PRM_Template returned must match the tokens in the GETSET_DATA_FUNCS_S macros.
• Create the macros to invoke the boiler plate for SIM_Data, namely DECLARE_STANDARD_GETCASTTOTYPE and DECLARE_DATAFACTORY.
• Create the macros used to create a data factory for the class, namely IMPLEMENT_DATAFACTORY when the simulation library initializes.

An example of how to construct a simple custom Auto DOP can be seen at SIM/SIM_ElectricalProperties.C.

Guide Geometry

Guide geometry can be added to SIM_Data to provide visual feedback in the viewport. Perform the following to add guide geometry to a custom Auto DOP:

• Add any custom parameters needed to control guide geometry to the SIM_DopDescription using the SIM_DopDescription::setGuideTemplates method. Guide parameters do not modify simulation state and may be modified without causing the simulation to re-cook.
• Override the SIM_Data::buildGuideGeometrySubclass methods with custom implementations build build geometry using the provided GU_DetailHandle. Values for the guide parameters can be queried from the provided SIM_Options.
• Override the SIM_Data::createGuideObjectSubclass with a custom implementation that returns a new object to hold the guide geometry. Return a new SIM_GuidePerObject instance if each object will have different guide geometry. Return a new SIM_GuideShared instance if all objects will have the same guide geometry. Return a SIM_GuideStatic instance if the guide geometry does not change.

An example of how to construct an Auto DOP with custom guide geometry can be seen at SIM/SIM_ForceOrbit.C.

Force Nodes

Force DOPs can be constructed as Auto DOP nodes. To create a force Auto DOP node, perform these steps:

• Create an Auto DOP node by following the steps described in Introduction but derive from SIM_Force instead of SIM_Data.
• Implement the virtual getForce*Subclass() methods defined on SIM_Force to specify the force's desired behavior. Solvers may query any of the getForce*() methods to discover the forces and torques applied to an object. The SIM_Force base class will adjust the forces and torques depending upon mask or noise fields attached to the force.

An example of how to construct a simple custom force Auto DOP can be seen at SIM/SIM_ForceOrbit.C.

Manipulating Auto DOP Data

The Auto DOP nodes allow users to attach a new type of SIM_Data to SIM_Object. This data is not much use if you cannot access it outside of the Auto DOP.

There are two macros to make it easy to both fetch and cast the desired data from an object, SIM_DATA_GET and SIM_DATA_GETCONST. Whenever you want read only access, one should always use SIM_DATA_GETCONST. The SIM_DATA_GET will create a non-const reference that will unique the data across time, a possible waste of memory if the data isn't changing.

Most of the standard DOP data is generated with Auto DOP Nodes. Things such as RBD_State, SIM_Position, etc, can be accessed in the following fashion.

const RBD_State         *state;
const SIM_Object        *obj;
UT_Vector3               pivot;

state = SIM_DATA_GETCONST(*obj,     /* Object to fetch */
                        "Position", /* Path to data to fetch. */
                        RBD_State   /* Type to cast to */
                        );
if (!state)
{
    // Either obj doesn't have subdata called "Position" OR 
    // that data can't be cast into type RBD_State
    pivot = 0.0;
}
else
{
    // We can now access all of the read-only methods of RBD_State.
    // This also includes stuff created by the GETSET_DATA_FUNC_S
    // style macros
    pivot = state->getPivot();
}

The next example shows how to write to the data. It will also create the data if it can't be found. If data exists of the wrong type, it will be deleted and replaced by the RBD_State data.

RBD_State               *state;
SIM_Object              *obj;

state = SIM_DATA_GET(*obj, "Position", RBD_State);
if (!state)
{
    state = SIM_DATA_CREATE(*obj, "Position", RBD_State,
                            0 /* Flags */);
}

state->setPivot(UT_Vector3(0,0,0));

Finally, this example will again create a missing RBD_State. However, it sets the flags to SIM_DATA_RETURN_EXISTING so if it already exists, the current version is used. This is orred with SIM_DATA_ADOPT_EXISTING_ON_DELETE which will try to up-convert any base types into RBD_State. In this way, if SIM_Position is already on the object and is named "Position", it will be converted into an RBD_State and returned.

RBD_State               *state;
SIM_Object              *obj;

state = SIM_DATA_CREATE(*obj, "Position", RBD_State
                        SIM_DATA_RETURN_EXISTING |
                        SIM_DATA_ADOPT_EXISTING_ON_DELETE);

state->setPivot(UT_Vector3(0,0,0));

Adding Subdata to Auto DOP Data

The Auto DOP Nodes by default do not accept any subdata. In the network editor they show up with a single grey input. If it is sensible to attache some types of subdata to them, you can list the types of subdata using the dopdatahint HScript command. The $HFS/houdini/scripts/dophints.cmd has examples of how to setup the valid subdata.

Note that when you add your own dophints.cmd to your HOUDINI_SCRIPT_PATH, only the first dophints.cmd is called. Thus you need to chain into the official dohints.cmd by assing as the final line:

source $HFS/houdini/scripts/dophints.cmd

Instead of adding to the dophints.cmd, you can also directly add hints in C++ in your initializeSIM hook.

SIM_DataHint::addHint(parenttype, childtype, childname, -1);