#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 UsdPrimDefinition *	GetSchemaClassPrimDefinition () 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 TfTokenVector &	GetSchemaAttributeNames (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 UsdSchemaKind UsdGeomImageable::_GetSchemaKind ( ) const

overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See Also: UsdSchemaKind

Reimplemented from UsdTyped.

Reimplemented in UsdGeomPointInstancer, UsdGeomXformable, UsdGeomMesh, UsdGeomNurbsPatch, UsdMediaSpatialAudio, UsdLuxLightFilter, UsdGeomNurbsCurves, UsdProcGenerativeProcedural, UsdGeomPlane, UsdVolVolume, UsdGeomTetMesh, UsdGeomPoints, UsdPhysicsSphericalJoint, UsdLuxPluginLight, UsdLuxPluginLightFilter, UsdPhysicsPrismaticJoint, UsdPhysicsRevoluteJoint, UsdSkelRoot, UsdSkelSkeleton, UsdVolField3DAsset, UsdVolOpenVDBAsset, UsdPhysicsJoint, UsdLuxRectLight, UsdGeomSphere, UsdLuxCylinderLight, UsdGeomScope, UsdLuxGeometryLight, UsdLuxPortalLight, UsdLuxDiskLight, UsdLuxDistantLight, UsdPhysicsDistanceJoint, UsdLuxSphereLight, UsdPhysicsFixedJoint, UsdGeomXform, UsdVolFieldAsset, UsdLuxBoundableLightBase, UsdLuxNonboundableLightBase, UsdGeomPointBased, and UsdVolFieldBase.

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.