All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Creating a File Format Plugin

You can create plugins that adapt other file formats to USD, and the plugin will dynamically translate the file's contents into data recognizable as SdfPrimSpec 's, SdfPropertySpec 's, etc.
If you plan to have the file's entire contents translated and cached in memory at the time the file is opened, then derive a class from the SdfFileFormat plugin base class.
If, however, you wish to access the data lazily (as most binary file formats are designed to do), then you should also create an SdfAbstractData -derived adapter as part of the plugin.

File Format Capabilities

When integrating USD into end user applications it can be helpful to determine if file format plugins provide reading, writing, and/or editing functionality. These collective operations are referred to as a plugin's capabilities.
Being able to query a plugin's capabilities can be helpful in situations such as creating a file format selector for import or export. In the absense of being able to query such capabilities, a user might, for example, select a format for export, and have the operation fail mysteriously due to the operation not being supported by the format plugin.

Declaring Capabilities

File format capabilities are specified in the file format plugin's plugInfo.json entry. By default, the system assumes that each file format plugin supports all capabilities. Plugin authors must explicitly enumerate the capabilities that a plugin does not support.

There are currently three standard file format capabilities:

Capability plugInfo.json property Description
Reading supportsReading

The plugin supports data import into SdfLayer. If "supportsReading" is false, SdfLayer API that reads serialized data will issue a coding error and fail if given an identifier that is handled by this plugin.

This includes:
SdfLayer::FindOrOpen
SdfLayer::Import

Writing supportsWriting

The plugin supports data export from SdfLayer. If "supportsWriting" is false, SdfLayer API that writes serialized data will issue a coding error and fail if given an identifier that is handled by this plugin.

This includes:
SdfLayer::Export
SdfLayer::Save

Editing supportsEditing The plugin supports interactive layer modification. Currently this capability is for informational purposes only. No runtime validation is performed.

Below is an example plugInfo.json file declaring a file format that does not support writing.

{
"Plugins": [
{
"Info": {
"Types": {
"UnwritableFormat": {
"bases": [
"SdfTextFileFormat"
],
"displayName": "Format that does not support writing",
"extensions": [
"unwritable"
],
"supportsWriting": false,
"formatId": "UnwritableFormat",
"primary": true
}
}
}
}
]
}

Querying Capabilities at Runtime

File format capabilities can be queried at runtime using the SdfFileFormat class:

Static Method Instance Method
SdfFileFormat::FormatSupportsReading SdfFileFormat::SupportsReading
SdfFileFormat::FormatSupportsWriting SdfFileFormat::SupportsWriting
SdfFileFormat::FormatSupportsEditing SdfFileFormat::SupportsEditing

Use of the static methods when possible is preferred because these methods read the metadata authored in plugInfo.json to determine capabilities without loading the plugins themselves. This avoids a potentially costly load of large and complex plugins.