fileFormat.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_SDF_FILE_FORMAT_H
#define PXR_USD_SDF_FILE_FORMAT_H
 
 
#include "pxr/pxr.h"
#include "pxr/usd/ar/ar.h"
#include "pxr/usd/sdf/api.h"
#include "pxr/usd/sdf/declareHandles.h"
#include "pxr/base/tf/declarePtrs.h"
#include "pxr/base/tf/refBase.h"
#include "pxr/base/tf/staticTokens.h"
#include "pxr/base/tf/token.h"
#include "pxr/base/tf/type.h"
#include "pxr/base/tf/weakBase.h"
 
#include <map>
#include <string>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class ArAssetInfo;
class SdfSchemaBase;
class SdfLayerHints;
 
SDF_DECLARE_HANDLES(SdfLayer);
SDF_DECLARE_HANDLES(SdfSpec);
TF_DECLARE_WEAK_AND_REF_PTRS(SdfAbstractData);
TF_DECLARE_WEAK_AND_REF_PTRS(SdfFileFormat);
 
#define SDF_FILE_FORMAT_TOKENS   \
    ((TargetArg, "target"))
 
TF_DECLARE_PUBLIC_TOKENS(SdfFileFormatTokens, SDF_API, SDF_FILE_FORMAT_TOKENS);
 
class SdfFileFormat
    : public TfRefBase
    , public TfWeakBase
{
public:
    SdfFileFormat(const SdfFileFormat&) = delete;
    SdfFileFormat& operator=(const SdfFileFormat&) = delete;
 
    SDF_API const SdfSchemaBase& GetSchema() const;
 
    SDF_API const TfToken& GetFormatId() const;
 
    SDF_API const TfToken& GetTarget() const;
 
    SDF_API const std::string& GetFileCookie() const;
 
    SDF_API const TfToken& GetVersionString() const;
 
    SDF_API bool IsPrimaryFormatForExtensions() const;
 
    SDF_API const std::vector<std::string>& GetFileExtensions() const;
 
    SDF_API const std::string& GetPrimaryFileExtension() const;
 
    SDF_API bool IsSupportedExtension(const std::string& extension) const;
 
    SDF_API 
    virtual bool IsPackage() const;
 
    SDF_API
    virtual std::string GetPackageRootLayerPath(
        const std::string& resolvedPath) const;
 
    typedef std::map<std::string, std::string> FileFormatArguments;
 
    SDF_API
    virtual FileFormatArguments GetDefaultFileFormatArguments() const;
 
    SDF_API
    virtual SdfAbstractDataRefPtr
    InitData(const FileFormatArguments& args) const;
 
    SDF_API
    SdfAbstractDataRefPtr InitDetachedData(
        const FileFormatArguments& args) const;
 
    SDF_API 
    SdfLayerRefPtr NewLayer(const SdfFileFormatConstPtr &fileFormat,
                            const std::string &identifier,
                            const std::string &realPath,
                            const ArAssetInfo& assetInfo,
                            const FileFormatArguments &args) const;
 
    SDF_API bool ShouldSkipAnonymousReload() const;
 
    SDF_API bool ShouldReadAnonymousLayers() const;
 
    SDF_API
    virtual bool CanRead(
        const std::string& file) const = 0;
 
    SDF_API
    virtual bool Read(
        SdfLayer* layer,
        const std::string& resolvedPath,
        bool metadataOnly) const = 0;
 
    SDF_API
    bool ReadDetached(
        SdfLayer* layer,
        const std::string& resolvedPath,
        bool metadataOnly) const;
 
    SDF_API
    virtual bool WriteToFile(
        const SdfLayer& layer,
        const std::string& filePath,
        const std::string& comment = std::string(),
        const FileFormatArguments& args = FileFormatArguments()) const;
 
    SDF_API
    virtual bool SaveToFile(
        const SdfLayer& layer,
        const std::string& filePath,
        const std::string& comment = std::string(),
        const FileFormatArguments& args = FileFormatArguments()) const;
 
    SDF_API
    virtual bool ReadFromString(
        SdfLayer* layer,
        const std::string& str) const;
 
    SDF_API
    virtual bool WriteToStream(
        const SdfSpecHandle &spec,
        std::ostream& out,
        size_t indent) const;
 
    SDF_API
    virtual bool WriteToString(
        const SdfLayer& layer,
        std::string* str,
        const std::string& comment = std::string()) const;
 
    SDF_API
    virtual std::set<std::string> GetExternalAssetDependencies(
        const SdfLayer& layer) const;
 
 
    SDF_API bool SupportsReading() const;
 
    // Returns true if this file format supports writing.
    SDF_API bool SupportsWriting() const;
 
    // Returns true if this file format supports editing.
    SDF_API bool SupportsEditing() const;
 
    SDF_API static std::string GetFileExtension(const std::string& s);
 
    SDF_API static std::set<std::string> FindAllFileFormatExtensions();
 
    SDF_API static std::set<std::string> FindAllDerivedFileFormatExtensions(
        const TfType& baseType);
 
    SDF_API
    static bool FormatSupportsReading(
        const std::string& extension,
        const std::string& target = std::string());
 
    SDF_API
    static bool FormatSupportsWriting(
        const std::string& extension,
        const std::string& target = std::string());
 
    SDF_API
    static bool FormatSupportsEditing(
        const std::string& extension,
        const std::string& target = std::string());
 
    SDF_API 
    static SdfFileFormatConstPtr FindById(
        const TfToken& formatId);
 
    SDF_API
    static SdfFileFormatConstPtr FindByExtension(
        const std::string& path,
        const std::string& target = std::string());
 
    SDF_API
    static SdfFileFormatConstPtr FindByExtension(
        const std::string& path,
        const FileFormatArguments& args);
 
protected:
    SDF_API SdfFileFormat(
        const TfToken& formatId,
        const TfToken& versionString,
        const TfToken& target,
        const std::string& extension);
 
    SDF_API SdfFileFormat(
        const TfToken& formatId,
        const TfToken& versionString,
        const TfToken& target,
        const std::string& extension,
        const SdfSchemaBase& schema);
 
    SdfFileFormat(
        const TfToken& formatId,
        const TfToken& versionString,
        const TfToken& target,
        const std::string& extension,
        const SdfSchemaBase&& schema) = delete;
 
    SDF_API SdfFileFormat(
        const TfToken& formatId,
        const TfToken& versionString,
        const TfToken& target,
        const std::vector<std::string> &extensions);
 
    SDF_API SdfFileFormat(
        const TfToken& formatId,
        const TfToken& versionString,
        const TfToken& target,
        const std::vector<std::string> &extensions,
        const SdfSchemaBase& schema);
 
    SdfFileFormat(
        const TfToken& formatId,
        const TfToken& versionString,
        const TfToken& target,
        const std::vector<std::string> &extensions,
        const SdfSchemaBase&& schema) = delete;
 
    SDF_API virtual ~SdfFileFormat();
 
    //
    // Minimally break layer encapsulation with the following methods.  These
    // methods are also intended to limit the need for SdfLayer friendship with 
    // SdfFileFormat child classes.
    //
 
    SDF_API
    static void _SetLayerData(
        SdfLayer* layer, SdfAbstractDataRefPtr& data);
 
    SDF_API
    static void _SetLayerData(
        SdfLayer* layer, SdfAbstractDataRefPtr& data,
        SdfLayerHints hints);
 
    SDF_API
    static SdfAbstractDataConstPtr _GetLayerData(const SdfLayer& layer);
 
    SDF_API
    bool _ReadAndCopyLayerDataToMemory(
        SdfLayer* layer,
        const std::string& resolvedPath,
        bool metadataOnly,
        bool* didCopyData = nullptr) const;
 
protected:
    SDF_API
    virtual SdfLayer *_InstantiateNewLayer(
        const SdfFileFormatConstPtr &fileFormat,
        const std::string &identifier,
        const std::string &realPath,
        const ArAssetInfo& assetInfo,
        const FileFormatArguments &args) const;
 
    // File format subclasses may override this if they prefer not to skip
    // reloading anonymous layers.  Default implementation returns true.
    SDF_API
    virtual bool _ShouldSkipAnonymousReload() const;
 
    SDF_API 
    virtual bool _ShouldReadAnonymousLayers() const;
 
    SDF_API
    virtual SdfAbstractDataRefPtr _InitDetachedData(
        const FileFormatArguments& args) const;
 
    SDF_API
    virtual bool _ReadDetached(
        SdfLayer* layer,
        const std::string& resolvedPath,
        bool metadataOnly) const;
 
private:
    const SdfSchemaBase& _schema;
    const TfToken _formatId;
    const TfToken _target;
    const std::string _cookie;
    const TfToken _versionString;
    const std::vector<std::string> _extensions;
    const bool _isPrimaryFormat;
};
 
// Base file format factory.
class Sdf_FileFormatFactoryBase : public TfType::FactoryBase {
public:
    SDF_API virtual ~Sdf_FileFormatFactoryBase();
    virtual SdfFileFormatRefPtr New() const = 0;
};
 
// Default file format factory.
template <typename T>
class Sdf_FileFormatFactory : public Sdf_FileFormatFactoryBase {
public:
    virtual SdfFileFormatRefPtr New() const
    {
        return TfCreateRefPtr(new T);
    }
};
 
#ifdef doxygen
#define SDF_DEFINE_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
#else
#define SDF_DEFINE_FILE_FORMAT(...) SdfDefineFileFormat<__VA_ARGS__>()
 
template <class FileFormat, class ...BaseFormats>
void SdfDefineFileFormat()
{
    TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>()
        .template SetFactory<Sdf_FileFormatFactory<FileFormat>>();
}
#endif // doxygen
 
#ifdef doxygen
#define SDF_DEFINE_ABSTRACT_FILE_FORMAT(FileFormatClass, BaseClass1, ...)
#else
#define SDF_DEFINE_ABSTRACT_FILE_FORMAT(...) \
    SdfDefineAbstractFileFormat<__VA_ARGS__>()
 
template <class FileFormat, class ...BaseFormats>
void SdfDefineAbstractFileFormat()
{
    TfType::Define<FileFormat, TfType::Bases<BaseFormats...>>();
}
#endif //doxygen
 
#ifdef doxygen
#define SDF_FILE_FORMAT_FACTORY_ACCESS
#else
#define SDF_FILE_FORMAT_FACTORY_ACCESS \
    template<typename T> friend class Sdf_FileFormatFactory
#endif //doxygen
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif