UsdGeomModelAPI#

Fully qualified name: usdrt::UsdGeomModelAPI

class UsdGeomModelAPI : public usdrt::UsdAPISchemaBase #

UsdGeomModelAPI extends the generic UsdModelAPI schema with geometry specific concepts such as cached extents for the entire model, constraint targets, and geometry-inspired extensions to the payload lofting process.

As described in GetExtentsHint() below, it is useful to cache extents at the model level. UsdGeomModelAPI provides schema for computing and storing these cached extents, which can be consumed by UsdGeomBBoxCache to provide fast access to precomputed extents that will be used as the model’s bounds ( see UsdGeomBBoxCache::UsdGeomBBoxCache() ).

Draw Modes#

Draw modes provide optional alternate imaging behavior for USD subtrees with kind model. model:drawMode (which is inheritable) and model:applyDrawMode (which is not) are resolved into a decision to stop traversing the scene graph at a certain point, and replace a USD subtree with proxy geometry.

The value of model:drawMode determines the type of proxy geometry:

origin - Draw the model-space basis vectors of the replaced prim.
bounds - Draw the model-space bounding box of the replaced prim.
cards - Draw textured quads as a placeholder for the replaced prim.
default - An explicit opinion to draw the USD subtree as normal.
inherited - Defer to the parent opinion.

model:drawMode falls back to inherited so that a whole scene, a large group, or all prototypes of a model hierarchy PointInstancer can be assigned a draw mode with a single attribute edit. If no draw mode is explicitly set in a hierarchy, the resolved value is default.

model:applyDrawMode is meant to be written when an asset is authored, and provides flexibility for different asset types. For example, a character assembly (composed of character, clothes, etc) might have model:applyDrawMode set at the top of the subtree so the whole group can be drawn as a single card object. An effects subtree might have model:applyDrawMode set at a lower level so each particle group draws individually.

Models of kind component are treated as if model:applyDrawMode were true. This means a prim is drawn with proxy geometry when: the prim has kind component, and/or model:applyDrawMode is set; and the prim’s resolved value for model:drawMode is not default.

Cards Geometry#

The specific geometry used in cards mode is controlled by the model:cardGeometry attribute:

cross - Generate a quad normal to each basis direction and negative. Locate each quad so that it bisects the model extents.
box - Generate a quad normal to each basis direction and negative. Locate each quad on a face of the model extents, facing out.
fromTexture - Generate a quad for each supplied texture from attributes stored in that texture’s metadata.

For cross and box mode, the extents are calculated for purposes default, proxy, and render, at their earliest authored time. If the model has no textures, all six card faces are rendered using model:drawModeColor. If one or more textures are present, only axes with one or more textures assigned are drawn. For each axis, if both textures (positive and negative) are specified, they’ll be used on the corresponding card faces; if only one texture is specified, it will be mapped to the opposite card face after being flipped on the texture’s s-axis. Any card faces with invalid asset paths will be drawn with model:drawModeColor.

Both model:cardGeometry and model:drawModeColor should be authored on the prim where the draw mode takes effect, since these attributes are not inherited.

For fromTexture mode, only card faces with valid textures assigned are drawn. The geometry is generated by pulling the worldtoscreen attribute out of texture metadata. This is expected to be a 4x4 matrix mapping the model-space position of the card quad to the clip-space quad with corners (-1,-1,0) and (1,1,0). The card vertices are generated by transforming the clip-space corners by the inverse of worldtoscreen. Textures are mapped so that (s) and (t) map to (+x) and (+y) in clip space. If the metadata cannot be read in the right format, or the matrix can’t be inverted, the card face is not drawn.

All card faces are drawn and textured as single-sided.

Todo:: CreatePayload() 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.

Public Functions

inline explicit UsdGeomModelAPI(const UsdPrim &prim = UsdPrim())#: Construct a UsdGeomModelAPI on UsdPrim prim. Equivalent to UsdGeomModelAPI::Get(prim.GetStage(), prim.GetPath()) for a valid prim , but will not immediately throw an error for an invalid prim.

inline explicit UsdGeomModelAPI(const UsdSchemaBase &schemaObj)#: Construct a UsdGeomModelAPI on the prim held by schemaObj . Should be preferred over UsdGeomModelAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

inline virtual ~UsdGeomModelAPI()#: Destructor.

inline UsdAttribute GetModelDrawModeAttr() const#

Alternate imaging mode; applied to this prim or child prims where model:applyDrawMode is true, or where the prim has kind component. See Draw Modes for mode descriptions.


Declaration	`uniform token model:drawMode = "inherited"`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform
Allowed Values	origin, bounds, cards, default, inherited

inline UsdAttribute CreateModelDrawModeAttr() const#: See GetModelDrawModeAttr(), 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 GetModelApplyDrawModeAttr() const#

If true, and the resolved value of model:drawMode is non-default, apply an alternate imaging mode to this prim. See Draw Modes.


Declaration	`uniform bool model:applyDrawMode = 0`
C++ Type	bool
Usd Type	SdfValueTypeNames->Bool
Variability	SdfVariabilityUniform

inline UsdAttribute CreateModelApplyDrawModeAttr() const#: See GetModelApplyDrawModeAttr(), 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 GetModelDrawModeColorAttr() const#

The base color of imaging prims inserted for alternate imaging modes. For origin and bounds modes, this controls line color; for cards mode, this controls the fallback quad color.


Declaration	`uniform float3 model:drawModeColor = (0.18, 0.18, 0.18)`
C++ Type	GfVec3f
Usd Type	SdfValueTypeNames->Float3
Variability	SdfVariabilityUniform

inline UsdAttribute CreateModelDrawModeColorAttr() const#: See GetModelDrawModeColorAttr(), 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 GetModelCardGeometryAttr() const#

The geometry to generate for imaging prims inserted for cards imaging mode. See Cards Geometry for geometry descriptions.


Declaration	`uniform token model:cardGeometry = "cross"`
C++ Type	TfToken
Usd Type	SdfValueTypeNames->Token
Variability	SdfVariabilityUniform
Allowed Values	cross, box, fromTexture

inline UsdAttribute CreateModelCardGeometryAttr() const#: See GetModelCardGeometryAttr(), 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 GetModelCardTextureXPosAttr() const#

In cards imaging mode, the texture applied to the X+ quad. The texture axes (s,t) are mapped to model-space axes (-y, -z).


Declaration	`asset model:cardTextureXPos`
C++ Type	SdfAssetPath
Usd Type	SdfValueTypeNames->Asset

inline UsdAttribute CreateModelCardTextureXPosAttr() const#: See GetModelCardTextureXPosAttr(), 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 GetModelCardTextureYPosAttr() const#

In cards imaging mode, the texture applied to the Y+ quad. The texture axes (s,t) are mapped to model-space axes (x, -z).


Declaration	`asset model:cardTextureYPos`
C++ Type	SdfAssetPath
Usd Type	SdfValueTypeNames->Asset

inline UsdAttribute CreateModelCardTextureYPosAttr() const#: See GetModelCardTextureYPosAttr(), 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 GetModelCardTextureZPosAttr() const#

In cards imaging mode, the texture applied to the Z+ quad. The texture axes (s,t) are mapped to model-space axes (x, -y).


Declaration	`asset model:cardTextureZPos`
C++ Type	SdfAssetPath
Usd Type	SdfValueTypeNames->Asset

inline UsdAttribute CreateModelCardTextureZPosAttr() const#: See GetModelCardTextureZPosAttr(), 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 GetModelCardTextureXNegAttr() const#

In cards imaging mode, the texture applied to the X- quad. The texture axes (s,t) are mapped to model-space axes (y, -z).


Declaration	`asset model:cardTextureXNeg`
C++ Type	SdfAssetPath
Usd Type	SdfValueTypeNames->Asset

inline UsdAttribute CreateModelCardTextureXNegAttr() const#: See GetModelCardTextureXNegAttr(), 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 GetModelCardTextureYNegAttr() const#

In cards imaging mode, the texture applied to the Y- quad. The texture axes (s,t) are mapped to model-space axes (-x, -z).


Declaration	`asset model:cardTextureYNeg`
C++ Type	SdfAssetPath
Usd Type	SdfValueTypeNames->Asset

inline UsdAttribute CreateModelCardTextureYNegAttr() const#: See GetModelCardTextureYNegAttr(), 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 GetModelCardTextureZNegAttr() const#

In cards imaging mode, the texture applied to the Z- quad. The texture axes (s,t) are mapped to model-space axes (-x, -y).


Declaration	`asset model:cardTextureZNeg`
C++ Type	SdfAssetPath
Usd Type	SdfValueTypeNames->Asset

inline UsdAttribute CreateModelCardTextureZNegAttr() const#: See GetModelCardTextureZNegAttr(), 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 UsdGeomModelAPI Apply(const UsdPrim &prim)#

Applies this single-apply API schema to the given prim. This information is stored by adding “GeomModelAPI” 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 UsdGeomModelAPI object is returned upon success. An invalid (or empty) UsdGeomModelAPI 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.