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