|
Base class for all prims that may require rendering or visualization of some sort. More...
#include <imageable.h>
Classes | |
struct | PurposeInfo |
Value type containing information about a prim's computed effective purpose as well as storing whether the prim's purpose value can be inherited by namespace children if necessary. More... | |
Public Member Functions | |
UsdGeomImageable (const UsdPrim &prim=UsdPrim()) | |
Construct a UsdGeomImageable on UsdPrim prim . | |
UsdGeomImageable (const UsdSchemaBase &schemaObj) | |
Construct a UsdGeomImageable on the prim held by schemaObj . | |
virtual USDGEOM_API | ~UsdGeomImageable () |
Destructor. | |
USDGEOM_API UsdAttribute | GetVisibilityAttr () const |
Visibility is meant to be the simplest form of "pruning" visibility that is supported by most DCC apps. | |
USDGEOM_API UsdAttribute | CreateVisibilityAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const |
See GetVisibilityAttr(), and also Create vs Get Property Methods for when to use Get vs Create. | |
USDGEOM_API UsdAttribute | 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. | |
USDGEOM_API UsdAttribute | CreatePurposeAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const |
See GetPurposeAttr(), and also Create vs Get Property Methods for when to use Get vs Create. | |
USDGEOM_API UsdRelationship | GetProxyPrimRel () const |
The proxyPrim relationship allows us to link a prim whose purpose is "render" to its (single target) purpose="proxy" prim. | |
USDGEOM_API UsdRelationship | CreateProxyPrimRel () const |
See GetProxyPrimRel(), and also Create vs Get Property Methods for when to use Get vs Create. | |
Visibility Authoring Helpers | |
USDGEOM_API void | MakeVisible (const UsdTimeCode &time=UsdTimeCode::Default()) const |
Make the imageable visible if it is invisible at the given time. | |
USDGEOM_API void | MakeInvisible (const UsdTimeCode &time=UsdTimeCode::Default()) const |
Makes the imageable invisible if it is visible at the given time. | |
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 |
Calculate the effective visibility of this prim, as defined by its most ancestral authored "invisible" opinion, if any. | |
USDGEOM_API UsdAttribute | GetPurposeVisibilityAttr (const TfToken &purpose=UsdGeomTokens->default_) const |
Return the attribute that is used for expressing visibility opinions for the given purpose . | |
USDGEOM_API TfToken | 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. | |
USDGEOM_API PurposeInfo | 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. | |
USDGEOM_API PurposeInfo | 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. | |
USDGEOM_API TfToken | ComputePurpose () const |
Calculate the effective purpose information about this prim. | |
USDGEOM_API UsdPrim | 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. | |
USDGEOM_API bool | SetProxyPrim (const UsdPrim &proxy) const |
Convenience function for authoring the renderProxy rel on this prim to target the given proxy prim. | |
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 |
Compute the bound of this prim in world space, at the specified time , and for the specified purposes. | |
USDGEOM_API GfBBox3d | 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. | |
USDGEOM_API GfBBox3d | 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. | |
USDGEOM_API GfMatrix4d | 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. | |
USDGEOM_API GfMatrix4d | 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. | |
Public Member Functions inherited from UsdTyped | |
UsdTyped (const UsdPrim &prim=UsdPrim()) | |
Construct a UsdTyped on UsdPrim prim . | |
UsdTyped (const UsdSchemaBase &schemaObj) | |
Construct a UsdTyped on the prim held by schemaObj . | |
virtual USD_API | ~UsdTyped () |
Destructor. | |
Public Member Functions inherited from UsdSchemaBase | |
bool | IsConcrete () const |
Returns whether or not this class corresponds to a concrete instantiable prim type in scene description. | |
bool | IsTyped () const |
Returns whether or not this class inherits from UsdTyped. | |
bool | IsAPISchema () const |
Returns whether this is an API schema or not. | |
bool | IsAppliedAPISchema () const |
Returns whether this is an applied API schema or not. | |
bool | IsMultipleApplyAPISchema () const |
Returns whether this is an applied API schema or not. | |
UsdSchemaKind | GetSchemaKind () const |
Returns the kind of schema this class is. | |
USD_API | UsdSchemaBase (const UsdPrim &prim=UsdPrim()) |
Construct and store prim as the held prim. | |
USD_API | UsdSchemaBase (const UsdSchemaBase &otherSchema) |
Construct and store for the same prim held by otherSchema . | |
virtual USD_API | ~UsdSchemaBase () |
Destructor. | |
UsdPrim | GetPrim () const |
Return this schema object's held prim. | |
SdfPath | GetPath () const |
Shorthand for GetPrim()->GetPath(). | |
USD_API const UsdPrimDefinition * | GetSchemaClassPrimDefinition () const |
Return the prim definition associated with this schema instance if one exists, otherwise return null. | |
USD_API | operator bool () const |
Return true if this schema object is compatible with its held prim, false otherwise. | |
Static Public Member Functions | |
static USDGEOM_API const TfTokenVector & | GetSchemaAttributeNames (bool includeInherited=true) |
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes. | |
static USDGEOM_API UsdGeomImageable | Get (const UsdStagePtr &stage, const SdfPath &path) |
Return a UsdGeomImageable holding the prim adhering to this schema at path on stage . | |
static USDGEOM_API const TfTokenVector & | GetOrderedPurposeTokens () |
Returns an ordered list of allowed values of the purpose attribute. | |
Static Public Member Functions inherited from UsdTyped | |
static USD_API const TfTokenVector & | GetSchemaAttributeNames (bool includeInherited=true) |
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes. | |
static USD_API UsdTyped | Get (const UsdStagePtr &stage, const SdfPath &path) |
Return a UsdTyped holding the prim adhering to this schema at path on stage . | |
Static Public Member Functions inherited from UsdSchemaBase | |
static const TfTokenVector & | GetSchemaAttributeNames (bool includeInherited=true) |
Static Public Attributes | |
static const UsdSchemaKind | schemaKind = UsdSchemaKind::AbstractTyped |
Compile time constant representing what kind of schema this class is. | |
Static Public Attributes inherited from UsdTyped | |
static const UsdSchemaKind | schemaKind = UsdSchemaKind::AbstractBase |
Compile time constant representing what kind of schema this class is. | |
Static Public Attributes inherited from UsdSchemaBase | |
static const UsdSchemaKind | schemaKind = UsdSchemaKind::AbstractBase |
Compile time constant representing what kind of schema this class is. | |
Protected Member Functions | |
USDGEOM_API UsdSchemaKind | _GetSchemaKind () const override |
Returns the kind of schema this class belongs to. | |
Protected Member Functions inherited from UsdTyped | |
USD_API UsdSchemaKind | _GetSchemaKind () const override |
Returns the kind of schema this class belongs to. | |
USD_API bool | _IsCompatible () const override |
Subclasses may override _IsCompatible to do specific compatibility checking with the given prim, such as type compatibility or value compatibility. | |
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 |
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.
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 57 of file imageable.h.
|
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 69 of file imageable.h.
|
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 77 of file imageable.h.
|
virtual |
Destructor.
|
overrideprotectedvirtual |
Returns the kind of schema this class belongs to.
Reimplemented from UsdTyped.
Reimplemented in UsdGeomMesh, UsdGeomNurbsCurves, UsdGeomNurbsPatch, UsdGeomPlane, UsdGeomPointBased, UsdGeomPointInstancer, UsdGeomPoints, UsdGeomScope, UsdGeomSphere, UsdGeomTetMesh, UsdGeomXform, UsdGeomXformable, UsdLuxBoundableLightBase, UsdLuxCylinderLight, UsdLuxDiskLight, UsdLuxDistantLight, UsdLuxDomeLight, UsdLuxDomeLight_1, UsdLuxGeometryLight, UsdLuxLightFilter, UsdLuxNonboundableLightBase, UsdLuxPluginLight, UsdLuxPluginLightFilter, UsdLuxPortalLight, UsdLuxRectLight, UsdLuxSphereLight, UsdMediaSpatialAudio, UsdPhysicsDistanceJoint, UsdPhysicsFixedJoint, UsdPhysicsJoint, UsdPhysicsPrismaticJoint, UsdPhysicsRevoluteJoint, UsdPhysicsSphericalJoint, UsdProcGenerativeProcedural, UsdSkelRoot, UsdSkelSkeleton, UsdVolField3DAsset, UsdVolFieldAsset, UsdVolFieldBase, UsdVolOpenVDBAsset, and UsdVolVolume.
USDGEOM_API TfToken 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.
USDGEOM_API GfBBox3d 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 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 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.
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.
USDGEOM_API TfToken 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.
USDGEOM_API PurposeInfo 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.
USDGEOM_API PurposeInfo 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.
USDGEOM_API GfBBox3d 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 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.
USDGEOM_API GfBBox3d 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 CreateProxyPrimRel | ( | ) | const |
See GetProxyPrimRel(), and also Create vs Get Property Methods for when to use Get vs Create.
USDGEOM_API UsdAttribute CreatePurposeAttr | ( | VtValue const & | defaultValue = VtValue() , |
bool | writeSparsely = false |
||
) | const |
See GetPurposeAttr(), 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
.
USDGEOM_API UsdAttribute CreateVisibilityAttr | ( | VtValue const & | defaultValue = VtValue() , |
bool | writeSparsely = false |
||
) | const |
See GetVisibilityAttr(), 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
.
|
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:
|
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
USDGEOM_API UsdRelationship 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:
USDGEOM_API UsdAttribute 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 Imageable Purpose 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 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.
|
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 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 MakeInvisible | ( | const UsdTimeCode & | time = UsdTimeCode::Default() | ) | const |
Makes the imageable invisible if it is visible at the given time.
USDGEOM_API void 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.
USDGEOM_API bool 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.
|
friend |
Definition at line 116 of file imageable.h.
|
static |
Compile time constant representing what kind of schema this class is.
Definition at line 63 of file imageable.h.