UsdGeomVisibilityAPI

Fully qualified name: usdrt::UsdGeomVisibilityAPI

class UsdGeomVisibilityAPI : public usdrt::UsdAPISchemaBase

/// UsdGeomVisibilityAPI introduces properties that can be used to author visibility opinions.

The purpose visibility attributes added by this schema, guideVisibility, proxyVisibility, and renderVisibility can each be used to control visibility for geometry of the corresponding purpose values, with the overall visibility attribute acting as an override. I.e., if visibility evaluates to “invisible”, purpose visibility is invisible; otherwise, purpose visibility is determined by the corresponding purpose visibility attribute.

Note that the behavior of guideVisibility is subtly different from the proxyVisibility and renderVisibility

attributes, in that “guide” purpose visibility always evaluates to either “invisible” or “visible”, whereas the other attributes may yield computed values of “inherited” if there is no authored opinion on the attribute or inherited from an ancestor. This is motivated by the fact that, in Pixar”s user workflows,

we have never found a need to have all guides visible in a scene by

default, whereas we do find that flexibility useful for “proxy” and

”render” geometry.

This schema can only be applied to UsdGeomImageable prims. The

UseGeomImageable schema provides API for computing the purpose visibility

values that result from the attributes introduced by this schema.

For any described attribute @em Fallback @em Value or @em Allowed @em Values below

that are text/tokens, the actual token is published and defined in @ref UsdGeomTokens.

So to set an attribute to the value “rightHanded”, use UsdGeomTokens->rightHanded as the value.

Note

Currently, this schema only introduces the attributes that are used to control purpose visibility. Later, this schema will define all visibility-related properties and UsdGeomImageable will no longer define those properties.

Public Functions

inline explicit UsdGeomVisibilityAPI(const UsdPrim &prim = UsdPrim())

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

inline explicit UsdGeomVisibilityAPI(const UsdSchemaBase &schemaObj)

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

inline virtual ~UsdGeomVisibilityAPI()

Destructor.

inline UsdAttribute GetGuideVisibilityAttr() const

/// This attribute controls visibility for geometry with purpose “guide”.

Unlike overall visibility, guideVisibility is uniform, and therefore cannot be animated.

Also unlike overall visibility, guideVisibility is tri-state, in that a descendant with an opinion of “visible” overrides an ancestor opinion of “invisible”.

The guideVisibility attribute works in concert with the overall visibility attribute: The visibility of a prim with purpose “guide” is determined by the inherited values it receives for the visibility and guideVisibility attributes. If visibility evaluates to “invisible”, the prim is invisible. If visibility evaluates to “inherited” and guideVisibility evaluates to “visible”, then the prim is visible. Otherwise, it is invisible.

Declaration	uniform token guideVisibility = "invisible"
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform
Allowed Values	inherited, invisible, visible

inline UsdAttribute CreateGuideVisibilityAttr() const

See GetGuideVisibilityAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetProxyVisibilityAttr() const

/// This attribute controls visibility for geometry with purpose “proxy”.

Unlike overall visibility, proxyVisibility is uniform, and therefore cannot be animated.

Also unlike overall visibility, proxyVisibility is tri-state, in that a descendant with an opinion of “visible” overrides an ancestor opinion of “invisible”.

The proxyVisibility attribute works in concert with the overall visibility attribute: The visibility of a prim with purpose “proxy” is determined by the inherited values it receives for the visibility and proxyVisibility attributes. If visibility evaluates to “invisible”, the prim is invisible. If visibility evaluates to “inherited” then: If proxyVisibility evaluates to “visible”, then the prim is visible; if proxyVisibility evaluates to “invisible”, then the prim is invisible; if proxyVisibility evaluates to “inherited”, then the prim may either be visible or invisible, depending on a fallback value determined by the calling context.

Declaration	uniform token proxyVisibility = "inherited"
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform
Allowed Values	inherited, invisible, visible

inline UsdAttribute CreateProxyVisibilityAttr() const

See GetProxyVisibilityAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetRenderVisibilityAttr() const

/// This attribute controls visibility for geometry with purpose “render”.

Unlike overall visibility, renderVisibility is uniform, and therefore cannot be animated.

Also unlike overall visibility, renderVisibility is tri-state, in that a descendant with an opinion of “visible” overrides an ancestor opinion of “invisible”.

The renderVisibility attribute works in concert with the overall visibility attribute: The visibility of a prim with purpose “render” is determined by the inherited values it receives for the visibility and renderVisibility attributes. If visibility evaluates to “invisible”, the prim is invisible. If visibility evaluates to “inherited” then: If renderVisibility evaluates to “visible”, then the prim is visible; if renderVisibility evaluates to “invisible”, then the prim is invisible; if renderVisibility evaluates to “inherited”, then the prim may either be visible or invisible, depending on a fallback value determined by the calling context.

Declaration	uniform token renderVisibility = "inherited"
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform
Allowed Values	inherited, invisible, visible

inline UsdAttribute CreateRenderVisibilityAttr() const

See GetRenderVisibilityAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

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 UsdGeomVisibilityAPI Apply(const UsdPrim &prim)

Applies this single-apply API schema to the given prim. This information is stored by adding “VisibilityAPI” to the token-valued, listOp metadata apiSchemas on the prim.

See also

UsdPrim::GetAppliedSchemas()

See also

UsdPrim::HasAPI()

See also

UsdPrim::ApplyAPI()

See also

UsdPrim::RemoveAPI()

Returns:

A valid UsdGeomVisibilityAPI object is returned upon success. An invalid (or empty) UsdGeomVisibilityAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

Public Static Attributes

static const UsdSchemaType schemaType = UsdSchemaType::SingleApplyAPI

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.