Struct Attribute 

pub struct Attribute { /* private fields */ }

Stage-composed attribute handle. Mirrors C++ UsdAttribute.

Returned by Stage::create_attribute / Prim::create_attribute with defaults variability = Varying, custom = true, matching C++ generic property authoring. Override via the fluent setters below.

Implementations

impl Attribute

pub fn path(&self) -> &Path

Composed namespace path of the attribute (e.g. /World/Mesh.points).

pub fn stage(&self) -> &Stage

The stage this handle is anchored to.

pub fn prim(&self) -> Prim

Handle to the owning prim.

pub fn set_variability( self, v: Variability, ) -> Result<Self, StageAuthoringError>

Set the attribute’s variability field. Always authors an explicit opinion so weaker layers don’t bubble up through composition; use the Sdf-tier Spec::remove directly if you instead want to clear the local opinion entirely.

pub fn set_custom(self, custom: bool) -> Result<Self, StageAuthoringError>

Set the attribute’s custom flag. Always authors an explicit opinion (see Attribute::set_variability for the rationale).

pub fn set(self, value: impl Into<Value>) -> Result<Self, StageAuthoringError>

Set the attribute’s default value. The convenience spelling of set_at(value, None); mirrors C++ UsdAttribute::Set(value).

pub fn set_at( self, value: impl Into<Value>, time: impl Into<Option<TimeCode>>, ) -> Result<Self, StageAuthoringError>

Set the attribute’s value at time. Mirrors C++ UsdAttribute::Set(value, time).

time is None to author the default value, or Some(tc) (a usd::TimeCode, which a bare TimeCode coerces into) to author a time sample. A numeric time is in stage (composed) time: when the current edit target is an arc with a non-identity layer offset, the sample is keyed at the inverse-mapped source-layer time (C++ UsdEditTarget::MapToSpecTime), so it reads back at time once composition re-applies the offset.

pub fn block(self) -> Result<Self, StageAuthoringError>

Block opinions from weaker layers by authoring a value block on the default and every authored time sample. Mirrors C++ UsdAttribute::Block().

pub fn set_color_space( self, color_space: impl Into<String>, ) -> Result<Self, StageAuthoringError>

Set the colorSpace token.

pub fn set_metadata( self, key: &'static str, value: impl Into<Value>, ) -> Result<Self, StageAuthoringError>

Author a generic metadata field on the attribute spec. Mirrors C++ UsdAttribute::SetMetadata(name, value).

Used for fields the schema layers on top of the core attribute metadata (e.g. UsdSkel’s weight on inbetweens:NAME, UsdGeom’s elementSize / interpolation on primvars). The dedicated setters above (set_variability, set_custom, set_color_space) cover the common cases — reach for this one when the schema requires a custom field key not represented by sdf::FieldKey.

key is &'static str so the change-tracking layer can record it without copying; pass a pub const FOO: &str = "..." token rather than a runtime-built string.

pub fn set_connections<I>(self, targets: I) -> Result<Self, StageAuthoringError>

where I: IntoIterator<Item = Path>,

Author the attribute’s connectionPaths — the .connect targets that wire this attribute to other properties. Mirrors C++ UsdAttribute::SetConnections / UsdShadeInput::ConnectToSource.

Each path is a full property path including its namespace, e.g. </Mat/Tex.outputs:rgb> or </Mat.inputs:diffuseColor>. Replaces any previously authored connections (the list op is written explicit). This is the primitive every UsdShade input/output connection is built on.

pub fn connect_to(self, source: &Attribute) -> Result<Self, StageAuthoringError>

Wire this attribute to a single source property, replacing any existing connections. The connectable shorthand for set_connections over one source; mirrors C++ UsdShadeInput / UsdShadeOutput::ConnectToSource. Chains after create_attribute / a UsdShade create_input / create_output, since the connection is authored on this (the consuming) property’s spec.

pub fn add_connection(self, target: Path) -> Result<Self, StageAuthoringError>

Add a single connection target at the default USD list position. No-op if already present (skips cache invalidation in that case). Joins the prepended-items list op, matching C++ UsdAttribute::AddConnection’s default back-of-prepend position.

pub fn add_connection_prepended( self, target: Path, ) -> Result<Self, StageAuthoringError>

Add a single connection target to the prepended list op. No-op if already present. This is the explicit spelling of the default USD AddConnection position.

pub fn add_connection_appended( self, target: Path, ) -> Result<Self, StageAuthoringError>

Add a single connection target to the appended list op. No-op if already present. Use this when the new target should compose behind prepended opinions from this layer.

pub fn remove_connection( &self, target: &Path, ) -> Result<bool, StageAuthoringError>

Remove a single connection target. Returns Ok(true) if it was present. Takes &self (returns bool, not Self, so it doesn’t chain). Mirrors C++ UsdAttribute::RemoveConnection.

pub fn clear_connections(self) -> Result<Self, StageAuthoringError>

Clear all authored connectionPaths on the edit target. Skips cache invalidation when no opinion was authored. Mirrors C++ UsdAttribute::ClearConnections.

pub fn has_authored_connections(&self) -> Result<bool>

true when any connection opinion is authored — including an explicit-empty list op (.connect = []), the canonical way to block weaker-layer connections. Mirrors C++ UsdAttribute::HasAuthoredConnections.

pub fn connections(&self) -> Result<Vec<Path>>

Composed connectionPaths, with list-op edits folded across every contributing layer (prepend / append / add / delete). Returns an empty vec when no connection is authored, the path is not a property, or the owning prim is outside the population mask. Mirrors C++ UsdAttribute::GetConnections.

pub fn compute_connections(&self) -> Result<(Vec<Path>, Vec<Path>)>

Composes this attribute’s connection paths together with the paths its list-op deletes, returned as (connections, deleted) (C++ PcpBuildFilteredTargetIndex and its deletedPaths out-param). Both are empty when the owning prim is outside the population mask.

pub fn variability(&self) -> Result<Option<Variability>>

Composed variability for this attribute (spec 12.2.3: the weakest authored opinion wins), if any layer authored one. Mirrors C++ UsdAttribute::GetVariability.

pub fn is_custom(&self) -> Result<bool>

true when this attribute is composed as custom (spec 12.2.4: true if any opinion in the stack is true). Mirrors C++ UsdProperty::IsCustom; an unauthored custom field resolves to false.

pub fn type_name(&self) -> Result<Option<Token>>

Composed value type (the typeName field), if set. Mirrors C++ UsdAttribute::GetTypeName.

typeName is a token; a value of any other type is treated as untyped (None).

pub fn get<T>(&self) -> Result<Option<T>>

where T: TryFrom<Value>, T::Error: Error + Send + Sync + 'static,

Composed default value decoded to T, if any layer authored one. The convenience spelling of get_at(None); mirrors C++ UsdAttribute::Get.

T is any type implementing TryFrom<sdf::Value> — a scalar (get::<f32>()), an array (get::<Vec<f32>>()), or sdf::Value itself (get::<sdf::Value>()) for the raw value. A type mismatch against the authored value surfaces as an Err, not None.

pub fn get_at<T>(&self, time: impl Into<Option<TimeCode>>) -> Result<Option<T>>

where T: TryFrom<Value>, T::Error: Error + Send + Sync + 'static,

Composed value at time decoded to T. Mirrors C++ UsdAttribute::Get(value, time).

time is None to read the default value, or Some(tc) (a usd::TimeCode, which a bare TimeCode coerces into) to resolve a time sample under the stage’s InterpolationType.

pub fn cast<T: FromValueCast>(&self) -> Result<Option<T>>

Retrieves the composed default sdf::Value and casts it to T via the registered coercions (sdf::Value::cast).

Unlike get — a strict fetch that requires the exact held variant (get::<String>() reads a Value::String but not a Value::Token) — cast converts the value to T (numeric scalars range-checked, token ↔ string, vector/quaternion precision) and returns an error if no conversion to T applies. None when no layer authored an opinion.

pub fn get_metadata<T>(&self, key: &str) -> Result<Option<T>>

where T: TryFrom<Value>, T::Error: Error + Send + Sync + 'static,

Composed value of a generic metadata field on the attribute decoded to T, if any layer authored one. Mirrors C++ UsdObject::GetMetadata(name, &value).

The read counterpart of Attribute::set_metadata; used for the schema-layered fields it authors (UsdGeom’s interpolation / elementSize on primvars, UsdSkel’s inbetween weight, …). Decode to the field’s type (get_metadata::<i32>("elementSize")) or to sdf::Value for the raw value.

pub fn time_samples(&self) -> Result<Option<TimeSampleMap>>

Composed timeSamples map.

pub fn query(&self) -> AttributeQuery

Builds an AttributeQuery for this attribute — a cached value source for repeated time-code reads. Mirrors C++ UsdAttributeQuery(attr). Prefer this over calling get_at in a loop when sampling one attribute at many time codes, since the query resolves the value source once.

pub fn time_sample_times(&self) -> Result<Vec<f64>>

The authored sample times in ascending order, or empty when none are authored. Mirrors C++ UsdAttribute::GetTimeSamples.

Gathers the times from the strongest value source — local timeSamples, then value clips (spec 12.3.4), then timeSamples across reference / payload arcs — each retimed to stage time.

pub fn time_samples_in_interval( &self, interval: RangeInclusive<f64>, ) -> Result<Vec<f64>>

The authored sample times within the closed interval interval, in ascending order. Mirrors C++ UsdAttribute::GetTimeSamplesInInterval.

The interval is inclusive at both ends. For samples authored at {0, 5, 10}, time_samples_in_interval(2.0..=8.0) returns [5.0], while time_samples_in_interval(0.0..=5.0) returns [0.0, 5.0].

pub fn num_time_samples(&self) -> Result<usize>

The number of authored time samples, zero when none. Mirrors C++ UsdAttribute::GetNumTimeSamples.

pub fn bracketing_time_samples( &self, time: impl Into<TimeCode>, ) -> Result<Option<(f64, f64)>>

The pair of authored sample times bracketing time, or None when no samples are authored. Mirrors C++ UsdAttribute::GetBracketingTimeSamples: the pair collapses to one repeated time at or beyond an end sample, or when time lands exactly on a sample; otherwise lower < time < upper. The two-sample primitive behind motion-blur and shutter sampling.

pub fn value_might_be_time_varying(&self) -> Result<bool>

true when the value may change over time, the fast check behind motion-blur and animation queries. Mirrors C++ UsdAttribute::ValueMightBeTimeVarying: true when more than one sample is composed, and conservatively when a participating value-clip set has more than one active clip (spec 12.3.4) — those clips can each serve a different value even where the reported sample count collapses to one.

pub fn property_stack(&self) -> Result<Vec<(String, Path)>>

Returns the property stack: each (layer identifier, spec path) site that authors a spec for this attribute, strongest first. Mirrors C++ UsdProperty::GetPropertyStack.

Trait Implementations

impl Clone for Attribute

fn clone(&self) -> Attribute

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.