External mover plugins
Movers can live in a separate repository and register with RigExec through a shared library. The host discovers the library through OpenUSD's plugin registry. Each registered type supplies a parameter assembly callback and a points computation; no changes to RigExec's built-in mover list are required.
Use the same compiler, architecture, build configuration, OpenUSD installation,
and RigExec SDK as the host. Plugin API version 8 spells the handler's schema
type as std::string_view. Libraries built for API 1, 2 or 3 must be rebuilt
and migrate their assembly callback; libraries built for API 4 through 7 must
be rebuilt, since the handler grew (and, before 6, the playback kernel) and 8
changes the layout of its first field. The loader rejects a library whose
metadata names another version before it loads the library.
declareExternalInputs runs only at compilation and declares ordered typed
RigExecRevisionLeafKey records. Each record specifies its canonical property
path, type, time policy, read flavour and missing-value fallback. Declared scalar
inputs receive normal evaluator override numbers; array inputs follow the
existing public and private array admission policy.
assembleExternal receives RigExecExternalInputContext: the immutable binding,
explicit provider values and sampled input values in declaration order. It must
compute a payload without querying a stage, registry or mutable shared state.
applyExternal computes the full-strength candidate from that payload and the
preceding points. The engine owns enable, envelope and failure handling.
Oracle handlers receive phasedPoints and phasedMatrix lookups with the exact
provider path, authored phase and reader identity. A preceding read of the
oracle's own target uses entering; the first revision falls back to base.
The lookups expose current-generation finished publications and bound record
versions supplied by the adapter. Cached values alone do not establish a
finished publication.
Build a mover repository¶
rigexec_add_mover builds a registered module with a separate USD-free kernel
archive and USD adapter plugin. The kernel definition supplies a State type,
Prepare returning std::shared_ptr<const State>, and Apply taking
const State & followed by the arguments of RigExecExternalKernel::apply.
Definitions receiving provider values implement ApplyWithProviders instead.
Temporal definitions also implement CaptureWindow and ApplyWindow with
typed state references. RigExecMakeMoverKernel<Definition>() generates the
ABI adapters. The prepared state is immutable; per-run work stays local to
the graph body. The decoder validates the mover's own payload version.
rigexec_add_mover(MyMover
DEFINITION kernel.h
TYPE my::MoverDefinition
KERNEL kernel.cpp
USD_ADAPTER moverUsd.cpp
FACTORY MakeMyMoverUsdAdapter
SCHEMA schema.usda
SCHEMA_TYPE MyMover)
The adapter exports rigExec::MakeMyMoverUsdAdapter(std::string_view
schemaType) returning a RigExecMoverHandler. It supplies scene binding,
declared inputs, payload assembly, encoding, and native application through
the shared kernel.
Generated code supplies the schema name, installs the typed runtime kernel,
and registers the handler when the plugin loads. The adapter does not call
RIGEXEC_REGISTER_MOVER for that same type. Existing manually registered
plugins continue to work.
The build runs generateMoverSchema.py with the Python interpreter selected
by Python3_EXECUTABLE. It reads schema.usda and generates
MyMoverSchema.h: the schema type, attribute
names/types/variability, and typed default constants. A property's : becomes
_, so inputs:gain becomes MyMoverSchema::inputs_gain. Adapters consume
these defaults when declaring leaves. Read time, read phase, provider binding,
and computational semantics remain explicit adapter contracts. Scalars,
tokens, numeric vectors, matrices, and their supported arrays are emitted as
USD-free constants; unsupported defaults fail generation. Use SCHEMA_DEPENDS
for additional local schema layers. SCHEMA_READS lists further schema types
(an API schema or a related prim type) whose defaults the adapter reads; their
constants are emitted in nested namespaces named after the type. Schema plugins
must set skipCodeGeneration = true; the helper runs usdGenSchema when the
OpenUSD install has Python bindings and packages its codeless resources beside
the adapter plugin. Against a Python-less install it reads the schema text
directly instead: one concrete class inheriting </Typed>, emitting
identical headers and documentation-free resources. Anything outside that
shape fails naming the construct, so a richer schema still needs a
Python-enabled OpenUSD.
The generated MyMoverRegistration.h declares RigExecDefineMyMover().
Standalone hosts link MyMoverKernel and pass an array of these definitions
to the RigExecRuntimeReader::Open(bytes, size, definitions, count, error)
overload. The runtime binds definitions once at Open, permits unused module
definitions, and rejects duplicate names or failed preparation. It retains
the existing per-reader replacement API. Keep module code loaded while its
readers exist. USD hosts discover the adapter through normal plugin metadata.
Within RigExec, BUILTIN adds the adapter to the USD library and the kernel to
the runtime. Direct factory references in the generated catalog retain the
kernel objects in static links. Registration and discovery occur before
execution; graph bodies perform no registry lookup. Existing binary opcodes
and payloads retain their meanings. The typed module contract currently uses
the external mover's full-strength whole-buffer execution and common envelope;
built-ins with specialized range or weighting semantics retain their existing
operation contracts.
NO_INSTALL, PLUGIN_ROOT, and LIBRARIES apply to the USD plugin;
KERNEL_LIBRARIES supplies USD-free kernel dependencies. Installation includes
the kernel archive, generated public headers, schema resources, and a
MyMover CMake package exporting rigExecMovers::MyMoverKernel. The complete
test module exercises separate
sources, generated schema defaults, automatic discovery, native/frozen parity,
and standalone playback. Its optional exporter output regenerates
tests/fixtures/registeredMover.rigexec for the USD-free playback test.
In the external repository, create a CMakeLists.txt:
cmake_minimum_required(VERSION 3.26)
project(MyMovers LANGUAGES CXX)
if(NOT TARGET rigExec::rigExec)
find_package(rigExec CONFIG REQUIRED)
endif()
rigexec_add_mover_plugin(MyMovers SOURCES mover.cpp)
rigexec_add_mover_plugin links rigExec::rigExec, enables C++17, generates
OpenUSD plugin metadata, and installs the library and metadata. Add
LIBRARIES otherTarget for dependencies or NO_INSTALL for a build-only plugin.
Use PLUGIN_ROOT path to place build metadata under a separate discovery root,
for example ${CMAKE_BINARY_DIR}/test-plugins for a test fixture. Relative paths
resolve from the current binary directory. The default root is
${CMAKE_BINARY_DIR}/usd/rigExecMoverPlugins.
The target property RIGEXEC_PLUGIN_RESOURCE_DIR contains its generated
resources path, including a CMake configuration generator expression.
To include that repository in the main usdRig build, set its actual location before invoking the existing helper. For example, in PowerShell:
Or in a POSIX shell:
For manual CMake configuration, pass
-DRIGEXEC_MOVER_PLUGIN_DIRS=/path/to/mover-plugins with the normal build
arguments. Multiple repositories use a quoted semicolon-separated list. Each
directory must contain a CMakeLists.txt that defines its mover plugin targets.
The build and launch helpers include build/usd/rigExecMoverPlugins in
PXR_PLUGINPATH_NAME, so these plugins are discovered when launching usdview.
The same repository can build independently against an installed SDK:
cmake -S /path/to/mover-plugins -B mover-build -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
"-DCMAKE_PREFIX_PATH=/path/to/rigexec-install;/path/to/usd-install"
cmake --build mover-build
cmake --install mover-build --prefix /path/to/mover-install
Implement and register a mover¶
This complete mover.cpp translates the preceding point revision by an
animated inputs:offset. Its payload uses GfVec3f, which already supports
the value comparison needed by VtValue and the evaluation cache.
#include "rigExec/movers/moverRegistry.h"
#include "rigExecScene/sceneDescriptors.h"
#include <cmath>
PXR_NAMESPACE_USING_DIRECTIVE
using namespace rigExec;
namespace {
// Interned once: building a token from text locks the token registry.
const TfToken kOffset("inputs:offset");
bool Validate(const RigExecMoverValidateContext &ctx, std::string *error)
{
const UsdAttribute attr = ctx.prim.GetAttribute(kOffset);
if (!attr || attr.GetTypeName() != SdfValueTypeNames->Float3) {
*error = "SampleOffsetMover requires float3 inputs:offset";
return false;
}
return true;
}
void DeclareInputs(const RigExecMoverBindContext &ctx,
std::vector<RigExecRevisionLeafKey> *inputs)
{
inputs->push_back({ctx.moverPrim.GetPath().AppendProperty(kOffset),
RigExecRevisionLeafType::Vec3f, RigExecRevisionLeafTime::AtTime,
RigExecRevisionLeafFlavour::Resolved, VtValue(GfVec3f(0))});
}
bool CompileScene(const RigExecSceneDescriptors &scene,const SdfPath &mover,
const SdfPath &,RigExecRevisionBinding *binding,std::string *error)
{
const auto path=mover.AppendProperty(kOffset);
const auto found=scene.attributes.find(path);
if(found==scene.attributes.end() || found->second.fact.type!=SdfValueTypeNames->Float3) {
*error="SampleOffsetMover requires float3 inputs:offset";return false;
}
binding->externalInputs={{path,RigExecRevisionLeafType::Vec3f,
RigExecRevisionLeafTime::AtTime,RigExecRevisionLeafFlavour::Resolved,VtValue(GfVec3f(0))}};
return true;
}
bool Assemble(const RigExecExternalInputContext &ctx, VtValue *data)
{
if (ctx.inputs.size() != 1 || !ctx.inputs[0].IsHolding<GfVec3f>()) return false;
const auto &offset = ctx.inputs[0].UncheckedGet<GfVec3f>();
if (!std::isfinite(offset[0]) || !std::isfinite(offset[1]) || !std::isfinite(offset[2])) return false;
*data = VtValue(offset);
return true;
}
bool Apply(const VtValue &data, std::vector<GfVec3f> *points)
{
if (!points || !data.IsHolding<GfVec3f>()) return false;
const GfVec3f &offset = data.UncheckedGet<GfVec3f>();
for (GfVec3f &point : *points) point += offset;
return true;
}
RigExecMoverHandler MakeHandler()
{
RigExecMoverHandler handler(
"SampleOffsetMover", RigExecFixedMoverOp<RigExecRevisionOp::External>,
RigExecMoverDomain::Points);
handler.singleTarget = true;
handler.hasScalarOracle = false;
handler.validate = Validate;
handler.declareExternalInputs = DeclareInputs;
handler.compileScene = CompileScene;
handler.assembleExternal = Assemble;
handler.applyExternal = Apply;
return handler;
}
RIGEXEC_REGISTER_MOVER(MakeHandler());
} // namespace
Registration keeps a copy of the handler and its type name. Duplicate names,
missing callbacks, and external handlers outside the points domain are rejected.
Hosts that need a returned registration error can call
RigExecRegisterMoverHandler(handler, &error) directly. Keep every plugin
library loaded for the lifetime of its evaluators and payload values.
assembleExternal computes an immutable, equality-comparable payload from its
sampled declarations. Only compilation and the engine's sampling boundary may
query the source scene. Custom payloads must be copyable and equality-comparable.
applyExternal performs pure, thread-safe computation over that payload and
the incoming points. Preserve the point count and produce a full-strength
candidate. RigExec handles inputs:enabled, inputs:defaultWeight, and the
weight-object envelope. Returning false fails the mover and preserves the
preceding revision. Optional bind, validate, and oracle callbacks support
additional bindings, compile checks, and scalar parity comparisons; omit an
oracle only when reporting that parity comparison is unavailable is acceptable.
Author a plugin mover¶
Use the registered type name and apply RigExecMoverAPI. A separate generated
USD schema is optional; it can provide defaults and richer authoring tools, but
the evaluator accepts the registered type with explicitly authored attributes.
#usda 1.0
def Xform "Asset"
{
def RigExecRoot "Rig"
{
def SampleOffsetMover "Offset" (
prepend apiSchemas = ["RigExecMoverAPI"]
)
{
rel rigExec:moves = </Asset/Geom.points>
float inputs:defaultWeight = 1
float3 inputs:offset = (0, 1, 0)
}
}
def Mesh "Geom"
{
point3f[] points = [(0, 0, 0), (1, 0, 0), (0, 1, 0)]
int[] faceVertexCounts = [3]
int[] faceVertexIndices = [0, 1, 2]
uniform token subdivisionScheme = "none"
}
}
The generic validator checks the native UsdGeomPointBased point3f[] target
and the handler's single-target rule before the custom validator runs. Mover
ordering and envelopes follow the same rules as built-in geometry movers.
A plugin schema can give its types a node-editor icon. Declare it on the class
and ship the image in the schema plugin's resources; the usdNoodles editor shows
it on every prim of that type, or of a type derived from it, that authors no
ui:nodegraph:node:icon. An authored icon still wins.
class MySampleOffsetMover "MySampleOffsetMover" (
inherits = </Typed>
customData = {
dictionary extraPlugInfo = {
string nodeGraphIcon = "icons/sample_offset_mover.png"
}
}
)
{
}
usdGenSchema copies extraPlugInfo into the type's plugInfo.json entry, and
nodeGraphIcon is a path relative to that plugin's resources directory. The
RigExec schema declares its own node types' icons the same way.
Export and play back a plugin mover¶
A .rigexec file is played by a runtime that has no stage, so it cannot call
assembleExternal. Two optional handler fields let a rig holding the mover
export and replay:
encodeExternalruns once at export, on the payloadassembleExternalproduced at the bake time. It splits the payload into compiled data bytes and frame bytes. Both are written once, and playback hands the kernel the same frame bytes on every run. When the handler also setsencodeExternalCompiledData, that callback supplies the compiled data bytes from the binding alone.runtimeKernelis the playback half, declared inrigExecBinary/external.hwithout any USD types.preparedecodes a revision's compiled data bytes each time a kernel is installed;applyrevises the preceding points in place from that state, the frame bytes, and the points the binding reads at a declared phase.
The bytes are the plugin's own format; RigExec stores them without reading
them. Start the compiled data bytes with a format tag so prepare can refuse bytes it
does not understand. Points named in binding.phases reach apply as playback
evaluated them, so a playback posed through SetInput moves them; frame bytes
can still carry the value the export read, for a phase playback holds no value
at. API4 also passes declared input values, typed and in declaration order,
with their actual availability and element count. Kernels must validate the
input tag and count before reading data, and prefer the current declared
input over encoded frame bytes. Default-time declarations retain their
Default read policy. The runtime applies inputs:enabled and the envelope,
and fails the mover for that frame when apply returns false or produces a
non-finite point.
A mover whose result follows its influences or its transform provider sets
runtimeKernel.applyWithProviders instead of apply. Playback then also
hands it RigExecExternalProviders: the binding's transform and influence
matrices as playback evaluated them at the binding's phase, and the chain's
base points, the values assembleExternal receives as
RigExecExternalProviderValues. The built-in RigExecLayeredSkinMover,
RigExecSurfaceBindingMover and RigExecPatchMover play this way: their kernels rebuild the payload
with their own assembleExternal logic and deform with applyExternal's, so
playback matches native evaluation bit for bit and a posed playback follows
the providers.
Extending the offset mover above:
#include <cstring>
bool Encode(const VtValue &data, const RigExecRevisionBinding &,
std::vector<uint8_t> *compiledData, std::vector<uint8_t> *frame)
{
if (!data.IsHolding<GfVec3f>()) return false;
compiledData->assign({'O', 'F', 'F', '1'});
frame->resize(sizeof(GfVec3f));
std::memcpy(frame->data(), data.UncheckedGet<GfVec3f>().data(),
frame->size());
return true;
}
std::shared_ptr<const void> Prepare(const uint8_t *compiledData, size_t size,
std::string *error)
{
if (size != 4 || std::memcmp(compiledData, "OFF1", 4) != 0) {
if (error) *error = "not OFF1 compiled data";
return nullptr;
}
return std::make_shared<int>(1);
}
bool Play(const void *, const uint8_t *frame, size_t frameSize,
const RigExecExternalPhasedPoints *, size_t,
const RigExecExternalInputValue *inputs, size_t inputCount,
float *xyz, size_t count)
{
float offset[3];
if (frameSize != sizeof(offset)) return false;
std::memcpy(offset, frame, sizeof(offset));
if (inputCount != 1 || inputs[0].type != uint8_t(RigExecExternalInputType::Vec3f) ||
!inputs[0].hasValue || !inputs[0].data || inputs[0].count != 1) return false;
std::memcpy(offset, inputs[0].data, sizeof(offset));
for (size_t i = 0; i < count * 3; ++i) xyz[i] += offset[i % 3];
return true;
}
// In MakeHandler():
// handler.encodeExternal = Encode;
// handler.runtimeKernel.prepare = Prepare;
// handler.runtimeKernel.apply = Play;
Export fails, naming the mover, when its plugin provides no encodeExternal
or an encoding callback returns false. When assembly fails at the bake time,
the file holds no frame bytes for the mover: playback passes the kernel null
frame bytes, and fails the mover when it declares no inputs.
A host that opens a .rigexec file installs kernels with
RigExecRuntimeReader::SetExternalKernel(type, kernel), by the type name the
plugin registered. GetExternalMoverTypes() lists the types a file holds and
GetMissingExternalKernels() the ones still without a prepared kernel. The
usdview playback path installs runtimeKernel from every loaded plugin. A mover
whose type has no kernel in the runtime is a no-op: its points pass through
unchanged, and every Execute adds a warning: line naming the mover to the
reader's diagnostics. A runtime built without USD carries a kernel only if it
links one in: Open installs the modules in RigExec's generated catalog (the
cloth mover), and the host installs any other.
Kernels may be installed or replaced after execution. The next Execute
updates the affected revisions and their consumers, even when inputs are
unchanged; independent operations retain their cached results. If a replacement
cannot prepare a revision, that revision returns to passing its points through
on the next execution. A later successful registration restores its evaluation.
Replacing a temporal revision clears its own retained history packets, whose
layout belongs to the previous kernel. Refill its history before evaluating a
frame that needs earlier ticks.
Temporal movers¶
A mover whose result at a frame depends on the frames before it -- a
simulation, a lag -- is a temporal mover. It declares how many earlier frames
it reads (windowFrames, at compile, and windowFramesScene, the same count
from captured scene facts for the scene program), the packet a frame captures
from its payload and entering points (captureWindow), and the solve over the
earlier frames' packets, oldest first, then the current one (applyWindow);
all four or none. The earlier frames are generations of the same compiled graph
at those times, run only as far as the mover's inputs reach, so the history is
produced by the one loop and the result is a pure function of the window:
scrubbing, playback and background caching agree. applyWindow receives a
cache slot the revision owns for a compiled rig build; anything held there
must not change the answer. An optional applyWindowDevice runs the same solve
on a device; the live program calls it at the publication boundary, never from
an operation body, and falls back to applyWindow. For .rigexec playback,
RigExecExternalKernel::captureWindow and applyWindow mirror the two
callbacks; the reader keeps the packets (PushHistory, ExecuteHistory,
ClearHistory). The built-in cloth mover is written this way; see
secondary motion and cloth.
Discovery and supported evaluation¶
For an independent build, add mover-build/usd/rigExecMoverPlugins to
PXR_PLUGINPATH_NAME. For an installed plugin, add
/path/to/mover-install/lib/usd/rigExecMoverPlugins. Include the plugin and
dependency library directories in the host's library search path, including
/path/to/mover-install/lib in Windows PATH. Path lists use semicolons on
Windows and colons on Linux/macOS. Keep the host's existing schema and imaging
plugin paths as well.
The generated plugInfo.json marks the library with
"Info": {"RigExecMoverPlugin": 8}. RigExec loads discoverable mover libraries
on the first unknown handler lookup. Hosts can call
RigExecLoadMoverPlugins(&diagnostics) explicitly to inspect version or load
errors. After adding search locations with
PlugRegistry::GetInstance().RegisterPlugins(path), call the loader again to
discover those additional libraries.
API4 external point callbacks execute from compiled immutable bindings and
declared typed inputs in native and frozen jobs. Exported playback also needs
the runtime callbacks. encodeExternalCompiledData encodes immutable compile facts
without requiring successful initial dynamic input sampling; unavailable inputs
can recover on later frames. Property-mover plugin callbacks are outside this
point-mover API.
A plugin's tests can export and replay its rigs by linking
rigExec::rigExecBake and rigExec::rigExecRuntime, which are available both
inside the usdRig build and from an installed SDK.
When integrating a mover, check the independent reference and exact golden results, animated and connected
inputs, override updates, envelope weights, disabled behavior, and failure
pass-through. If it exports, check that playback matches the independently captured published pose on
every played frame and when posed through SetInput. Also check that an unavailable
library or incompatible plugin version produces a diagnostic instead of a
successful deformation.
API4 requires compileScene for normalized standalone compilation. It receives
owned composed RigExecSceneDescriptors, fills immutable binding facts and the
ordered typed externalInputs, and retains no source access. The same
assembleExternal and applyExternal callbacks run in native, frozen and
detached graphs. Plugins declare any auxiliary source-only schema types in
sceneDataSchemas; those records remain data rather than extra operations.
Every attribute a binding lists in externalStructure is watched: its type,
sample count and connections are digested. A uniform one recompiles when its
Default value changes. A varying one is a per-frame input (a weight array, a
UV primvar): a value edit stays neutral, and only a sample or spline change
recompiles.
externalCompileSources lists the attributes whose Default value is resolved
into externalCompileData (a setup transform composed from xform operations,
say). Editing one recompiles even when it is varying, because its value is
digested. List a source in externalStructure as well when the baked program
must also name it. The digest hashes a dictionary payload by value, so facts
the adapter resolves at compile belong in externalCompileData, and the
attributes they come from in externalCompileSources. Both compilers must
produce them identically. Build paths only for attributes the compile
actually read; do not list every attribute of a prim.