Evaluation and independent checks
RigExec compiles a rig into one operation graph. Native evaluation reads scene
inputs at the owning-thread sampling boundary, then executes operations over
typed values. Frozen evaluation samples those inputs first and runs detached
state through the same graph. A .rigexec binary supplies compiled declarations
and values to the runtime. There is no evaluator mode selector or fallback walk.
Compilation and execution¶
A compiled rig is the operation graph and bindings produced by rig compilation. Control changes and animation frames reuse that compiled rig. Structural edits, such as reconnecting a mover or changing mesh topology, require recompilation and produce a new compiled rig version. Topology and dependency bindings remain fixed for each compiled rig version.
The compiled rig signature identifies its structural bindings for cache
and validity checks. A worker snapshot holds the compiled rig version it was
created from, so later structural edits cannot change the program it runs.
C++ callers read the structural signature with GetCompiledRigSignature();
Python callers use Rig.compiled_rig_signature().
Each operation declares its input and output values. The shared compiler binds reads to exact producers, computes a canonical dependency order, and translates clusters without introducing extra causal dependencies. Descriptor emission order does not require an input producer to be emitted before its consumer. Changed input values activate their downstream operations; unchanged outputs remain available to later generations. Serial and parallel execution use the same graph and readiness rules.
Structural scene edits rebuild the compiled declarations. Cyclic operations are reported by canonical loop keys and set aside; their outputs are cleared so a later or held generation cannot reuse stale cyclic results. Unsupported source declarations or failed compilation produce an invalid pose with a reason, rather than selecting a second evaluator.
Optional independent judges¶
Rig.cpu_reference enables the independent scalar point reference. Its original
arithmetic consumes captured source facts and explicit current-generation
phase values. The pose reports reference_agreements and
reference_mismatches; the C++ pose also holds the reference points in
movedPropertiesCpu. This check does not select a production engine.
rigExecPose --cpu-reference checks that reference coverage matches the
published point chains. --exec-crosscheck checks actual operation rows against
OpenExec requests fed with captured original inputs; see
OpenExec reference checks. Exact golden
verification compares published values, status and ordered semantic
diagnostics against independent original captures;
work counters are outside that value contract. CPU point agreement retains its
existing numerical comparison policy and is separate from exact golden checks.
The golden tool supports --golden-backend native, frozen, or runtime.
Runtime visits also require --golden-program file.rigexec. Each backend uses
the same explicit first, held, forward, reverse, cold and action visit protocol.
An unsupported checker/backend or interactive/runtime combination fails
explicitly.
OpenExec reference checks¶
RigExec builds against OpenExec
and registers computations with it, but production evaluation never runs it.
Native, frozen, frame-cache, .rigexec runtime and standalone evaluation all
compile and execute the shared operation graph. No environment variable or
option selects OpenExec evaluation, and no failure falls back to it. OpenExec
answers only the requests of one optional check and of tests.
What is registered¶
libs/rigExec registers nine value types with ExecTypeRegistry and these
schema computations with EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA:
- Joint, Control and VolumeWeight:
computeRestFrame, the default-space ladder (computedDefaultSpaceand its parent, avar and posed variants, plus expressions on the five*:spacematrices),computePointFrameandcomputeMatrix. - FkChain, TwoBoneIk, BlendPointFrames, TwistDistribution, SplineIk and Ribbon:
computePointFrameArray. - Static, dynamic, volume and combine weights:
computeWeightPacket. BlendInput and BlendSample: channel and sample descriptors. - Nine built-in geometry movers (matrix, blend shape, curve, Delta Mush,
lattice, smooth, surface, volume-correct and wrinkle):
computeMoverParametersandcomputeMoverStatus. Affine-frame providers: expressions onoutputs:matrix.
The registered callbacks call the same kernels as the compiled operations; for
example, the solver glue in libs/rigExec/solverKernels.h serves both. A
matching row shows that a registration binds the same inputs as the compiled
operation. It is not an independent check of the arithmetic.
Nothing requests the mover-parameter or affine-frame registrations.
computeFalloffLut is a stub that returns an empty table; a check supplies
the compiled table as an override.
What the check judges¶
rigExecPose --exec-crosscheck enables the check on a native program. For
every compiled step, RigExecBakedExecCheckRows::Build records one row. These
step kinds are judged by OpenExec:
| Step kind | Requested computation |
|---|---|
| ComposeSubtree | computePointFrame, one row per slot |
| RestCompose | computeRestFrame, one row per slot |
| LadderCompose | computedDefaultSpace, one row per slot |
| ProviderMatrix, FrameMatrix | computeMatrix |
| Solve | computePointFrameArray |
| WeightPacket | computeWeightPacket |
| VolumePlacements | computePointFrame, converted to a volume placement |
Each judged row owns a RigExecTapSet with one value key. Before the
operation body runs, the row captures the values the operation read, and the
check passes them to OpenExec as value overrides, so OpenExec recomputes only
that operation. A row fails when an override for a declared input is missing
or dropped, when an override names the row's own result, when OpenExec returns
no value, or when the encoded result differs in any bit.
Other rows are not judged by OpenExec:
- Aim, rotation and parent constraints in supported configurations are judged
by an independent C++ witness (
libs/rigExec/independentConstraintCheck.h). - Other constraints, every other step kind, and rows whose provider slot is
not a first-frame pose are skip-only
NoEquivalentrows. Blend channels and samples are recorded for presence only.
Switches and coverage¶
RigExecBakedProgramTesting::EnableExecCrossCheckbuilds the rows;rigExecPose --exec-crosscheckcalls it. Operation inputs are captured only while rows exist, and the frozen snapshot does not copy them.- The check is native-only.
rigExecPoserefuses--exec-crosscheckwith--golden-backend frozenorruntime. - CTest runs every
example_graph_*test with--exec-crosscheck --cpu-reference. Theexec_crosscheck_*fixtures andtestRigExecExecCrossCheckcarry theexeclabel (ctest -L exec). testRigExecDefaultSpaces,testRigExecArm,testRigExecConstraints,testRigExecStandaloneandtestRigExecInteractiveuseRigExecTapSetrequests directly as reference values.TF_DEBUG=RIGEXEC_TAP_TIMINGreports the time spent building and computingExecUsdSystemrequests.
Stage edits and shared types¶
Production invalidation uses the compiled dependency edges. All
RigExecTapSet objects on one stage share one ExecUsdSystem, created on
first use. The imaging registry calls RigExecTapSet::PrepareStageChange on
source-stage notices, and the shared context also listens to its stage,
registered after the system so that it runs ahead of OpenExec's own
listener. Without tap sets this does nothing; with them, it retires their
requests before a prim removal reaches OpenExec, which works around the
EsfUsd resync defect described in
tests/python/test_rigexec_stage_edits.py.
RigExecValueAddress and RigExecValueOverride are declared in
libs/rigExec/tapSet.h but are plain data types. Production uses them for
interactive overrides, falloff tables and input replay, and the header includes
no OpenExec header.
libs/rigExecStandalone/adapter.{h,cpp} implements OpenExec's Esf scene
interfaces over RigExecSceneDb, but nothing calls it. The
standalone runtime translates its scene into the
shared operation graph instead.
Scene and binary playback¶
rigExec:asset selects a .rigexec asset in hosts that support binary playback.
Without that asset selection, the host evaluates the scene program. This is a
choice of input representation and playback source, not an evaluator policy
mode. Rendering the scene requires no exported bake:
USD/bin/usdrecord --renderer GL --camera /IkAsset/MainCam \
--frames 1001:1012 docs/examples/two_bone_ik.usda frame.###.png
Pass an explicit camera that covers the evaluated motion.
Exporting: a stage that needs no plugin¶
rigexec.export_baked(stage, rig_paths, times, path) is a different thing
again. It evaluates the rig at the sample times you name and writes a
standalone standard USD file: ordinary animated points, and joint,
control and revised-provider frames written as plain local
xformOp:transform:baked matrices. Geometry topology, materials, primvars and
metadata survive the flattened copy; joint and control prims become Xform,
other execution prims become inert Scopes, and the runtime schemas, their
properties and connections into them are removed. The result renders anywhere,
with no RigExec plugin.
import rigexec
baked = rigexec.export_baked(
stage, ["/Character/Rig"], range(1001, 1050), "character-baked.usdc")
You must name every active RigExecRoot in the stage, so stripping runtime
schemas cannot silently leave another rig unevaluated. The source stage is
never authored, a destination naming a source layer is rejected, and the file is
published by atomic replacement only after every sample succeeds. Treat the
result as a sampled geometry/transform cache: it does not create a new
UsdSkel skinning rig, and USD's interpolation between your requested samples
is not a substitute for evaluating nonlinear rig motion at more times.
Implementation¶
See architecture, frame warming,
bake APIs, and
tests/testRigExecBakedSchedule.cpp.
Godot and baked rigs describes a self-contained
.rigexec asset with embedded visuals and exposed controllers.
OpenExec code pointers¶
Paths are relative to the repository root.
| Role | What | Where |
|---|---|---|
| Production graph | Shared compiler and readiness executor; OpenExec is not called | libs/rigExecGraph/opGraph.cpp:97, libs/rigExecGraph/opGraph.cpp:409 |
| Build and link | rigExec links exec execUsd ef vdf publicly |
CMakeLists.txt:230-234 |
rigExecStandalone links exec esf |
CMakeLists.txt:293 |
|
rigExecRuntime links neither USD nor OpenExec |
CMakeLists.txt:407 |
|
| The installed package requires the same OpenUSD targets | cmake/rigExecConfig.cmake.in:20-25 |
|
The schema plugin's library is rigExecImaging; there is no Exec plugInfo block |
CMakeLists.txt:2673-2675 |
|
RigExecLoadComputations() is an empty link anchor |
libs/rigExec/types.cpp:16 |
|
probeEsfCompatibility is built only on request and has no test |
CMakeLists.txt:1958-1959 |
|
| Value types | Nine ExecTypeRegistry::RegisterType calls |
libs/rigExec/types.cpp:205-215 |
| Schema computations | Joint, Control and VolumeWeight providers (macros, then uses) | libs/rigExec/computations.cpp:434-563, :565, :567, :590 |
| FkChain, TwoBoneIk, BlendPointFrames, TwistDistribution, SplineIk | libs/rigExec/computations.cpp:764, :951, :1088, :1151, :1378 |
|
| Weight packets, blend descriptors and Ribbon | libs/rigExec/moverKernels.cpp:665-886 |
|
computeFalloffLut stub |
libs/rigExec/moverKernels.cpp:732-735 |
|
| Mover parameters and status, never requested | libs/rigExec/movers/matrixMover.cpp:437, blendShapeMover.cpp:625, curveMover.cpp:662, deltaMushMover.cpp:151, latticeMover.cpp:286, smoothMover.cpp:117, surfaceMover.cpp:276, volumeCorrectMover.cpp:106, wrinkleMover.cpp:174 |
|
| Affine-frame expressions, never requested | libs/rigExec/affineFrameComputations.cpp:231-315 |
|
| Production affine-frame operation | libs/rigExecScene/providerProgram.cpp:631 |
|
| Requests | One ExecUsdSystem per stage in a weak table, created only here |
libs/rigExec/tapSet.cpp:82-147, libs/rigExec/tapSet.cpp:108 |
| Value keys, request build and preparation | libs/rigExec/tapSet.cpp:213-255 |
|
| Time change, overrides, compute and extraction | libs/rigExec/tapSet.cpp:316, :319-340, :344-346, :350-357 |
|
RIGEXEC_TAP_TIMING |
libs/rigExec/debugCodes.h:19, libs/rigExec/tapSet.cpp:44-50 |
|
The only tap-set creator under libs |
libs/rigExecOracle/bakedExecCrossCheck.cpp:50 |
|
| Invalidation | Registry stage-notice hook | libs/rigExecImaging/registryInvalidation.cpp:499 |
| Prim-removal workaround and its defect | libs/rigExec/tapSet.cpp:111-113, :118-136, tests/python/test_rigexec_stage_edits.py:7-12 |
|
| Reference check | Row construction | libs/rigExecOracle/bakedExecCrossCheckRows.cpp:441-608 |
| Constraint rows and their independent witness | libs/rigExecOracle/bakedExecCrossCheckRows.cpp:505-542, libs/rigExec/independentConstraintCheck.h |
|
| Override coverage | libs/rigExecOracle/bakedExecCrossCheck.cpp:37-43, :76-86 |
|
| Request evaluation and bit-exact comparison | libs/rigExecOracle/bakedExecCrossCheck.cpp:103, :114-119 |
|
| Row capture around operation bodies | libs/rigExec/bakedSchedule.cpp:2360-2362, libs/rigExec/bakedPose.cpp:3613, :3679, :4666, :5485-5486 |
|
| Frozen clone, which omits the rows | libs/rigExec/frozenSnapshot.cpp:89 |
|
| Enable hook | libs/rigExecOracle/bakedExecCrossCheckRows.cpp:680-685 |
|
rigExecPose --exec-crosscheck and backend refusals |
tools/rigExecPose.cpp:1435, :1551-1557, :1159, :1168 |
|
| CTest registration | CMakeLists.txt:768-770, :974-975, :988-996 |
|
| Direct test references | Tap sets built by tests | tests/testRigExecDefaultSpaces.cpp:56, tests/testRigExecArm.cpp:198, tests/testRigExecConstraints.cpp:2641, tests/testRigExecStandalone.cpp:547, tests/testRigExecStandalone.cpp:915, tests/testRigExecInteractive.cpp:161 |
| Esf | Adapter with no callers | libs/rigExecStandalone/adapter.h:7-8, libs/rigExecStandalone/adapter.cpp:182-186 |
| Standalone runtime translation into the shared graph | libs/rigExecStandalone/sceneRuntime.cpp:4-18 |
|
| Shared data types | RigExecValueAddress, RigExecValueOverride |
libs/rigExec/tapSet.h:41-57, libs/rigExec/tapSet.h:73-98 |
| Production uses of the override type | libs/rigExec/bakedProgram.h:439, libs/rigExec/frameCache.h:158 |