|
Base class for file format implementations. More...
#include <fileFormat.h>
Public Types | |
typedef std::map< std::string, std::string > | FileFormatArguments |
Type for specifying additional file format-specific arguments to the various API below. | |
Public Types inherited from TfRefBase | |
typedef void(* | UniqueChangedFuncPtr) (TfRefBase const *, bool) |
Public Member Functions | |
SdfFileFormat (const SdfFileFormat &)=delete | |
SdfFileFormat & | operator= (const SdfFileFormat &)=delete |
SDF_API const SdfSchemaBase & | GetSchema () const |
Returns the schema for this format. | |
SDF_API const TfToken & | GetFormatId () const |
Returns the format identifier. | |
SDF_API const TfToken & | GetTarget () const |
Returns the target for this file format. | |
SDF_API const std::string & | GetFileCookie () const |
Returns the cookie to be used when writing files with this format. | |
SDF_API const TfToken & | GetVersionString () const |
Returns the current version of this file format. | |
SDF_API bool | IsPrimaryFormatForExtensions () const |
Returns true if this file format is the primary format for the extensions it handles. | |
SDF_API const std::vector< std::string > & | GetFileExtensions () const |
Returns a list of extensions that this format supports. | |
SDF_API const std::string & | GetPrimaryFileExtension () const |
Returns the primary file extension for this format. | |
SDF_API bool | IsSupportedExtension (const std::string &extension) const |
Returns true if extension matches one of the extensions returned by GetFileExtensions. | |
virtual SDF_API bool | IsPackage () const |
Returns true if this file format is a package containing other assets. | |
virtual SDF_API std::string | GetPackageRootLayerPath (const std::string &resolvedPath) const |
Returns the path of the "root" layer contained in the package layer at resolvedPath produced by this file format. | |
virtual SDF_API FileFormatArguments | GetDefaultFileFormatArguments () const |
Returns the FileFormatArguments that correspond to the default behavior of this file format when no FileFormatArguments are passed to NewLayer or InitData. | |
virtual SDF_API SdfAbstractDataRefPtr | InitData (const FileFormatArguments &args) const |
This method allows the file format to bind to whatever data container is appropriate. | |
SDF_API SdfAbstractDataRefPtr | InitDetachedData (const FileFormatArguments &args) const |
Returns a new SdfAbstractData providing access to the layer's data. | |
SDF_API SdfLayerRefPtr | NewLayer (const SdfFileFormatConstPtr &fileFormat, const std::string &identifier, const std::string &realPath, const ArAssetInfo &assetInfo, const FileFormatArguments &args) const |
Instantiate a layer. | |
SDF_API bool | ShouldSkipAnonymousReload () const |
Return true if this file format prefers to skip reloading anonymous layers. | |
SDF_API bool | ShouldReadAnonymousLayers () const |
Returns true if anonymous layer identifiers should be passed to Read when a layer is opened or reloaded. | |
virtual SDF_API bool | CanRead (const std::string &file) const =0 |
Returns true if file can be read by this format. | |
virtual SDF_API bool | Read (SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly) const =0 |
Reads scene description from the asset specified by resolvedPath into the layer layer . | |
SDF_API bool | ReadDetached (SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly) const |
Reads scene description from the asset specified by resolvedPath into the detached layer layer . | |
virtual SDF_API bool | WriteToFile (const SdfLayer &layer, const std::string &filePath, const std::string &comment=std::string(), const FileFormatArguments &args=FileFormatArguments()) const |
Writes the content in layer into the file at filePath . | |
virtual SDF_API bool | SaveToFile (const SdfLayer &layer, const std::string &filePath, const std::string &comment=std::string(), const FileFormatArguments &args=FileFormatArguments()) const |
Write the content in layer to the file at filePath , which is the backing store for layer itself. | |
virtual SDF_API bool | ReadFromString (SdfLayer *layer, const std::string &str) const |
Reads data in the string str into the layer layer . | |
virtual SDF_API bool | WriteToStream (const SdfSpecHandle &spec, std::ostream &out, size_t indent) const |
Write the provided spec to out indented indent levels. | |
virtual SDF_API bool | WriteToString (const SdfLayer &layer, std::string *str, const std::string &comment=std::string()) const |
Writes the content in layer to the string str . | |
virtual SDF_API std::set< std::string > | GetExternalAssetDependencies (const SdfLayer &layer) const |
Returns the set of resolved paths to external asset file dependencies for the given layer . | |
SDF_API bool | SupportsReading () const |
Returns true if this file format supports reading. | |
SDF_API bool | SupportsWriting () const |
This is a convenience method for invoking FormatSupportsWriting with this format's extension and target. | |
SDF_API bool | SupportsEditing () const |
This is a convenience method for invoking FormatSupportsEditing with this format's extension and target. | |
Public Member Functions inherited from TfRefBase | |
TfRefBase (TfRefBase const &) | |
TfRefBase & | operator= (TfRefBase const &) |
size_t | GetCurrentCount () const |
Return the current reference count of this object. | |
bool | IsUnique () const |
Return true if only one TfRefPtr points to this object. | |
void | SetShouldInvokeUniqueChangedListener (bool shouldCall) |
Public Member Functions inherited from TfWeakBase | |
TfWeakBase (const TfWeakBase &) | |
const TfWeakBase & | __GetTfWeakBase__ () const |
const TfWeakBase & | operator= (const TfWeakBase &) |
void | EnableNotification2 () const |
TF_API void const * | GetUniqueIdentifier () const |
Static Public Member Functions | |
static SDF_API std::string | GetFileExtension (const std::string &s) |
Returns the file extension for path or file name s , without the leading dot character. | |
static SDF_API std::set< std::string > | FindAllFileFormatExtensions () |
Returns a set containing the extension(s) corresponding to all registered file formats. | |
static SDF_API std::set< std::string > | FindAllDerivedFileFormatExtensions (const TfType &baseType) |
Returns a set containing the extension(s) corresponding to all registered file formats that derive from baseType . | |
static SDF_API bool | FormatSupportsReading (const std::string &extension, const std::string &target=std::string()) |
Returns true if the file format for the supplied extension and target pair supports reading. | |
static SDF_API bool | FormatSupportsWriting (const std::string &extension, const std::string &target=std::string()) |
Returns true if the file format for the supplied extension and target pair supports writing. | |
static SDF_API bool | FormatSupportsEditing (const std::string &extension, const std::string &target=std::string()) |
Returns true if the file format for the supplied extension and target pair supports editing. | |
static SDF_API SdfFileFormatConstPtr | FindById (const TfToken &formatId) |
Returns the file format instance with the specified formatId identifier. | |
static SDF_API SdfFileFormatConstPtr | FindByExtension (const std::string &path, const std::string &target=std::string()) |
Returns the file format instance that supports the extension for path . | |
static SDF_API SdfFileFormatConstPtr | FindByExtension (const std::string &path, const FileFormatArguments &args) |
Returns a file format instance that supports the extension for path and whose target matches one of those specified by the given args . | |
Static Public Member Functions inherited from TfRefBase | |
static TF_API void | SetUniqueChangedListener (UniqueChangedListener listener) |
Protected Member Functions | |
SDF_API | SdfFileFormat (const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::string &extension) |
Constructor. | |
SDF_API | SdfFileFormat (const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::string &extension, const SdfSchemaBase &schema) |
Constructor. | |
SdfFileFormat (const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::string &extension, const SdfSchemaBase &&schema)=delete | |
Disallow temporary SdfSchemaBase objects being passed to the c'tor. | |
SDF_API | SdfFileFormat (const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::vector< std::string > &extensions) |
Constructor. | |
SDF_API | SdfFileFormat (const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::vector< std::string > &extensions, const SdfSchemaBase &schema) |
Constructor. | |
SdfFileFormat (const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::vector< std::string > &extensions, const SdfSchemaBase &&schema)=delete | |
Disallow temporary SdfSchemaBase objects being passed to the c'tor. | |
virtual SDF_API | ~SdfFileFormat () |
Destructor. | |
SDF_API bool | _ReadAndCopyLayerDataToMemory (SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly, bool *didCopyData=nullptr) const |
Helper function for _ReadDetached. | |
virtual SDF_API SdfLayer * | _InstantiateNewLayer (const SdfFileFormatConstPtr &fileFormat, const std::string &identifier, const std::string &realPath, const ArAssetInfo &assetInfo, const FileFormatArguments &args) const |
virtual SDF_API bool | _ShouldSkipAnonymousReload () const |
virtual SDF_API bool | _ShouldReadAnonymousLayers () const |
File format subclasses may override this to specify whether Read should be called when creating, opening, or reloading an anonymous layer of this format. | |
virtual SDF_API SdfAbstractDataRefPtr | _InitDetachedData (const FileFormatArguments &args) const |
virtual SDF_API bool | _ReadDetached (SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly) const |
Protected Member Functions inherited from TfWeakBase | |
TfRefPtr< Tf_Remnant > | _Register () const |
template<class T > | |
TfRefPtr< Tf_Remnant > | _Register (T *tempRmnt) const |
bool | _HasRemnant () const |
Static Protected Member Functions | |
static SDF_API void | _SetLayerData (SdfLayer *layer, SdfAbstractDataRefPtr &data) |
Set the internal data for layer to data , possibly transferring ownership of data . | |
static SDF_API void | _SetLayerData (SdfLayer *layer, SdfAbstractDataRefPtr &data, SdfLayerHints hints) |
Set the internal data for layer to data , possibly transferring ownership of data . | |
static SDF_API SdfAbstractDataConstPtr | _GetLayerData (const SdfLayer &layer) |
Get the internal data for layer . | |
Base class for file format implementations.
Definition at line 47 of file fileFormat.h.
typedef std::map<std::string, std::string> FileFormatArguments |
Type for specifying additional file format-specific arguments to the various API below.
Definition at line 102 of file fileFormat.h.
|
protected |
Constructor.
|
protected |
Constructor.
schema
must remain valid for the lifetime of this file format.
|
protecteddelete |
Disallow temporary SdfSchemaBase objects being passed to the c'tor.
|
protected |
Constructor.
|
protected |
Constructor.
schema
must remain valid for the lifetime of this file format.
|
protecteddelete |
Disallow temporary SdfSchemaBase objects being passed to the c'tor.
|
protectedvirtual |
Destructor.
|
staticprotected |
Get the internal data for layer
.
|
protectedvirtual |
This function must return a new SdfAbstractData object that is detached, i.e. SdfAbstractData::IsDetached returns false.
The default implementation returns an SdfData object.
Reimplemented in UsdUsdFileFormat.
|
protected |
Helper function for _ReadDetached.
Calls Read with the given parameters. If successful and layer
is not detached (i.e., SdfLayer::IsDetached returns false) copies the layer data into an SdfData object and set that into layer
. If this copy occurs and didCopyData
is given, it will be set to true.
Note that the copying process is a simple spec-by-spec, field-by-field value copy. This process may not produce detached layers if the data object used by layer
after the initial call to Read returns VtValues that are not detached. One example is a VtValue holding a VtArray backed by a foreign data source attached to a memory mapping.
Returns true if Read was successful, false otherwise.
|
protectedvirtual |
Upon completion, layer
must have an SdfAbstractData object set that is detached, i.e. SdfAbstractData::IsDetached returns false.
The default implementation calls _ReadAndCopyLayerDataToMemory to read the specified layer and copy its data into an SdfData object if it is not detached. If data is copied, a warning will be issued since this may be an expensive operation. If the above behavior is desired, subclasses can just call _ReadAndCopyLayerDataToMemory to do the same thing but without the warning.
Reimplemented in UsdUsdFileFormat, and UsdUsdzFileFormat.
|
staticprotected |
Set the internal data for layer
to data
, possibly transferring ownership of data
.
Existing layer hints are reset to the default hints.
|
staticprotected |
Set the internal data for layer
to data
, possibly transferring ownership of data
.
Existing layer hints are replaced with hints
.
|
protectedvirtual |
File format subclasses may override this to specify whether Read should be called when creating, opening, or reloading an anonymous layer of this format.
Default implementation returns false.
|
pure virtual |
Returns true if file
can be read by this format.
Implemented in SdfTextFileFormat, UsdUsdFileFormat, UsdUsdzFileFormat, and UsdUsdcFileFormat.
|
static |
Returns a set containing the extension(s) corresponding to all registered file formats that derive from baseType
.
baseType
must derive from SdfFileFormat.
|
static |
Returns a set containing the extension(s) corresponding to all registered file formats.
|
static |
Returns a file format instance that supports the extension for path
and whose target matches one of those specified by the given args
.
If the args
specify no target, then the file format that is registered as the primary plugin will be returned. If a format with a matching extension is not found, this returns a null file format pointer.
|
static |
Returns the file format instance that supports the extension for path
.
If a format with a matching extension is not found, this returns a null file format pointer.
An extension may be handled by multiple file formats, but each with a different target. In such cases, if no target
is specified, the file format that is registered as the primary plugin will be returned. Otherwise, the file format whose target matches target
will be returned.
|
static |
Returns the file format instance with the specified formatId
identifier.
If a format with a matching identifier is not found, this returns a null file format pointer.
|
static |
Returns true if the file format for the supplied extension
and target
pair supports editing.
This method will not load the plugin that provides the specified file format. If the extension and target pair is invalid, this method will return false.
|
static |
Returns true if the file format for the supplied extension
and target
pair supports reading.
This method will not load the plugin that provides the specified file format. If the extension and target pair is invalid, this method will return false.
|
static |
Returns true if the file format for the supplied extension
and target
pair supports writing.
This method will not load the plugin that provides the specified file format. If the extension and target pair is invalid, this method will return false.
|
virtual |
Returns the FileFormatArguments that correspond to the default behavior of this file format when no FileFormatArguments are passed to NewLayer or InitData.
|
virtual |
Returns the set of resolved paths to external asset file dependencies for the given layer
.
These are additional dependencies, specific to the file format, that are needed when generating the layer's contents and would not otherwise be discoverable through composition dependencies (i.e. sublayers, references, and payloads).
The default implementation returns an empty set. Derived file formats that depend on external assets to read and generate layer content should implement this function to return the external asset paths.
SDF_API const std::string & GetFileCookie | ( | ) | const |
Returns the cookie to be used when writing files with this format.
|
static |
Returns the file extension for path or file name s
, without the leading dot character.
SDF_API const std::vector< std::string > & GetFileExtensions | ( | ) | const |
Returns a list of extensions that this format supports.
SDF_API const TfToken & GetFormatId | ( | ) | const |
Returns the format identifier.
|
virtual |
Returns the path of the "root" layer contained in the package layer at resolvedPath
produced by this file format.
If this file format is not a package, returns the empty string.
The package root layer is the layer in the package layer that is used when that package is opened via SdfLayer.
Reimplemented in UsdUsdzFileFormat.
SDF_API const std::string & GetPrimaryFileExtension | ( | ) | const |
Returns the primary file extension for this format.
This is the extension that is reported for layers using this file format.
SDF_API const SdfSchemaBase & GetSchema | ( | ) | const |
Returns the schema for this format.
SDF_API const TfToken & GetTarget | ( | ) | const |
Returns the target for this file format.
SDF_API const TfToken & GetVersionString | ( | ) | const |
Returns the current version of this file format.
|
virtual |
This method allows the file format to bind to whatever data container is appropriate.
Returns a shared pointer to an SdfAbstractData implementation.
Reimplemented in UsdUsdcFileFormat, UsdUsdFileFormat, and UsdUsdzFileFormat.
SDF_API SdfAbstractDataRefPtr InitDetachedData | ( | const FileFormatArguments & | args | ) | const |
Returns a new SdfAbstractData providing access to the layer's data.
This data object is detached from any underlying storage.
|
virtual |
Returns true if this file format is a package containing other assets.
Reimplemented in UsdUsdzFileFormat.
SDF_API bool IsPrimaryFormatForExtensions | ( | ) | const |
Returns true if this file format is the primary format for the extensions it handles.
SDF_API bool IsSupportedExtension | ( | const std::string & | extension | ) | const |
Returns true if extension
matches one of the extensions returned by GetFileExtensions.
SDF_API SdfLayerRefPtr NewLayer | ( | const SdfFileFormatConstPtr & | fileFormat, |
const std::string & | identifier, | ||
const std::string & | realPath, | ||
const ArAssetInfo & | assetInfo, | ||
const FileFormatArguments & | args | ||
) | const |
Instantiate a layer.
|
pure virtual |
Reads scene description from the asset specified by resolvedPath
into the layer layer
.
metadataOnly
is a flag that asks for only the layer metadata to be read in, which can be much faster if that is all that is required. Note that this is just a hint: some FileFormat readers may disregard this flag and still fully populate the layer contents.
Returns true if the asset is successfully read into layer
, false otherwise.
Implemented in SdfTextFileFormat, UsdUsdFileFormat, UsdUsdzFileFormat, and UsdUsdcFileFormat.
SDF_API bool ReadDetached | ( | SdfLayer * | layer, |
const std::string & | resolvedPath, | ||
bool | metadataOnly | ||
) | const |
Reads scene description from the asset specified by resolvedPath
into the detached layer layer
.
After reading is completed, layer
must be detached from any underlying storage.
metadataOnly
is a flag that asks for only the layer metadata to be read in, which can be much faster if that is all that is required. Note that this is just a hint: some FileFormat readers may disregard this flag and still fully populate the layer contents.
Returns true if the asset is successfully read into layer
, false if the the asset could not be read or if the resulting layer is not detached.
|
virtual |
Reads data in the string str
into the layer layer
.
If the file is successfully read, this method returns true. Otherwise, false is returned and errors are posted.
Reimplemented in SdfTextFileFormat, UsdUsdFileFormat, UsdUsdzFileFormat, and UsdUsdcFileFormat.
|
virtual |
Write the content in layer
to the file at filePath
, which is the backing store for layer
itself.
If the content is successfully written, this method returns true. Otherwise, false is returned and errors are posted. The default implementation just calls WriteToFile() passing all the same arguments.
The purpose of this member function is to provide a distinction between a "Save" operation that updates the backing store for the layer
itself and an "Export" operation that writes the layer
data to a distinct asset. File formats that retain all data in memory can typically override only WriteToFile(), but formats that do not may need to take different action on "Save" vs "Export".
Reimplemented in UsdUsdFileFormat, and UsdUsdcFileFormat.
SDF_API bool ShouldReadAnonymousLayers | ( | ) | const |
Returns true if anonymous layer identifiers should be passed to Read when a layer is opened or reloaded.
Anonymous layers will not have an asset backing and thus for most file formats there is nothing that can be read for an anonymous layer. However, there are file formats that use Read to generate dynamic layer content without reading any data from the resolved asset associated with the layer's identifier.
For these types of file formats it is useful to be able to open anonymous layers and allow Read to populate them to avoid requiring a placeholder asset to exist just so Read can populate the layer.
SDF_API bool ShouldSkipAnonymousReload | ( | ) | const |
Return true if this file format prefers to skip reloading anonymous layers.
SDF_API bool SupportsEditing | ( | ) | const |
This is a convenience method for invoking FormatSupportsEditing with this format's extension and target.
SDF_API bool SupportsReading | ( | ) | const |
Returns true if this file format supports reading.
This is a convenience method for invoking FormatSupportsReading with this format's extension and target
SDF_API bool SupportsWriting | ( | ) | const |
This is a convenience method for invoking FormatSupportsWriting with this format's extension and target.
|
virtual |
Writes the content in layer
into the file at filePath
.
If the content is successfully written, this method returns true. Otherwise, false is returned and errors are posted. The default implementation returns false.
This member function makes no distinction between a "Save" operation that updates the backing store for the layer
itself and an "Export" operation that writes the layer
data to a distinct asset. For file formats that retain all data in memory this is typically fine. But for file formats that handle data requests by reading from the backing store, this distinction can be important. In that case, additionally override the member function SaveToFile() to take different action.
Reimplemented in SdfTextFileFormat, UsdUsdFileFormat, UsdUsdzFileFormat, and UsdUsdcFileFormat.
|
virtual |
Write the provided spec
to out
indented indent
levels.
Reimplemented in SdfTextFileFormat, UsdUsdcFileFormat, UsdUsdFileFormat, and UsdUsdzFileFormat.
|
virtual |
Writes the content in layer
to the string str
.
This function should write a textual representation of layer
to the stream that can be read back in via ReadFromString.
Reimplemented in SdfTextFileFormat, UsdUsdFileFormat, UsdUsdzFileFormat, and UsdUsdcFileFormat.