fileFormat.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_SDF_FILE_FORMAT_H
25 #define PXR_USD_SDF_FILE_FORMAT_H
26 
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/ar/ar.h"
31 #include "pxr/usd/sdf/api.h"
34 #include "pxr/base/tf/refBase.h"
36 #include "pxr/base/tf/token.h"
37 #include "pxr/base/tf/type.h"
38 #include "pxr/base/tf/weakBase.h"
39 
40 #include <map>
41 #include <string>
42 #include <vector>
43 
44 PXR_NAMESPACE_OPEN_SCOPE
45 
46 class ArAssetInfo;
47 class SdfSchemaBase;
48 class SdfLayerHints;
49 
50 SDF_DECLARE_HANDLES(SdfLayer);
51 SDF_DECLARE_HANDLES(SdfSpec);
54 
55 #define SDF_FILE_FORMAT_TOKENS \
56  ((TargetArg, "target"))
57 
58 TF_DECLARE_PUBLIC_TOKENS(SdfFileFormatTokens, SDF_API, SDF_FILE_FORMAT_TOKENS);
59 
65  : public TfRefBase
66  , public TfWeakBase
67 {
68 public:
69  SdfFileFormat(const SdfFileFormat&) = delete;
70  SdfFileFormat& operator=(const SdfFileFormat&) = delete;
71 
73  SDF_API const SdfSchemaBase& GetSchema() const;
74 
76  SDF_API const TfToken& GetFormatId() const;
77 
79  SDF_API const TfToken& GetTarget() const;
80 
82  SDF_API const std::string& GetFileCookie() const;
83 
85  SDF_API const TfToken& GetVersionString() const;
86 
89  SDF_API bool IsPrimaryFormatForExtensions() const;
90 
92  SDF_API const std::vector<std::string>& GetFileExtensions() const;
93 
96  SDF_API const std::string& GetPrimaryFileExtension() const;
97 
100  SDF_API bool IsSupportedExtension(const std::string& extension) const;
101 
104  SDF_API
105  virtual bool IsPackage() const;
106 
113  SDF_API
114  virtual std::string GetPackageRootLayerPath(
115  const std::string& resolvedPath) const;
116 
119  typedef std::map<std::string, std::string> FileFormatArguments;
120 
124  SDF_API
126 
131  SDF_API
132  virtual SdfAbstractDataRefPtr
133  InitData(const FileFormatArguments& args) const;
134 
137  SDF_API
138  SdfAbstractDataRefPtr InitDetachedData(
139  const FileFormatArguments& args) const;
140 
142  SDF_API
143  SdfLayerRefPtr NewLayer(const SdfFileFormatConstPtr &fileFormat,
144  const std::string &identifier,
145  const std::string &realPath,
146  const ArAssetInfo& assetInfo,
147  const FileFormatArguments &args) const;
148 
151  SDF_API bool ShouldSkipAnonymousReload() const;
152 
165  SDF_API bool ShouldReadAnonymousLayers() const;
166 
168  SDF_API
169  virtual bool CanRead(
170  const std::string& file) const = 0;
171 
182  SDF_API
183  virtual bool Read(
184  SdfLayer* layer,
185  const std::string& resolvedPath,
186  bool metadataOnly) const = 0;
187 
200  SDF_API
201  bool ReadDetached(
202  SdfLayer* layer,
203  const std::string& resolvedPath,
204  bool metadataOnly) const;
205 
210  SDF_API
211  virtual bool WriteToFile(
212  const SdfLayer& layer,
213  const std::string& filePath,
214  const std::string& comment = std::string(),
215  const FileFormatArguments& args = FileFormatArguments()) const;
216 
220  SDF_API
221  virtual bool ReadFromString(
222  SdfLayer* layer,
223  const std::string& str) const;
224 
226  SDF_API
227  virtual bool WriteToStream(
228  const SdfSpecHandle &spec,
229  std::ostream& out,
230  size_t indent) const;
231 
235  SDF_API
236  virtual bool WriteToString(
237  const SdfLayer& layer,
238  std::string* str,
239  const std::string& comment = std::string()) const;
240 
253  SDF_API
254  virtual std::set<std::string> GetExternalAssetDependencies(
255  const SdfLayer& layer) const;
256 
259  SDF_API static std::string GetFileExtension(const std::string& s);
260 
263  SDF_API static std::set<std::string> FindAllFileFormatExtensions();
264 
268  SDF_API
269  static SdfFileFormatConstPtr FindById(
270  const TfToken& formatId);
271 
281  SDF_API
282  static SdfFileFormatConstPtr FindByExtension(
283  const std::string& path,
284  const std::string& target = std::string());
285 
292  SDF_API
293  static SdfFileFormatConstPtr FindByExtension(
294  const std::string& path,
295  const FileFormatArguments& args);
296 
297 protected:
299  SDF_API SdfFileFormat(
300  const TfToken& formatId,
301  const TfToken& versionString,
302  const TfToken& target,
303  const std::string& extension);
304 
307  SDF_API SdfFileFormat(
308  const TfToken& formatId,
309  const TfToken& versionString,
310  const TfToken& target,
311  const std::string& extension,
312  const SdfSchemaBase& schema);
313 
316  const TfToken& formatId,
317  const TfToken& versionString,
318  const TfToken& target,
319  const std::string& extension,
320  const SdfSchemaBase&& schema) = delete;
321 
323  SDF_API SdfFileFormat(
324  const TfToken& formatId,
325  const TfToken& versionString,
326  const TfToken& target,
327  const std::vector<std::string> &extensions);
328 
331  SDF_API SdfFileFormat(
332  const TfToken& formatId,
333  const TfToken& versionString,
334  const TfToken& target,
335  const std::vector<std::string> &extensions,
336  const SdfSchemaBase& schema);
337 
340  const TfToken& formatId,
341  const TfToken& versionString,
342  const TfToken& target,
343  const std::vector<std::string> &extensions,
344  const SdfSchemaBase&& schema) = delete;
345 
347  SDF_API virtual ~SdfFileFormat();
348 
349  //
350  // Minimally break layer encapsulation with the following methods. These
351  // methods are also intended to limit the need for SdfLayer friendship with
352  // SdfFileFormat child classes.
353  //
354 
359  SDF_API
360  static void _SetLayerData(
361  SdfLayer* layer, SdfAbstractDataRefPtr& data);
362 
367  SDF_API
368  static void _SetLayerData(
369  SdfLayer* layer, SdfAbstractDataRefPtr& data,
370  SdfLayerHints hints);
371 
373  SDF_API
374  static SdfAbstractDataConstPtr _GetLayerData(const SdfLayer& layer);
375 
390  SDF_API
392  SdfLayer* layer,
393  const std::string& resolvedPath,
394  bool metadataOnly,
395  bool* didCopyData = nullptr) const;
396 
397 protected:
398  SDF_API
399  virtual SdfLayer *_InstantiateNewLayer(
400  const SdfFileFormatConstPtr &fileFormat,
401  const std::string &identifier,
402  const std::string &realPath,
403  const ArAssetInfo& assetInfo,
404  const FileFormatArguments &args) const;
405 
406  // File format subclasses may override this if they prefer not to skip
407  // reloading anonymous layers. Default implementation returns true.
408  SDF_API
409  virtual bool _ShouldSkipAnonymousReload() const;
410 
415  SDF_API
416  virtual bool _ShouldReadAnonymousLayers() const;
417 
424  SDF_API
425  virtual SdfAbstractDataRefPtr _InitDetachedData(
426  const FileFormatArguments& args) const;
427 
439  SDF_API
440  virtual bool _ReadDetached(
441  SdfLayer* layer,
442  const std::string& resolvedPath,
443  bool metadataOnly) const;
444 
445 private:
446  const SdfSchemaBase& _schema;
447  const TfToken _formatId;
448  const TfToken _target;
449  const std::string _cookie;
450  const TfToken _versionString;
451  const std::vector<std::string> _extensions;
452  const bool _isPrimaryFormat;
453 };
454 
455 // Base file format factory.
456 class Sdf_FileFormatFactoryBase : public TfType::FactoryBase {
457 public:
458  SDF_API virtual ~Sdf_FileFormatFactoryBase();
459  virtual SdfFileFormatRefPtr New() const = 0;
460 };
461 
462 // Default file format factory.
463 template <typename T>
464 class Sdf_FileFormatFactory : public Sdf_FileFormatFactoryBase {
465 public:
466  virtual SdfFileFormatRefPtr New() const
467  {
468  return TfCreateRefPtr(new T);
469  }
470 };
471 
493 #ifdef doxygen
494 #define SDF_DEFINE_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
495 #else
496 #define SDF_DEFINE_FILE_FORMAT(...) SdfDefineFileFormat<__VA_ARGS__>()
497 
498 template <class FileFormat, class ...BaseFormats>
499 void SdfDefineFileFormat()
500 {
501  TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>()
502  .template SetFactory<Sdf_FileFormatFactory<FileFormat>>();
503 }
504 #endif // doxygen
505 
527 #ifdef doxygen
528 #define SDF_DEFINE_ABSTRACT_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
529 #else
530 #define SDF_DEFINE_ABSTRACT_FILE_FORMAT(...) \
531  SdfDefineAbstractFileFormat<__VA_ARGS__>()
532 
533 template <class FileFormat, class ...BaseFormats>
534 void SdfDefineAbstractFileFormat()
535 {
536  TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>();
537 }
538 #endif //doxygen
539 
557 #ifdef doxygen
558 #define SDF_FILE_FORMAT_FACTORY_ACCESS
559 #else
560 #define SDF_FILE_FORMAT_FACTORY_ACCESS \
561  template<typename T> friend class Sdf_FileFormatFactory
562 #endif //doxygen
563 
564 PXR_NAMESPACE_CLOSE_SCOPE
565 
566 #endif
SDF_API const TfToken & GetTarget() const
Returns the target for this file format.
virtual SDF_API SdfAbstractDataRefPtr _InitDetachedData(const FileFormatArguments &args) const
A scene description container that can combine with other such containers to form simple component as...
Definition: layer.h:94
static SDF_API std::set< std::string > FindAllFileFormatExtensions()
Returns a set containing the extension(s) corresponding to all registered file formats.
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 ...
Standard pointer typedefs.
virtual SDF_API bool CanRead(const std::string &file) const =0
Returns true if file can be read by this format.
SDF_API SdfAbstractDataRefPtr InitDetachedData(const FileFormatArguments &args) const
Returns a new SdfAbstractData providing access to the layer's data.
virtual SDF_API bool _ReadDetached(SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly) const
SDF_API const std::vector< std::string > & GetFileExtensions() const
Returns a list of extensions that this format supports.
SDF_API bool IsPrimaryFormatForExtensions() const
Returns true if this file format is the primary format for the extensions it handles.
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.
Generic class that provides information about scene description fields but doesn't actually provide a...
Definition: schema.h:62
Base class for all Sdf spec classes.
Definition: spec.h:51
SDF_API const TfToken & GetFormatId() const
Returns the format identifier.
#define TF_DECLARE_WEAK_AND_REF_PTRS(type)
Define standard weak, ref, and vector pointer types.
Definition: declarePtrs.h:89
virtual SDF_API bool WriteToStream(const SdfSpecHandle &spec, std::ostream &out, size_t indent) const
Write the provided spec to out indented indent levels.
Base class of all factory types.
Definition: type.h:73
Enable a concrete base class for use with TfRefPtr.
Definition: refBase.h:71
SDF_API const std::string & GetPrimaryFileExtension() const
Returns the primary file extension for this format.
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
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.
virtual SDF_API bool IsPackage() const
Returns true if this file format is a package containing other assets.
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 FindById(const TfToken &formatId)
Returns the file format instance with the specified formatId identifier.
SDF_API bool IsSupportedExtension(const std::string &extension) const
Returns true if extension matches one of the extensions returned by GetFileExtensions.
#define TF_DECLARE_PUBLIC_TOKENS(...)
Macro to define public tokens.
Definition: staticTokens.h:118
virtual SDF_API bool _ShouldReadAnonymousLayers() const
File format subclasses may override this to specify whether Read should be called when creating,...
A type-list of C++ base types.
Definition: type.h:100
virtual SDF_API ~SdfFileFormat()
Destructor.
SDF_API bool ShouldSkipAnonymousReload() const
Return true if this file format prefers to skip reloading anonymous layers.
virtual SDF_API FileFormatArguments GetDefaultFileFormatArguments() const
Returns the FileFormatArguments that correspond to the default behavior of this file format when no F...
std::map< std::string, std::string > FileFormatArguments
Type for specifying additional file format-specific arguments to the various API below.
Definition: fileFormat.h:119
static TfType const & Define()
Define a TfType with the given C++ type T and C++ base types B.
Definition: type_Impl.h:90
SDF_API bool ShouldReadAnonymousLayers() const
Returns true if anonymous layer identifiers should be passed to Read when a layer is opened or reload...
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 std::string GetFileExtension(const std::string &s)
Returns the file extension for path or file name s, without the leading dot character.
This file defines some macros that are useful for declaring and using static TfTokens.
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 SdfAbstractDataRefPtr InitData(const FileFormatArguments &args) const
This method allows the file format to bind to whatever data container is appropriate.
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.
SDF_API bool _ReadAndCopyLayerDataToMemory(SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly, bool *didCopyData=nullptr) const
Helper function for _ReadDetached.
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.
Contains hints about layer contents that may be used to accelerate certain composition operations.
Definition: layerHints.h:33
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 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 & GetVersionString() const
Returns the current version of this file format.
SDF_API const std::string & GetFileCookie() const
Returns the cookie to be used when writing files with this format.
static SDF_API SdfAbstractDataConstPtr _GetLayerData(const SdfLayer &layer)
Get the internal data for layer.
Base class for file format implementations.
Definition: fileFormat.h:64
SDF_API const SdfSchemaBase & GetSchema() const
Returns the schema for this format.
Enable a concrete base class for use with TfWeakPtr.
Definition: weakBase.h:141
TfToken class for efficient string referencing and hashing, plus conversions to and from stl string c...
Interface for scene description data storage.
Definition: abstractData.h:73
Contains information about a resolved asset.
Definition: assetInfo.h:40