Multi-stage RigExec imaging¶
Several stages can be imaged and evaluated in one process, each on its own. The typical case is several usdview sessions in one host process (usdOrchestrate SPEC 14). Two stages opened from the same file (identical prim paths) are the hardest case, and they do not interfere. Before this change the imaging registry was one process-global object: one stage, one snapshot store, one chain list, and one preview. Only the most recent activation evaluated, and every other viewport showed its rest pose.
Code: libs/rigExecImaging/registry.h with the registry*.cpp domain
sources, sceneIndices.{h,cpp},
sceneIndexPlugin.cpp, rigAdapter.cpp, touchPose*.{h,cpp}; for the usdview
plugins, plugin/rigExecUsdview/imagingHandle.py and sessionRegistry.py
(see "usdview plugins").
Tests: tests/testRigExecImagingMultiStage.cpp, and the headless
tests/python/test_imaging_handle.py and tests/python/test_session_state.py.
Contexts¶
One RigExecImagingRegistry object is one imaging context, and each
context belongs to exactly one UsdStage. The following state used to be
process-global and is now per context:
| state | notes |
|---|---|
| snapshot store | read by the context's bound chains, never swapped |
rig sessions and the active _stage |
the stage is held strongly while active |
stage-notice key (_OnObjectsChanged) |
registered on the context's own stage |
| noted rig roots, generated scopes, asset roots, read roots | |
_lastTime, generation, published compiled rig (id and pointer) |
|
| preview slots, preview stage (weak), xform deltas | only this context's chains receive the deltas |
| weight overlay selection | remembered before activation |
| background scheduler | created on the first activation, stopped by every deactivation |
warming counters (GetBackgroundStats) |
per context, kept across deactivations (see below) |
| warm-frame index, warm budgets, burst prep slice |
A context without an active rig owns no threads. The scheduler, with two
workers by default, starts when the context commits its first activation. It
is released by Deactivate, and its last holder joins the workers outside
every lock. Triggers and fenced clears hold a shared_ptr to the scheduler
across their unlocked sections. The scheduler keys jobs by rig path within its
own context, so equal paths on two stages never share a queue, generation or
fence.
Warming counters outlive the scheduler. GetBackgroundStats and
GetWarmingCompletedCountForStage count over the context's lifetime, not
one activation's. A deactivation adds the stopped scheduler's totals, read
when it deactivates, to a per-context accumulator, and the running
scheduler's counts are added on top. Completions of jobs that were still
running at that moment are not counted. The gauges (queue depth, running)
come from the running scheduler only and are zero while no rig is active.
The old singleton kept one scheduler for the whole process, so its counters
never went back to zero; the cache strip's "completed" label and its repaint
gate depend on that. MutableSchedulerProfiler is per activation: it
belongs to the scheduler, and is null while no rig is active.
The directory¶
The directory is a process-level map from stage to context. It lives in
registryDirectory.cpp as RigExecImagingDirectory.
static Ptr ForStage(const UsdStageRefPtr &stage, bool create = true);
static Ptr ForStageCacheId(long long id, bool create); // UsdUtilsStageCache::Get()
static Ptr ForKey(uint64_t key);
static size_t ContextCount();
uint64_t GetKey() const;
UsdStageRefPtr GetBoundStage() const;
- Keyed by stage identity. Entries are found by the
UsdStage*and validated through aUsdStageWeakPtr. An expired stage therefore never aliases a new stage allocated at the same address. Every context carries a monotonically increasing key, never the raw pointer. Anything that outlives a stage holds the key: chains, TouchPose highlights, and therigExec/stageKeyleaf. - Lifetime. The directory holds contexts strongly until their stage expires. The next directory call then prunes them. An active context holds its stage, so only an inactive context can expire. Pruned contexts are destroyed after the directory unlocks. Who ends an activation depends on who started it; see "Activation lifetimes".
- Contexts are created on demand. The rig adapter creates one for every
stage it images, and so do
RigExecTouchPose_Open,SetWeightOverlayForStage,BeginPreviewForStageandActivateForStage. A context with no rig is cheap: a store, an index and a mutex.
Chain to context binding¶
There is no stage at AppendSceneIndex time, so a chain binds when it is
first populated:
- The scene-index plugin builds pruning, xforms, binding and results over an
empty store, and registers the chain with the directory as unbound
(
RegisterUnboundChain). An unbound chain receives nothing stage-specific. - The keyless rig adapter (
RigExecImagingRigAdapter) contributes arigExec/stageKeyleaf on top-level prims only. The leaf is aHdRetainedTypedSampledDataSource<uint64_t>holdingForStage(prim.GetStage())->GetKey(). When a top-level prim is also aRigExecRoot, the leaf is merged into the samerigExeccontainer as therigExec/timetrigger. Any prim that is neither top-level nor a rig root still gets no subprim data. RigExecResultsSceneIndex::_PrimsAddedpulls the leaf from its input (RigExecStageKeyFromAddedEntries) on every batch that holds a top-level prim. When the leaf names a context other than the bound one, the results index callsBindChain(this, key). This happens on the first population, and again when a stage is replaced under the same engine. The directory records the key, and the context seeds the chain with its store (an atomicSetStorethat announces the swap as a structural generation), its generated scopes, its preview deltas and its compiled rig.- From then on the chain resolves its context through the key:
- the time trigger (
_PrimsDirtiedcallsForKey(key)->SetTime); - eager activation (
IsNotedRigRooton the bound context); -
_Broadcast,_SetChainXformDeltasand the scope updates, which reach only the chains bound to the context's key. -
A chain leaves its context in two ways. A later batch can rebind it to another key (a stage replaced under the engine), or its results index can be destroyed (the engine is gone). The destructor calls
ReleaseChain(this), and the directory drops the record by identity. In both cases the context the chain left is checked for release (see "Activation lifetimes").
The mechanism is the same as the time trigger's: a data-source leaf that the stage scene index already builds, with no side channel. The TouchPose highlight scene index binds through the same leaf.
Activation lifetimes¶
When initial compilation or evaluation fails, the context publishes authored
rest guides for controls, joints, and sphere, plane, and curve weights.
Activation still reports failure and IsActive() stays false. These guides
follow authored rest and style edits and time samples; completing missing
inputs retries normal activation. They publish no evaluated control frames,
deformation, shader results, or computed weight overlays. Static weight maps
need their target geometry to display an influence overlay.
The display uses the existing guide drawing helpers and cold-bounds rest placement. It does not execute solvers or movers. An unsuccessful explicit reactivation preserves an already active generation. If an active rig later fails during evaluation, its driven results are replaced with authored guides.
A context is activated in one of two ways, and the way it was activated decides who deactivates it.
- Explicit:
ForStage(stage, true)->Activate(...), orRigExecImaging_ActivateForStage. The host owns the activation, and it lasts until the host callsDeactivate/RigExecImaging_DeactivateForStage. An explicit activation outlives its engines. usdview's plugin relies on this: it activates once and keeps evaluating while usdview rebuilds its renderer. - Automatic: the rig adapter's
EnsureActivatedactivates a stage when its rig root is first imaged, which is how usdrecord and a plain Hydra host evaluate. The library owns this activation. When the last chain bound to the context goes away, the context deactivates itself and releases its stage, its compiled rigs, its edit listener and its worker threads. A chain goes away when its engine is destroyed, or when aSetStagerebinds it to another stage. Nobody else would release it: the host never asked for the activation, and an active context keeps its stage alive, so the directory would never prune it.
Rules:
- The release checks, under the context's
_mutex, that the activation is still automatic and that no chain is bound to the context. A chain that binds in the meantime is either counted, or it adopts the cleared state and re-activates through its own population. - A release is not a host deactivation. A later engine on the same stage
activates the context again through
EnsureActivated. - An explicit activation of an automatically active context takes the
lifetime over (
IsAutoActivated()turns false). After that, only the host deactivates it. - A context only ever evaluates its own stage:
ActivateorEnsureActivatedcalled with another stage is forwarded to that stage's context (created when it has none), and never re-activates or deactivates the caller. A context never refuses a stage on account of a different stage being active. - A context activated automatically that no chain ever binds to is not released. This happens with a hand-built pipeline that never registers with the directory. It lasts until its stage's host deactivates it.
- The results index's destructor is the hook. It runs with no context lock held, because contexts and the directory hold chains only weakly. A results index destroyed during static destruction, after the directory, does nothing.
C API¶
Every entry point names its stage: the stage's UsdUtilsStageCache id comes
first, and the call acts on that stage's context only. An unknown id,
or a stage with no context, answers exactly as an inactive registry would.
Every name below carries the RigExecImaging_ prefix.
| stage-scoped entry point | notes |
|---|---|
int ActivateForStage(long long id, const char *rig, double frame) |
creates the context; an explicit activation. 0 on success, 1 with no stage for id, 2 for a malformed rig path, 3 for a failed activation |
int SetTimeForStage(long long id, double frame) |
|
int OnEditCommittedForStage(long long id) |
the primary warming trigger |
int OnIdleForStage(long long id) |
the secondary warming trigger |
int ServiceFrameDemandForStage(long long id) |
frames on demand: the entries added, -1 when inactive |
int HasFrameDemandForStage(long long id) |
1 while demand waits, 0 when none, -1 when inactive |
int WriteProfileSummaryForStage(long long id, const char *path) |
|
void DeactivateForStage(long long id) |
a HOST deactivation: EnsureActivated never revives the context afterwards |
long long GetGenerationForStage(long long id) |
0 before this context's first publication, and with no context |
int GetMovedFloatsForStage(long long id, const char *paths, float *out, int count) |
how many paths this generation published |
int GetGuideBoundsAssetSpaceForStage(long long id, const char *prim, double out[6]) |
1 when the prim draws something, 0 otherwise |
int GetAllGuideBoundsAssetSpaceForStage(long long id, double out[6]) |
the union over every prim; 0 when the guides belong to multiple asset roots |
int SetWeightOverlayForStage(long long id, const char *prim) |
creates the context; the selection belongs to this context and is remembered before activation |
int GetFrameStatesForStage(long long id, const char *rig, const double *frames, int *states, int count) |
one state per frame (0 uncached, 1 warming, 2 cached, 3 dirty) |
int ClearFrameCacheForStage(long long id, const char *rig) |
|
int WarmRangeForStage(long long id, const char *rig, const double *frames, int count) |
|
long long GetWarmingCompletedCountForStage(long long id) |
completions over this context's lifetime, surviving deactivation and re-activation |
long long GetWarmingProgressCountForStage(long long id) |
|
int BeginPreviewForStage(long long id, const char *paths) |
creates the context; returns the value count UpdatePreviewForStage expects, or -1 |
int UpdatePreviewForStage(long long id, const double *values, int count) |
|
int EndPreviewForStage(long long id) |
|
int EndPreviewWithoutPublishForStage(long long id) |
|
int GetPreviewIdentityForStage(long long id, unsigned long long *session, unsigned long long *revision, int *active) |
the monotonic preview session/revision a snapshot is keyed against |
int DeclarePreviewEditForStage(long long id, const char *paths, int policy, const double *values, int count) |
adds to the preview's edit description (0 default value, 1 time sample, 2 connection) |
int GetPreviewEditStatsForStage(long long id, unsigned long long *session, unsigned long long *revision, int *edits, int *values, int *policy) |
|
int PreviewValueIsIndependentForStage(long long id, const char *attribute, double frame, char *reason, int capacity) |
1 when the composed value at that frame provably does not come from the pending default |
int AdmitWarmRouteForStage(long long id, int route, const char *rig, double frame, unsigned long long session, char *reason, int capacity) |
1 admitted, 0 refused with a reason |
int GetPublishedPointsForStage(long long id, const char *prim, float *xyz, int capacity) |
the point count, -1 when the prim publishes no points, -2 with no context |
int GetPublishedScalarPrimvarForStage(long long id, const char *prim, const char *primvarName, float *out) |
1 published, 0 not published, -2 with no context |
int GetPublishedXformRevisionForStage(long long id, const char *prim, double out[16]) |
1 with the revised * base^-1 map, 0 when the rig drives no transform there, -2 with no context |
ActivateForStage, SetWeightOverlayForStage and BeginPreviewForStage
create the stage's context when it has none (an activation creates it first;
a selection is remembered before activation, and a stage with no rig still
previews its Xforms); no other entry point creates one. These reads already
carry the id in their own signature rather than as a
ForStage suffix, and use that stage's context:
int RigExecImaging_GetControlFrameAssetSpace(long long id, const char *prim, double frame, int isDefault, double out[16]).int RigExecImaging_GetMovedDoublesForStage(long long id, const char *property, double frame, int isDefault, double *out, int capacity).
Migration. The stage-less spelling has been removed: Activate,
SetTime, Deactivate, OnEditCommitted, OnIdle, ServiceFrameDemand,
HasFrameDemand, GetGeneration, GetMovedFloats,
GetGuideBoundsAssetSpace, GetAllGuideBoundsAssetSpace,
WriteProfileSummary, SetWeightOverlay, GetFrameStates,
ClearFrameCache, WarmRange, GetWarmingCompletedCount,
GetWarmingProgressCount, BeginPreview, UpdatePreview, EndPreview and
EndPreviewWithoutPublish without the ForStage suffix, and on the C++ side
RigExecImagingRegistry::GetInstance() and Current(). The break is
intentional and no compatibility shim is retained: an external C or Python
host rebuilds against ForStage / ...ForStage and names its own stage on
every call. A host that activates one stage at a time and deactivates before
switching behaves as it did with the singleton, with one difference worth
naming: activating another stage never releases the first one, so a
single-stage-at-a-time host deactivates the old stage itself.
Two functions exist for diagnostics and tests:
int RigExecImaging_IsActiveForStage(long long id)returns 1 or 0.int RigExecImaging_ContextCount()returns the number of contexts for live stages.
The UsdGeomBoundable extent callback reads the queried stage's own context.
RigExecTouchPose_SyncPose reads the pose from the handle's stage context,
and TouchPose highlights are keyed by that context. Key 0 is unscoped: it is
used for topology-only handles and lights every chain.
Previews. A context whose stage has no rig can still preview. It resolves
xform-lane slots on its bound stage, so BeginPreviewForStage works on a plain
Xform, and the deltas reach only that stage's chains. The rig lane previews
through the context's own evaluator.
Viewport release queues authoring on the stage's owner thread, retaining the final preview until the commit. Undo, a new drag, time or selection changes, and saving drain the pending edit first; a replacement stage invalidates its queued callback. A clean preview committed with exactly the same values keeps its published generation, including the first opinion in an empty session layer. A drag on a property that movers revise previews its base, so its exact commit settles the same way. Empty-field ancestor overs are inert; real metadata, structural edits and connections still require evaluation.
Preview snapshots. Each preview carries a session id and a revision that
increase monotonically: BeginPreviewForStage mints the session, every
UpdatePreviewForStage bumps the revision, and EndPreviewForStage,
EndPreviewWithoutPublishForStage, an undo or redo of a declared path, a
resync at or above a declared path (a resync covers its descendants, and the
stage notice only names the ancestor), a weight-overlay change, a recompile,
deactivation or a replaced stage retire it — the session moves forward, the
revision returns to zero. A host that declares what an edit would write
(DeclarePreviewEditForStage, additive: a repeated path updates rather than
appends) can ask whether a candidate frame is independent of that pending value
(PreviewValueIsIndependentForStage). The answer is yes only when an authored
time sample or a stronger layer opinion provably answers that attribute in the
stage's own layer stack; an attribute a compiled property chain revises, one
with authored connections, one the stage authors nowhere, or a mapped or
non-local edit target (a reference or variant target authors a different spec
path, so a same-spelled sample there decides nothing about the composed value)
is refused. Every rule but the default-time check reads the stage and its
layers rather than the candidate frame, so an activated context holds the
answer per declared path across a burst of warm frames and drops it when a
stage notice retires the declaration; a context with no rig activated hears no
stage notices and re-runs the rules each time. The proof's stage and layer
reads run with the registry's lock released, so a notice authored on another
thread can retire the declaration while a verdict is being derived: a verdict
read under a description that retired or was re-declared inside that window is
refused, and a warm request whose preview provenance has moved on is refused
outright. Warm work carries a route:
the frame the preview stands on is refused as pending, a frame already
backed by a prepared burst is admitted as committed, and a frame built ahead
of its destination is admitted only when
every declared edit is provably independent of it.
usdview plugins¶
The Python plugins (plugin/rigExecUsdview, plugin/touchPose,
plugin/shapeEditor) are loaded once per process, but usdview builds their
containers once per session. A host that runs several usdview sessions in one
process (usdOrchestrate's shared host) therefore shares every module between
its windows, and the plugins keep their state per session.
- Imaging handle (
plugin/rigExecUsdview/imagingHandle.py). Every call a plugin makes into rigExecImaging goes through anImagingHandle(lib, stage)bound to its own session's stage, found by the stage'sUsdUtilsStageCacheid, and the handle calls the stage-scoped surface only. It also answers to the plain names (SetTime,OnIdle,GetGeneration, ...) and to theRigExecImaging_<Name>spellings (cacheStripModellooks entry points up that way) as handle adapters: each one resolves to<Name>ForStage(handle.CacheId(), ...)with the id prepended once, never to a library symbol of that name. A name the library does not export raisesAttributeErrorfrom both the method andgetattr, exactly like aCDLL, sohandle.Has(name)and theexcept AttributeErrorfallbacks say "absent" for it. - Activation goes through
RigExecImaging_ActivateForStage(id, ...); the handle'sActivate()is that call with this session's own id. A library that does not export the required scoped symbols (ActivateForStage,SetTimeForStage,DeactivateForStage) cannot keep this session's calls on this session's stage, soBindLibraryfails at load and the container warns and runs with no imaging rather than acting on whichever stage another session activated last. Optional scoped features (the warming triggers, the frame-cache queries, the preview, the influence overlay) are still probed for at their call sites. Deactivation isDeactivateForStagefor the container's own stage only; a container never deactivates another session's stage, and a session holding no cached stage deactivates nothing. - Per-session state (
plugin/rigExecUsdview/sessionRegistry.py). ASessionRegistryfiles one value per session. Its key is the session's main window (usdviewApi.qMainWindow), held weakly, and the entry is dropped when the window is destroyed. The state kept this way: the rigExec, TouchPose and shape editor containers (rigExecUsdview.ContainerFor(api)), the gizmo and view cube controllers and their pending installs (gizmoUI.GetController(api),viewCubeUI.GetController(api)), gizmo tool settings,gizmoMath's published-frame readers,gizmoPreview's channels, and every panel's_instance. A caller that passes no api gets the session that ownsQApplication.activeWindow(), else the only session, else None. No session wins by registering last. The old module attributes (gizmoUI._controller,viewCubeUI._controller,rigExecUsdview._container) can still be read, and give that same answer.sessionRegistry.ForgetSession(api)drops a session from every registry at once; usdOrchestrate's host calls it when a session closes. - Application-wide event filters. The gizmo hotkeys act only on events
whose window belongs to their session (
sessionRegistry.SessionOfEvent). The graph editor's hotkeys act only inside its own panel. - Published control frames. Each session's
gizmoMathreader answers only for its own stage, compared by identity, so a gizmo never reads another session's evaluated frame, even at an identical prim path.
Lock order¶
scheduler fence mutex (ClearFrameCache / SetWeightOverlay only)
-> context _mutex
-> context _notedMutex
-> scheduler state -> warm index / frame cache shards
-> DIRECTORY mutex (leaf)
- The directory mutex is a leaf. It is taken under a context's
_mutex, for chain snapshots inActivate,Deactivateand_SetChainXformDeltas, and it is taken on its own. While it is held, nothing calls into a context and no context is destroyed. _notedMutexstays separate from_mutex. The adapter notes rig roots, and now also resolvesForStage(directory leaf), from traversals that_DirtyXformSubtreemakes while holding_mutex.- Notices that re-enter a context are always sent unlocked. This covers
_Broadcast,_AdoptChain, and the results index's trigger throughForKey._SetChainXformDeltassends under_mutex, as it always did, because the xform dirties never intersectrigExec/time. The results index tests the trigger locator before it looks up the context. - An automatic release (
ReleaseChain, or a rebind inBindChain) resolves the context through the directory with no lock held. It then takes that context's_mutex, checks the bound chains under the directory leaf, and deactivates. The broadcast and the scheduler join run unlocked, exactly as inDeactivate.
Lifetimes (summary)¶
- A stage's context lives while the stage lives. After the stage expires, the next directory call releases the context. An active context holds its stage, so the activation has to end first:
- An automatic activation ends by itself when its last bound chain goes away, whether the engine is destroyed or the stage is replaced under it.
- An explicit activation ends only when its host deactivates it.
UsdImaging's own chain also holds the stage until the engine is destroyed;
SetStage(nullptr)is not enough. A host-deactivated context stays inactive until the host activates it again, so an engine torn down after the deactivation cannot revive it. - A chain's registration dies with its results index (its destructor calls
ReleaseChain). A chain that outlives its context keeps the stale key,ForKeyresolves that key to nothing, and the chain keeps working and can rebind. - Nothing in the library holds a context just because it was activated last.
What ends with the activation -- a host deactivation, or an automatic
release when the last bound chain goes away (see "Activation lifetimes")
-- is the active context's own hold on its stage, its rig sessions, and
its worker threads. The directory keeps the context itself strongly for as
long as the stage lives, including after a host deactivation: a later
re-activation sees the same context, with its warming counters surviving
deactivation and re-activation (see "The directory" and the
ForStagetable). The context is released only when its stage expires and the next directory call prunes it.