|
Sdf provides the foundations for serializing scene description to a reference text format, or a multitude of plugin-defined formats. It also provides the primitive abstractions for interacting with scene description, such as SdfPath, SdfLayer, SdfPrimSpec.
Implements scene description layers in USD. In USD, a complete scene description is composed from partial scene description stored in SdfLayer objects. The primary unit of scene description within a layer is a prim spec, represented by the SdfPrimSpec class. A complete UsdPrim on a stage is a composition of the prim's built-in fallback values and all of the prim spec objects specified in Sdf layers. (For an overview of prims and stages, see the Usd library overview.)
Use methods on an SdfLayer object to export and save a layer to a file, or to load a file from disk. Scene description files are stored in .usd
format (one layer per file, text or binary). Other features abstracted at the layer level include undo/redo functionality and logging, which can be customized by subclassing SdfLayerStateDelegateBase .
You should primarily work with scene description using the classes in the Usd library. The UsdStage object not only represents a complete scene; it also knows how each of the partial scene descriptions were combined to form the complete scene. For example, the UsdStage object has the context to know how the path of a UsdPrim object on the stage relates to the paths of each SdfPrimSpec object in each layer that contributes a partial description to the complete prim. SdfLayer objects do not have the context to know how they relate to other layers.
An SdfPrimSpec object is named and forms a namespace hierarchy with other prims. Each layer contains one or more root prims, each of which may have a hierarchy of children. The SdfPath class provides methods to manipulate paths for all of the objects that comprise a layer's scene description. For example, SdfPath assigns unique paths for each of the objects in a namespace hierarchy; this includes paths to scene description that "lives inside of" particular variants of a VariantSet.
Layers can be combined in several ways. An SdfLayer can have sublayers. When layering, the SdfPrimSpec objects in an SdfLayer object merge over the prims at the same namespace path in the layer. An SdfPrimSpec object can also reference another prim within its own layer or a prim from another layer. When referencing, a prim and its name children merge over the other prim that it references.
Note that layering and referencing means that multiple SdfPrimSpec objects may contribute partial descriptions for the same logical prim. The full description of the prim in a given scene comes only from combining or composing the contributions of each of the SdfPrimSpec objects.
You can think of the partial scene spec in an SdfLayer object as one opinion on an aspect of a complete scene. Several properties at the layer level determine how or whether the opinion offered at a particular layer is considered when the system composes a complete prim on a stage. For example, the SdfPrimSpec and SdfPropertySpec classes have an access permission property (SdfPermission) that you can use to specify whether a layer is public or private.
There are many different kinds of prims, but at the level of scene description they are all represented by an SdfPrimSpec object. An SdfPrimSpec object represents a partial description of an individual prim in a scene. It does not require values for every property it contains. In addition, the list of properties that an SdfPrimSpec object owns may be sparse. An SdfPrimSpec object that describes a Cylinder may have a radius but no height, relying on either another SdfPrimSpec object or the prim's fallback definition to provide the height. Similarly, the list of name children on an SdfPrimSpec object may be sparse.
SdfPrimSpec properties are represented by the SdfPropertySpec class. Property specs also represent partial scene description. The SdfPropertySpec subclasses represent the basic types of properties that prims can have:
radius
attribute of a Sphere gprim holds a scalar value; the points
attribute of a Mesh gprim holds an array value. material:binding
relationship that assigns Materials to Gprims. Plugins can extend scene description to store additional plugin-specific metadata by registering custom metadata fields. Consumers can query and author data for these fields in the same way as the built-in metadata fields in Sdf. This data will be serialized to and read from layers just like all other scene description.
Plugin metadata fields must be defined in a dictionary called "SdfMetadata" in the "Info" section of the plugin's plugInfo.json
file. Each entry in the dictionary defines a single field and has the following syntax:
For example:
The "type" entry for a metadata field must be one of the types listed below.
|
|
|
If not specified, the default value for plugin metadata fields is the default value for the associated scene description type. However, plugins may specify default values for each field. The current implementation allows default values to be specified using a double, an int, a string, or a flat list of one of these types. For example:
Default values may not be specified for list operation types and dictionary types.
Clients can query the default value for a plugin metadata field by calling SdfSchema::GetFallback.
By default, a plugin metadata field can be used with any spec type. However, this can be limited by setting the "appliesTo" field to a comma-separated list of values from the table below:
"appliesTo" value | Spec type |
---|---|
layers | SdfLayer (SdfPseudoRootSpec) |
prims | SdfPrimSpec, SdfVariantSpec |
properties | SdfPropertySpec |
attributes | SdfAttributeSpec |
relationships | SdfRelationshipSpec |
variants | SdfVariantSpec |
Note that metadata that "appliesTo" prims also applies to variants, as variants can hold the same scene description as prims.
A plugin metadata field may be associated with a display group by specifying a value for the "displayGroup" field. This is purely an affordance to allow external applications to group metadata fields together for display purposes. Sdf does not consume this data itself.
See Creating a File Format Plugin for information about creating file format plugins..
See Variable Expressions for information about variable expressions.