How usdExecImaging integrates OpenExec into Hydra (OpenUSD v26.08)¶
OpenUSD 26.08 study notes, not a description of RigExec. RigExec publishes through filtering scene indices (
libs/rigExecImaging/sceneIndices.h); see OpenExec reference checks for how RigExec uses OpenExec.
Reference notes for implementing rigExecImaging, based on a source study of OpenUSD v26.08. All source paths below are relative to the OpenUSD root, and line numbers refer to that release.
1. Integration / activation: who creates the exec scene index¶
1.1 The factory¶
usdExecImaging exposes exactly one public construction entry point:
// pxr/usdImaging/usdExecImaging/stageSceneIndexFactory.h:26
USDEXECIMAGING_API
UsdExecImagingStageSceneIndexInterfaceRefPtr UsdExecImagingCreateStageSceneIndex();
Two alternative TUs implement it, selected by CMake:
stageSceneIndexFactory_execOn.cpp:14-18— returnsUsdExecImaging_StageSceneIndex::New()(compiled whenPXR_BUILD_EXEC=ON).stageSceneIndexFactory_execOff.cpp:12-16— returnsnullptr(compiled whenPXR_BUILD_EXEC=OFF).
pxr/usdImaging/usdExecImaging/CMakeLists.txt:7-33 selects the TU: with
PXR_BUILD_EXEC on, it links execGeom execIr execUsd and compiles the
private classes (adapterRegistry debugCodes geomXformablePrimAdapter
irXformablePrimAdapter request requestBuilder stageSceneIndex); with it off,
only the stub factory is built. The library itself is always built when
PXR_BUILD_USD_IMAGING=ON (comment at CMakeLists.txt:4-5), so downstream code
can link it unconditionally.
The concrete implementation is deliberately private
(UsdExecImaging_StageSceneIndex, underscore-prefixed,
stageSceneIndex.h:23-27); clients only see the abstract
UsdExecImagingStageSceneIndexInterface (public, stageSceneIndexInterface.h:37-72),
which derives HdSceneIndexBase and adds three pure virtuals:
SetStage(UsdStageRefPtr), SetTime(UsdTimeCode), ApplyPendingUpdates().
1.2 The one and only caller: UsdImagingGLEngine¶
The only consumer in the entire tree is
pxr/usdImaging/usdImagingGL/engine.cpp (a repo-wide grep for
UsdExecImaging matches nothing else outside usdExecImaging itself — notably,
pxr/usdImaging/usdImaging never references it).
Gate: an env setting, off by default:
// engine.cpp:90-96
TF_DEFINE_ENV_SETTING(
USDIMAGINGGL_ENGINE_ENABLE_EXEC_SCENE_INDEX, false,
"Inserts an initial scene index which provides values computed by exec. ...
To use this feature, usdImaging must be built with PXR_BUILD_EXEC=ON.");
Instantiation happens inside the engine's overrides scene index callback:
// engine.cpp:1611-1644 UsdImagingGLEngine::_AppendOverridesSceneIndices
if (TfGetEnvSetting(USDIMAGINGGL_ENGINE_ENABLE_EXEC_SCENE_INDEX)) {
_execStageSceneIndex = UsdExecImagingCreateStageSceneIndex();
if (TF_VERIFY(_execStageSceneIndex)) {
const HdMergingSceneIndexRefPtr mergingSceneIndex = HdMergingSceneIndex::New();
mergingSceneIndex->AddInputScene(_execStageSceneIndex, // FIRST => strongest
SdfPath::AbsoluteRootPath());
mergingSceneIndex->AddInputScene(inputScene, SdfPath::AbsoluteRootPath());
_noticeBatchingStageSceneIndex = HdNoticeBatchingSceneIndex::New(mergingSceneIndex);
_noticeBatchingStageSceneIndex->SetBatchingEnabled(true);
sceneIndex = _noticeBatchingStageSceneIndex;
}
}
Key mechanics:
- The exec SI is an initial (input) scene index (no upstream inputs). It is
merged with the UsdImaging input scene via
HdMergingSceneIndex; being added first, its data sources overshadow the UsdImaging data sources for the same prim path (comment at engine.cpp:1620-1623). - An
HdNoticeBatchingSceneIndexwraps the merge so that notices from both the UsdImaging stage SI and the exec SI are held back until the exec request has been refreshed, then flushed together (engine.cpp:1633-1640; flush sites below).
1.3 Where the callback plugs into the UsdImaging chain¶
_AppendOverridesSceneIndices is bound as the
UsdImagingSceneIndexAppendCallback handed to UsdImagingSceneIndex::New:
// engine.cpp:1677-1701 _CreateUsdImagingSceneIndices
sceneIndex = _usdImagingSceneIndex =
UsdImagingSceneIndex::New(
sceneIndexCreateArgs,
std::bind(&UsdImagingGLEngine::_AppendOverridesSceneIndices,
this, std::placeholders::_1));
sceneIndex = _displayStyleSceneIndex = HdsiLegacyDisplayStyleOverrideSceneIndex::New(sceneIndex);
if (!_sceneDelegateId.IsAbsoluteRootPath())
sceneIndex = HdPrefixingSceneIndex::New(sceneIndex, _sceneDelegateId);
UsdImagingSceneIndexAppendCallback is
std::function<HdSceneIndexBaseRefPtr(HdSceneIndexBaseRefPtr const&)>
(pxr/usdImaging/usdImaging/sceneIndex.h:21-23). Internally
UsdImagingSceneIndex delegates to UsdImagingCreateSceneIndices
(pxr/usdImaging/usdImaging/sceneIndices.cpp:191-325), and the callback is
invoked very early in the chain:
UsdImagingStageSceneIndex (sceneIndices.cpp:201-206)
-> HdsiLocatorCachingSceneIndex (materials) (:218-220)
-> overridesSceneIndexCallback(sceneIndex) (:222-225) <== exec merge inserted HERE
-> UsdImagingUnloadedDrawModeSceneIndex (opt) (:227-230)
-> UsdImagingExtentResolvingSceneIndex (:232-234)
-> UsdImagingPiPrototypePropagatingSceneIndex (:236-241)
-> UsdImagingNiPrototypePropagatingSceneIndex (:243-284) (draw-mode SI inserted inside; xform flattening happens inside prototype propagation)
-> HdNoticeBatchingSceneIndex (postInstancing) (:286-287)
-> UsdImaging_InstanceProxyPathTranslationSI (:295-296)
-> UsdImagingMaterialBindingsResolvingSceneIndex (:298-299)
-> _AddPluginSceneIndices (UsdImagingSceneIndexPlugin, see §6.4) (:301-302)
-> UsdImagingSelectionSceneIndex (:304-305)
-> UsdImagingRenderSettingsFlatteningSceneIndex (:307-308)
So the exec overlay sits before instancing propagation and before
flattening, on raw stage paths — this is why the exec adapters can publish a
world-space matrix with resetXformStack = true and have flattening honor it.
1.4 How usdview reaches this code¶
Stock usdview constructs the engine directly:
pxr/usdImaging/usdviewq/stageView.py:965-968 —
self._renderer = UsdImagingGL.Engine(params). The engine builds the full
chain in _CreateSceneIndicesAndRenderer (engine.cpp:1506-1597), which calls
_CreateSceneIndexChainAndRenderer (engine.cpp:1748-1794) and
_CreateUsdImagingSceneIndices (engine.cpp:1677-1701). Scene index
mode is on by default (USDIMAGINGGL_ENGINE_ENABLE_SCENE_INDEX default true,
engine.cpp:78-79). Net: running stock usdview with
USDIMAGINGGL_ENGINE_ENABLE_EXEC_SCENE_INDEX=1 (and a PXR_BUILD_EXEC=ON
build) activates the exec scene index; nothing else is required.
usdview does not pass any append callback itself and there is no registry of such callbacks — the engine hard-binds its own member function.
2. Stage access and ExecUsdSystem creation¶
The engine forwards the stage explicitly, right next to the UsdImaging SI:
// engine.cpp:536-543 (during first PrepareBatch/population)
_usdImagingSceneIndex->SetStage(stage);
if (_execStageSceneIndex) {
_execStageSceneIndex->SetStage(stage);
}
UsdExecImaging_StageSceneIndex::SetStage (stageSceneIndex.cpp:42-51) simply
creates/destroys the request object:
UsdExecImaging_Request (request.h:55-142) owns everything:
// request.cpp:83-94 (ctor)
_system.emplace(_stage); // std::optional<ExecUsdSystem>, request.h:131
_objectsChangedListener = _ObjectsChangedListener::New(this); // AFTER system, request.cpp:91-93
So the ExecUsdSystem is created inside the request, per stage, at
SetStage time. ExecUsdSystem is constructed from a
UsdStageConstRefPtr (pxr/exec/execUsd/system.h:48-49) and extends the
stage's lifetime (system.h:40-43). The request also registers its own
TfNotice listener for UsdNotice::ObjectsChanged scoped to that stage
(request.cpp:33-68, key registration at :49-53) — this is in addition to the
listener ExecUsdSystem itself installs.
There is no discovery mechanism: the stage arrives only because
UsdImagingGLEngine pushes it via the interface's SetStage.
3. Evaluation & time: when Compute happens, and how values reach Hydra¶
3.1 Driving methods (all called by the engine on the render thread)¶
The engine drives the exec SI in lock-step with the UsdImaging SI, from
UsdImagingGLEngine::PrepareBatch (called by Render) / _PreSetTime — i.e.
on whatever thread calls Render() (the main thread in usdview), with the GIL
released (TF_PY_ALLOW_THREADS_IN_SCOPE, engine.cpp:481):
// engine.cpp:484-498 (PrepareBatch -> scene time)
_usdImagingSceneIndex->SetTime(params.frame);
if (_execStageSceneIndex) {
_execStageSceneIndex->SetTime(params.frame);
_noticeBatchingStageSceneIndex->Flush(); // release batched notices
}
// engine.cpp:2368-2376 (_PreSetTime -> pending edits)
_usdImagingSceneIndex->ApplyPendingUpdates();
if (_execStageSceneIndex) {
_execStageSceneIndex->ApplyPendingUpdates();
_noticeBatchingStageSceneIndex->Flush();
}
UsdExecImaging_StageSceneIndex (stageSceneIndex.cpp):
void SetTime(UsdTimeCode time) { // :53-61
_request->SetTime(time); // -> ExecUsdSystem::ChangeTime (request.cpp:121)
_request->Refresh(); // rebuild/recompute as needed
_SendPrimsDirtied(_request->TakeDirtiedPrimEntries());
}
void ApplyPendingUpdates() { // :63-70
_request->Refresh();
_SendPrimsDirtied(_request->TakeDirtiedPrimEntries());
}
UsdExecImaging_Request::Refresh (request.cpp:96-109):
if (_requiresRebuild || !_request || !_request->IsValid()) _Rebuild();
if (_requiresRecompute) _Recompute();
_Rebuild(request.cpp:205-277): full_stage->Traverse()(:218); for each prim with an adapter (§5) it callsrequestBuilder.SetAdaptedPrim(prim, *adapter)thenadapter->BuildRequest(prim, requestBuilder)(:232-233), then conservatively dirties the whole prim (_primToDirtyDataSourcesMap[path] = HdDataSourceLocatorSet::UniversalSet(), :239-240 — flagged as a TODO/optimization). It then builds the exec request:
// request.cpp:246-249
_request = _system->BuildRequest(
requestBuilder.TakeValueKeys(),
std::bind(&This::_InvalidateRequestIndices, this, _1), // valueCallback
std::bind(&This::_InvalidateRequestIndices, this, _1)); // timeCallback
(ExecUsdSystem::BuildRequest(std::vector<ExecUsdValueKey>&&,
ExecRequestComputedValueInvalidationCallback&&,
ExecRequestTimeChangeInvalidationCallback&&), execUsd/system.h:105-110.)
Sets _requiresRebuild = false; _requiresRecompute = true (:255-256).
Debug flag USDEXECIMAGING_GRAPH_AFTER_REBUILD dumps the network to a
.dot file via _system->PrepareRequest + ExecSystem::Diagnostics
(:259-276).
_Recompute(request.cpp:279-292):_cacheView.emplace(_system->Compute(*_request));— the only placeComputeis called. (ExecUsdCacheView Compute(const ExecUsdRequest&), execUsd/system.h:129-130; implicitly compiles/schedules.)
3.2 GetPrim never computes¶
GetPrim (stageSceneIndex.cpp:23-34) returns:
return { TfToken(), // empty prim type: type comes
// from UsdImagingStageSceneIndex
// through the merging SI
_request ? _request->GetPrimData(primPath) : nullptr };
GetChildPrimPaths returns {} (:36-40) — the exec SI never contributes
topology and never sends PrimsAdded; the merging scene index gets topology
from the UsdImaging input.
UsdExecImaging_Request::GetPrimData (request.cpp:151-176):
- Looks up _valueKeyMap.primToAdapterMap — no adapter, no data source
(nullptr; not an error) (:161-164).
- Builds a UsdExecImagingRequestAccessorInterfaceSharedPtr as an aliasing
shared_ptr onto the request itself (shared_from_this(), :168-170) — data
sources therefore keep the request (and the ExecUsdSystem) alive.
- Delegates to adapter->GetPrimData(primPath, requestAccessor) (:175).
Actual value extraction is lazy, inside the returned Hd data sources:
UsdExecImagingComputedSampledDataSource/UsdExecImagingComputedTypedSampledDataSource<T>(computedDataSource.h:61-132) wrap aUsdExecImaging_ComputedDataSourceImplwhoseGetValue(shutterOffset)ignores the shutter offset and calls_requestAccessor->GetComputedValue(_valueKey)(computedDataSource.cpp:49-53).GetContributingSampleTimesForIntervalreturnsfalse— no motion-blur samples from exec values (computedDataSource.cpp:55-62).UsdExecImaging_Request::GetComputedValue(request.cpp:124-149) does not compute either; itTF_VERIFYs that!_requiresRebuild && !_requiresRecompute && _request->IsValid(), then maps the value key to a request index via_valueKeyMap.valueKeyToIndexMapand returns_cacheView->Get(index).
Gotcha: if a consumer pulls a computed data source after invalidation but
before the next SetTime/ApplyPendingUpdates (Refresh), the TF_VERIFY fires
and an empty VtValue is returned. The whole design assumes the host app calls
SetTime/ApplyPendingUpdates before Hydra pulls — the notice batching SI
plus the engine's call order guarantee that in usdImagingGL.
3.3 Which locators are overlaid — confirmed xform-only¶
Only two adapters exist, both publishing exactly HdXformSchema:
UsdExecImaging_GeomXformablePrimAdapter::GetPrimData(geomXformablePrimAdapter.cpp:44-63): container{ xform: { matrix: <computed GfMatrix4d from ExecGeomXformableTokens->computeLocalToWorldTransform>, resetXformStack: retained true } }.resetXformStack=truebecause the computed matrix is world-space (comment :24-26).UsdExecImaging_IrXformablePrimAdapter::GetPrimData(irXformablePrimAdapter.cpp:32-51): same shape, value key ={primPath.AppendProperty(ExecIrTokens->posedSpace), ExecBuiltinComputations->computeValue}.
Nothing publishes points/normals/extent/primvars. Confirmed: v26.08 usdExecImaging is xform-only.
4. Invalidation¶
4.1 Exec invalidation -> dirty locators¶
Both the value-invalidation and time-change callbacks of the exec request bind
to UsdExecImaging_Request::_InvalidateRequestIndices(const ExecRequestIndexSet&)
(request.cpp:294-330):
for (const int valueKeyIndex : invalidIndices) {
const ValueKeyInfo &info = _valueKeyMap.indexToValueKeyInfo[valueKeyIndex];
HdDataSourceLocatorSet &dirty = _primToDirtyDataSourcesMap[info.adaptedPrimPath];
info.primAdapter->InvalidatePrimData(info.adaptedPrimPath, info.valueKey, &dirty);
}
_requiresRecompute = true;
i.e. exec reports invalid request indices; the value-key map (built during
_Rebuild by UsdExecImaging_RequestBuilder::_AddValueKey,
requestBuilder.cpp:62-77) maps index -> {valueKey, adaptedPrimPath,
primAdapter} (valueKeyMap.h:32-61). The adapter translates the value key into
Hd locators, e.g. geomXformablePrimAdapter.cpp:65-81 appends
HdDataSourceLocator(xform, matrix).
The accumulated _primToDirtyDataSourcesMap is drained by
TakeDirtiedPrimEntries (request.cpp:178-203) into
HdSceneIndexObserver::DirtiedPrimEntries, which the scene index passes to
_SendPrimsDirtied inside SetTime/ApplyPendingUpdates
(stageSceneIndex.cpp:59, :68).
4.2 Threading¶
ExecUsdSystem::ChangeTimemay invoke the time callback synchronously on the calling thread (comment "This may invoke _TimeChangedInvalidationCallback", request.cpp:120-121). Since the engine callsSetTimefromRender(), everything runs on the render/main thread.- The value callback runs during change processing of authored edits — i.e.
synchronously on whichever thread authored the USD edit (main thread in
usdview). The dirty set is just accumulated;
_SendPrimsDirtiedonly happens later insideSetTime/ApplyPendingUpdates. - Hard rule from exec (execUsd/system.h:99-102): callbacks must NOT call
back into execution (no Compute, no extraction) — hence the deferred
_requiresRecomputeflag + Refresh design. - Value callbacks are only guaranteed after
Compute()has been called, and interest must be renewed by computing again (system.h:85-90).
4.3 Structural (resync) changes¶
_ObjectsChangedCallback (request.cpp:332-393) exists to detect adapter
membership changes that exec cannot see: for each resynced path, it walks
UsdPrimRange(resyncedPrim) and compares the previously mapped adapter
(_valueKeyMap.primToAdapterMap) to UsdExecImaging_AdapterRegistry::GetPrimAdapter(prim):
- resynced adapted prim => _requiresRecompute = true (:376-378);
- adapter changed (prim gained/lost an adapter) => _requiresRebuild = true
and early-out (:382-389).
Prims failing UsdPrimDefaultPredicate are skipped (exec expires deleted
providers on its own, :347-354).
4.4 Time changes dirtying prims¶
Time flow: engine SetTime -> ChangeTime (invokes time callback for
actually time-varying value keys only, filtered by exec — system.h:92-97) ->
adapters convert to locators -> Refresh recomputes -> _SendPrimsDirtied ->
_noticeBatchingStageSceneIndex->Flush() releases the batch downstream.
5. Adapters and the adapter registry¶
Interfaces (all public headers):
// primAdapterInterface.h:33-86
class UsdExecImagingPrimAdapterInterface {
virtual void BuildRequest(const UsdPrim &, UsdExecImagingRequestBuilderInterface &) const = 0;
virtual HdContainerDataSourceHandle GetPrimData(
const SdfPath &, const UsdExecImagingRequestAccessorInterfaceSharedPtr &) const = 0;
virtual void InvalidatePrimData(
const SdfPath &, const UsdExecImagingValueKey &, HdDataSourceLocatorSet *) const = 0;
};
// requestBuilderInterface.h:25-43
class UsdExecImagingRequestBuilderInterface {
virtual void AddValueKey(const UsdPrim &providerPrim, const TfToken &computationName) = 0;
virtual void AddValueKey(const UsdAttribute &providerAttribute) = 0; // computeValue
};
// valueKey.h:26-51 — {SdfPath providerPath; TfToken computationName;} with TfHash/==
5.1 The registry is CLOSED in v26.08¶
UsdExecImaging_AdapterRegistry (note the underscore: private class,
adapterRegistry.h:25-35) is a static function with hard-coded types:
// adapterRegistry.cpp:28-51
UsdExecImagingPrimAdapterInterface *
UsdExecImaging_AdapterRegistry::GetPrimAdapter(const UsdPrim &prim) {
// TODO: The adapter currently has a few hard-coded adapter types. This
// will change in the future to generically handle adapters registered in plugins.
if (prim.IsA<UsdGeomXformable>() && enableUsdGeomXformableAdapter) { ... static GeomXformable adapter ... }
if (prim.IsA<ExecIrXformable>()) { ... static IrXformable adapter ... }
return nullptr;
}
USDEXECIMAGING_ENABLE_USDGEOM_XFORMABLE_ADAPTER(defaulttrue, adapterRegistry.cpp:19-26) can disable the Xformable adapter (it only honorsxformOp:transform, per the setting's docstring).- There is no plugin metadata for adapters. usdExecImaging's
plugInfo.jsonhas an emptyInfoblock (plugInfo.json:4) — it exists only to declare the library to Plug for resource purposes. Compare usdImaging'sUsdImagingPrimAdapterplugInfo entries, which usdExecImaging deliberately does not have yet. adapterRegistry,requestBuilder,request,stageSceneIndex,valueKeyMapare allPRIVATE_CLASSES/PRIVATE_HEADERSin CMake (CMakeLists.txt:13-23), so external code cannot even include them.
Conclusion for question 6: you cannot register a rigExec adapter into
UsdExecImagingAdapterRegistry in v26.08. The registry is closed, private, and
xform-only. The public pieces (computedDataSource.h,
primAdapterInterface.h, requestAccessorInterface.h,
requestBuilderInterface.h, stageSceneIndexInterface.h,
stageSceneIndexFactory.h, valueKey.h — CMakeLists.txt:46-56) are the
shape of a future plugin API, not a working one.
6. External hooks available WITHOUT modifying OpenUSD¶
6.1 (a) HdSceneIndexPlugin via HdSceneIndexPluginRegistry¶
Declaration (docs in pxr/imaging/hd/sceneIndexPlugin.h:25-70):
// plugInfo.json — cf. pxr/imaging/hdGp/plugInfo.json:4-23
"Info": { "Types": {
"RigExecImagingSceneIndexPlugin": {
"bases": ["HdSceneIndexPlugin"],
"displayName": "...", "priority": 0,
"loadWithRenderer": "", // "" == all renderers (mandatory; this is what triggers library preload)
"loadWithApps": [], // optional filter
"tags": [...], "ordering": {"after": [...], "before": [...], "position": "firstAfter"}
} } }
C++ side (pattern from pxr/imaging/hdGp/sceneIndexPlugin.cpp:20-40):
TF_REGISTRY_FUNCTION(TfType) { HdSceneIndexPluginRegistry::Define<RigExecImagingSceneIndexPlugin>(); }
TF_REGISTRY_FUNCTION(HdSceneIndexPlugin) {
HdSceneIndexPluginRegistry::GetInstance().RegisterSceneIndexForRenderer(
HdSceneIndexPluginRegistryTokens->allRenderers, // ""
TfToken("RigExecImagingSceneIndexPlugin"), nullptr,
/*insertionPhase=*/0, HdSceneIndexPluginRegistry::InsertionOrderAtStart);
}
// subclass HdSceneIndexPlugin, override
// _AppendSceneIndex(renderInstanceId, inputScene, inputArgs) (hd/sceneIndexPlugin.h:107-125)
// and optionally _IsEnabled(inputArgs) (:127-134)
Mechanics (all in pxr/imaging/hd/sceneIndexPluginRegistry.cpp):
- Discovery: registry ctor forces Plug discovery (:1154-1164);
_CollectAdditionalMetadata (:1300-1356) reads loadWithRenderer,
loadWithApps, tags, ordering from plugInfo.
- AppendSceneIndicesForRenderer(rendererDisplayName, inputScene,
renderInstanceId, appName) (:1421-1475) first _LoadPluginsForRenderer
(:1358-1402 — loads libraries whose loadWithRenderer matches "" or the
renderer, which runs your TF_REGISTRY_FUNCTIONs), then orders entries
(policy HD_SCENE_INDEX_PLUGIN_ORDERING_POLICY_DEFAULT, default Hybrid,
:40-48) and chains each plugin's _AppendSceneIndex (or registered
callback) over the input scene (:1448-1467).
- inputArgs always contains __rendererDisplayName (underlay, :1435-1439).
Insertion point relative to UsdImaging: UsdImagingGLEngine
_CreateSceneIndexChainAndRenderer (engine.cpp:1748-1794) calls
AppendSceneIndicesForRenderer on _mergingSceneIndex (engine.cpp:1776-1779),
i.e. after the entire UsdImaging chain (which was inserted into that
merging SI, engine.cpp:1592-1593 also merges the task-controller SI) and
before the optional terminal caching SI and the renderer. So such a plugin
sees fully instanced, draw-mode-resolved, xform-flattened data, plus
task-controller prims.
The engine itself uses the callback flavor
(RegisterSceneIndexForRenderer(rendererDisplayName,
SceneIndexAppendCallback, ...), sceneIndexPluginRegistry.h:150-189) for its
_AppSceneIndices (sceneGlobals, material pruning, etc.) at phase 0 /
InsertionOrderAtStart (engine.cpp:183-202). Application code may call this
callback registration before engine construction — that is a supported
public path.
Can an HdSceneIndexPlugin discover the UsdStage? No. _AppendSceneIndex
receives only (renderInstanceId, inputScene, inputArgs); there is no stage in
inputArgs, UsdImagingStageSceneIndex has no public GetStage()
(stageSceneIndex.h — only SetStage, :67), and stock usdview does not put the
stage into UsdUtils.StageCache (verified: no StageCache use in usdviewq;
appController.py:1268-1273 opens the stage directly). What such a plugin can
rely on: the Hydra prim data sources (points, xforms, primvars, etc. as
already resolved by UsdImaging) and its own out-of-band channels.
6.2 (b) UsdImagingSceneIndexAppendCallback / CreateSceneIndicesInfo¶
UsdImagingCreateSceneIndicesInfo::overridesSceneIndexCallback
(pxr/usdImaging/usdImaging/sceneIndices.h:34-52) / the second argument of
UsdImagingSceneIndex::New (sceneIndex.h:48-55). This is the hook
usdExecImaging itself uses (§1.3) and is the only pre-instancing hook.
- Who can pass it: only the code that constructs the UsdImaging scene index
chain. In stock usdview that is
UsdImagingGLEngine, which hard-binds_AppendOverridesSceneIndices(engine.cpp:1687-1689). There is no registry, env var, or Python API to inject an additional callback; the header explicitly notes callback-through-registration "might be revisited later" (sceneIndex.h:42-46). TheUsdImagingCreateSceneIndicesoverloads are deprecated in favor ofUsdImagingSceneIndex(sceneIndices.h:64,73). - Therefore (b) is unusable for stock usdview without patching OpenUSD or replacing the engine.
RigExec sources installed through this callback can publish a rigExecInputs
container. See the upstream input contract for admission,
sampling, warming and binary playback.
6.3 (c) Other public mechanisms¶
- The callback flavor of
RegisterSceneIndexForRenderer(see 6.1) — usable from C++ application code loaded before engine construction, but it inserts at the same post-UsdImaging position. HdGpgenerative procedurals — resolved post-scene-assembly; not suitable for stage-backed exec evaluation.UsdImagingSceneIndexPlugin(the sleeper hit — see 6.4).
6.4 UsdImagingSceneIndexPlugin — plugin hook INSIDE the UsdImaging chain¶
Available since v25.05 (pxr/usdImaging/usdImaging/sceneIndexPlugin.h):
"A base class for scene index plugins that can insert filtering scene indices
into UsdImaging ... intended for UsdSkelImaging" (:27-33). It is TfType/Plug
discovered — open to third parties:
// sceneIndexPlugin.h:51-128
class UsdImagingSceneIndexPlugin {
virtual HdSceneIndexBaseRefPtr AppendSceneIndex(HdSceneIndexBaseRefPtr const &inputScene) = 0;
virtual HdContainerDataSourceHandle FlattenedDataSourceProviders(); // extend flattening
virtual TfTokenVector InstanceDataSourceNames(); // extend NI aggregation keys
virtual TfTokenVector ProxyPathTranslationDataSourceNames();
template<typename T> static void Define(); // TfType::Define<T, Bases<UsdImagingSceneIndexPlugin>> + factory
};
Registration (exactly like UsdSkel,
pxr/usdImaging/usdSkelImaging/resolvingSceneIndexPlugin.cpp:22-41 and
usdSkelImaging/plugInfo.json:42-47):
TF_REGISTRY_FUNCTION(UsdImagingSceneIndexPlugin)
{ UsdImagingSceneIndexPlugin::Define<RigExecImagingResolvingSceneIndexPlugin>(); }
Instantiation: UsdImagingSceneIndexPlugin::GetAllSceneIndexPlugins()
(sceneIndexPlugin.cpp:41-89) enumerates all Plug-derived types, Load()s
their libraries and creates instances; called from _AddPluginSceneIndices
at sceneIndices.cpp:66-78, applied at sceneIndices.cpp:301-302 — i.e.
inside the UsdImaging chain, after instancing/material-binding resolution and
before selection/render-settings flattening. UsdSkel implements full
skinning (points!) at exactly this level
(UsdSkelImagingPointsResolvingSceneIndex), which proves points overlay works
here. No env var gates it; presence of the plugInfo entry is enough.
Caveats:
- Runs for every UsdImaging consumer (usdview, usdrecord, tests) — gate
yourself with your own TfEnvSetting inside AppendSceneIndex.
- Still no UsdStage handle and no time callback (see workarounds below).
- Position is post-instancing: prims inside PI/NI prototypes have propagated
(renamed) paths.
7. usdExecImaging build/plugInfo declaration (for mirroring)¶
pxr_library(usdExecImaging ... RESOURCE_FILES plugInfo.json)(CMakeLists.txt:35-69).Type: "library",Info: {}, standard@PLUG_INFO_*@substitution tokens (plugInfo.json:1-12).- Public/private split as listed in §5; the exec-off build compiles only the stub factory so the library has no exec dependency (CMakeLists.txt:27-33).
- Debug codes:
USDEXECIMAGING_REQUEST,USDEXECIMAGING_GRAPH_AFTER_REBUILD(debugCodes.cpp).
For rigExecImaging, mirror: a pxr_library/equivalent with a plugInfo.json
resource, Type: "library", and (unlike usdExecImaging) a real
Info.Types block declaring your plugin class(es) with their bases.
8. Recommendation: how rigExecImaging should integrate for stock usdview (v26.08)¶
Superseded.
rigExecImagingowns noExecUsdSystem, has noRIGEXECIMAGING_ENABLEsetting and builds no merging overlay of an exec scene index. ItsUsdImagingSceneIndexPlugin(libs/rigExecImaging/sceneIndexPlugin.cpp) appends the filtering scene indices declared inlibs/rigExecImaging/sceneIndices.h, which publish results evaluated by the shared operation graph. The text below is kept as study material.
Do not plan on UsdExecImagingAdapterRegistry — it is closed, private, and
xform-only in v26.08 (adapterRegistry.cpp:31-33 TODO). Also do not plan on
UsdImagingSceneIndexAppendCallback — stock usdview cannot inject one.
Recommended architecture¶
Primary hook: a UsdImagingSceneIndexPlugin (§6.4) — the only public,
plugInfo-driven hook that inserts inside the UsdImaging chain, proven to
support points-level overlays (UsdSkel). In
AppendSceneIndex(inputScene), replicate the usdExecImaging overlay pattern
from engine.cpp:1617-1643:
HdSceneIndexBaseRefPtr RigPlugin::AppendSceneIndex(HdSceneIndexBaseRefPtr const &input) {
if (!TfGetEnvSetting(RIGEXECIMAGING_ENABLE)) return input;
_rigSceneIndex = RigExecImagingSceneIndex::New(); // initial SI, no inputs
auto merge = HdMergingSceneIndex::New();
merge->AddInputScene(_rigSceneIndex, SdfPath::AbsoluteRootPath()); // first => wins
merge->AddInputScene(input, SdfPath::AbsoluteRootPath());
return merge; // (optionally wrap in HdNoticeBatchingSceneIndex you Flush after refresh)
}
Your RigExecImagingSceneIndex should copy UsdExecImaging_StageSceneIndex +
UsdExecImaging_Request structurally: own std::optional<ExecUsdSystem> +
ExecUsdRequest + ExecUsdCacheView, a value-key map
(index -> {valueKey, primPath, locators}), rebuild/recompute flags, exec
invalidation callbacks that only accumulate HdDataSourceLocatorSets, lazy
sampled data sources that read the cache view, and a Refresh() that
rebuilds/Compute()s before _SendPrimsDirtied. For your payload, publish and
invalidate these locators instead of/in addition to xform:
- points:
HdPrimvarsSchema->primvars/points/primvarValue(typedVtVec3fArraydata source under anHdPrimvarSchemacontainer with interpolationvertex); - normals:
primvars/normals/...likewise; - extent:
HdExtentSchema(extent/min,extent/max) — safe becauseUsdImagingExtentResolvingSceneIndexruns upstream of the plugin insertion point (sceneIndices.cpp:232-234); - xform:
xform/matrix+xform/resetXformStack=true— but note that at this chain position xforms are already flattened inside NI propagation, so a world matrix overlay affects only that prim, not descendants.
Stage and time feed: a usdview PluginContainer. The scene index plugin
API gives you neither the UsdStage nor SetTime; stock usdview gives you
both through its own plugin system (pxr/usdImaging/usdviewq/plugin.py:100-129;
a Python PluginContainer declared via plugInfo, discovered through
Plug.Registry.GetAllDerivedTypes(PluginContainerTfType), plugin.py:296-297).
usdview loads these before opening the stage (appController.py:426-432:
"We do this before loading the stage in case a plugin wants to modify global
settings"). Your container:
- registers with
usdviewApiand connects todataModel.signalStageReplaced/ frame-changed signals; - pushes the current
UsdStageRefPtrandUsdTimeCodeinto a small process-wide C++ singleton in rigExecImaging (exposed via a python module), mirroringSetStage/SetTimeofUsdExecImagingStageSceneIndexInterface(stageSceneIndexInterface.h:53-71); - the singleton forwards to the live
RigExecImagingSceneIndexinstance(s), which runChangeTime+Refresh+_SendPrimsDirtied— all on the main thread, matching usdExecImaging's threading model (§3.1, §4.2).
This combination requires zero OpenUSD modifications, works in stock
usdview, and is also reusable outside usdview by any host that calls the
singleton's SetStage/SetTime directly.
Fallback / alternatives¶
- If post-UsdImaging insertion is acceptable (non-instanced rigs, per-prim
primvars only), an
HdSceneIndexPluginwithloadWithRenderer: ""(§6.1) works identically (same stage/time feeding via the usdview plugin) and gives you plugInfo-based ordering (tags/ordering), at the cost of seeing propagated prototype paths and task-controller prims. - Longer term, track upstream: the adapter registry TODO
(adapterRegistry.cpp:31-33) says plugin-registered exec imaging adapters are
planned; when that lands, rigExecImaging should become a
UsdExecImagingPrimAdapterInterfaceimplementation (the public headers —primAdapterInterface.h,requestBuilderInterface.h,computedDataSource.h,valueKey.h— are already shaped for it) and rideUSDIMAGINGGL_ENGINE_ENABLE_EXEC_SCENE_INDEX.
Gotchas checklist¶
- Never call
Compute/extraction from inside exec invalidation callbacks (execUsd/system.h:99-102); only set flags and accumulate locators. - Re-
Computeafter every invalidation to renew callback interest (system.h:85-90). - Send
PrimsDirtiedonly from yourSetTime/ApplyPendingUpdatesequivalents, not from notice/exec callbacks (usdExecImaging pattern, stageSceneIndex.cpp:53-70). - On request rebuild, dirty adapted prims with
HdDataSourceLocatorSet::UniversalSet()(request.cpp:235-240) unless you can be precise. - Your merging-overlay SI must return an empty prim type from
GetPrimand{}fromGetChildPrimPaths(stageSceneIndex.cpp:23-40) so topology and types come from UsdImaging. - Watch
UsdNotice::ObjectsChangedyourself to detect prims gaining/losing rig adapters (request.cpp:332-393); exec handles value/topology expiry for existing providers. GetContributingSampleTimesForInterval->falseunless you implement motion samples (computedDataSource.cpp:55-62).- Gate everything behind your own
TF_DEFINE_ENV_SETTINGso the plugin is inert for other UsdImaging hosts.