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 
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 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 
64 class SdfFileFormat : public TfRefBase, public TfWeakBase, boost::noncopyable
65 {
66 public:
68  SDF_API const SdfSchemaBase& GetSchema() const;
69 
71  SDF_API const TfToken& GetFormatId() const;
72 
74  SDF_API const TfToken& GetTarget() const;
75 
77  SDF_API const std::string& GetFileCookie() const;
78 
80  SDF_API const TfToken& GetVersionString() const;
81 
84  SDF_API bool IsPrimaryFormatForExtensions() const;
85 
87  SDF_API const std::vector<std::string>& GetFileExtensions() const;
88 
91  SDF_API const std::string& GetPrimaryFileExtension() const;
92 
95  SDF_API bool IsSupportedExtension(const std::string& extension) const;
96 
99  SDF_API
100  virtual bool IsPackage() const;
101 
108  SDF_API
109  virtual std::string GetPackageRootLayerPath(
110  const std::string& resolvedPath) const;
111 
114  typedef std::map<std::string, std::string> FileFormatArguments;
115 
119  SDF_API
121 
126  SDF_API
127  virtual SdfAbstractDataRefPtr InitData(const FileFormatArguments& args) const;
128 
130  SDF_API
131  SdfLayerRefPtr NewLayer(const SdfFileFormatConstPtr &fileFormat,
132  const std::string &identifier,
133  const std::string &realPath,
134  const ArAssetInfo& assetInfo,
135  const FileFormatArguments &args) const;
136 
139  SDF_API bool ShouldSkipAnonymousReload() const;
140 
155  SDF_API bool LayersAreFileBased() const;
156 
158  SDF_API
159  virtual bool CanRead(
160  const std::string& file) const = 0;
161 
172  SDF_API
173  virtual bool Read(
174  SdfLayer* layer,
175  const std::string& resolvedPath,
176  bool metadataOnly) const = 0;
177 
182  SDF_API
183  virtual bool WriteToFile(
184  const SdfLayer& layer,
185  const std::string& filePath,
186  const std::string& comment = std::string(),
187  const FileFormatArguments& args = FileFormatArguments()) const;
188 
192  SDF_API
193  virtual bool ReadFromString(
194  SdfLayer* layer,
195  const std::string& str) const;
196 
198  SDF_API
199  virtual bool WriteToStream(
200  const SdfSpecHandle &spec,
201  std::ostream& out,
202  size_t indent) const;
203 
207  SDF_API
208  virtual bool WriteToString(
209  const SdfLayer& layer,
210  std::string* str,
211  const std::string& comment = std::string()) const;
212 
225  SDF_API
226  virtual std::set<std::string> GetExternalAssetDependencies(
227  const SdfLayer& layer) const;
228 
231  SDF_API static std::string GetFileExtension(const std::string& s);
232 
235  SDF_API static std::set<std::string> FindAllFileFormatExtensions();
236 
240  SDF_API
241  static SdfFileFormatConstPtr FindById(
242  const TfToken& formatId);
243 
253  SDF_API
254  static SdfFileFormatConstPtr FindByExtension(
255  const std::string& path,
256  const std::string& target = std::string());
257 
264  SDF_API
265  static SdfFileFormatConstPtr FindByExtension(
266  const std::string& path,
267  const FileFormatArguments& args);
268 
269 protected:
271  SDF_API SdfFileFormat(
272  const TfToken& formatId,
273  const TfToken& versionString,
274  const TfToken& target,
275  const std::string& extension);
276 
279  SDF_API SdfFileFormat(
280  const TfToken& formatId,
281  const TfToken& versionString,
282  const TfToken& target,
283  const std::string& extension,
284  const SdfSchemaBase& schema);
285 
288  const TfToken& formatId,
289  const TfToken& versionString,
290  const TfToken& target,
291  const std::string& extension,
292  const SdfSchemaBase&& schema) = delete;
293 
295  SDF_API SdfFileFormat(
296  const TfToken& formatId,
297  const TfToken& versionString,
298  const TfToken& target,
299  const std::vector<std::string> &extensions);
300 
303  SDF_API SdfFileFormat(
304  const TfToken& formatId,
305  const TfToken& versionString,
306  const TfToken& target,
307  const std::vector<std::string> &extensions,
308  const SdfSchemaBase& schema);
309 
312  const TfToken& formatId,
313  const TfToken& versionString,
314  const TfToken& target,
315  const std::vector<std::string> &extensions,
316  const SdfSchemaBase&& schema) = delete;
317 
319  SDF_API virtual ~SdfFileFormat();
320 
321  //
322  // Minimally break layer encapsulation with the following methods. These
323  // methods are also intended to limit the need for SdfLayer friendship with
324  // SdfFileFormat child classes.
325  //
326 
331  SDF_API
332  static void _SetLayerData(
333  SdfLayer* layer, SdfAbstractDataRefPtr& data);
334 
339  SDF_API
340  static void _SetLayerData(
341  SdfLayer* layer, SdfAbstractDataRefPtr& data,
342  SdfLayerHints hints);
343 
345  SDF_API
346  static SdfAbstractDataConstPtr _GetLayerData(const SdfLayer& layer);
347 
348 private:
349  SDF_API
350  virtual SdfLayer *_InstantiateNewLayer(
351  const SdfFileFormatConstPtr &fileFormat,
352  const std::string &identifier,
353  const std::string &realPath,
354  const ArAssetInfo& assetInfo,
355  const FileFormatArguments &args) const;
356 
357  // File format subclasses may override this if they prefer not to skip
358  // reloading anonymous layers. Default implementation returns true.
359  SDF_API
360  virtual bool _ShouldSkipAnonymousReload() const;
361 
365  SDF_API
366  virtual bool _LayersAreFileBased() const;
367 
368  const SdfSchemaBase& _schema;
369  const TfToken _formatId;
370  const TfToken _target;
371  const std::string _cookie;
372  const TfToken _versionString;
373  const std::vector<std::string> _extensions;
374  const bool _isPrimaryFormat;
375 };
376 
378 class Sdf_FileFormatFactoryBase : public TfType::FactoryBase {
379 public:
380  virtual SdfFileFormatRefPtr New() const = 0;
381 };
382 
384 template <typename T>
385 class Sdf_FileFormatFactory : public Sdf_FileFormatFactoryBase {
386 public:
387  virtual SdfFileFormatRefPtr New() const
388  {
389  return TfCreateRefPtr(new T);
390  }
391 };
392 
396 #define SDF_DEFINE_FILE_FORMAT(c, ...) \
397  TfType::Define<c BOOST_PP_COMMA_IF(TF_NUM_ARGS(__VA_ARGS__)) \
398  BOOST_PP_IF(TF_NUM_ARGS(__VA_ARGS__), \
399  TfType::Bases<__VA_ARGS__>, BOOST_PP_EMPTY) >() \
400  .SetFactory<Sdf_FileFormatFactory<c> >()
401 
405 #define SDF_DEFINE_ABSTRACT_FILE_FORMAT(c, ...) \
406  TfType::Define<c BOOST_PP_COMMA_IF(TF_NUM_ARGS(__VA_ARGS__)) \
407  BOOST_PP_IF(TF_NUM_ARGS(__VA_ARGS__), \
408  TfType::Bases<__VA_ARGS__>, BOOST_PP_EMPTY) >();
409 
410 #define SDF_FILE_FORMAT_FACTORY_ACCESS \
411  template<typename T> friend class Sdf_FileFormatFactory
412 
413 PXR_NAMESPACE_CLOSE_SCOPE
414 
415 #endif // PXR_USD_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:94
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.
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...
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
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:73
Enable a concrete base class for use with TfRefPtr.
Definition: refBase.h:71
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: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.
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.
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:114
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.
Contains hints about layer contents that may be used to accelerate certain composition operations...
Definition: layerHints.h:33
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:64
SDF_API const TfToken & GetFormatId() const
Returns the format identifier.
Enable a concrete base class for use with TfWeakPtr.
Definition: weakBase.h:141
Interface for scene description data storage.
Definition: abstractData.h:73
Contains information about a resolved asset.
Definition: assetInfo.h:40