This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
fileFormat.h
Go to the documentation of this file.
1//
2// Copyright 2016 Pixar
3//
4// Licensed under the terms set forth in the LICENSE.txt file available at
5// https://openusd.org/license.
6//
7#ifndef PXR_USD_SDF_FILE_FORMAT_H
8#define PXR_USD_SDF_FILE_FORMAT_H
9
11
12#include "pxr/pxr.h"
13#include "pxr/usd/ar/ar.h"
14#include "pxr/usd/sdf/api.h"
17#include "pxr/base/tf/refBase.h"
19#include "pxr/base/tf/token.h"
20#include "pxr/base/tf/type.h"
22
23#include <map>
24#include <string>
25#include <vector>
26
27PXR_NAMESPACE_OPEN_SCOPE
28
29class ArAssetInfo;
30class SdfSchemaBase;
31class SdfLayerHints;
32
33SDF_DECLARE_HANDLES(SdfLayer);
34SDF_DECLARE_HANDLES(SdfSpec);
37
38#define SDF_FILE_FORMAT_TOKENS \
39 ((TargetArg, "target"))
40
41TF_DECLARE_PUBLIC_TOKENS(SdfFileFormatTokens, SDF_API, SDF_FILE_FORMAT_TOKENS);
42
48 : public TfRefBase
49 , public TfWeakBase
50{
51public:
52 SdfFileFormat(const SdfFileFormat&) = delete;
53 SdfFileFormat& operator=(const SdfFileFormat&) = delete;
54
56 SDF_API const SdfSchemaBase& GetSchema() const;
57
59 SDF_API const TfToken& GetFormatId() const;
60
62 SDF_API const TfToken& GetTarget() const;
63
65 SDF_API const std::string& GetFileCookie() const;
66
68 SDF_API const TfToken& GetVersionString() const;
69
72 SDF_API bool IsPrimaryFormatForExtensions() const;
73
75 SDF_API const std::vector<std::string>& GetFileExtensions() const;
76
79 SDF_API const std::string& GetPrimaryFileExtension() const;
80
83 SDF_API bool IsSupportedExtension(const std::string& extension) const;
84
87 SDF_API
88 virtual bool IsPackage() const;
89
96 SDF_API
97 virtual std::string GetPackageRootLayerPath(
98 const std::string& resolvedPath) const;
99
102 typedef std::map<std::string, std::string> FileFormatArguments;
103
107 SDF_API
109
114 SDF_API
115 virtual SdfAbstractDataRefPtr
116 InitData(const FileFormatArguments& args) const;
117
120 SDF_API
121 SdfAbstractDataRefPtr InitDetachedData(
122 const FileFormatArguments& args) const;
123
125 SDF_API
126 SdfLayerRefPtr NewLayer(const SdfFileFormatConstPtr &fileFormat,
127 const std::string &identifier,
128 const std::string &realPath,
129 const ArAssetInfo& assetInfo,
130 const FileFormatArguments &args) const;
131
134 SDF_API bool ShouldSkipAnonymousReload() const;
135
148 SDF_API bool ShouldReadAnonymousLayers() const;
149
151 SDF_API
152 virtual bool CanRead(
153 const std::string& file) const = 0;
154
165 SDF_API
166 virtual bool Read(
167 SdfLayer* layer,
168 const std::string& resolvedPath,
169 bool metadataOnly) const = 0;
170
183 SDF_API
185 SdfLayer* layer,
186 const std::string& resolvedPath,
187 bool metadataOnly) const;
188
201 SDF_API
202 virtual bool WriteToFile(
203 const SdfLayer& layer,
204 const std::string& filePath,
205 const std::string& comment = std::string(),
206 const FileFormatArguments& args = FileFormatArguments()) const;
207
220 SDF_API
221 virtual bool SaveToFile(
222 const SdfLayer& layer,
223 const std::string& filePath,
224 const std::string& comment = std::string(),
225 const FileFormatArguments& args = FileFormatArguments()) const;
226
230 SDF_API
231 virtual bool ReadFromString(
232 SdfLayer* layer,
233 const std::string& str) const;
234
236 SDF_API
237 virtual bool WriteToStream(
238 const SdfSpecHandle &spec,
239 std::ostream& out,
240 size_t indent) const;
241
245 SDF_API
246 virtual bool WriteToString(
247 const SdfLayer& layer,
248 std::string* str,
249 const std::string& comment = std::string()) const;
250
263 SDF_API
264 virtual std::set<std::string> GetExternalAssetDependencies(
265 const SdfLayer& layer) const;
266
267
271 SDF_API bool SupportsReading() const;
272
273 // Returns true if this file format supports writing.
276 SDF_API bool SupportsWriting() const;
277
278 // Returns true if this file format supports editing.
281 SDF_API bool SupportsEditing() const;
282
285 SDF_API static std::string GetFileExtension(const std::string& s);
286
289 SDF_API static std::set<std::string> FindAllFileFormatExtensions();
290
295 SDF_API static std::set<std::string> FindAllDerivedFileFormatExtensions(
296 const TfType& baseType);
297
305 SDF_API
307 const std::string& extension,
308 const std::string& target = std::string());
309
317 SDF_API
319 const std::string& extension,
320 const std::string& target = std::string());
321
329 SDF_API
331 const std::string& extension,
332 const std::string& target = std::string());
333
337 SDF_API
338 static SdfFileFormatConstPtr FindById(
339 const TfToken& formatId);
340
350 SDF_API
351 static SdfFileFormatConstPtr FindByExtension(
352 const std::string& path,
353 const std::string& target = std::string());
354
361 SDF_API
362 static SdfFileFormatConstPtr FindByExtension(
363 const std::string& path,
364 const FileFormatArguments& args);
365
366protected:
369 const TfToken& formatId,
370 const TfToken& versionString,
371 const TfToken& target,
372 const std::string& extension);
373
377 const TfToken& formatId,
378 const TfToken& versionString,
379 const TfToken& target,
380 const std::string& extension,
381 const SdfSchemaBase& schema);
382
385 const TfToken& formatId,
386 const TfToken& versionString,
387 const TfToken& target,
388 const std::string& extension,
389 const SdfSchemaBase&& schema) = delete;
390
393 const TfToken& formatId,
394 const TfToken& versionString,
395 const TfToken& target,
396 const std::vector<std::string> &extensions);
397
401 const TfToken& formatId,
402 const TfToken& versionString,
403 const TfToken& target,
404 const std::vector<std::string> &extensions,
405 const SdfSchemaBase& schema);
406
409 const TfToken& formatId,
410 const TfToken& versionString,
411 const TfToken& target,
412 const std::vector<std::string> &extensions,
413 const SdfSchemaBase&& schema) = delete;
414
416 SDF_API virtual ~SdfFileFormat();
417
418 //
419 // Minimally break layer encapsulation with the following methods. These
420 // methods are also intended to limit the need for SdfLayer friendship with
421 // SdfFileFormat child classes.
422 //
423
428 SDF_API
429 static void _SetLayerData(
430 SdfLayer* layer, SdfAbstractDataRefPtr& data);
431
436 SDF_API
437 static void _SetLayerData(
438 SdfLayer* layer, SdfAbstractDataRefPtr& data,
439 SdfLayerHints hints);
440
442 SDF_API
443 static SdfAbstractDataConstPtr _GetLayerData(const SdfLayer& layer);
444
459 SDF_API
461 SdfLayer* layer,
462 const std::string& resolvedPath,
463 bool metadataOnly,
464 bool* didCopyData = nullptr) const;
465
466protected:
467 SDF_API
468 virtual SdfLayer *_InstantiateNewLayer(
469 const SdfFileFormatConstPtr &fileFormat,
470 const std::string &identifier,
471 const std::string &realPath,
472 const ArAssetInfo& assetInfo,
473 const FileFormatArguments &args) const;
474
475 // File format subclasses may override this if they prefer not to skip
476 // reloading anonymous layers. Default implementation returns true.
477 SDF_API
478 virtual bool _ShouldSkipAnonymousReload() const;
479
484 SDF_API
485 virtual bool _ShouldReadAnonymousLayers() const;
486
493 SDF_API
494 virtual SdfAbstractDataRefPtr _InitDetachedData(
495 const FileFormatArguments& args) const;
496
508 SDF_API
509 virtual bool _ReadDetached(
510 SdfLayer* layer,
511 const std::string& resolvedPath,
512 bool metadataOnly) const;
513
514private:
515 const SdfSchemaBase& _schema;
516 const TfToken _formatId;
517 const TfToken _target;
518 const std::string _cookie;
519 const TfToken _versionString;
520 const std::vector<std::string> _extensions;
521 const bool _isPrimaryFormat;
522};
523
524// Base file format factory.
525class Sdf_FileFormatFactoryBase : public TfType::FactoryBase {
526public:
527 SDF_API virtual ~Sdf_FileFormatFactoryBase();
528 virtual SdfFileFormatRefPtr New() const = 0;
529};
530
531// Default file format factory.
532template <typename T>
533class Sdf_FileFormatFactory : public Sdf_FileFormatFactoryBase {
534public:
535 virtual SdfFileFormatRefPtr New() const
536 {
537 return TfCreateRefPtr(new T);
538 }
539};
540
562#ifdef doxygen
563#define SDF_DEFINE_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
564#else
565#define SDF_DEFINE_FILE_FORMAT(...) SdfDefineFileFormat<__VA_ARGS__>()
566
567template <class FileFormat, class ...BaseFormats>
568void SdfDefineFileFormat()
569{
570 TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>()
571 .template SetFactory<Sdf_FileFormatFactory<FileFormat>>();
572}
573#endif // doxygen
574
596#ifdef doxygen
597#define SDF_DEFINE_ABSTRACT_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
598#else
599#define SDF_DEFINE_ABSTRACT_FILE_FORMAT(...) \
600 SdfDefineAbstractFileFormat<__VA_ARGS__>()
601
602template <class FileFormat, class ...BaseFormats>
603void SdfDefineAbstractFileFormat()
604{
605 TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>();
606}
607#endif //doxygen
608
626#ifdef doxygen
627#define SDF_FILE_FORMAT_FACTORY_ACCESS
628#else
629#define SDF_FILE_FORMAT_FACTORY_ACCESS \
630 template<typename T> friend class Sdf_FileFormatFactory
631#endif //doxygen
632
633PXR_NAMESPACE_CLOSE_SCOPE
634
635#endif
Contains information about a resolved asset.
Definition: assetInfo.h:25
Interface for scene description data storage.
Definition: abstractData.h:57
Base class for file format implementations.
Definition: fileFormat.h:50
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.
static SDF_API SdfAbstractDataConstPtr _GetLayerData(const SdfLayer &layer)
Get the internal data for layer.
virtual SDF_API bool _ShouldReadAnonymousLayers() const
File format subclasses may override this to specify whether Read should be called when creating,...
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.
SDF_API const TfToken & GetVersionString() const
Returns the current version of this file format.
std::map< std::string, std::string > FileFormatArguments
Type for specifying additional file format-specific arguments to the various API below.
Definition: fileFormat.h:102
SDF_API const TfToken & GetTarget() const
Returns the target for this file format.
SDF_API SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::string &extension)
Constructor.
SDF_API bool SupportsWriting() const
This is a convenience method for invoking FormatSupportsWriting with this format's extension and targ...
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.
SDF_API const SdfSchemaBase & GetSchema() const
Returns the schema for this format.
SDF_API const std::string & GetFileCookie() const
Returns the cookie to be used when writing files with this format.
static SDF_API void _SetLayerData(SdfLayer *layer, SdfAbstractDataRefPtr &data, SdfLayerHints hints)
Set the internal data for layer to data, possibly transferring ownership of data.
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 bool WriteToStream(const SdfSpecHandle &spec, std::ostream &out, size_t indent) const
Write the provided spec to out indented indent levels.
SDF_API bool _ReadAndCopyLayerDataToMemory(SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly, bool *didCopyData=nullptr) const
Helper function for _ReadDetached.
SDF_API bool ShouldReadAnonymousLayers() const
Returns true if anonymous layer identifiers should be passed to Read when a layer is opened or reload...
SDF_API bool SupportsReading() const
Returns true if this file format supports reading.
virtual SDF_API bool IsPackage() const
Returns true if this file format is a package containing other assets.
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 ~SdfFileFormat()
Destructor.
static SDF_API SdfFileFormatConstPtr FindById(const TfToken &formatId)
Returns the file format instance with the specified formatId identifier.
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::vector< std::string > &extensions, const SdfSchemaBase &&schema)=delete
Disallow temporary SdfSchemaBase objects being passed to the c'tor.
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.
virtual SDF_API SdfAbstractDataRefPtr InitData(const FileFormatArguments &args) const
This method allows the file format to bind to whatever data container is appropriate.
virtual SDF_API FileFormatArguments GetDefaultFileFormatArguments() const
Returns the FileFormatArguments that correspond to the default behavior of this file format when no F...
SDF_API bool SupportsEditing() const
This is a convenience method for invoking FormatSupportsEditing with this format's extension and targ...
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.
static SDF_API void _SetLayerData(SdfLayer *layer, SdfAbstractDataRefPtr &data)
Set the internal data for layer to data, possibly transferring ownership of data.
virtual SDF_API bool _ReadDetached(SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly) const
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 fr...
virtual SDF_API SdfAbstractDataRefPtr _InitDetachedData(const FileFormatArguments &args) const
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 std::string GetFileExtension(const std::string &s)
Returns the file extension for path or file name s, without the leading dot character.
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 const TfToken & GetFormatId() const
Returns the format identifier.
SDF_API const std::vector< std::string > & GetFileExtensions() const
Returns a list of extensions that this format supports.
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.
SDF_API const std::string & GetPrimaryFileExtension() const
Returns the primary file extension for this format.
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 t...
SDF_API bool IsPrimaryFormatForExtensions() const
Returns true if this file format is the primary format for the extensions it handles.
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.
SDF_API SdfAbstractDataRefPtr InitDetachedData(const FileFormatArguments &args) const
Returns a new SdfAbstractData providing access to the layer's data.
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.
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 ...
SDF_API bool IsSupportedExtension(const std::string &extension) const
Returns true if extension matches one of the extensions returned by GetFileExtensions.
SDF_API bool ShouldSkipAnonymousReload() const
Return true if this file format prefers to skip reloading anonymous layers.
SDF_API SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::vector< std::string > &extensions, const SdfSchemaBase &schema)
Constructor.
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.
SDF_API SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::vector< std::string > &extensions)
Constructor.
virtual SDF_API bool CanRead(const std::string &file) const =0
Returns true if file can be read by this format.
Contains hints about layer contents that may be used to accelerate certain composition operations.
Definition: layerHints.h:17
A scene description container that can combine with other such containers to form simple component as...
Definition: layer.h:84
Generic class that provides information about scene description fields but doesn't actually provide a...
Definition: schema.h:45
Base class for all Sdf spec classes.
Definition: spec.h:33
Enable a concrete base class for use with TfRefPtr.
Definition: refBase.h:56
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
Base class of all factory types.
Definition: type.h:56
TfType represents a dynamic runtime type.
Definition: type.h:48
static TfType const & Define()
Define a TfType with the given C++ type T and C++ base types B.
A type-list of C++ base types.
Definition: type.h:83
Enable a concrete base class for use with TfWeakPtr.
Definition: weakBase.h:124
Standard pointer typedefs.
#define TF_DECLARE_WEAK_AND_REF_PTRS(type)
Define standard weak, ref, and vector pointer types.
Definition: declarePtrs.h:72
This file defines some macros that are useful for declaring and using static TfTokens.
#define TF_DECLARE_PUBLIC_TOKENS(...)
Macro to define public tokens.
Definition: staticTokens.h:81
TfToken class for efficient string referencing and hashing, plus conversions to and from stl string c...