HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 
27 /// \file sdf/fileFormat.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/sdf/api.h"
33 #include "pxr/base/tf/refBase.h"
35 #include "pxr/base/tf/token.h"
36 #include "pxr/base/tf/type.h"
37 #include "pxr/base/tf/weakBase.h"
38 
39 #include <hboost/noncopyable.hpp>
40 #include <map>
41 #include <string>
42 #include <vector>
43 
45 
46 class ArAssetInfo;
47 class SdfSchemaBase;
48 
53 
54 #define SDF_FILE_FORMAT_TOKENS \
55  ((TargetArg, "target"))
56 
58 
59 /// \class SdfFileFormat
60 ///
61 /// Base class for file format implementations.
62 ///
63 class SdfFileFormat : public TfRefBase, public TfWeakBase, hboost::noncopyable
64 {
65 public:
66  /// Returns the schema for this format.
67  SDF_API const SdfSchemaBase& GetSchema() const;
68 
69  /// Returns the format identifier.
70  SDF_API const TfToken& GetFormatId() const;
71 
72  /// Returns the target for this file format.
73  SDF_API const TfToken& GetTarget() const;
74 
75  /// Returns the cookie to be used when writing files with this format.
76  SDF_API const std::string& GetFileCookie() const;
77 
78  /// Returns the current version of this file format.
79  SDF_API const TfToken& GetVersionString() const;
80 
81  /// Returns true if this file format is the primary format for the
82  /// extensions it handles.
84 
85  /// Returns a list of extensions that this format supports.
86  SDF_API const std::vector<std::string>& GetFileExtensions() const;
87 
88  /// Returns the primary file extension for this format. This is the
89  /// extension that is reported for layers using this file format.
91 
92  /// Returns true if \p extension matches one of the extensions returned by
93  /// GetFileExtensions.
95 
96  /// Returns true if this file format is a package containing other
97  /// assets.
98  SDF_API
99  virtual bool IsPackage() const;
100 
101  /// Returns the path of the "root" layer contained in the package
102  /// layer at \p resolvedPath produced by this file format. If this
103  /// file format is not a package, returns the empty string.
104  ///
105  /// The package root layer is the layer in the package layer that
106  /// is used when that package is opened via SdfLayer.
107  SDF_API
109  const std::string& resolvedPath) const;
110 
111  /// Type for specifying additional file format-specific arguments
112  /// to the various API below.
113  typedef std::map<std::string, std::string> FileFormatArguments;
114 
115  /// Returns the FileFormatArguments that correspond to the default behavior
116  /// of this file format when no FileFormatArguments are passed to NewLayer
117  /// or InitData.
118  SDF_API
120 
121  /// This method allows the file format to bind to whatever data container is
122  /// appropriate.
123  ///
124  /// Returns a shared pointer to an SdfAbstractData implementation.
125  SDF_API
126  virtual SdfAbstractDataRefPtr InitData(const FileFormatArguments& args) const;
127 
128  /// Instantiate a layer.
129  SDF_API
130  SdfLayerRefPtr NewLayer(const SdfFileFormatConstPtr &fileFormat,
131  const std::string &identifier,
132  const std::string &realPath,
133  const ArAssetInfo& assetInfo,
134  const FileFormatArguments &args) const;
135 
136  /// Return true if this file format prefers to skip reloading anonymous
137  /// layers.
138  SDF_API bool ShouldSkipAnonymousReload() const;
139 
140  /// Return true if layers produced by this file format are based
141  /// on physical files on disk. If so, this file format requires
142  /// layers to be serialized to and read from files on disk.
143  ///
144  /// For file formats where this function returns true, when
145  /// opening a layer Sdf will fetch layers to the filesystem
146  /// via calls to ArResolver::FetchToLocalResolvedPath prior
147  /// to calling ReadFromFile.
148  ///
149  /// This allows asset systems that do not store layers as individual
150  /// files to operate with file formats that require these files.
151  ///
152  /// \sa ArResolver::Resolve
153  /// \sa ArResolver::FetchToLocalResolvedPath
154  SDF_API bool LayersAreFileBased() const;
155 
156  /// Returns true if \p file can be read by this format.
157  SDF_API
158  virtual bool CanRead(
159  const std::string& file) const = 0;
160 
161  /// Reads scene description from the asset specified by \p resolvedPath
162  /// into the layer \p layer.
163  ///
164  /// \p metadataOnly is a flag that asks for only the layer metadata
165  /// to be read in, which can be much faster if that is all that is
166  /// required. Note that this is just a hint: some FileFormat readers
167  /// may disregard this flag and still fully populate the layer contents.
168  ///
169  /// Returns true if the asset is successfully read into \p layer,
170  /// false otherwise.
171  SDF_API
172  virtual bool Read(
173  SdfLayer* layer,
174  const std::string& resolvedPath,
175  bool metadataOnly) const = 0;
176 
177  /// Writes the content in \p layer into the file at \p filePath. If the
178  /// content is successfully written, this method returns true. Otherwise,
179  /// false is returned and errors are posted. The default implementation
180  /// returns false.
181  SDF_API
182  virtual bool WriteToFile(
183  const SdfLayer& layer,
184  const std::string& filePath,
185  const std::string& comment = std::string(),
186  const FileFormatArguments& args = FileFormatArguments()) const;
187 
188  /// Reads data in the string \p str into the layer \p layer. If
189  /// the file is successfully read, this method returns true. Otherwise,
190  /// false is returned and errors are posted.
191  SDF_API
192  virtual bool ReadFromString(
193  SdfLayer* layer,
194  const std::string& str) const;
195 
196  /// Write the provided \p spec to \p out indented \p indent levels.
197  SDF_API
198  virtual bool WriteToStream(
199  const SdfSpecHandle &spec,
200  std::ostream& out,
201  size_t indent) const;
202 
203  /// Writes the content in \p layer to the string \p str. This function
204  /// should write a textual representation of \p layer to the stream
205  /// that can be read back in via ReadFromString.
206  SDF_API
207  virtual bool WriteToString(
208  const SdfLayer& layer,
209  std::string* str,
210  const std::string& comment = std::string()) const;
211 
212  /// Returns the file extension for path or file name \p s, without the
213  /// leading dot character.
215 
216  /// Returns a set containing the extension(s) corresponding to
217  /// all registered file formats.
218  SDF_API static std::set<std::string> FindAllFileFormatExtensions();
219 
220  /// Returns the file format instance with the specified \p formatId
221  /// identifier. If a format with a matching identifier is not found, this
222  /// returns a null file format pointer.
223  SDF_API
224  static SdfFileFormatConstPtr FindById(
225  const TfToken& formatId);
226 
227  /// Returns the file format instance that supports the extension for
228  /// \p path. If a format with a matching extension is not found, this
229  /// returns a null file format pointer.
230  ///
231  /// An extension may be handled by multiple file formats, but each
232  /// with a different target. In such cases, if no \p target is specified,
233  /// the file format that is registered as the primary plugin will be
234  /// returned. Otherwise, the file format whose target matches \p target
235  /// will be returned.
236  SDF_API
237  static SdfFileFormatConstPtr FindByExtension(
238  const std::string& path,
239  const std::string& target = std::string());
240 
241  /// Returns a file format instance that supports the extension for \p
242  /// path and whose target matches one of those specified by the given
243  /// \p args. If the \p args specify no target, then the file format that is
244  /// registered as the primary plugin will be returned. If a format with a
245  /// matching extension is not found, this returns a null file format
246  /// pointer.
247  SDF_API
248  static SdfFileFormatConstPtr FindByExtension(
249  const std::string& path,
250  const FileFormatArguments& args);
251 
252 protected:
253  /// Constructor.
255  const TfToken& formatId,
256  const TfToken& versionString,
257  const TfToken& target,
258  const std::string& extension);
259 
260  /// Constructor.
261  /// \p schema must remain valid for the lifetime of this file format.
263  const TfToken& formatId,
264  const TfToken& versionString,
265  const TfToken& target,
266  const std::string& extension,
267  const SdfSchemaBase& schema);
268 
269  /// Disallow temporary SdfSchemaBase objects being passed to the c'tor.
271  const TfToken& formatId,
272  const TfToken& versionString,
273  const TfToken& target,
274  const std::string& extension,
275  const SdfSchemaBase&& schema) = delete;
276 
277  /// Constructor.
279  const TfToken& formatId,
280  const TfToken& versionString,
281  const TfToken& target,
282  const std::vector<std::string> &extensions);
283 
284  /// Constructor.
285  /// \p schema must remain valid for the lifetime of this file format.
287  const TfToken& formatId,
288  const TfToken& versionString,
289  const TfToken& target,
290  const std::vector<std::string> &extensions,
291  const SdfSchemaBase& schema);
292 
293  /// Disallow temporary SdfSchemaBase objects being passed to the c'tor.
295  const TfToken& formatId,
296  const TfToken& versionString,
297  const TfToken& target,
298  const std::vector<std::string> &extensions,
299  const SdfSchemaBase&& schema) = delete;
300 
301  /// Destructor.
302  SDF_API virtual ~SdfFileFormat();
303 
304  //
305  // Minimally break layer encapsulation with the following methods. These
306  // methods are also intended to limit the need for SdfLayer friendship with
307  // SdfFileFormat child classes.
308  //
309 
310  /// Set the internal data for \p layer to \p data, possibly transferring
311  /// ownership of \p data.
312  SDF_API
313  static void _SetLayerData(
314  SdfLayer* layer, SdfAbstractDataRefPtr& data);
315 
316  /// Get the internal data for \p layer.
317  SDF_API
318  static SdfAbstractDataConstPtr _GetLayerData(const SdfLayer& layer);
319 
320 private:
321  SDF_API
322  virtual SdfLayer *_InstantiateNewLayer(
323  const SdfFileFormatConstPtr &fileFormat,
324  const std::string &identifier,
325  const std::string &realPath,
326  const ArAssetInfo& assetInfo,
327  const FileFormatArguments &args) const;
328 
329  // File format subclasses may override this if they prefer not to skip
330  // reloading anonymous layers. Default implementation returns true.
331  SDF_API
332  virtual bool _ShouldSkipAnonymousReload() const;
333 
334  /// File format subclasses may override this to specify whether
335  /// their layers are backed by physical files on disk.
336  /// Default implementation returns true.
337  SDF_API
338  virtual bool _LayersAreFileBased() const;
339 
340  const SdfSchemaBase& _schema;
341  const TfToken _formatId;
342  const TfToken _target;
343  const std::string _cookie;
344  const TfToken _versionString;
345  const std::vector<std::string> _extensions;
346  const bool _isPrimaryFormat;
347 };
348 
349 /// Base file format factory.
351 public:
352  virtual SdfFileFormatRefPtr New() const = 0;
353 };
354 
355 /// Default file format factory.
356 template <typename T>
358 public:
359  virtual SdfFileFormatRefPtr New() const
360  {
361  return TfCreateRefPtr(new T);
362  }
363 };
364 
365 /// Defines a file format and factory. This macro is intended for use in a
366 /// TfType registry function block. It defines a type for the first argument,
367 /// with optional bases as additional arguments, and adds a factory.
368 #define SDF_DEFINE_FILE_FORMAT(c, ...) \
369  TfType::Define<c HBOOST_PP_COMMA_IF(TF_NUM_ARGS(__VA_ARGS__)) \
370  HBOOST_PP_IF(TF_NUM_ARGS(__VA_ARGS__), \
371  TfType::Bases<__VA_ARGS__>, HBOOST_PP_EMPTY) >() \
372  .SetFactory<Sdf_FileFormatFactory<c> >()
373 
374 /// Defines a file format without a factory. This macro is intended for use in
375 /// a TfType registry function block. It defines a type for the first
376 /// argument, with optional bases as additional arguments.
377 #define SDF_DEFINE_ABSTRACT_FILE_FORMAT(c, ...) \
378  TfType::Define<c HBOOST_PP_COMMA_IF(TF_NUM_ARGS(__VA_ARGS__)) \
379  HBOOST_PP_IF(TF_NUM_ARGS(__VA_ARGS__), \
380  TfType::Bases<__VA_ARGS__>, HBOOST_PP_EMPTY) >();
381 
382 #define SDF_FILE_FORMAT_FACTORY_ACCESS \
383  template<typename T> friend class Sdf_FileFormatFactory
384 
386 
387 #endif // PXR_USD_SDF_FILE_FORMAT_H
GLdouble s
Definition: glew.h:1390
Base file format factory.
Definition: fileFormat.h:350
TfRefPtr< T > TfCreateRefPtr(T *ptr)
Definition: refPtr.h:1248
SDF_API bool LayersAreFileBased() const
Definition: layer.h:93
static SDF_API SdfFileFormatConstPtr FindByExtension(const std::string &path, const std::string &target=std::string())
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.
TF_DECLARE_PUBLIC_TOKENS(SdfFileFormatTokens, SDF_API, SDF_FILE_FORMAT_TOKENS)
SDF_API bool IsPrimaryFormatForExtensions() const
const Args & args
Definition: printf.h:628
GLenum target
Definition: glew.h:2865
virtual SDF_API bool WriteToFile(const SdfLayer &layer, const std::string &filePath, const std::string &comment=std::string(), const FileFormatArguments &args=FileFormatArguments()) const
Definition: spec.h:51
SDF_API const TfToken & GetFormatId() const
Returns the format identifier.
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 ~SdfFileFormat()
Destructor.
static SDF_API SdfAbstractDataConstPtr _GetLayerData(const SdfLayer &layer)
Get the internal data for 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.
Base class of all factory types.
Definition: type.h:73
Definition: token.h:87
virtual SdfFileFormatRefPtr New() const =0
OIIO_API std::string extension(const std::string &filepath, bool include_dot=true)
static SDF_API SdfFileFormatConstPtr FindById(const TfToken &formatId)
GLint GLenum GLsizei GLint GLsizei const void * data
Definition: glew.h:1379
SDF_API const std::vector< std::string > & GetFileExtensions() const
Returns a list of extensions that this format supports.
SDF_API bool ShouldSkipAnonymousReload() const
SDF_API const SdfSchemaBase & GetSchema() const
Returns the schema for this format.
SDF_API const std::string & GetPrimaryFileExtension() const
virtual SdfFileFormatRefPtr New() const
Definition: fileFormat.h:359
SDF_DECLARE_HANDLES(SdfLayer)
SDF_API bool IsSupportedExtension(const std::string &extension) const
SDF_API const TfToken & GetTarget() const
Returns the target for this file format.
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 IsPackage() const
GLsizei const GLchar *const * path
Definition: glew.h:6461
#define SDF_API
Definition: api.h:40
virtual SDF_API bool Read(SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly) const =0
GLsizei const GLchar *const * string
Definition: glew.h:1844
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
virtual SDF_API SdfAbstractDataRefPtr InitData(const FileFormatArguments &args) const
static SDF_API std::set< std::string > FindAllFileFormatExtensions()
Default file format factory.
Definition: fileFormat.h:357
GLint GLboolean GLint layer
Definition: glew.h:3601
TF_DECLARE_WEAK_AND_REF_PTRS(SdfAbstractData)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
virtual SDF_API std::string GetPackageRootLayerPath(const std::string &resolvedPath) const
virtual SDF_API bool WriteToString(const SdfLayer &layer, std::string *str, const std::string &comment=std::string()) const
static SDF_API std::string GetFileExtension(const std::string &s)
virtual SDF_API bool ReadFromString(SdfLayer *layer, const std::string &str) const
#define SDF_FILE_FORMAT_TOKENS
Definition: fileFormat.h:54
static SDF_API void _SetLayerData(SdfLayer *layer, SdfAbstractDataRefPtr &data)
virtual SDF_API FileFormatArguments GetDefaultFileFormatArguments() const
std::map< std::string, std::string > FileFormatArguments
Definition: fileFormat.h:113
SDF_API SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::string &extension)
Constructor.