fileFormat.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache 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 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