usdrt::UsdGeomModelAPI

Defined in usdrt/scenegraph/usd/usdGeom/modelAPI.h

Functions

Variables

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 operator bool() const

Boolean operator.

Returns

Return true if the contained prim is has this api schema applied using HasAPI, and false otherwise.

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.

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.