Skip to content

Upstream rig inputs

An upstream Hydra scene index can supply authored-level rig inputs without editing the USD stage. On the prim that owns an attribute, publish a rigExecInputs container with an HdSampledDataSource child named by that attribute. For example, the avars:rz child on a joint supplies that joint's avars:rz attribute. Install the source before the RigExec results scene index through the overrides callback. The evaluator API is SetUpstreamInputs; its list replaces the previous list, and an empty list lifts all standing values.

Admission and precedence

Each key must name an existing, unconnected attribute with a stage value. Its value must hold exactly the attribute's supported input type, and the rig must have a listed read of that attribute. This includes admitted mover and weight-object reads, including oracle reads. Upstream values replace the attribute's authored value; interactive overrides take precedence, and connected attributes are rejected. The stage remains unchanged. Admitted paths are sorted by GetUpstreamInputPaths.

Unsupported keys are ignored with a diagnostic:

upstream input <path>: <reason>; ignored

Array admission additionally requires the same element count as the stage value at the evaluated time. A constant stage count is memoized until a relevant stage edit; varying counts are checked at the time of admission. The supported array pool types are int, float, double, vec2f and vec3f. The exact admitted paths, types, time kinds and consumers come from RigExecBakedUpstreamAdmissibleArrays(evaluator).

Array admission is on by default; tests can suspend it with RigExecSetUpstreamArrayAdmissionForTesting. Structural arrays are excluded: painted values and indices read per element by weight packets, folded solver volume weights, ribbon structural points and Derived bases do not become upstream inputs. A geometry chain's base points can be admitted. A path that a weight packet reads per element is structural even when it is also a chain base.

Time and source changes

T0 is the input scene index's time from the latest RigExec time trigger. Data-source sample offsets are relative to T0; stored sample times are absolute (T0 + offset). Pulls run on time triggers, rigExecInputs additions or dirties, and warm-range changes, without holding the registry lock.

For each source, RigExec asks GetContributingSampleTimesForInterval once for the pull window. A uniform source is read at offset zero. A varying source is read only at the returned sample offsets. Values at T0 and warm frames are reconstructed from those samples using the stage's interpolation setting. Linear interpolation applies to float, double, vec3f, vec3d and matrix4d values, and to equal-length float, double, vec2f and vec3f arrays. Other types, unequal array lengths and Held interpolation hold the preceding sample. Boundary samples hold beyond the returned sample times within the pull window.

An in-window time move with unchanged sources reanchors the stored table without calling the source again. A varying source has no pulled value outside that window. A source must dirty rigExecInputs when its samples or source set change; a time trigger alone does not announce a source change. A dirty during a pull permits one deferred pull. Another dirty during that deferred pull is dropped with a diagnostic. With several scene-index chains, the triggering chain supplies the session's table; conflicting keys are diagnosed.

These rules require sources to answer offsets relative to the trigger's T0. A lagging trigger produces values anchored to the wrong time. Long warm windows or large varying arrays can make the pull expensive, even though workers never call the source.

Warming and cache reuse

Live evaluation and warm jobs consume the pulled table. Warm jobs reconstruct arrays from shared sample buffers and carry a per-frame fold hash; the table does not store an array copy for every frame. Uniform and held values share buffers. Frame-cache keys include the frame's admitted upstream values, and sparse reuse misses when an upstream value changes. A missing varying value skips that warm frame with upstream not pulled for this time.

A source-set, window or frame-value change advances the session's upstream serial and cancels the live session's warm generation. Moving only T0 through the same signal does not. The lookup fast path relies on a completed warm row's generation postdating the last upstream source change. A burst is available only when no upstream source varies, and its pins include the upstream serial. Preview updates do not change upstream inputs. Playback sessions consume the table but do not warm frames.

Binary playback

Binary playback admits a key only when FindInput finds the attribute, the file's input tag matches the value type, and the stage attribute is unconnected and has a value. Drop diagnostics follow live admission.

Playback applies upstream values after the stage sampler's Apply, without invalidating the sampler. Numeric keys use SetSampledInputAt; Token keys use SetInputToken with their text, including text absent from the file. The sampler reports which slots it sampled, so playback reapplies those keys, including static SourceBacked inputs during a refresh. Upstream changes do not refresh unrelated static inputs. Lifting a bound key restores the sampler's value when it just sampled that slot; otherwise it rereads that one stage attribute at the playback time. Unbound keys restore their captured defaults with ResetInput.

Playback applies arrays with the authored SetInputArray API. Admission checks against the stage count at evaluation time; the runtime additionally requires the stored default's count. A refused set lifts the key and reports the refusal. Animated arrays with actual AtTime consumers restore the current stage sample when lifted, including a same-time lift or a first refused value. Default-only arrays use ResetInput even when numeric samples mark their slots Animated. Standing upstream arrays are reapplied after stage sampling.

The stage sampler copies Animated AtTime arrays of any element count. Each consumer validates the resulting count as live evaluation does. An oracle's failed sampleSource Get falls back to the raw canonical weightTarget; successful empty samples take precedence and undergo the normal count check. A failed Get clears HasValue; a successful empty array remains a value. Both leaves retain separate captured Default data, so stage samples affect only AtTime reads. Eligibility comes from the file's actual chain base, layout, dense sample, AtTime path-read and oracle consumers. Structural and Default-only leaves are excluded; wire knots (double[]) are currently Default-only. Animated skin layouts retain the exporter's existing refusal. Static reports omit only arrays covered by this same sampler inventory.

Only the evaluator's admitted array paths are public file inputs. Structural painted arrays and excluded point/oracle arrays remain captured as private typed storage slots and are absent from GetInputInfo, FindInput and public set APIs. An internal stage-only bridge samples eligible private oracle arrays, without granting authored overrides or changing public input counts. Static private arrays retain their captured defaults.

An authored upstream array replaces both AtDefault and AtTime reads. With a varying upstream source, each evaluated frame's upstream value also feeds its AtDefault leaves; it does not freeze those leaves at the bake time. If one cage attribute supplies both rest and live lattice reads, both see the standing value. A stage time sample alone reaches AtTime reads only. Playback keeps this distinction: upstream arrays use the authored set, and the stage sampler sets only the AtTime side.

Baking

A bake accepts admitted upstream scalars and arrays. It suspends the complete requested list while evaluating and capturing the authored stage, then restores that list on success or failure. Every standing admitted path must be a listed file input; a missing slot reports an exporter invariant defect. File defaults and static data remain authored-stage values, so the bytes equal a bake with upstream values lifted. RigExecBakeResult::upstreamInputs reports the sorted admitted names on success; callers retain and reapply their values through the scalar or authored array input API. Authored array sets still require the file's default element count. Interactive overrides still refuse a bake.