All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Sdf : Scene Description Foundations

Sdf provides the foundations for serializing scene description to a reference ascii format, or a (multitude of) plugin-defined format. It also provides the primitive abstractions for interacting with scene description, such as SdfPath, SdfLayer, SdfPrimSpec.

Overview

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, ascii 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.

Layering and Referencing

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.

Layers and Opinions

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.

Prim Spec

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:

  • SdfAttributeSpec. Represents values, which can be scalar or array-valued. For example, the radius attribute of a Sphere gprim holds a scalar value; the points attribute of a Mesh gprim holds an array value.
  • SdfRelationshipSpec. Represents a relationship to other prims, attributes, or relationships, such as the material:binding relationship that assigns Materials to Gprims.

Plugin Metadata

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:

"<field_name>" : {
"appliesTo": "<Optional comma-separated list of spec types this field applies to>"
"default": "<Optional default value for field>",
"displayGroup": "<Optional name of associated display group>",
"type": "<Required name indicating field type>",
}

For example:

# plugInfo.json
{
"Plugins": [
{
...
"Info": {
"SdfMetadata": {
"custom_double": {
"type": "double",
"appliesTo": "prims"
},
"custom_string": {
"type": "string",
"default": "default metadata value"
}
}
}
...
}
]
}
Note
Plugin metadata in a layer will remain intact and will round-trip properly even if the definition for that metadata is unavailable when the layer is opened. However, this metadata will not be inspectable using the normal Sdf API.

Types

The "type" entry for a metadata field must be one of the types listed below.

Scalar Types
"type" valueC++ type
assetSdfAssetPath
boolbool
doubledouble
floatfloat
halfGfHalf
intint
int64int64_t
stringstd::string
timecodeSdfTimeCode
tokenTfToken
ucharunsigned char
uintunsigned int
uint64uint64_t
Dimensioned Types
"type" valueC++ type
double2GfVec2d
double3GfVec3d
double4GfVec4d
float2GfVec2f
float3GfVec3f
float4GfVec4f
half2GfVec2h
half3GfVec3h
half4GfVec4h
int2GfVec2i
int3GfVec3i
int4GfVec4i
matrix2dGfMatrix2d
matrix3dGfMatrix3d
matrix4dGfMatrix4d
quatdGfQuatd
quatfGfQuatf
quathGfQuath
Array Types
"type" valueC++ type
Element type name + "[]"VtArray<Element C++ type>
Any scalar type + "[]"VtArray<C++ type>
  ex: string[]  ex: VtArray<std::string>
Any dimensioned type + "[]"VtArray<C++ type>
  ex: float2[]  ex: VtArray<GfVec2f>
Dictionary Types
"type" valueC++ type
dictionaryVtDictionary
List Operation Types
"type" valueC++ type
intlistopSdfIntListOp
int64listopSdfInt64ListOp
uintlistopSdfUIntListOp
uint64listopSdfUInt64ListOp
stringlistopSdfStringListOp
tokenlistopSdfTokenListOp

Default Values

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:

"SdfMetadata": {
# Defines a field named "double_single_default" with default value of 1.0
"double_single_default": {
"type": "double",
"default": 1.0
},
# Defines a field named "double_shaped_default" with default value of VtArray<double>: {0.0, 1.0}
"double_array_with_default": {
"type": "double[]",
"default": [0.0, 1.0]
}
# Defines a field named "double2_single_default" with default value of GfVec2d(0.0, 1.0)
"double2_single_default": {
"type": "double2",
"default": [0.0, 1.0]
}
# Defines a field named "matrix4d_single_default" with default value of GfMatrix4d(0.5, 1.5, 2.5, 3.5, ...)
"matrix4d_single_default": {
"type": "matrix4d"
"default": [0.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5, 10.5, 11.5, 12.5, 13.5, 14.5, 15.5]
}
}

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.

Limiting to Specific Spec Types

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.

Display Groups

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.

Custom File Formats

It is possible to create plugins that adapt other file formats to USD, such that a USD file can reference a file of another format, and the plugin will dynamically translate the file's contents into data recognizable as SdfPrimSpec 's, SdfPropertySpec 's, etc. If it is acceptable to have the file's entire contents translated and cached in memory at the time the file is opened, then deriving a class from the SdfFileFormat plugin base class is the primary task. If, however, one wishes to access the data lazily (as most binary file formats are designed to do), then one must also create an SdfAbstractData -derived adapter as part of the plugin.