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 
136  SDF_API
137  SdfLayerRefPtr NewLayer(const SdfFileFormatConstPtr &fileFormat,
138  const std::string &identifier,
139  const std::string &realPath,
140  const ArAssetInfo& assetInfo,
141  const FileFormatArguments &args) const;
142 
145  SDF_API bool ShouldSkipAnonymousReload() const;
146 
147 #if AR_VERSION == 1
148  SDF_API bool LayersAreFileBased() const;
163 #endif
164 
177  SDF_API bool ShouldReadAnonymousLayers() const;
178 
180  SDF_API
181  virtual bool CanRead(
182  const std::string& file) const = 0;
183 
194  SDF_API
195  virtual bool Read(
196  SdfLayer* layer,
197  const std::string& resolvedPath,
198  bool metadataOnly) const = 0;
199 
204  SDF_API
205  virtual bool WriteToFile(
206  const SdfLayer& layer,
207  const std::string& filePath,
208  const std::string& comment = std::string(),
209  const FileFormatArguments& args = FileFormatArguments()) const;
210 
214  SDF_API
215  virtual bool ReadFromString(
216  SdfLayer* layer,
217  const std::string& str) const;
218 
220  SDF_API
221  virtual bool WriteToStream(
222  const SdfSpecHandle &spec,
223  std::ostream& out,
224  size_t indent) const;
225 
229  SDF_API
230  virtual bool WriteToString(
231  const SdfLayer& layer,
232  std::string* str,
233  const std::string& comment = std::string()) const;
234 
247  SDF_API
248  virtual std::set<std::string> GetExternalAssetDependencies(
249  const SdfLayer& layer) const;
250 
253  SDF_API static std::string GetFileExtension(const std::string& s);
254 
257  SDF_API static std::set<std::string> FindAllFileFormatExtensions();
258 
262  SDF_API
263  static SdfFileFormatConstPtr FindById(
264  const TfToken& formatId);
265 
275  SDF_API
276  static SdfFileFormatConstPtr FindByExtension(
277  const std::string& path,
278  const std::string& target = std::string());
279 
286  SDF_API
287  static SdfFileFormatConstPtr FindByExtension(
288  const std::string& path,
289  const FileFormatArguments& args);
290 
291 protected:
293  SDF_API SdfFileFormat(
294  const TfToken& formatId,
295  const TfToken& versionString,
296  const TfToken& target,
297  const std::string& extension);
298 
301  SDF_API SdfFileFormat(
302  const TfToken& formatId,
303  const TfToken& versionString,
304  const TfToken& target,
305  const std::string& extension,
306  const SdfSchemaBase& schema);
307 
310  const TfToken& formatId,
311  const TfToken& versionString,
312  const TfToken& target,
313  const std::string& extension,
314  const SdfSchemaBase&& schema) = delete;
315 
317  SDF_API SdfFileFormat(
318  const TfToken& formatId,
319  const TfToken& versionString,
320  const TfToken& target,
321  const std::vector<std::string> &extensions);
322 
325  SDF_API SdfFileFormat(
326  const TfToken& formatId,
327  const TfToken& versionString,
328  const TfToken& target,
329  const std::vector<std::string> &extensions,
330  const SdfSchemaBase& schema);
331 
334  const TfToken& formatId,
335  const TfToken& versionString,
336  const TfToken& target,
337  const std::vector<std::string> &extensions,
338  const SdfSchemaBase&& schema) = delete;
339 
341  SDF_API virtual ~SdfFileFormat();
342 
343  //
344  // Minimally break layer encapsulation with the following methods. These
345  // methods are also intended to limit the need for SdfLayer friendship with
346  // SdfFileFormat child classes.
347  //
348 
353  SDF_API
354  static void _SetLayerData(
355  SdfLayer* layer, SdfAbstractDataRefPtr& data);
356 
361  SDF_API
362  static void _SetLayerData(
363  SdfLayer* layer, SdfAbstractDataRefPtr& data,
364  SdfLayerHints hints);
365 
367  SDF_API
368  static SdfAbstractDataConstPtr _GetLayerData(const SdfLayer& layer);
369 
370 protected:
371  SDF_API
372  virtual SdfLayer *_InstantiateNewLayer(
373  const SdfFileFormatConstPtr &fileFormat,
374  const std::string &identifier,
375  const std::string &realPath,
376  const ArAssetInfo& assetInfo,
377  const FileFormatArguments &args) const;
378 
379  // File format subclasses may override this if they prefer not to skip
380  // reloading anonymous layers. Default implementation returns true.
381  SDF_API
382  virtual bool _ShouldSkipAnonymousReload() const;
383 
384 #if AR_VERSION == 1
385  SDF_API
389  virtual bool _LayersAreFileBased() const;
390 #endif
391 
396  SDF_API
397  virtual bool _ShouldReadAnonymousLayers() const;
398 
399 private:
400  const SdfSchemaBase& _schema;
401  const TfToken _formatId;
402  const TfToken _target;
403  const std::string _cookie;
404  const TfToken _versionString;
405  const std::vector<std::string> _extensions;
406  const bool _isPrimaryFormat;
407 };
408 
409 // Base file format factory.
410 class Sdf_FileFormatFactoryBase : public TfType::FactoryBase {
411 public:
412  virtual SdfFileFormatRefPtr New() const = 0;
413 };
414 
415 // Default file format factory.
416 template <typename T>
417 class Sdf_FileFormatFactory : public Sdf_FileFormatFactoryBase {
418 public:
419  virtual SdfFileFormatRefPtr New() const
420  {
421  return TfCreateRefPtr(new T);
422  }
423 };
424 
446 #ifdef doxygen
447 #define SDF_DEFINE_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
448 #else
449 #define SDF_DEFINE_FILE_FORMAT(...) SdfDefineFileFormat<__VA_ARGS__>()
450 
451 template <class FileFormat, class ...BaseFormats>
452 void SdfDefineFileFormat()
453 {
454  TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>()
455  .template SetFactory<Sdf_FileFormatFactory<FileFormat>>();
456 }
457 #endif // doxygen
458 
480 #ifdef doxygen
481 #define SDF_DEFINE_ABSTRACT_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
482 #else
483 #define SDF_DEFINE_ABSTRACT_FILE_FORMAT(...) \
484  SdfDefineAbstractFileFormat<__VA_ARGS__>()
485 
486 template <class FileFormat, class ...BaseFormats>
487 void SdfDefineAbstractFileFormat()
488 {
489  TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>();
490 }
491 #endif //doxygen
492 
510 #ifdef doxygen
511 #define SDF_FILE_FORMAT_FACTORY_ACCESS
512 #else
513 #define SDF_FILE_FORMAT_FACTORY_ACCESS \
514  template<typename T> friend class Sdf_FileFormatFactory
515 #endif //doxygen
516 
517 PXR_NAMESPACE_CLOSE_SCOPE
518 
519 #endif
SDF_API const TfToken & GetTarget() const
Returns the target for this file format.
A unit of scene description that you combine with other units of scene description to form a shot,...
Definition: layer.h:96
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 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.
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
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