Loading...
Searching...
No Matches
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"
39
40#include <map>
41#include <string>
42#include <vector>
43
44PXR_NAMESPACE_OPEN_SCOPE
45
46class ArAssetInfo;
47class SdfSchemaBase;
48class SdfLayerHints;
49
50SDF_DECLARE_HANDLES(SdfLayer);
51SDF_DECLARE_HANDLES(SdfSpec);
54
55#define SDF_FILE_FORMAT_TOKENS \
56 ((TargetArg, "target"))
57
58TF_DECLARE_PUBLIC_TOKENS(SdfFileFormatTokens, SDF_API, SDF_FILE_FORMAT_TOKENS);
59
65 : public TfRefBase
66 , public TfWeakBase
67{
68public:
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
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
257
261 SDF_API bool SupportsReading() const;
262
263 // Returns true if this file format supports writing.
266 SDF_API bool SupportsWriting() const;
267
268 // Returns true if this file format supports editing.
271 SDF_API bool SupportsEditing() const;
272
275 SDF_API static std::string GetFileExtension(const std::string& s);
276
279 SDF_API static std::set<std::string> FindAllFileFormatExtensions();
280
285 SDF_API static std::set<std::string> FindAllDerivedFileFormatExtensions(
286 const TfType& baseType);
287
295 SDF_API
297 const std::string& extension,
298 const std::string& target = std::string());
299
307 SDF_API
309 const std::string& extension,
310 const std::string& target = std::string());
311
319 SDF_API
321 const std::string& extension,
322 const std::string& target = std::string());
323
327 SDF_API
328 static SdfFileFormatConstPtr FindById(
329 const TfToken& formatId);
330
340 SDF_API
341 static SdfFileFormatConstPtr FindByExtension(
342 const std::string& path,
343 const std::string& target = std::string());
344
351 SDF_API
352 static SdfFileFormatConstPtr FindByExtension(
353 const std::string& path,
354 const FileFormatArguments& args);
355
356protected:
359 const TfToken& formatId,
360 const TfToken& versionString,
361 const TfToken& target,
362 const std::string& extension);
363
367 const TfToken& formatId,
368 const TfToken& versionString,
369 const TfToken& target,
370 const std::string& extension,
371 const SdfSchemaBase& schema);
372
375 const TfToken& formatId,
376 const TfToken& versionString,
377 const TfToken& target,
378 const std::string& extension,
379 const SdfSchemaBase&& schema) = delete;
380
383 const TfToken& formatId,
384 const TfToken& versionString,
385 const TfToken& target,
386 const std::vector<std::string> &extensions);
387
391 const TfToken& formatId,
392 const TfToken& versionString,
393 const TfToken& target,
394 const std::vector<std::string> &extensions,
395 const SdfSchemaBase& schema);
396
399 const TfToken& formatId,
400 const TfToken& versionString,
401 const TfToken& target,
402 const std::vector<std::string> &extensions,
403 const SdfSchemaBase&& schema) = delete;
404
406 SDF_API virtual ~SdfFileFormat();
407
408 //
409 // Minimally break layer encapsulation with the following methods. These
410 // methods are also intended to limit the need for SdfLayer friendship with
411 // SdfFileFormat child classes.
412 //
413
418 SDF_API
419 static void _SetLayerData(
420 SdfLayer* layer, SdfAbstractDataRefPtr& data);
421
426 SDF_API
427 static void _SetLayerData(
428 SdfLayer* layer, SdfAbstractDataRefPtr& data,
429 SdfLayerHints hints);
430
432 SDF_API
433 static SdfAbstractDataConstPtr _GetLayerData(const SdfLayer& layer);
434
449 SDF_API
451 SdfLayer* layer,
452 const std::string& resolvedPath,
453 bool metadataOnly,
454 bool* didCopyData = nullptr) const;
455
456protected:
457 SDF_API
458 virtual SdfLayer *_InstantiateNewLayer(
459 const SdfFileFormatConstPtr &fileFormat,
460 const std::string &identifier,
461 const std::string &realPath,
462 const ArAssetInfo& assetInfo,
463 const FileFormatArguments &args) const;
464
465 // File format subclasses may override this if they prefer not to skip
466 // reloading anonymous layers. Default implementation returns true.
467 SDF_API
468 virtual bool _ShouldSkipAnonymousReload() const;
469
474 SDF_API
475 virtual bool _ShouldReadAnonymousLayers() const;
476
483 SDF_API
484 virtual SdfAbstractDataRefPtr _InitDetachedData(
485 const FileFormatArguments& args) const;
486
498 SDF_API
499 virtual bool _ReadDetached(
500 SdfLayer* layer,
501 const std::string& resolvedPath,
502 bool metadataOnly) const;
503
504private:
505 const SdfSchemaBase& _schema;
506 const TfToken _formatId;
507 const TfToken _target;
508 const std::string _cookie;
509 const TfToken _versionString;
510 const std::vector<std::string> _extensions;
511 const bool _isPrimaryFormat;
512};
513
514// Base file format factory.
515class Sdf_FileFormatFactoryBase : public TfType::FactoryBase {
516public:
517 SDF_API virtual ~Sdf_FileFormatFactoryBase();
518 virtual SdfFileFormatRefPtr New() const = 0;
519};
520
521// Default file format factory.
522template <typename T>
523class Sdf_FileFormatFactory : public Sdf_FileFormatFactoryBase {
524public:
525 virtual SdfFileFormatRefPtr New() const
526 {
527 return TfCreateRefPtr(new T);
528 }
529};
530
552#ifdef doxygen
553#define SDF_DEFINE_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
554#else
555#define SDF_DEFINE_FILE_FORMAT(...) SdfDefineFileFormat<__VA_ARGS__>()
556
557template <class FileFormat, class ...BaseFormats>
558void SdfDefineFileFormat()
559{
560 TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>()
561 .template SetFactory<Sdf_FileFormatFactory<FileFormat>>();
562}
563#endif // doxygen
564
586#ifdef doxygen
587#define SDF_DEFINE_ABSTRACT_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
588#else
589#define SDF_DEFINE_ABSTRACT_FILE_FORMAT(...) \
590 SdfDefineAbstractFileFormat<__VA_ARGS__>()
591
592template <class FileFormat, class ...BaseFormats>
593void SdfDefineAbstractFileFormat()
594{
595 TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>();
596}
597#endif //doxygen
598
616#ifdef doxygen
617#define SDF_FILE_FORMAT_FACTORY_ACCESS
618#else
619#define SDF_FILE_FORMAT_FACTORY_ACCESS \
620 template<typename T> friend class Sdf_FileFormatFactory
621#endif //doxygen
622
623PXR_NAMESPACE_CLOSE_SCOPE
624
625#endif
Contains information about a resolved asset.
Definition: assetInfo.h:42
Interface for scene description data storage.
Definition: abstractData.h:74
Base class for file format implementations.
Definition: fileFormat.h:67
SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::string &extension, const SdfSchemaBase &&schema)=delete
Disallow temporary SdfSchemaBase objects being passed to the c'tor.
static SDF_API SdfAbstractDataConstPtr _GetLayerData(const SdfLayer &layer)
Get the internal data for layer.
virtual SDF_API bool _ShouldReadAnonymousLayers() const
File format subclasses may override this to specify whether Read should be called when creating,...
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.
SDF_API const TfToken & GetVersionString() const
Returns the current version of this file format.
std::map< std::string, std::string > FileFormatArguments
Type for specifying additional file format-specific arguments to the various API below.
Definition: fileFormat.h:119
SDF_API const TfToken & GetTarget() const
Returns the target for this file format.
SDF_API SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::string &extension)
Constructor.
SDF_API bool SupportsWriting() const
This is a convenience method for invoking FormatSupportsWriting with this format's extension and targ...
SDF_API const SdfSchemaBase & GetSchema() const
Returns the schema for this format.
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, SdfLayerHints hints)
Set the internal data for layer to data, possibly transferring ownership of data.
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 WriteToStream(const SdfSpecHandle &spec, std::ostream &out, size_t indent) const
Write the provided spec to out indented indent levels.
SDF_API bool _ReadAndCopyLayerDataToMemory(SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly, bool *didCopyData=nullptr) const
Helper function for _ReadDetached.
SDF_API bool ShouldReadAnonymousLayers() const
Returns true if anonymous layer identifiers should be passed to Read when a layer is opened or reload...
SDF_API bool SupportsReading() const
Returns true if this file format supports reading.
virtual SDF_API bool IsPackage() const
Returns true if this file format is a package containing other assets.
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 ~SdfFileFormat()
Destructor.
static SDF_API SdfFileFormatConstPtr FindById(const TfToken &formatId)
Returns the file format instance with the specified formatId identifier.
SDF_API SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::string &extension, const SdfSchemaBase &schema)
Constructor.
SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::vector< std::string > &extensions, const SdfSchemaBase &&schema)=delete
Disallow temporary SdfSchemaBase objects being passed to the c'tor.
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.
virtual SDF_API FileFormatArguments GetDefaultFileFormatArguments() const
Returns the FileFormatArguments that correspond to the default behavior of this file format when no F...
SDF_API bool SupportsEditing() const
This is a convenience method for invoking FormatSupportsEditing with this format's extension and targ...
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 void _SetLayerData(SdfLayer *layer, SdfAbstractDataRefPtr &data)
Set the internal data for layer to data, possibly transferring ownership of data.
virtual SDF_API bool _ReadDetached(SdfLayer *layer, const std::string &resolvedPath, bool metadataOnly) const
static SDF_API std::set< std::string > FindAllFileFormatExtensions()
Returns a set containing the extension(s) corresponding to all registered file formats.
static SDF_API std::set< std::string > FindAllDerivedFileFormatExtensions(const TfType &baseType)
Returns a set containing the extension(s) corresponding to all registered file formats that derive fr...
virtual SDF_API SdfAbstractDataRefPtr _InitDetachedData(const FileFormatArguments &args) const
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 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 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 & GetFormatId() const
Returns the format identifier.
SDF_API const std::vector< std::string > & GetFileExtensions() const
Returns a list of extensions that this format supports.
static SDF_API bool FormatSupportsEditing(const std::string &extension, const std::string &target=std::string())
Returns true if the file format for the supplied extension and target pair supports editing.
SDF_API const std::string & GetPrimaryFileExtension() const
Returns the primary file extension for this format.
static SDF_API SdfFileFormatConstPtr FindByExtension(const std::string &path, const FileFormatArguments &args)
Returns a file format instance that supports the extension for path and whose target matches one of t...
SDF_API bool IsPrimaryFormatForExtensions() const
Returns true if this file format is the primary format for the extensions it handles.
static SDF_API bool FormatSupportsReading(const std::string &extension, const std::string &target=std::string())
Returns true if the file format for the supplied extension and target pair supports reading.
SDF_API SdfAbstractDataRefPtr InitDetachedData(const FileFormatArguments &args) const
Returns a new SdfAbstractData providing access to the layer's data.
static SDF_API bool FormatSupportsWriting(const std::string &extension, const std::string &target=std::string())
Returns true if the file format for the supplied extension and target pair supports writing.
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 ...
SDF_API bool IsSupportedExtension(const std::string &extension) const
Returns true if extension matches one of the extensions returned by GetFileExtensions.
SDF_API bool ShouldSkipAnonymousReload() const
Return true if this file format prefers to skip reloading anonymous layers.
SDF_API SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::vector< std::string > &extensions, const SdfSchemaBase &schema)
Constructor.
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.
SDF_API SdfFileFormat(const TfToken &formatId, const TfToken &versionString, const TfToken &target, const std::vector< std::string > &extensions)
Constructor.
virtual SDF_API bool CanRead(const std::string &file) const =0
Returns true if file can be read by this format.
Contains hints about layer contents that may be used to accelerate certain composition operations.
Definition: layerHints.h:34
A scene description container that can combine with other such containers to form simple component as...
Definition: layer.h:100
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:50
Enable a concrete base class for use with TfRefPtr.
Definition: refBase.h:73
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:88
Base class of all factory types.
Definition: type.h:73
TfType represents a dynamic runtime type.
Definition: type.h:65
static TfType const & Define()
Define a TfType with the given C++ type T and C++ base types B.
A type-list of C++ base types.
Definition: type.h:100
Enable a concrete base class for use with TfWeakPtr.
Definition: weakBase.h:141
Standard pointer typedefs.
#define TF_DECLARE_WEAK_AND_REF_PTRS(type)
Define standard weak, ref, and vector pointer types.
Definition: declarePtrs.h:89
This file defines some macros that are useful for declaring and using static TfTokens.
#define TF_DECLARE_PUBLIC_TOKENS(...)
Macro to define public tokens.
Definition: staticTokens.h:108
TfToken class for efficient string referencing and hashing, plus conversions to and from stl string c...