OpenExec Plugin-Computation Registration — API Notes (OpenUSD v26.08)¶
OpenUSD 26.08 study notes, not a description of RigExec. See OpenExec reference checks for what RigExec registers and requests.
Source studied: the OpenUSD v26.08 pxr/exec/ tree (exec, execUsd, execGeom,
execIr, vdf) and extras/exec/examples/definingComputations/. All signatures
below are verbatim from source.
1. Registration macro, plugInfo.json, plugin discovery¶
1.1 EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(SchemaType)¶
Header: pxr/exec/exec/registerSchema.h.
#include "pxr/exec/exec/registerSchema.h"
#include "pxr/exec/vdf/context.h"
EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(RigExecMySchema) // token pasted AND stringized
{
// `self` is an ExecComputationBuilder&
self.PrimComputation(_tokens->computeThing)
.Callback<double>(...)
.Inputs(...);
}
Mechanics (exact, from the macro body):
- SchemaType is used both as an identifier (pasted into the function name
Exec_RegisterSchema_##SchemaType) and stringized (#SchemaType) — so it must be the
TfType alias/name of the schema class, e.g. UsdGeomXformable,
TestExecUsdConstantInputCustomSchema, ExecIrFkController. The string is resolved at
registry-run time via TfType::FindByName(schemaTypeName)
(computationBuilders.cpp:428); unknown name → coding error.
- The macro expands to a TF_REGISTRY_FUNCTION(ExecDefinitionRegistryTag) that constructs
ExecComputationBuilder self and calls your block, which becomes the body of
static void PXR_NS::exec_registration::Exec_RegisterSchema_<SchemaType>(ExecComputationBuilder &self).
- The block lives in namespace exec_registration, which is why AttributeValue, Computation,
Relationship, Constant, etc. are usable unqualified inside the block.
- Works for typed and applied (API) schemas alike. Only one macro invocation per schema
per process (a second registration for the same schema is an error —
definitionRegistry.cpp:554; two plugins declaring the same schema in Exec.Schemas is also
an error — see TestExecConflictingPluginRegistration*). Computations registered for base schema types and
applied API schemas are all found when resolving a computation on a prim.
- Computation names must NOT start with __ (reserved prefix for builtins,
builtinComputationRegistry.cpp).
1.2 plugInfo.json Info.Exec.Schemas block¶
The library that defines the computations (need not be the schema-defining library) must declare which schemas it registers computations for:
{
"Plugins": [
{
"Info": {
"Exec": {
"Schemas": {
"RigExecMySchema": { "allowsPluginComputations": true },
"RigExecOtherAPI": { }
}
}
},
"LibraryPath": "@PLUG_INFO_LIBRARY_PATH@",
"Name": "rigExec",
"ResourcePath": "@PLUG_INFO_RESOURCE_PATH@",
"Root": "@PLUG_INFO_ROOT@",
"Type": "library"
}
]
}
- Keys under
Schemasare TfType names (resolved withTfType::FindByName; the schema's plugin must already be discoverable so the type exists). allowsPluginComputationsdefaults to true when omitted. Setting itfalsedeclares the schema cannot have plugin computations (registrations for it are errors/ignored).- Real examples:
pxr/exec/execGeom/plugInfo.json,pxr/exec/execIr/plugInfo.json(the latter combinesExec.Schemaswith the usual usdGenSchemaTypes+SdfMetadatablocks in one plugin).
1.3 Discovery / loading (pxr/exec/exec/pluginData.cpp)¶
- At first use,
Exec_PluginDataiteratesPlugRegistry::GetInstance().GetAllPlugins()and builds a mapschema TfType -> pluginfrom every plugin whose metadata has anExecblock. - When exec needs computations for a schema,
LoadPluginComputationsForSchema(schemaType)callsplugin->Load()— loading the shared library runs yourTF_REGISTRY_FUNCTION(ExecDefinitionRegistryTag)registrations (the macro) and yourTF_REGISTRY_FUNCTION(ExecTypeRegistry)type registrations. - So the computation library must be a normal Plug
"Type": "library"plugin (shared lib + installed plugInfo.json). The schema library itself can be a codeless"Type": "resource"plugin (seeexecUsd/testenv/testExecUsdAttributeValueInput/resources/plugInfo.json, which defines the schemaTypesonly, while the computations are statically linked in the test binary). If your computations are linked into the host app instead of a plugin, they register when exec first builds its definition registry (definitionRegistry.cpp:81) and noExecplugInfo block is needed — the block exists purely so exec knows which library to load on demand. RigExec takes this route:librigExecholds its registrations, and therigExecSchemaplugin (whose build-generated plugInfo namesrigExecImagingas its library) has noExecblock. - Standalone tools must make the plugins discoverable, e.g.
PlugRegistry::GetInstance().RegisterPlugins(path)orPXR_PLUGINPATH_NAME.
2. Registering a custom value type (ExecTypeRegistry)¶
Header: pxr/exec/exec/typeRegistry.h.
template <typename ValueType>
static void ExecTypeRegistry::RegisterType(const ValueType &fallback); // static!
template <typename ValueType>
TfType ExecTypeRegistry::CheckForRegistration() const; // fatal error if not registered
Correct registry-function tag is exactly TF_REGISTRY_FUNCTION(ExecTypeRegistry):
// rigExecMath/pointFrame.h (namespace rigExec)
struct RigExecPointFrame {
std::array<GfVec3d, 4> points{ GfVec3d(0), GfVec3d(1, 0, 0),
GfVec3d(0, 1, 0), GfVec3d(0, 0, 1) };
uint32_t flags = RigExecPointFrameValid;
bool operator==(const RigExecPointFrame &o) const {
return points == o.points && flags == o.flags;
}
bool operator!=(const RigExecPointFrame &o) const { return !(*this == o); }
// A TfHashAppend overload is needed only if the type is used with
// Constant(...) inputs; RigExecPointFrame has none.
};
// rigExec/types.cpp
#include "pxr/exec/exec/typeRegistry.h"
TF_REGISTRY_FUNCTION(ExecTypeRegistry)
{
ExecTypeRegistry::RegisterType(rigExec::RigExecPointFrame{}); // arg = fallback value
// ... eight more RigExec value types
}
Requirements / behavior (all verified in source):
- Equality comparable — static_assert(VdfIsEqualityComparable<ValueType>, ...).
(VdfIsEqualityComparable<T> in vdf/traits.h detects a valid T == T expression, with
recursive specializations for std::vector, std::pair, std::map, std::unordered_map.)
- Not a VtArray — static_assert(!VtIsArray<ValueType>::value, ...). VtArray is never an
exec value type; arrays flow as vectorized element values (see §3b).
- Copyable + a valid fallback value — the fallback is returned by
VdfContext::GetInputValue<T> when a value is missing (after emitting a coding error), so it
needs a sane default. Default-constructibility per se is only needed to spell
RegisterType(T{}).
- TfType registration is automatic: VdfExecutionTypeRegistry::Define(fallback) calls
TfType::Define<T>() if TfType::Find<T>() is unknown (vdf/executionTypeRegistry.h:216).
No TF_REGISTRY_FUNCTION(TfType) and no VtValue "traits"/Sdf value-type registration
needed — RegisterType also installs the VtValue extractor
(so ExecUsdCacheView::Get() returns a VtValue holding T) and the
VtValue→VdfVector converter used for Constant inputs.
- Hashable (VtIsHashable, i.e. TfHashAppend overload) only if used with Constant(...)
(static_assert lives in the Constant accessor, not in RegisterType).
- Registering the same type twice is allowed but all calls must pass an equal fallback.
- Registration must be loaded before use: put types.cpp in the same plugin library as the
computations (execIr does exactly this: execIr/types.cpp).
- The type registry is preloaded with every Sdf attribute value type (SDF_VALUE_TYPES:
double, GfVec3d, TfToken, GfMatrix4d, std::string, ...) and its VtArray, plus EfTime,
SdfPath and VtArray<SdfPath> (typeRegistry.cpp) — do not re-register those.
- Precedent for a container-as-scalar value type: execIr registers
using ExecIrResult = TfDenseHashMap<TfToken, VtValue, TfToken::HashFunctor>; and callbacks
simply return ExecIrResult{...};.
Using it: once registered, the type works anywhere a ResultType is accepted —
.Callback<RigExecPointFrame>(...), Computation<RigExecPointFrame>(token),
Relationship(rel).TargetedObjects<RigExecPointFrame>(token),
ctx.GetInputValue<RigExecPointFrame>(token), ctx.SetOutput(frame). Every DSL specifier
calls ExecTypeRegistry::GetInstance().CheckForRegistration<T>() at registration time and
emits a fatal error if the type is unknown.
3. The computation-definition DSL (computationBuilders.h)¶
3.1 Computation registrations (methods on self)¶
ExecPrimComputationBuilder PrimComputation(const TfToken &computationName);
ExecAttributeComputationBuilder AttributeComputation(const TfToken &attributeName,
const TfToken &computationName);
ExecAttributeExpressionBuilder AttributeExpression(const TfToken &attributeName);
// Dispatched variants (visible cross-prim only via FallsBackToDispatched() inputs):
template <class... Types> ExecPrimComputationBuilder
DispatchedPrimComputation(const TfToken &name, Types &&...schemaTypes /* TfType... */);
template <class... Types> ExecAttributeComputationBuilder
DispatchedAttributeComputation(const TfToken &name, Types &&...schemaTypes);
AttributeExpression overrides the attribute's builtin computeValue; to consume the authored
value inside it, take an input Computation<T>(ExecBuiltinComputations->computeResolvedValue).
3.2 .Callback(...) (on any of the three builders; chainable with .Inputs)¶
// (1) Function pointer (incl. non-capturing lambda via unary +):
template <typename ResultType = /*deduced*/, typename ReturnType = /*deduced*/>
Derived& Callback(ReturnType (*callback)(const VdfContext &));
// - ReturnType == ResultType: deduced, e.g. .Callback(+[](const VdfContext&) -> double {...})
// - ReturnType convertible to explicit ResultType: .Callback<std::string>(+[]{ return "x"; })
// - ReturnType void + explicit ResultType: callback MUST call ctx.SetOutput / SetEmptyOutput
// / write-iterator: .Callback<double>(+[](const VdfContext &ctx) { ctx.SetOutput(1.0); })
// (2) Function object / capturing lambda: ResultType mandatory, return type MUST be void:
template <typename ResultType, typename FuncType>
Derived& Callback(FuncType &&callback);
VtArray.
Callbacks must be pure, thread-safe, cache-safe (all inputs must come through the context).
3.3 .Inputs(...) — input registrations¶
Inputs(Args&&...) takes any number of registrations; each is
[accessor(s)] -> value specifier -> [options]. Default provider (no accessor) is the owning
prim/attribute.
Object accessors (namespace exec_registration):
- Attribute(attrNameToken) — prim computations: sibling attribute of the prim.
- Relationship(relNameToken) — prim computations: relationship on the prim.
- Prim() — attribute computations: the owning prim; has .Attribute(name),
.Relationship(name), .AttributeValue<T>(name).
- Stage() — any computation; must be the sole accessor (for
ExecBuiltinComputations->computeTime etc.).
Value specifiers (exactly one per input registration):
- Computation<ResultType>(computationName) — computation on the current provider.
- accessor.Computation<ResultType>(computationName) — computation on the accessed object.
- accessor.Metadata<ResultType>(metadataKey) / Metadata<T>(key) — metadata value
(default input name = key).
- Relationship(rel).TargetedObjects<ResultType>(computationName) — see §4c.
- Attribute(attr).Connections<ResultType>(name) / Connections<ResultType>(name) (attribute
computations) — computation on objects targeted by the attribute's connections.
- IncomingConnections<ResultType>(name) — computation on attributes whose connections target
the provider (unordered when multiple).
- NamespaceAncestor<ResultType>(computationName) — nearest namespace ancestor prim that
provides the computation.
- Constant(value).InputName(nameToken) — bakes a constant (type must be registered AND
hashable; string literals become std::string via deduction guide; .InputName mandatory).
Aliases:
- AttributeValue<T>(attrToken) ≡
Attribute(attrToken).Computation<T>(ExecBuiltinComputations->computeValue).InputName(attrToken)
- Prim().AttributeValue<T>(attrToken) — same, from an attribute computation.
Input options (chainable on a value specifier, return This&):
- .InputName(TfToken) — overrides default input name (default = computation name, or
attribute name for AttributeValue, or metadata key for Metadata).
- .Required() — inputs are optional by default; Required() makes compilation emit an
error if the input cannot be compiled. There is no public .Optional() (optional is the
default; _SetOptional is protected) and no .Fallback(value) option — do fallbacks in
the callback via GetInputValuePtr (see §4d).
- .FallsBackToDispatched() — allows the input to resolve to a Dispatched*Computation when no
local computation of that name exists on the provider.
- Disambiguating ids exist in the specifier base-class ctor
(Exec_ComputationBuilderComputationValueSpecifier(name, type, resolution, disambiguatingId = TfToken()))
but are not exposed as a chainable DSL option in v26.08; two inputs may share the same
input name and their values simply appear on the same-named input (read them vectorized —
see testExecUsdRecompilation.cpp computeUsingDuplicateInputNames).
4. Reading inputs in callbacks (VdfContext, iterators)¶
pxr/exec/vdf/context.h — key members:
template <typename T> VdfByValueOrConstRef<T> GetInputValue(const TfToken &name) const;
// Expects exactly one value; if none: TF_CODING_ERROR + returns registered fallback.
template <typename T> const T *GetInputValuePtr(const TfToken &name) const; // nullptr if absent
template <typename T> const T *GetInputValuePtr(const TfToken &name, const T *defPtr) const;
bool HasInputValue(const TfToken &name) const;
bool IsOutputRequested(const TfToken &outputName) const;
template <typename T> void SetOutput(const T &value) const; // sole output
template <typename T> void SetOutput(T &&value) const; // move
template <typename T> void SetOutput(const TfToken &outputName, const T &value) const;
void SetEmptyOutput() const; // + (outputName) overload
void SetOutputToReferenceInput(const TfToken &inputName) const; // pass-through optimization
void Warn(const char *fmt, ...) const; void CodingError(const char *fmt, ...) const;
pxr/exec/vdf/readIterator.h / readIteratorRange.h:
template <typename T> class VdfReadIterator {
VdfReadIterator(const VdfContext &context, const TfToken &inputName);
VdfReadIterator &operator++();
reference operator*() const; // const T&
bool IsAtEnd() const;
size_t ComputeSize() const; // total elements across all connections
void AdvanceToEnd();
};
template <typename T> class VdfReadIteratorRange; // VdfReadIteratorRange<T> range(ctx, name);
// begin()/end() for range-for / std::accumulate
pxr/exec/vdf/readWriteIterator.h (vectorized/boxed output):
template <typename T> class VdfReadWriteIterator {
VdfReadWriteIterator(const VdfContext &context, const TfToken &name); // in-place r/w
explicit VdfReadWriteIterator(const VdfContext &context); // sole output
static VdfReadWriteIterator Allocate(const VdfContext &context,
const TfToken &name, size_t count);
static VdfReadWriteIterator Allocate(const VdfContext &context, size_t count); // sole output
// elements default-initialized; iterate and assign *it
};
(a) Scalar attribute value¶
self.PrimComputation(_tokens->computeDoubleAttr)
.Callback<double>(+[](const VdfContext &ctx) {
return ctx.GetInputValue<double>(_tokens->doubleAttr);
})
.Inputs(AttributeValue<double>(_tokens->doubleAttr)); // add .Required() to hard-require
AttributeValue = the attribute token itself.
(b) Array-valued attribute (e.g. point3d[4])¶
Authored VtArray attribute values enter exec as vectorized element values — you register
AttributeValue<GfVec3d> (the element type; AttributeValue<VtVec3dArray> will not work,
VtArray is rejected) and read the elements with VdfReadIterator. Verbatim from
execUsd/testenv/testExecUsdAttributeValueInput.cpp (attribute Vec3f[] arrayAttr):
self.PrimComputation(_tokens->computeArrayAttr)
.Callback<std::vector<GfVec3f>>(+[](const VdfContext &ctx) {
VdfReadIterator<GfVec3f> rIt(ctx, _tokens->arrayAttr);
std::vector<GfVec3f> result;
result.reserve(rIt.ComputeSize());
for (size_t i = 0; !rIt.IsAtEnd(); ++rIt, ++i) { result.push_back(*rIt); }
return result;
})
.Inputs(AttributeValue<GfVec3f>(_tokens->arrayAttr));
ExecTypeRegistry::RegisterType(std::vector<GfVec3f>{}) to use
std::vector<GfVec3f> as the result type — VtArray can't be a result type either. For a
point3d[4] attribute you'd read 4 GfVec3d elements and pack them into a registered struct
of four points, such as RigExecPointFrame.)
GetInputValue<GfVec3d> on an array input would return only the first element; use the
iterator. RegisterType note: extraction of a VtArray-typed attribute's computed value back
to VtValue (cache view) yields VtArray<Element> automatically via the built-in extractors.
(c) Another prim's computation via relationship targets¶
Provider resolution DynamicTraversal::RelationshipTargetedObjects
(providerResolution.h): all relationship targets (with relationship forwarding transitively
expanded to non-relationship objects) become providers. Multiple targets → multiple values
delivered on the single named input, in target order — read them vectorized with
VdfReadIterator<T>. GetInputValue/GetInputValuePtr return just the first value.
Verbatim from testExecUsdRecompilation.cpp:
self.PrimComputation(_tokens->computeUsingCustomRel)
.Callback(+[](const VdfContext &context) {
int result = 0;
VdfReadIterator<int> it(context, ExecBuiltinComputations->computeValue);
for (; !it.IsAtEnd(); ++it) { result += *it; }
return result;
})
.Inputs(
Relationship(_tokens->customRel)
.TargetedObjects<int>(ExecBuiltinComputations->computeValue));
libs/rigExec/computations.cpp:764):
.Inputs(Relationship(_tokens->controls)
.TargetedObjects<RigExecPointFrame>(_tokens->computePointFrame)
.InputName(_tokens->controlFrames)) // optional rename
// callback: VdfReadIterator<RigExecPointFrame> it(ctx, _tokens->controlFrames);
.Required() errors if nothing can be compiled. .FallsBackToDispatched() lets targets match
a DispatchedPrimComputation you registered for your own schema.
(d) Optional inputs and fallbacks¶
- All inputs are optional unless
.Required(). - Preferred patterns (from execGeom/execUsd tests):
const GfMatrix4d *const parentToWorld = ctx.GetInputValuePtr<GfMatrix4d>(ExecGeomXformableTokens->computeLocalToWorldTransform); GfMatrix4d out = parentToWorld ? *parentToWorld : GfMatrix4d(1.0); static const std::string empty; const std::string *v = ctx.GetInputValuePtr<std::string>(_tokens->attr, &empty); // default ptr if (ctx.HasInputValue(_tokens->x)) { ... } - Never call
GetInputValue<T>on a possibly-missing input: it coding-errors and returns the type's registered fallback.
5. Builtin computations — exact tokens¶
Header: pxr/exec/exec/builtinComputations.h; access via the static data pointer
ExecBuiltinComputations (type TfStaticData<Exec_BuiltinComputationTokens>):
| C++ spelling | Token string | Provider | Result type |
|---|---|---|---|
ExecBuiltinComputations->computeValue |
"__computeValue" |
attribute | attribute's scalar value type (or expression's type); source order: attribute expression → single same-typed connection's computed value → resolved value |
ExecBuiltinComputations->computeResolvedValue |
"__computeResolvedValue" |
attribute | attribute's scalar value type; always the authored/resolved value (bypasses expressions) |
ExecBuiltinComputations->computePath |
"__computePath" |
any object | SdfPath |
ExecBuiltinComputations->computeTime |
"__computeTime" |
stage (Stage() accessor only) |
EfTime |
- All builtin names are prefixed
__internally (builtinComputationRegistry.cpp);__is a reserved prefix for plugin computation names. - There is no public
computeConnectedValuetoken: "connected value" is an internal definition (Exec_ComputeConnectedValueComputationDefinition,builtinAttributeComputations.h) used bycomputeValuewhen the attribute has exactly one valid same-typed connection. It does not support multiple connections. builtinStageComputations.h/builtinObjectComputations.himplementcomputeTime/computePathproviders.
6. Real registrations in the repo (models to copy)¶
execGeom (pxr/exec/execGeom/xformable.cpp) — scalar callback, optional inputs, recursion up namespace¶
static GfMatrix4d _ComputeLocalToWorldTransform(const VdfContext &ctx) {
const GfMatrix4d *const localToParent =
ctx.GetInputValuePtr<GfMatrix4d>(_tokens->xformOpTransform);
const GfMatrix4d *const parentToWorld =
ctx.GetInputValuePtr<GfMatrix4d>(
ExecGeomXformableTokens->computeLocalToWorldTransform);
if (parentToWorld) {
return localToParent ? (*localToParent) * (*parentToWorld) : (*parentToWorld);
}
return localToParent ? (*localToParent) : GfMatrix4d(1.0);
}
EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(UsdGeomXformable)
{
self.PrimComputation(ExecGeomXformableTokens->computeLocalToWorldTransform)
.Callback<GfMatrix4d>(&_ComputeLocalToWorldTransform)
.Inputs(
AttributeValue<GfMatrix4d>(_tokens->xformOpTransform),
NamespaceAncestor<GfMatrix4d>(
ExecGeomXformableTokens->computeLocalToWorldTransform));
}
NamespaceAncestor input — this is how per-prim computations chain
up a hierarchy (each prim's node feeds its children's nodes; exec caches per prim).
execIr (fkControllerComputations.cpp + types.cpp) — custom value type as result¶
using ExecIrResult = TfDenseHashMap<TfToken, VtValue, TfToken::HashFunctor>; // types.h
TF_REGISTRY_FUNCTION(ExecTypeRegistry) { ExecTypeRegistry::RegisterType(ExecIrResult{}); }
static ExecIrResult _Compute(const VdfContext &ctx) {
const GfMatrix4d outSpaceValue = ExecIr_UtilsCompute(
ExecIr_ComputeFkParams(ctx),
ExecIr_UtilsComputeLocalTranslation(ctx),
ExecIr_UtilsComputeLocalRotation(ctx));
return ExecIrResult({{ExecIrTokens->outSpace, VtValue(outSpaceValue)}});
}
EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA(ExecIrFkController)
{
ExecIrControllerBuilder builder(self, &_Compute, &_Invert); // helper wrapping the DSL
builder.InvertibleInputAttribute<double>(ExecIrTokens->inTx);
...
}
self can be passed
around by reference and the sub-builders returned by PrimComputation can be stored/composed.)
Vectorized output (from vdf tests, e.g. testVdfReadWriteIterator.cpp)¶
A callback whose output should hold N elements (rather than one struct):
.Callback<GfVec3d>(+[](const VdfContext &ctx) { // ResultType = element type
VdfReadWriteIterator<GfVec3d> out =
VdfReadWriteIterator<GfVec3d>::Allocate(ctx, 4); // sole output, 4 elements
for (int i = 0; !out.IsAtEnd(); ++out, ++i) { *out = GfVec3d(i); }
})
RigExecPointFrame), a
single scalar value — simpler extraction and equality-based invalidation.
7. CMake / build & install¶
From execGeom/CMakeLists.txt and execIr/CMakeLists.txt:
set(PXR_PREFIX pxr/exec) # or your own prefix
set(PXR_PACKAGE rigExec)
pxr_library(rigExec
LIBRARIES # public+link deps; execGeom uses: gf tf execUsd usdGeom
gf
tf
usd # if you have generated schema classes
execUsd # pulls in exec, esf, esfUsd, vdf, ef transitively
INCLUDE_SCHEMA_FILES # only if this lib contains usdGenSchema-generated classes (execIr)
PUBLIC_HEADERS api.h
PUBLIC_CLASSES tokens types # types.cpp holds TF_REGISTRY_FUNCTION(ExecTypeRegistry)
CPPFILES myComputations.cpp # holds EXEC_REGISTER_COMPUTATIONS_FOR_SCHEMA
RESOURCE_FILES plugInfo.json
)
RigExec does not use pxr_library: librigExec is a plain CMake target that links
exec execUsd ef vdf publicly and holds both its type registrations and its computations.
- Minimum link set for a computation-only plugin:
tf+exec(that's allTestExecPluginComputationlinks:pxr_build_test_shared_lib(TestExecPluginComputation INSTALL_PREFIX ExecPlugins LIBRARIES tf exec CPPFILES ...)). Addgf/vt/sdffor value types,usd*for schema classes,execUsdonly if you also evaluate (ExecUsdSystem / BuildRequest / CacheView) from the same lib.vdfcomes transitively viaexec(contexts and iterators are headers inpxr/exec/vdf/...). plugInfo.jsonis listed underRESOURCE_FILES;pxr_library/_install_resource_filessubstitutes@PLUG_INFO_LIBRARY_PATH@,@PLUG_INFO_RESOURCE_PATH@,@PLUG_INFO_ROOT@and installs it to<prefix>/lib/usd/rigExec/resources/plugInfo.json(picked up via the top-levellib/usd/plugInfo.jsoninclude mechanism /PXR_PLUGINPATH_NAME).- Tests:
pxr_build_test(name LIBRARIES tf exec execUsd plug sdf vdf usd CPPFILES ...)+pxr_register_test(... TESTENV ...); codeless schema plugins for tests live intestenv/<test>/resources/plugInfo.json("Type": "resource","ResourcePath": ".") and are loaded at runtime withPlugRegistry::GetInstance().RegisterPlugins(TfAbsPath("resources")). - execIr note for generated schemas: it unsets
CMAKE_CXX_VISIBILITY_PRESETbeforepxr_library, working around a Linux symbol-export problem in generated schema code under hidden visibility. - Tests that rely on plugins require
BUILD_SHARED_LIBS(static builds don't support them — guarded in exec's and execGeom's CMakeLists).
8. Gotchas checklist¶
- Macro argument must be the exact TfType name and a valid C++ identifier; the macro is used
at file scope (it opens/closes
PXR_NAMESPACEitself). One invocation per schema, ever. Callback<T>with capturing lambda must returnvoidand callctx.SetOutput(...); only function pointers (+[]) may return the value directly.VtArray<T>is banned as result and input value type — use element-vectorized flow (VdfReadIterator<Element>) or register astd::vector<T>/custom struct.- Inputs are optional by default; misspelled input names silently produce "no value" — the
default input name is the computation name except for
AttributeValue/Metadataaliases. GetInputValueon an absent input = coding error + fallback; useGetInputValuePtr.- Multiple values on one input (multiple rel targets, duplicate input names, array elements)
require
VdfReadIterator;GetInputValue*sees only the first. Constant(...)values must be hashable (TfHashAppend) and.InputName(...)is mandatory.- Register custom value types in the same plugin library (
TF_REGISTRY_FUNCTION(ExecTypeRegistry)); they auto-TfType::Define— do not also hand-register the TfType with a different name. Stage()accessor must be the only accessor in its input registration.- Computation names starting with
__are reserved for builtins. - Callbacks must be pure/thread-safe; no reading stage data directly inside a callback — all scene dependencies must be declared as inputs or invalidation breaks ("cache safety").