All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Important Properties of Scene Description

Names, Namespace Ordering, and Property Namespaces

TimeSamples, Defaults, and Value Resolution

Defs, Overs, Classes, and Prim Types

See Also
What's the difference between an "over" and a "typeless def"?

Model Hierarchy: Meaning and Purpose

Borrowing from The Core Kind Hierarchy, we review the primary kinds we use to create the model hierarchy.

  • model - Everything in the model hierarchy is a kind of model.
    • component - A component model is a terminal model in the model hierarchy - it can have no child models.
    • group - a model that is simply a container for other models.
      • assembly - An "important" group model - often because it is itself a published asset.
  • subcomponent - Within a component model, subcomponents identify important (generally articulable) sub-trees. Subcomponents are "stopping points" when dynamically unrolling/expanding a component into an application's native scene description.

We interrogate and author kinds on UsdPrim using UsdModelAPI::GetKind() and UsdModelAPI::SetKind(), in order to establish a Model Hierarchy, which is a contiguous prefix of a scene's namespace. The intention of model hierarchy is to recognize that we often organize our scenes into hierarchical collections of "components" each of which is a substantial, meaningful partition of the scene (generally, but not required to be, referenced assets), and codify that organization to facilitate navigating and reasoning about the scene at a high-level. In other words, Model Hierarchy acts as a scene's table of contents.

Assuming that the prims on a UsdStage are organized into assembly, group, and component models, we can use the Prim Predicate Flags UsdPrimIsModel and UsdPrimIsGroup in constructing predicates for UsdPrimRange and UsdStage::Traverse() that will visit all models on a stage, and no "sub-model" prims. UsdPrim::IsModel() and UsdPrim::IsGroup() answer the corresponding questions.

How "active" Affects Prims on a UsdStage

How does one "delete a prim" in USD? Considering that any given UsdPrim on a UsdStage may be comprised of SdfPrimSpec's from numerous layers, and that one or more (typically many) may not be editable by the user who wants to delete a prim or subtree rooted at a prim, the "obvious" approach of directly editing all of the particpating layers, while possible, is not often practical or desirable.

Therefore USD provides a "non-destructive" and reversible form of prim deletion, which we call deactivation. One deactivates a prim using UsdPrim::SetActive(false), which sets the prim metadata active to false. For any prim on a stage whose active metadata resolves to false, we consider the prim to be deactivated, which has two important consequences:

  • The prim will be excluded from default stage traversals as determined by the UsdPrimDefaultPredicate. It is important that the deactivated prim still be present on the stage, or else we would no longer be able to re-activate the prim; however, we promote UsdPrimDefaultPredicate as the means to visit/process the "important" part of the stage, thus deactivation effectively removes the prim.
  • All scene description for prims beneath the deactivated prim will not be composed - therefore, the deactivated prim will become a leaf node in the scenegraph. This property makes deactivation a useful tool for reducing scene complexity and cost.

Ascii, Binary, and Plugin Filetypes

Resolving Asset References