Prim And Win

[Fito Coulter]

USDintroduces quite a few terms and concepts, some of which, unavoidably,already have different meanings in other contexts, so it can be quite dauntingto make sense of all of our documentation and code until you have become fullyindoctrinated. This document attempts to define and explain all the majorconcepts and behaviors referred to in other parts of the USD documentation.

One might also create a non-applied schema to interact with some related (foryour purposes) properties that exist on some number of other typed schemas,which may allow for more concise coding patterns.

API schemas can be generated using the USD schema generation tools, and extended with custom methods,just as typed schemas can. We use schema generation even for non-applied APIschemas that have no builtin properties, to ensure consistency.

In USD an assembly is a kind of Model. Assemblies are group models,i.e. models that aggregate other models into meaningful collections. An assemblymay consist primarily of references to other models, and themselves be publishedassets.

AssetInfo is a metadata dictionary that can be applied to any UsdPrim or UsdProperty to conveyasset-identification-and-management-related information. Typically a UsdStage pulls in many assets through composition arcs. When interacting with prims and propertieson the stage, however, the presence and location of the arcs and the identityof the assets they target is, by design, fairly deeply hidden as animplementation detail. We do provide low-level tools for examining thearc-by-arc index for each prim, but it can be difficultto reconstruct intent and asset identity from the arc structurealone. AssetInfo provides a mechanism for identifying and locating assetsthat survives composition (and even stage flattening)to allow clients to discover the namespace locationat which an asset is introduced, and generally how to construct a reference tothe asset.

assetInfo authored in USD files is advisory data one supplies forclient applications to use. It is not consulted or consumed by theUSD core in any way during Stage loading/composition.

Change processing is the action a UsdStage takes in response to editsof any of the layers that contribute to its composition. During changeprocessing, prims on the stage may be re-indexed ordisappear entirely, or new prims may come into being. The key things tounderstand about change processing are:

When a stage has completed a round of change processing, it willsend notification to clients who have registeredinterest, so that they may keep themselves updated in light of authoredchanges to the stage.

Clients listening to UsdStage notifications should not updatethemselves immediately upon receiving a notice, but instead note what hasbecome out-of-date (dirty), and defer updating until necessary; this helpsminimize the amount of work an application needs to undertake when manyedits are being performed rapidly.

For all of the layers that contribute to a given UsdStage, onlyone thread at a time may be editing any of those layers, and no other threadcan be reading from the stage while the editing and change processing aretaking place. This is because we do not want to weigh down read access toUsdStage data with any kind of locking.

Class is one of the three possible specifiers aprim (and also a primSpec) canpossess. A class prim and all of the prims nested inside it in namespace will report that they are abstract, viaUsdPrim::IsAbstract, which causes the prims to be skipped by stage andchild traversals, unless a client specifically asks to include abstractprims. The most common use of classes is to create prims from which other primscan inherit. Classes can define/override metadata aswell as properties and nested prims. The following example contains a class_class_Ball that provides a value for the radius attribute for any primthat would inherit or reference it. The _class_ prefix is a Pixar conventionfor naming classes, and is not a requirement.

Collections build on the ability of relationshipsto identify objects in a USD scene. Whereas a relationship is (resolves to, byfetching its Targets) simply an ordered list of paths identifying otherobjects in the scene, a Collection uses a pair of relationships and extra rulesto compactly encode potentially large sets of objects by identifying a set ofpaths to hierarchically include in the Collection, and a separate set ofpaths to hierarchically exclude. For example, the following Collectionidentifies all of the prims comprising the two buildings, except for all theprims organized under the Floor13 prim in each.

Except for subLayers, all composition arcs are list editable, which means that each layer in a layerStack can sparsely prepend, append, remove, or resettargets, which allows us to non-destructively edit the composition structure ofa scene as it evolves or passes through multiple stages of a pipeline. Followingis an example of list-edited references. The resolved value of references on/MyPrim that will be consumed during composition of superLayer.usd is a two-elementlist: [ @file1.usd@, @file3.usd@ ]

Connections empower USD to robustly encode dataflow networks of prims, but USDitself provides no dataflow behavior across connections. Instead, USDstipulates that schemas can impose semantics onconnections, to be interpreted/implemented by the schema or higher-levelsystems. We do so for two reasons:

Editing crate files does not copy all data to a new file. Instead, itappends. Disused values consume disk space, so repeated editing mayproduce files larger than ideal. Use usdcat to rewritefiles in their most compact form.

Gprims are boundable,and should always submit to computing an extent (even if it be an emptyextent), and valid UsdGeom scene description should alwaysprovide an authored extent on a gprim that captures its changing shape(if its shape is animated).

All of the queries on USD classes except for stage-level metadata rely on primindices to perform value resolution. USDalso uses prim indices to compute primStacks fordebugging, and to construct Edit Targets.

If you paste the example into a .usda file and view the composedresult in usdview, you will see that /TreeA and/TreeB both inherit the child prims and properties nested inside/_class_Tree You can also observe an important property of inheritsbehavior in /TreeB/Leaves, which is that inherited opinions areweaker than direct opinions on prims thatinherit the opinions. This allows us to always create exceptions to thebroadcast behavior of inherits, in the same layerStack in which we are broadcasting inherited overrides.

Instanceable is a metadatum that declareswhether a given prim should be considered as acandidate for instancing, and is authored viaUsdPrim::SetInstanceable. If instanceable = true on a prim,then the prim will become an instance of an implicit prototype when composedon a stage, if and only if the prim also contains oneor more direct composition arcs. It doesnot matter whether instanceable is authored in a referenced layer (onthe prim being referenced) or in the layer (or a super-layer) in which thereference is authored: only the composed value on the prim matters. See Instancing for more information.

By default, when UsdAttribute::Get resolves avalue from timeSamples, if the value-typesupports linear interpolation, the returned value will be linearly interpolatedbetween the timeSamples that bracket the requested sample time. This behaviorcan be inhibited for all attributes on a stage by callingUsdStage::SetInterpolationType(UsdInterpolationTypeHeld), which will force all timeSamples to resolvewith held interpolation.

IsA schemas can be either abstract or concrete; UsdGeomImageable is anabstract IsA schema: many prims will answer true toUsdPrim::IsA(), but there is noUsdGeomImageable::Define() method because you cannot create a prim oftype Imageable. UsdGeomMesh, however, is a concrete IsAschema, since it has a Define() method and prims can possess the typeNameMesh.

A Layer is the atomic persistent container of scene description for USD. Alayer contains zero or more PrimSpecs, that in turndescribe Property and Metadata values. Each layer possesses an identifier that canbe used to construct references to the layer from other layers.

Composition arcs such as References and SubLayers caninclude an offset and scaling of time to be applied during attribute valueresolution for all data composed from thetarget layer. We call this a Layer Offset, embodied inSdfLayerOffset. Layer offsets compose, so that if A referencesB with a time-scale of 2.0 and B references C with a time-scale of3.5, then data resolved at A whose source is C will have a totaltime-scale of 7.0 applied to it.

When an arc has both an offset and scale applied, the referenced animation isfirst scaled, then offset as it is brought into the referencing layer. So,in the following example, a timeSample at timeCode 12 in the file someAnimation.usd willappear at ((12 * 0.5) + 10) = 16 as resolved from the referencinglayer. Layer offsets cannot themselves vary over time. If a consuming contextrequires variable retiming of referenced data, it can use the more powerful (andsomewhat more costly) Value Clips feature.

When a layer references (or payloads or sub-layers) another layer, it is targeting(and therefore composing) not just the data in the single layer, but allthe data (in strength-order) in the LayerStack rooted at the targetedlayer.

Many of the composition arcs (as well as relationships) describe not just a single target, but anorderable list of targets, that will be processed (in order) accordingto the type of the arc. References can be list edited among the layers of a LayerStack. This canbe a powerful method of non-destructively changing the large-scalestructure of a scene as it flows down the pipeline.

3a8082e126