HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdGeomImageable Class Reference

#include <imageable.h>

+ Inheritance diagram for UsdGeomImageable:

Classes

struct  PurposeInfo
 

Public Member Functions

 UsdGeomImageable (const UsdPrim &prim=UsdPrim())
 
 UsdGeomImageable (const UsdSchemaBase &schemaObj)
 
virtual USDGEOM_API ~UsdGeomImageable ()
 Destructor. More...
 
USDGEOM_API UsdAttribute GetVisibilityAttr () const
 
USDGEOM_API UsdAttribute CreateVisibilityAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetPurposeAttr () const
 
USDGEOM_API UsdAttribute CreatePurposeAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdRelationship GetProxyPrimRel () const
 
USDGEOM_API UsdRelationship CreateProxyPrimRel () const
 
Visibility Authoring Helpers

Convenience API for making an imageable visible or invisible.

USDGEOM_API void MakeVisible (const UsdTimeCode &time=UsdTimeCode::Default()) const
 
USDGEOM_API void MakeInvisible (const UsdTimeCode &time=UsdTimeCode::Default()) const
 
Computed Attribute Helpers

Visbility, Purpose, Bounds (World, Local, and Untransformed), and Transform (LocalToWorld and ParentToWorld) are all qualities of a prim's location in namespace that require non-local data and computation. Computing these efficiently requires a stage-level cache, but when performance is not a concern, it is convenient to query these quantities directly on a prim, so we provide convenience API here for doing so.

USDGEOM_API TfToken ComputeVisibility (UsdTimeCode const &time=UsdTimeCode::Default()) const
 
USDGEOM_API UsdAttribute GetPurposeVisibilityAttr (const TfToken &purpose=UsdGeomTokens->default_) const
 
USDGEOM_API TfToken ComputeEffectiveVisibility (const TfToken &purpose=UsdGeomTokens->default_, const UsdTimeCode &time=UsdTimeCode::Default()) const
 
USDGEOM_API PurposeInfo ComputePurposeInfo () const
 
USDGEOM_API PurposeInfo ComputePurposeInfo (const PurposeInfo &parentPurposeInfo) const
 
USDGEOM_API TfToken ComputePurpose () const
 
USDGEOM_API UsdPrim ComputeProxyPrim (UsdPrim *renderPrim=NULL) const
 
USDGEOM_API bool SetProxyPrim (const UsdPrim &proxy) const
 
USDGEOM_API bool SetProxyPrim (const UsdSchemaBase &proxy) const
 
USDGEOM_API GfBBox3d ComputeWorldBound (UsdTimeCode const &time, TfToken const &purpose1=TfToken(), TfToken const &purpose2=TfToken(), TfToken const &purpose3=TfToken(), TfToken const &purpose4=TfToken()) const
 
USDGEOM_API GfBBox3d ComputeLocalBound (UsdTimeCode const &time, TfToken const &purpose1=TfToken(), TfToken const &purpose2=TfToken(), TfToken const &purpose3=TfToken(), TfToken const &purpose4=TfToken()) const
 
USDGEOM_API GfBBox3d ComputeUntransformedBound (UsdTimeCode const &time, TfToken const &purpose1=TfToken(), TfToken const &purpose2=TfToken(), TfToken const &purpose3=TfToken(), TfToken const &purpose4=TfToken()) const
 
USDGEOM_API GfMatrix4d ComputeLocalToWorldTransform (UsdTimeCode const &time) const
 
USDGEOM_API GfMatrix4d ComputeParentToWorldTransform (UsdTimeCode const &time) const
 
- Public Member Functions inherited from UsdTyped
 UsdTyped (const UsdPrim &prim=UsdPrim())
 
 UsdTyped (const UsdSchemaBase &schemaObj)
 
virtual USD_API ~UsdTyped ()
 Destructor. More...
 
- Public Member Functions inherited from UsdSchemaBase
bool IsConcrete () const
 
bool IsTyped () const
 
bool IsAPISchema () const
 Returns whether this is an API schema or not. More...
 
bool IsAppliedAPISchema () const
 
bool IsMultipleApplyAPISchema () const
 
UsdSchemaKind GetSchemaKind () const
 Returns the kind of schema this class is. More...
 
USD_API UsdSchemaBase (const UsdPrim &prim=UsdPrim())
 Construct and store prim as the held prim. More...
 
USD_API UsdSchemaBase (const UsdSchemaBase &otherSchema)
 Construct and store for the same prim held by otherSchema. More...
 
virtual USD_API ~UsdSchemaBase ()
 Destructor. More...
 
USD_API operator bool () const
 
UsdPrim GetPrim () const
 Return this schema object's held prim. More...
 
SdfPath GetPath () const
 Shorthand for GetPrim()->GetPath(). More...
 
USD_API const UsdPrimDefinitionGetSchemaClassPrimDefinition () const
 

Static Public Member Functions

static USDGEOM_API const
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 
static USDGEOM_API UsdGeomImageable Get (const UsdStagePtr &stage, const SdfPath &path)
 
static USDGEOM_API const
TfTokenVector
GetOrderedPurposeTokens ()
 
- Static Public Member Functions inherited from UsdTyped
static USD_API const
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 
static USD_API UsdTyped Get (const UsdStagePtr &stage, const SdfPath &path)
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractTyped
 
- Static Public Attributes inherited from UsdTyped
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 
- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 

Protected Member Functions

USDGEOM_API UsdSchemaKind _GetSchemaKind () const override
 
- Protected Member Functions inherited from UsdTyped
USD_API bool _IsCompatible () const override
 
- Protected Member Functions inherited from UsdSchemaBase
virtual UsdSchemaKind _GetSchemaType () const
 
const TfType_GetType () const
 
USD_API UsdAttribute _CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const
 

Friends

class UsdSchemaRegistry
 

Detailed Description

Base class for all prims that may require rendering or visualization of some sort. The primary attributes of Imageable are visibility and purpose, which each provide instructions for what geometry should be included for processing by rendering and other computations.

Deprecated:
Imageable also provides API for accessing primvars, which has been moved to the UsdGeomPrimvarsAPI schema, because primvars can now be applied on non-Imageable prim types. This API is planned to be removed, UsdGeomPrimvarsAPI should be used directly instead.

For any described attribute Fallback Value or Allowed Values below that are text/tokens, the actual token is published and defined in UsdGeomTokens. So to set an attribute to the value "rightHanded", use UsdGeomTokens->rightHanded as the value.

Definition at line 74 of file imageable.h.

Constructor & Destructor Documentation

UsdGeomImageable::UsdGeomImageable ( const UsdPrim prim = UsdPrim())
inlineexplicit

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

Definition at line 86 of file imageable.h.

UsdGeomImageable::UsdGeomImageable ( const UsdSchemaBase schemaObj)
inlineexplicit

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

Definition at line 94 of file imageable.h.

virtual USDGEOM_API UsdGeomImageable::~UsdGeomImageable ( )
virtual

Destructor.

Member Function Documentation

USDGEOM_API TfToken UsdGeomImageable::ComputeEffectiveVisibility ( const TfToken purpose = UsdGeomTokens->default_,
const UsdTimeCode time = UsdTimeCode::Default() 
) const

Calculate the effective purpose visibility of this prim for the given purpose, taking into account opinions for the corresponding purpose attribute, along with overall visibility opinions.

If ComputeVisibility() returns "invisible", then ComputeEffectiveVisibility() is "invisible" for all purpose values. Otherwise, ComputeEffectiveVisibility() returns the value of the nearest ancestral authored opinion for the corresponding purpose visibility attribute, as retured by GetPurposeVisibilityAttr(purpose).

Note that the value returned here can be "invisible" (indicating the prim is invisible for the given purpose), "visible" (indicating that it's visible), or "inherited" (indicating that the purpose visibility is context-dependent and the fallback behavior must be determined by the caller.

This function should be considered a reference implementation for correctness. If called on each prim in the context of a traversal we will perform massive overcomputation, because sibling prims share sub-problems in the query that can be efficiently cached, but are not (cannot be) by this simple implementation. If you have control of your traversal, it will be far more efficient to manage visibility on a stack as you traverse.

See Also
UsdGeomVisibilityAPI
GetPurposeVisibilityAttr()
ComputeVisibility()
USDGEOM_API GfBBox3d UsdGeomImageable::ComputeLocalBound ( UsdTimeCode const &  time,
TfToken const &  purpose1 = TfToken(),
TfToken const &  purpose2 = TfToken(),
TfToken const &  purpose3 = TfToken(),
TfToken const &  purpose4 = TfToken() 
) const

Compute the bound of this prim in local space, at the specified time, and for the specified purposes.

The bound of the prim is computed, including the transform (if any) authored on the node itself.

It is an error to not specify any purposes, which will result in the return of an empty box.

If you need to compute bounds for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomBBoxCache and query it directly; doing so will reuse sub-computations shared by the prims.

USDGEOM_API GfMatrix4d UsdGeomImageable::ComputeLocalToWorldTransform ( UsdTimeCode const &  time) const

Compute the transformation matrix for this prim at the given time, including the transform authored on the Prim itself, if present.

If you need to compute the transform for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomXformCache and query it directly; doing so will reuse sub-computations shared by the prims.

USDGEOM_API GfMatrix4d UsdGeomImageable::ComputeParentToWorldTransform ( UsdTimeCode const &  time) const

Compute the transformation matrix for this prim at the given time, NOT including the transform authored on the prim itself.

If you need to compute the transform for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomXformCache and query it directly; doing so will reuse sub-computations shared by the prims.

USDGEOM_API UsdPrim UsdGeomImageable::ComputeProxyPrim ( UsdPrim renderPrim = NULL) const

Find the prim whose purpose is proxy that serves as the proxy for this prim, as established by the GetProxyPrimRel(), or an invalid UsdPrim if this prim has no proxy.

This method will find the proxy for any prim whose computed purpose (see ComputePurpose()) is render. If provided and a proxy was found, we will set *renderPrim to the root of the render subtree upon which the renderProxy relationship was authored.

If the renderProxy relationship has more than one target, we will issue a warning and return an invalid UsdPrim. If the targeted prim does not have a resolved purpose of proxy, we will warn and return an invalid prim.

This function should be considered a reference implementation for correctness. If called on each prim in the context of a traversal we will perform massive overcomputation, because sibling prims share sub-problems in the query that can be efficiently cached, but are not (cannot be) by this simple implementation. If you have control of your traversal, it will be far more efficient to compute proxy-prims on a stack as you traverse.

Note
Currently the returned prim will not contain any instancing context if it is inside a prototype - its path will be relative to the prototype's root. Once UsdPrim is instancing-aware in the core, we can change this method to return a context-aware result.
See Also
SetProxyPrim(), GetProxyPrimRel()
USDGEOM_API TfToken UsdGeomImageable::ComputePurpose ( ) const

Calculate the effective purpose information about this prim. This is equivalent to extracting the purpose from the value returned by ComputePurposeInfo().

This function should be considered a reference implementation for correctness. If called on each prim in the context of a traversal we will perform massive overcomputation, because sibling prims share sub-problems in the query that can be efficiently cached, but are not (cannot be) by this simple implementation. If you have control of your traversal, it will be far more efficient to manage purpose, along with visibility, on a stack as you traverse.

See Also
GetPurposeAttr(), UsdGeom_ImageablePurpose
USDGEOM_API PurposeInfo UsdGeomImageable::ComputePurposeInfo ( ) const

Calculate the effective purpose information about this prim which includes final computed purpose value of the prim as well as whether the purpose value should be inherited by namespace children without their own purpose opinions.

This function should be considered a reference implementation for correctness. If called on each prim in the context of a traversal we will perform massive overcomputation, because sibling prims share sub-problems in the query that can be efficiently cached, but are not (cannot be) by this simple implementation. If you have control of your traversal, it will be far more efficient to manage purpose, along with visibility, on a stack as you traverse.

See Also
GetPurposeAttr(), UsdGeom_ImageablePurpose
USDGEOM_API PurposeInfo UsdGeomImageable::ComputePurposeInfo ( const PurposeInfo parentPurposeInfo) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calculates the effective purpose information about this prim, given the computed purpose information of its parent prim. This can be much more efficient than using CommputePurposeInfo() when PurposeInfo values are properly computed and cached for a hierarchy of prims using this function.

See Also
GetPurposeAttr(), UsdGeom_ImageablePurpose
USDGEOM_API GfBBox3d UsdGeomImageable::ComputeUntransformedBound ( UsdTimeCode const &  time,
TfToken const &  purpose1 = TfToken(),
TfToken const &  purpose2 = TfToken(),
TfToken const &  purpose3 = TfToken(),
TfToken const &  purpose4 = TfToken() 
) const

Compute the untransformed bound of this prim, at the specified time, and for the specified purposes.

The bound of the prim is computed in its object space, ignoring any transforms authored on or above the prim.

It is an error to not specify any purposes, which will result in the return of an empty box.

If you need to compute bounds for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomBBoxCache and query it directly; doing so will reuse sub-computations shared by the prims.

USDGEOM_API TfToken UsdGeomImageable::ComputeVisibility ( UsdTimeCode const &  time = UsdTimeCode::Default()) const

Calculate the effective visibility of this prim, as defined by its most ancestral authored "invisible" opinion, if any.

A prim is considered visible at the current time if none of its Imageable ancestors express an authored "invisible" opinion, which is what leads to the "simple pruning" behavior described in GetVisibilityAttr().

This function should be considered a reference implementation for correctness. If called on each prim in the context of a traversal we will perform massive overcomputation, because sibling prims share sub-problems in the query that can be efficiently cached, but are not (cannot be) by this simple implementation. If you have control of your traversal, it will be far more efficient to manage visibility on a stack as you traverse.

See Also
GetVisibilityAttr()
USDGEOM_API GfBBox3d UsdGeomImageable::ComputeWorldBound ( UsdTimeCode const &  time,
TfToken const &  purpose1 = TfToken(),
TfToken const &  purpose2 = TfToken(),
TfToken const &  purpose3 = TfToken(),
TfToken const &  purpose4 = TfToken() 
) const

Compute the bound of this prim in world space, at the specified time, and for the specified purposes.

The bound of the prim is computed, including the transform (if any) authored on the node itself, and then transformed to world space.

It is an error to not specify any purposes, which will result in the return of an empty box.

If you need to compute bounds for multiple prims on a stage, it will be much, much more efficient to instantiate a UsdGeomBBoxCache and query it directly; doing so will reuse sub-computations shared by the prims.

USDGEOM_API UsdRelationship UsdGeomImageable::CreateProxyPrimRel ( ) const

See GetProxyPrimRel(), and also Usd_Create_Or_Get_Property for when to use Get vs Create

USDGEOM_API UsdAttribute UsdGeomImageable::CreatePurposeAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetPurposeAttr(), and also Usd_Create_Or_Get_Property 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.

USDGEOM_API UsdAttribute UsdGeomImageable::CreateVisibilityAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetVisibilityAttr(), and also Usd_Create_Or_Get_Property 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.

static USDGEOM_API UsdGeomImageable UsdGeomImageable::Get ( const UsdStagePtr &  stage,
const SdfPath path 
)
static

Return a UsdGeomImageable holding the prim adhering to this schema at path on stage. If no prim exists at path on stage, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdGeomImageable(stage->GetPrimAtPath(path));
static USDGEOM_API const TfTokenVector& UsdGeomImageable::GetOrderedPurposeTokens ( )
static

Returns an ordered list of allowed values of the purpose attribute.

The ordering is important because it defines the protocol between UsdGeomModelAPI and UsdGeomBBoxCache for caching and retrieving extents hints by purpose.

The order is: [default, render, proxy, guide]

See

See Also
UsdGeomModelAPI::GetExtentsHint().
GetOrderedPurposeTokens()
USDGEOM_API UsdRelationship UsdGeomImageable::GetProxyPrimRel ( ) const

The proxyPrim relationship allows us to link a prim whose purpose is "render" to its (single target) purpose="proxy" prim. This is entirely optional, but can be useful in several scenarios:

  • In a pipeline that does pruning (for complexity management) by deactivating prims composed from asset references, when we deactivate a purpose="render" prim, we will be able to discover and additionally deactivate its associated purpose="proxy" prim, so that preview renders reflect the pruning accurately.
  • DCC importers may be able to make more aggressive optimizations for interactive processing and display if they can discover the proxy for a given render prim.
  • With a little more work, a Hydra-based application will be able to map a picked proxy prim back to its render geometry for selection.
Note
It is only valid to author the proxyPrim relationship on prims whose purpose is "render".
USDGEOM_API UsdAttribute UsdGeomImageable::GetPurposeAttr ( ) const

Purpose is a classification of geometry into categories that can each be independently included or excluded from traversals of prims on a stage, such as rendering or bounding-box computation traversals.

See UsdGeom_ImageablePurpose for more detail about how purpose is computed and used.

Declaration uniform token purpose = "default"
C++ Type TfToken
Usd Type SdfValueTypeNames->Token
Variability SdfVariabilityUniform
Allowed Values default, render, proxy, guide
USDGEOM_API UsdAttribute UsdGeomImageable::GetPurposeVisibilityAttr ( const TfToken purpose = UsdGeomTokens->default_) const

Return the attribute that is used for expressing visibility opinions for the given purpose.

For "default" purpose, return the overall visibility attribute. For "guide", "proxy", or "render" purpose, return guideVisibility, proxyVisibility, or renderVisibility if UsdGeomVisibilityAPI is applied to the prim. If UsdGeomvVisibiltyAPI is not applied, an empty attribute is returned for purposes other than default.

See Also
UsdGeomVisibilityAPI::Apply
UsdGeomVisibilityAPI::GetPurposeVisibilityAttr
static USDGEOM_API const TfTokenVector& UsdGeomImageable::GetSchemaAttributeNames ( bool  includeInherited = true)
static

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes. Does not include attributes that may be authored by custom/extended methods of the schemas involved.

USDGEOM_API UsdAttribute UsdGeomImageable::GetVisibilityAttr ( ) const

Visibility is meant to be the simplest form of "pruning" visibility that is supported by most DCC apps. Visibility is animatable, allowing a sub-tree of geometry to be present for some segment of a shot, and absent from others; unlike the action of deactivating geometry prims, invisible geometry is still available for inspection, for positioning, for defining volumes, etc.

Declaration token visibility = "inherited"
C++ Type TfToken
Usd Type SdfValueTypeNames->Token
Allowed Values inherited, invisible
USDGEOM_API void UsdGeomImageable::MakeInvisible ( const UsdTimeCode time = UsdTimeCode::Default()) const

Makes the imageable invisible if it is visible at the given time.

Note
When visibility is animated, this only works when it is invoked sequentially at increasing time samples. If visibility is already authored and animated in the scene, calling MakeVisible() at an arbitrary (in-between) frame isn't guaranteed to work.
Be sure to set the edit target to the layer containing the strongest visibility opinion or to a stronger layer.
See Also
MakeVisible()
ComputeVisibility()
USDGEOM_API void UsdGeomImageable::MakeVisible ( const UsdTimeCode time = UsdTimeCode::Default()) const

Make the imageable visible if it is invisible at the given time.

Since visibility is pruning, this may need to override some ancestor's visibility and all-but-one of the ancestor's children's visibility, for all the ancestors of this prim up to the highest ancestor that is explicitly invisible, to preserve the visibility state.

If MakeVisible() (or MakeInvisible()) is going to be applied to all the prims on a stage, ancestors must be processed prior to descendants to get the correct behavior.

Note
When visibility is animated, this only works when it is invoked sequentially at increasing time samples. If visibility is already authored and animated in the scene, calling MakeVisible() at an arbitrary (in-between) frame isn't guaranteed to work.
This will only work properly if all ancestor prims of the imageable are defined, as the imageable schema is only valid on defined prims.
Be sure to set the edit target to the layer containing the strongest visibility opinion or to a stronger layer.
See Also
MakeInvisible()
ComputeVisibility()
USDGEOM_API bool UsdGeomImageable::SetProxyPrim ( const UsdPrim proxy) const

Convenience function for authoring the renderProxy rel on this prim to target the given proxy prim.

To facilitate authoring on sparse or unloaded stages, we do not perform any validation of this prim's purpose or the type or purpose of the specified prim.

See Also
ComputeProxyPrim(), GetProxyPrimRel()
USDGEOM_API bool UsdGeomImageable::SetProxyPrim ( const UsdSchemaBase proxy) const

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

Friends And Related Function Documentation

friend class UsdSchemaRegistry
friend

Definition at line 133 of file imageable.h.

Member Data Documentation

const UsdSchemaKind UsdGeomImageable::schemaKind = UsdSchemaKind::AbstractTyped
static

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

See Also
UsdSchemaKind

Definition at line 80 of file imageable.h.


The documentation for this class was generated from the following file: