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 SDF_FILE_FORMAT_H
25 #define SDF_FILE_FORMAT_H
26 
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/sdf/api.h"
31 #include "pxr/usd/sdf/declareHandles.h"
32 #include "pxr/base/tf/declarePtrs.h"
33 #include "pxr/base/tf/refBase.h"
34 #include "pxr/base/tf/staticTokens.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 <boost/noncopyable.hpp>
40 #include <map>
41 #include <string>
42 #include <vector>
43 
44 PXR_NAMESPACE_OPEN_SCOPE
45 
46 class ArAssetInfo;
47 class SdfSchemaBase;
48 
49 SDF_DECLARE_HANDLES(SdfLayer);
50 SDF_DECLARE_HANDLES(SdfSpec);
53 
54 #define SDF_FILE_FORMAT_TOKENS \
55  ((TargetArg, "target"))
56 
57 TF_DECLARE_PUBLIC_TOKENS(SdfFileFormatTokens, SDF_API, SDF_FILE_FORMAT_TOKENS);
58 
63 class SdfFileFormat : public TfRefBase, public TfWeakBase, boost::noncopyable
64 {
65 public:
67  SDF_API const SdfSchemaBase& GetSchema() const;
68 
70  SDF_API const TfToken& GetFormatId() const;
71 
73  SDF_API const TfToken& GetTarget() const;
74 
76  SDF_API const std::string& GetFileCookie() const;
77 
79  SDF_API const TfToken& GetVersionString() const;
80 
83  SDF_API bool IsPrimaryFormatForExtensions() const;
84 
86  SDF_API const std::vector<std::string>& GetFileExtensions() const;
87 
90  SDF_API const std::string& GetPrimaryFileExtension() const;
91 
94  SDF_API bool IsSupportedExtension(const std::string& extension) const;
95 
98  SDF_API
99  virtual bool IsPackage() const;
100 
107  SDF_API
108  virtual std::string GetPackageRootLayerPath(
109  const std::string& resolvedPath) const;
110 
113  typedef std::map<std::string, std::string> FileFormatArguments;
114 
118  SDF_API
120 
125  SDF_API
126  virtual SdfAbstractDataRefPtr InitData(const FileFormatArguments& args) const;
127 
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 
138  SDF_API bool ShouldSkipAnonymousReload() const;
139 
154  SDF_API bool LayersAreFileBased() const;
155 
157  SDF_API
158  virtual bool CanRead(
159  const std::string& file) const = 0;
160 
171  SDF_API
172  virtual bool Read(
173  SdfLayer* layer,
174  const std::string& resolvedPath,
175  bool metadataOnly) const = 0;
176 
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 
191  SDF_API
192  virtual bool ReadFromString(
193  SdfLayer* layer,
194  const std::string& str) const;
195 
197  SDF_API
198  virtual bool WriteToStream(
199  const SdfSpecHandle &spec,
200  std::ostream& out,
201  size_t indent) const;
202 
206  SDF_API
207  virtual bool WriteToString(
208  const SdfLayer& layer,
209  std::string* str,
210  const std::string& comment = std::string()) const;
211 
214  SDF_API static std::string GetFileExtension(const std::string& s);
215 
218  SDF_API static std::set<std::string> FindAllFileFormatExtensions();
219 
223  SDF_API
224  static SdfFileFormatConstPtr FindById(
225  const TfToken& formatId);
226 
236  SDF_API
237  static SdfFileFormatConstPtr FindByExtension(
238  const std::string& extension,
239  const std::string& target = std::string());
240 
241 protected:
243  SDF_API SdfFileFormat(
244  const TfToken& formatId,
245  const TfToken& versionString,
246  const TfToken& target,
247  const std::string& extension);
248 
251  SDF_API SdfFileFormat(
252  const TfToken& formatId,
253  const TfToken& versionString,
254  const TfToken& target,
255  const std::string& extension,
256  const SdfSchemaBase& schema);
257 
259  SDF_API SdfFileFormat(
260  const TfToken& formatId,
261  const TfToken& versionString,
262  const TfToken& target,
263  const std::string& extension,
264  const SdfSchemaBase&& schema) = delete;
265 
267  SDF_API SdfFileFormat(
268  const TfToken& formatId,
269  const TfToken& versionString,
270  const TfToken& target,
271  const std::vector<std::string> &extensions);
272 
275  SDF_API SdfFileFormat(
276  const TfToken& formatId,
277  const TfToken& versionString,
278  const TfToken& target,
279  const std::vector<std::string> &extensions,
280  const SdfSchemaBase& schema);
281 
283  SDF_API SdfFileFormat(
284  const TfToken& formatId,
285  const TfToken& versionString,
286  const TfToken& target,
287  const std::vector<std::string> &extensions,
288  const SdfSchemaBase&& schema) = delete;
289 
291  SDF_API virtual ~SdfFileFormat();
292 
293  //
294  // Minimally break layer encapsulation with the following methods. These
295  // methods are also intended to limit the need for SdfLayer friendship with
296  // SdfFileFormat child classes.
297  //
298 
301  SDF_API
302  static void _SetLayerData(
303  SdfLayer* layer, SdfAbstractDataRefPtr& data);
304 
306  SDF_API
307  static SdfAbstractDataConstPtr _GetLayerData(const SdfLayer& layer);
308 
309 private:
310  SDF_API
311  virtual SdfLayer *_InstantiateNewLayer(
312  const SdfFileFormatConstPtr &fileFormat,
313  const std::string &identifier,
314  const std::string &realPath,
315  const ArAssetInfo& assetInfo,
316  const FileFormatArguments &args) const;
317 
318  // File format subclasses may override this if they prefer not to skip
319  // reloading anonymous layers. Default implementation returns true.
320  SDF_API
321  virtual bool _ShouldSkipAnonymousReload() const;
322 
326  SDF_API
327  virtual bool _LayersAreFileBased() const;
328 
329  const SdfSchemaBase& _schema;
330  const TfToken _formatId;
331  const TfToken _target;
332  const std::string _cookie;
333  const TfToken _versionString;
334  const std::vector<std::string> _extensions;
335  const bool _isPrimaryFormat;
336 };
337 
339 class Sdf_FileFormatFactoryBase : public TfType::FactoryBase {
340 public:
341  virtual SdfFileFormatRefPtr New() const = 0;
342 };
343 
345 template <typename T>
346 class Sdf_FileFormatFactory : public Sdf_FileFormatFactoryBase {
347 public:
348  virtual SdfFileFormatRefPtr New() const
349  {
350  return TfCreateRefPtr(new T);
351  }
352 };
353 
357 #define SDF_DEFINE_FILE_FORMAT(c, ...) \
358  TfType::Define<c BOOST_PP_COMMA_IF(TF_NUM_ARGS(__VA_ARGS__)) \
359  BOOST_PP_IF(TF_NUM_ARGS(__VA_ARGS__), \
360  TfType::Bases<__VA_ARGS__>, BOOST_PP_EMPTY) >() \
361  .SetFactory<Sdf_FileFormatFactory<c> >()
362 
366 #define SDF_DEFINE_ABSTRACT_FILE_FORMAT(c, ...) \
367  TfType::Define<c BOOST_PP_COMMA_IF(TF_NUM_ARGS(__VA_ARGS__)) \
368  BOOST_PP_IF(TF_NUM_ARGS(__VA_ARGS__), \
369  TfType::Bases<__VA_ARGS__>, BOOST_PP_EMPTY) >();
370 
371 #define SDF_FILE_FORMAT_FACTORY_ACCESS \
372  template<typename T> friend class Sdf_FileFormatFactory
373 
374 PXR_NAMESPACE_CLOSE_SCOPE
375 
376 #endif // SDF_FILE_FORMAT_H
virtual SDF_API FileFormatArguments GetDefaultFileFormatArguments() const
Returns the FileFormatArguments that correspond to the default behavior of this file format when no F...
A unit of scene description that you combine with other units of scene description to form a shot...
Definition: layer.h:93
SDF_API bool IsSupportedExtension(const std::string &extension) const
Returns true if extension matches one of the extensions returned by GetFileExtensions.
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 LayersAreFileBased() const
Return true if layers produced by this file format are based on physical files on disk...
SDF_API const std::vector< std::string > & GetFileExtensions() const
Returns a list of extensions that this format supports.
static SDF_API std::set< std::string > FindAllFileFormatExtensions()
Returns a set containing the extension(s) corresponding to all registered file formats.
virtual SDF_API bool CanRead(const std::string &file) const =0
Returns true if file can be read by this format.
Generic class that provides information about scene description fields but doesn&#39;t actually provide a...
Definition: schema.h:62
Base class for all Sdf spec classes.
Definition: spec.h:51
SDF_API const TfToken & GetTarget() const
Returns the target for this file format.
#define TF_DECLARE_WEAK_AND_REF_PTRS(type)
Define standard weak, ref, and vector pointer types.
Definition: declarePtrs.h:89
static SDF_API SdfFileFormatConstPtr FindByExtension(const std::string &extension, const std::string &target=std::string())
Returns the file format instance that supports the specified file extension.
SDF_API bool IsPrimaryFormatForExtensions() const
Returns true if this file format is the primary format for the extensions it handles.
Base class of all factory types.
Definition: type.h:79
Enable a concrete base class for use with TfRefPtr.
Definition: refBase.h:72
SDF_API const TfToken & GetVersionString() const
Returns the current version of this file format.
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:89
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 SdfFileFormatConstPtr FindById(const TfToken &formatId)
Returns the file format instance with the specified formatId identifier.
virtual SDF_API bool IsPackage() const
Returns true if this file format is a package containing other assets.
virtual SDF_API std::string GetPackageRootLayerPath(const std::string &resolvedPath) const
Returns the path of the &quot;root&quot; layer contained in the package layer at resolvedPath produced by this ...
#define TF_DECLARE_PUBLIC_TOKENS(...)
Macro to define public tokens.
Definition: staticTokens.h:118
SDF_API const SdfSchemaBase & GetSchema() const
Returns the schema for this format.
virtual SDF_API ~SdfFileFormat()
Destructor.
std::map< std::string, std::string > FileFormatArguments
Type for specifying additional file format-specific arguments to the various API below.
Definition: fileFormat.h:113
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.
SDF_API bool ShouldSkipAnonymousReload() const
Return true if this file format prefers to skip reloading anonymous layers.
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)
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.
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 bool WriteToStream(const SdfSpecHandle &spec, std::ostream &out, size_t indent) const
Write the provided spec to out indented indent levels.
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.
static SDF_API SdfAbstractDataConstPtr _GetLayerData(const SdfLayer &layer)
Get the internal data for layer.
SDF_API SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::string &extension)
Constructor.
SDF_API const std::string & GetPrimaryFileExtension() const
Returns the primary file extension for this format.
Base class for file format implementations.
Definition: fileFormat.h:63
SDF_API const TfToken & GetFormatId() const
Returns the format identifier.
Enable a concrete base class for use with TfWeakPtr.
Definition: weakBase.h:142
Interface for scene description data storage.
Definition: abstractData.h:73
Contains information about a resolved asset.
Definition: assetInfo.h:40