UsdGeomPrimvarsAPI#

Fully qualified name: usdrt::UsdGeomPrimvarsAPI

class UsdGeomPrimvarsAPI : public usdrt::UsdAPISchemaBase#

UsdGeomPrimvarsAPI encodes geometric “primitive variables”, as UsdGeomPrimvar, which interpolate across a primitive’s topology, can override shader inputs, and inherit down namespace.

Which Method to Use to Retrieve Primvars#

While creating primvars is unambiguous (CreatePrimvar()), there are quite a few methods available for retrieving primvars, making it potentially confusing knowing which one to use. Here are some guidelines:

• If you are populating a GUI with the primvars already available for authoring values on a prim, use GetPrimvars().

• If you want all of the “useful” (e.g. to a renderer) primvars available at a prim, including those inherited from ancestor prims, use FindPrimvarsWithInheritance(). Note that doing so individually for many prims will be inefficient.

• To find a particular primvar defined directly on a prim, which may or may not provide a value, use GetPrimvar().

• To find a particular primvar defined on a prim or inherited from ancestors, which may or may not provide a value, use FindPrimvarWithInheritance().

• To efficiently query for primvars using the overloads of FindPrimvarWithInheritance() and FindPrimvarsWithInheritance(), one must first cache the results of FindIncrementallyInheritablePrimvars() for each non-leaf prim on the stage.

Public Functions

inline explicit UsdGeomPrimvarsAPI(const UsdPrim &prim = UsdPrim())#

Construct a UsdGeomPrimvarsAPI on UsdPrim prim. Equivalent to UsdGeomPrimvarsAPI::Get(prim.GetStage(), prim.GetPath()) for a valid prim , but will not immediately throw an error for an invalid prim.

inline explicit UsdGeomPrimvarsAPI(const UsdSchemaBase &schemaObj)#

Construct a UsdGeomPrimvarsAPI on the prim held by schemaObj . Should be preferred over UsdGeomPrimvarsAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

inline virtual ~UsdGeomPrimvarsAPI()#

Destructor.

inline UsdGeomPrimvar CreatePrimvar(

const TfToken &name,

const SdfValueTypeName &typeName,

const TfToken &interpolation = TfToken(),

) const#

Author scene description to create an attribute on this prim that will be recognized as Primvar (i.e. will present as a valid UsdGeomPrimvar).

The name of the created attribute may or may not be the specified name, due to the possible need to apply property namespacing for primvars. See Usd_Creating_and_Accessing_Primvars for more information. Creation may fail and return an invalid Primvar if name contains a reserved keyword, such as the “indices” suffix we use for indexed primvars.

The behavior with respect to the provided typeName is the same as for UsdAttributes::Create(), and interpolation is as described in UsdGeomPrimvar::GetInterpolation().

If interpolation is left unspecified, we will author no opinions for them, which means any (strongest) opinion already authored in any contributing layer for these fields will become the Primvar’s values, or the fallbacks if no opinions have been authored.

See also

UsdPrim::CreateAttribute(), UsdGeomPrimvar::IsPrimvar()

Returns:

an invalid UsdGeomPrimvar if we failed to create a valid attribute, a valid UsdGeomPrimvar otherwise. It is not an error to create over an existing, compatible attribute.

inline UsdGeomPrimvar GetPrimvar(const TfToken &name) const#

Return the Primvar object named by name, which will be valid if a Primvar attribute definition already exists.

Name lookup will account for Primvar namespacing, which means that this method will succeed in some cases where

UsdGeomPrimvar(prim->GetAttribute(name))

will not, unless name is properly namespace prefixed.

See also

HasPrimvar(), Which Method to Use to Retrieve Primvars

Note

Just because a Primvar is valid and defined, and even if its underlying UsdAttribute (GetAttr()) answers HasValue() affirmatively, one must still check the return value of Get(), due to the potential of time-varying value blocks (see Usd_AttributeBlocking).

std::vector<UsdGeomPrimvar> GetPrimvars() const#

Return valid UsdGeomPrimvar objects for all defined Primvars on this prim, similarly to UsdPrim::GetAttributes().

The returned primvars may not possess any values, and therefore not be useful to some clients. For the primvars useful for inheritance computations, see GetPrimvarsWithAuthoredValues(), and for primvars useful for direct consumption, see GetPrimvarsWithValues().

See also

Which Method to Use to Retrieve Primvars

std::vector<UsdGeomPrimvar> GetAuthoredPrimvars() const#

Like GetPrimvars(), but include only primvars that have some authored scene description (though not necessarily a value).

See also

Which Method to Use to Retrieve Primvars

std::vector<UsdGeomPrimvar> GetPrimvarsWithValues() const#

Like GetPrimvars(), but include only primvars that have some value, whether it comes from authored scene description or a schema fallback.

For most purposes, this method is more useful than GetPrimvars().

See also

Which Method to Use to Retrieve Primvars

std::vector<UsdGeomPrimvar> GetPrimvarsWithAuthoredValues() const#

Like GetPrimvars(), but include only primvars that have an authored value.

This is the query used when computing inheritable primvars, and is generally more useful than GetAuthoredPrimvars().

See also

Which Method to Use to Retrieve Primvars

inline std::vector<UsdGeomPrimvar> FindInheritablePrimvars() const#

Compute the primvars that can be inherited from this prim by its child prims, including the primvars that this prim inherits from ancestor prims. Inherited primvars will be bound to attributes on the corresponding ancestor prims.

Only primvars with authored, non-blocked, constant interpolation values are inheritable; fallback values are not inherited. The order of the returned primvars is undefined.

It is not generally useful to call this method on UsdGeomGprim leaf prims, and furthermore likely to be expensive since most primvars are defined on Gprims.

See also

Which Method to Use to Retrieve Primvars

inline std::vector<UsdGeomPrimvar> FindIncrementallyInheritablePrimvars(

const std::vector<UsdGeomPrimvar> &inheritedFromAncestors,

) const#

Compute the primvars that can be inherited from this prim by its child prims, starting from the set of primvars inherited from this prim’s ancestors. If this method returns an empty vector, then this prim’s children should inherit the same set of primvars available to this prim, i.e. the input inheritedFromAncestors .

As opposed to FindInheritablePrimvars(), which always recurses up through all of the prim’s ancestors, this method allows more efficient computation of inheritable primvars by starting with the list of primvars inherited from this prim’s ancestors, and returning a newly allocated vector only when this prim makes a change to the set of inherited primvars. This enables O(n) inherited primvar computation for all prims on a Stage, with potential to share computed results that are identical (i.e. when this method returns an empty vector, its parent’s result can (and must!) be reused for all of the prim’s children.

See also

Which Method to Use to Retrieve Primvars

inline UsdGeomPrimvar FindPrimvarWithInheritance(

const TfToken &name,

) const#

Like GetPrimvar(), but if the named primvar does not exist or has no authored value on this prim, search for the named, value-producing primvar on ancestor prims.

The returned primvar will be bound to the attribute on the corresponding ancestor prim on which it was found (if any). If neither this prim nor any ancestor contains a value-producing primvar, then the returned primvar will be the same as that returned by GetPrimvar().

This is probably the method you want to call when needing to consume a primvar of a particular name.

See also

Which Method to Use to Retrieve Primvars

inline UsdGeomPrimvar FindPrimvarWithInheritance(

const TfToken &name,

const std::vector<UsdGeomPrimvar> &inheritedFromAncestors,

) const#

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This version of FindPrimvarWithInheritance() takes the pre-computed set of primvars inherited from this prim’s ancestors, as computed by FindInheritablePrimvars() or FindIncrementallyInheritablePrimvars() on the prim’s parent.

See also

Which Method to Use to Retrieve Primvars

inline std::vector<UsdGeomPrimvar> FindPrimvarsWithInheritance(

) const#

Find all of the value-producing primvars either defined on this prim, or inherited from ancestor prims.

See also

Which Method to Use to Retrieve Primvars

inline std::vector<UsdGeomPrimvar> FindPrimvarsWithInheritance(

const std::vector<UsdGeomPrimvar> &inheritedFromAncestors,

) const#

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This version of FindPrimvarsWithInheritance() takes the pre-computed set of primvars inherited from this prim’s ancestors, as computed by FindInheritablePrimvars() or FindIncrementallyInheritablePrimvars() on the prim’s parent.

See also

Which Method to Use to Retrieve Primvars

inline std::vector<UsdGeomPrimvar> FindInheritedPrimvars() const#

Find all primvars inherited from ancestor prims.

inline UsdGeomPrimvar FindInheritedPrimvar(const TfToken &name) const#

Find primvar with given name inherited from ancestor prims.

inline bool HasPossiblyInheritedPrimvar(const TfToken &name) const#

Is there a Primvar named name with an authored value on this prim or any of its ancestors?

This is probably the method you want to call when wanting to know whether or not the prim “has” a primvar of a particular name.

See also

FindPrimvarWithInheritance()

UsdPrim GetPrim() const#

Return this schema object’s held prim.

SdfPath GetPath() const#

Return the SdfPath to this schema object’s held prim.

inline explicit operator bool() const#

Check if this schema object is compatible with it’s held prim and that the prim is valid.

A typed schema object is compatible if the held prim’s type is or is a subtype of the schema’s type. Based on prim.IsA().

An API schema object is compatible if the API is of type SingleApplyAPI or UsdSchemaType::MultipleApplyAPI, and the schema has been applied to the prim. Based on prim.HasAPI.

This method invokes polymorphic behaviour.

See also

UsdSchemaBase::_IsCompatible()

Returns:

True if the help prim is valid, and the schema object is compatible with its held prim.

Public Static Functions

static inline bool CanContainPropertyName(const TfToken &name)#

Test whether a given name contains the “primvars:” prefix.

Public Static Attributes

static const UsdSchemaType schemaType = UsdSchemaType::NonAppliedAPI#

Compile time constant representing what kind of schema this class is.

See also

UsdSchemaType

Protected Functions

inline const TfToken &_GetInstanceName() const#

Returns the instance name of the API schema object belonging to a multiple-apply API schema.

The returned instance name will be empty for non-applied and single-apply API schemas.

inline virtual bool _IsCompatible() const#

Check whether this APISchema object is valid for the currently held prim.

If this is an applied API schema, this returns true if the held prim is valid and already has the API schema applied to it, along with the instanceName (in the case of multiple-apply). The instanceName should not be empty in the case of a multiple-apply API schema.

This check is performed when clients invoke the explicit bool conversion operator, implemented in UsdSchemaBase.

See also

UsdPrim::HasAPI()

inline const TfToken _GetType() const#

Helper for subclasses to get this schema’s type token.

Note

This diverges from Usd and returns a TfToken, since we don’t implements TfType.

Returns:

The token representing the schema’s TfType.