OpenExec (ExecUsd) Client Evaluation API — Condensed Reference¶
OpenUSD 26.08 study notes, not a description of RigExec. See OpenExec reference checks for how
RigExecTapSetis used.
Source studied: the OpenUSD v26.08 pxr/exec/ tree (headers:
execUsd/system.h, execUsd/request.h, execUsd/valueKey.h,
execUsd/cacheView.h, execUsd/valueOverride.h, exec/request.h,
exec/builtinComputations.h, ef/time.h, ef/timeInterval.h; tests:
execUsd/testenv/*; docs: execUsd/docs/tutorial1ComputingValues.md).
Audience: the RigExecTapSet facade — stage → system → batched request → prepare → per-time compute → typed extraction → invalidation subscription.
1. Core headers a client includes¶
#include "pxr/exec/execUsd/system.h" // ExecUsdSystem
#include "pxr/exec/execUsd/request.h" // ExecUsdRequest
#include "pxr/exec/execUsd/valueKey.h" // ExecUsdValueKey
#include "pxr/exec/execUsd/cacheView.h" // ExecUsdCacheView
#include "pxr/exec/execUsd/valueOverride.h" // ExecUsdValueOverride (optional)
#include "pxr/exec/exec/request.h" // ExecRequestIndexSet + callback typedefs
#include "pxr/exec/exec/builtinComputations.h" // ExecBuiltinComputations tokens
#include "pxr/exec/ef/timeInterval.h" // EfTimeInterval (value-invalidation cb)
#include "pxr/exec/ef/time.h" // EfTime (only if consuming computeTime)
For computeLocalToWorldTransform on Xformables: pxr/exec/execGeom/tokens.h
(ExecGeomXformableTokens->computeLocalToWorldTransform, links execGeom).
2. ExecUsdSystem (execUsd/system.h)¶
Non-copyable, non-movable. Extends the lifetime of the stage it wraps (holds a ref); normally lives right alongside the UsdStage.
class ExecUsdSystem : public ExecSystem {
public:
explicit ExecUsdSystem(const UsdStageConstRefPtr &stage);
~ExecUsdSystem();
void ChangeTime(UsdTimeCode time);
ExecUsdRequest BuildRequest(
std::vector<ExecUsdValueKey> &&valueKeys,
ExecRequestComputedValueInvalidationCallback &&valueCallback = {},
ExecRequestTimeChangeInvalidationCallback &&timeCallback = {});
void PrepareRequest(const ExecUsdRequest &request); // compile + schedule
ExecUsdCacheView Compute(const ExecUsdRequest &request); // implicit prepare
ExecUsdCacheView ComputeWithOverrides(
const ExecUsdRequest &request,
ExecUsdValueOverrideVector &&valueOverrides); // one-shot overrides
};
Notes:
- The system internally subscribes to UsdStage change notices (a private
_NoticeListener); any authoring on the stage is immediately reflected
(invalidates cached values, may trigger request value-invalidation callbacks
synchronously during UsdAttribute::Set() / SdfChangeBlock close).
- Constructor takes UsdStageConstRefPtr — a UsdStageRefPtr converts
implicitly.
- Multiple requests can share one system; compilation/schedule state is
amortized across them.
Time model¶
ChangeTime(UsdTimeCode)sets the single "current evaluation time" of the whole system. There is no per-Compute time argument — the pattern is:ChangeTime(t); Compute(reqA); Compute(reqB); ChangeTime(t2); ...(compute all requests at one time before moving to the next time; this keeps time-dependent intermediate results cached — per system.h note).- A fresh system starts at
UsdTimeCode::Default(). ChangeTimere-resolves time-dependent inputs and invalidates only values whose inputs actually differ between old and new time. Revisiting a time whose values are still cached recomputes nothing (verified bytestExecUsdRequest.cppTestTimeVaryingCache).EfTime(ef/time.h) is the internal time type: wraps aUsdTimeCodeplus app-specificSplineEvaluationFlags(uint8_t). Client-facing ExecUsd API only speaksUsdTimeCode. Left-side evaluation usesChangeTime(UsdTimeCode::PreTime(t)): the pre-time flag rides in theEfTime's time code, and attribute input nodes resolve values with it (exec/attributeInputNode.cpp:72-75).PreTime(t)andtare distinct times.- The builtin stage computation
ExecBuiltinComputations->computeTimeproduces anEfTime(used as an input by time-dependent plugin computations; can also be requested directly with the stage pseudo-root as provider — rarely needed by clients).
3. ExecUsdValueKey (execUsd/valueKey.h)¶
explicit ExecUsdValueKey(const UsdAttribute &provider);
// == { provider, ExecBuiltinComputations->computeValue } (see valueKey.cpp)
ExecUsdValueKey(const UsdAttribute &provider, const TfToken &computation);
ExecUsdValueKey(const UsdPrim &provider, const TfToken &computation);
- Brace-init works in the vector for the two-argument forms:
{prim, TfToken("computeXf")},{attr, someAttrComputation}. The one-argument attribute constructor isexplicit, so spell itExecUsdValueKey{attr}(attribute computeValue); a bare{attr}does not compile. - Keys are copyable value types holding a
std::variantof {expired, attribute-computation, prim-computation}. Keys for objects that get removed from the stage are internally "expired"; the request'sIsValid()then returns false andPrepareRequest/Computepost errors, so build a new request (seetestExecUsdRequestExpiration.cpp). - In 26.08, removing a prim while a system is alive also posts "Applying
predicate to invalid prim":
EsfUsdStageData::_UpdateForResyncappliesUsdPrimDefaultPredicateto the missing prim (esfUsd/stageData.cpp:361).RigExecTapSetdrops its requests and system before that listener runs (libs/rigExec/tapSet.cpp:118-136).
Builtin computation tokens (exec/builtinComputations.h)¶
Accessed via ExecBuiltinComputations->...:
- computeValue (attribute provider) — attribute's computed value:
1) registered attribute expression, else 2) the computed value of the
target of its single connection, when that target is a valid attribute of
the same type, else 3) resolved (authored) value. Result type = the
attribute's scalar value type (an attribute expression may produce any
type).
- computeResolvedValue (attribute provider) — always the resolved authored
value at the current system time (respects default/timeSamples/splines;
see testExecUsdInvalidation.cpp).
- computeTime (stage provider) — current time as EfTime.
- computePath — provider's SdfPath.
4. ExecUsdRequest (execUsd/request.h)¶
- Move-only handle (
unique_ptrimpl). Keep it alive as long as you compute with it / want invalidation callbacks. bool IsValid() const— true means Prepare/Compute may be called (not that anything is cached/compiled); false once any of its keys has expired.- Value-key index = position in the vector passed to
BuildRequest; the same indices are used byCacheView::Get(i)and both callbacks. - Destroying the request unregisters it (callbacks stop).
5. ExecUsdCacheView (execUsd/cacheView.h)¶
ExecUsdCacheView view = system.Compute(request);
VtValue v = view.Get(0); // by request index
double d = v.Get<double>(); // typed extraction; v.IsHolding<T>() to test
Get(int index) constreturnsVtValue; emits a TF error and returns an emptyVtValueif the index was not evaluated.- Default-constructed view is invalid.
- Lifetime: must not outlive the system OR the request it came from. It is
a cheap view; re-obtain a fresh one from every
Compute()call (values extracted after later scene edits/time changes would otherwise be stale — extract promptly after Compute). - Concurrent
Get()from multiple threads on one view is supported (testExecUsdRequest.cppextracts underWorkParallelForN). - Any
VtValue-holdable type comes through: plugin-registered custom types,GfMatrix4d,double,std::string,VtArray<T>(extract withv.Get<VtArray<T>>()/v.IsHolding<VtDoubleArray>()),UsdTimeCode, ...
6. Invalidation (exec/request.h)¶
Callbacks are registered only at BuildRequest time (2nd and 3rd args):
using ExecRequestIndexSet = pxr_tsl::robin_set<int>; // set of request indices
using ExecRequestComputedValueInvalidationCallback =
std::function<void(const ExecRequestIndexSet &, const EfTimeInterval &)>;
using ExecRequestTimeChangeInvalidationCallback =
std::function<void(const ExecRequestIndexSet &)>;
Semantics (system.h docs + testExecUsdRequestInvalidation.cpp):
- valueCallback: fired on authored-value / structural scene changes that
invalidate previously computed values. Delivers the invalid request indices
plus the EfTimeInterval over which they are invalid (authored default
value changes deliver the full interval; interval.IsFullInterval(),
IsEmpty(), Contains(EfTime), GetTimeMultiInterval(), and |= to
accumulate). Multiple simultaneous invalidations may be batched into one
invocation (e.g. one SdfChangeBlock → one callback).
- One-shot interest: each callback is guaranteed to fire at least once
per (index, interval) combination, and only after a Compute. Re-calling
Compute() renews interest; repeated edits between Computes may not
re-notify.
Pattern: on callback → mark dirty; next pull → Compute → extract.
- timeCallback: fired from within ChangeTime() with the indices of
time-dependent keys whose inputs actually differ between old and new time.
No interval argument.
- Threading/reentrancy caveats:
- Callbacks run synchronously inside the authoring call
(attr.Set(...), change-block close) or inside ChangeTime(): that call
returns only after they finish. There is no queue/deferral. Exec visits
the system's requests with WorkParallelForEach
(exec/requestTracker.h:97-107), so a callback may run on a worker
thread, and callbacks of different requests may run concurrently.
- You must NOT call back into execution (Compute, PrepareRequest, value
extraction, ...) from inside either callback. Record dirty state and
return.
- No callback fires during the initial Compute() itself, and edits to
irrelevant fields (e.g. documentation metadata) do not notify.
7. ComputeWithOverrides (execUsd/valueOverride.h)¶
struct ExecUsdValueOverride {
ExecUsdValueKey valueKey; // which computed value to replace
VtValue overrideValue; // must match the computation's value type
};
using ExecUsdValueOverrideVector = std::vector<ExecUsdValueOverride>;
ExecUsdCacheView v = system.ComputeWithOverrides(request,
{ {ExecUsdValueKey{prim, token}, VtValue(3.0)} });
Overrides apply to that single invocation only; downstream dependents consume the overridden value. Type mismatch → coding error.
8. Minimal end-to-end example¶
#include "pxr/exec/execUsd/system.h"
#include "pxr/exec/execUsd/request.h"
#include "pxr/exec/execUsd/valueKey.h"
#include "pxr/exec/execUsd/cacheView.h"
#include "pxr/exec/exec/request.h"
#include "pxr/exec/ef/timeInterval.h"
#include "pxr/exec/execGeom/tokens.h"
#include "pxr/base/gf/matrix4d.h"
#include "pxr/usd/usd/stage.h"
PXR_NAMESPACE_USING_DIRECTIVE
void Run()
{
UsdStageRefPtr stage = UsdStage::Open("rig.usda");
// 1. System (one per stage; holds compiled network, listens to changes).
ExecUsdSystem system(stage);
// 2. Batched value keys. Index in this vector == extraction index.
UsdPrim xform = stage->GetPrimAtPath(SdfPath("/Root/A1"));
UsdAttribute in = stage->GetAttributeAtPath(SdfPath("/Root/A1.myAttr"));
std::vector<ExecUsdValueKey> keys {
{xform, ExecGeomXformableTokens->computeLocalToWorldTransform}, // [0] prim comp
{xform, TfToken("computeMyCustomThing")}, // [1] custom plugin comp
ExecUsdValueKey{in}, // [2] attribute computeValue (builtin)
};
// 3. Request with invalidation subscriptions (registered here, only here).
std::atomic<bool> dirty{false};
ExecUsdRequest request = system.BuildRequest(
std::move(keys),
/*valueCallback*/ [&](const ExecRequestIndexSet &indices,
const EfTimeInterval &interval) {
// Runs synchronously during stage edits. Do NOT compute here.
for (int i : indices) { /* mark tap i dirty over 'interval' */ }
dirty = true;
},
/*timeCallback*/ [&](const ExecRequestIndexSet &indices) {
// Runs synchronously inside ChangeTime for actually-varying keys.
dirty = true;
});
TF_AXIOM(request.IsValid());
// 4. Front-load compile + schedule.
system.PrepareRequest(request);
// 5. Evaluate over times: set time, compute, extract immediately.
for (double t : {1.0, 2.0, 3.0}) {
system.ChangeTime(UsdTimeCode(t));
ExecUsdCacheView view = system.Compute(request); // renews invalidation interest
VtValue v0 = view.Get(0);
GfMatrix4d xf = v0.Get<GfMatrix4d>();
VtValue v1 = view.Get(1); // custom-typed plugin value
// if (v1.IsHolding<MyRigType>()) { ... }
VtValue v2 = view.Get(2); // attribute value (scalar or VtArray)
// if (v2.IsHolding<VtDoubleArray>()) { auto arr = v2.Get<VtDoubleArray>(); }
}
// Default (non-animated) evaluation:
system.ChangeTime(UsdTimeCode::Default());
ExecUsdCacheView dv = system.Compute(request);
}
Custom computations are published from a plugin via
EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(SchemaTypeName) { self.PrimComputation(token).Callback<T>(...).Inputs(...); }
(pxr/exec/exec/registerSchema.h; expands to a
TF_REGISTRY_FUNCTION(ExecDefinitionRegistryTag)), living in a library whose
plugInfo.json lists the schema under Info.Exec.Schemas. Exec loads the
plugin defining computations for a schema on demand
(exec/pluginData.cpp:42-52).
9. Linking and environment¶
execUsd's own CMake LIBRARIES (all public link deps of the library):
esf esfUsd exec tf trace sdf usd.
A realistic client link line (mirrors the testenv executables), superset:
execUsd exec esf ef vdf # exec core (ef for EfTimeInterval, vdf if writing computations)
usd sdf plug tf gf vt work trace
execGeom usdGeom # only if using computeLocalToWorldTransform etc.
ts # only if authoring/inspecting splines
Minimum for pure evaluation + invalidation: execUsd exec ef usd sdf tf gf vt
(transitives via execUsd cover esf/esfUsd/trace). If you register your own
computations you also need vdf (VdfContext) and plug.
Build/runtime requirements:
- OpenUSD must be built with exec enabled: PXR_BUILD_EXEC defaults to
ON (forced off for Wasm), and build_usd.py has no exec switch. Only the
execIr invertible-rig schemas and APIs carry a "not yet ready for
production" warning (execIr/README.md); the execUsd and exec READMEs
carry none.
- Plugin discovery: execUsd, execGeom, and any custom computation plugin
must be discoverable via the usual PXR_PLUGINPATH_NAME / installed
plugInfo.json mechanism.
- Env settings (TfEnvSetting):
- VDF_ENABLE_PARALLEL_EVALUATION_ENGINE — default true
(pxr/exec/vdf/types.cpp); enables parallel evaluation within a single
round of exec evaluation. Set to 0 to force serial engine when
debugging.
- No other exec-specific env settings are defined under pxr/exec.
- Useful debug flags (TF_DEBUG): EXEC_REQUEST_INVALIDATION (request
invalidation traffic); ExecSystem::Diagnostics(&system).InvalidateAll()
and .GraphNetwork("out.dot") exist on exec/systemDiagnostics.h for
debugging.
10. Facade design implications (RigExecTapSet)¶
- Hold:
UsdStageRefPtr(or rely on system's ref), one move-onlyExecUsdRequest, and the key vector's index→tap mapping. All tap sets on a stage share oneExecUsdSystem(one compiled network and value cache per stage;libs/rigExec/tapSet.cpp:82-147). - Rebuilding the tap set means building a new request (keys are fixed at BuildRequest; there is no append API).
- Invalidations arrive synchronously inside authoring and ChangeTime calls,
possibly on a worker thread: your callback should only flip atomic dirty
bits / forward notifications; evaluation must happen later on the caller's
pull.
RigExecTapSetsets astd::atomic<bool>(libs/rigExec/tapSet.h:214). - Re-Compute after invalidation to keep callbacks flowing (interest renewal).
- Cache views are transient: compute → extract → drop; never store a view across stage edits, ChangeTime, or request/system destruction.