mapFunction.h

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_USD_PCP_MAP_FUNCTION_H
#define PXR_USD_PCP_MAP_FUNCTION_H
 
#include "pxr/pxr.h"
#include "pxr/usd/pcp/api.h"
#include "pxr/usd/sdf/path.h"
#include "pxr/usd/sdf/layerOffset.h"
#include "pxr/usd/sdf/pathExpression.h"
 
#include <atomic>
#include <memory>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class PcpMapFunction
{
public:
    typedef std::map<SdfPath, SdfPath, SdfPath::FastLessThan> PathMap;
 
    PCP_API
    PcpMapFunction();
 
    PCP_API
    static PcpMapFunction 
    Create(const PathMap &sourceToTargetMap,
           const SdfLayerOffset &offset);
 
    PCP_API
    static PcpMapFunction
    DeferredComposition(const PcpMapFunction& mapFn);
 
    PCP_API
    static PcpMapFunction
    ImpliedClass(const PcpMapFunction& transferFunc,
                 const PcpMapFunction& classArc);
 
    PCP_API
    static const PcpMapFunction &Identity();
 
    PCP_API
    static const PathMap &IdentityPathMap();
    
    PCP_API
    void Swap(PcpMapFunction &map);
    void swap(PcpMapFunction &map) { Swap(map); }
 
    PCP_API
    bool operator==(const PcpMapFunction &map) const;
 
    PCP_API
    bool operator!=(const PcpMapFunction &map) const;
 
    PCP_API
    bool IsNull() const;
 
    PCP_API
    bool IsDeferredComposition() const;
 
    PCP_API
    bool IsIdentity() const;
    
    PCP_API
    bool IsIdentityPathMapping() const;
 
    PCP_API
    bool HasRootIdentity() const;
 
    PCP_API
    SdfPath MapSourceToTarget(const SdfPath &path) const;
 
    PCP_API
    SdfPath MapTargetToSource(const SdfPath &path) const;
 
    PCP_API
    SdfPathExpression
    MapSourceToTarget(
        const SdfPathExpression &pathExpr,
        std::vector<SdfPathExpression::PathPattern>
            *unmappedPatterns = nullptr,
        std::vector<SdfPathExpression::ExpressionReference>
            *unmappedRefs = nullptr
        ) const;
 
    PCP_API
    SdfPathExpression
    MapTargetToSource(
        const SdfPathExpression &pathExpr,
        std::vector<SdfPathExpression::PathPattern>
            *unmappedPatterns = nullptr,
        std::vector<SdfPathExpression::ExpressionReference>
            *unmappedRefs = nullptr
        ) const;
    
    PCP_API
    PcpMapFunction Compose(const PcpMapFunction &f) const;
 
    PCP_API
    PcpMapFunction ComposeOffset(const SdfLayerOffset &newOffset) const;
 
    PCP_API
    PcpMapFunction GetInverse() const;
 
    PCP_API
    PathMap GetSourceToTargetMap() const;
 
    const SdfLayerOffset &GetTimeOffset() const { return _offset; }
 
    PCP_API
    std::string GetString() const;
 
    PCP_API
    size_t Hash() const;
 
private:
    struct _Mappings;
 
    PcpMapFunction(
        std::shared_ptr<_Mappings>&& mappings,
        SdfLayerOffset offset);
 
    SdfPath
    _MapPathImpl(
        bool invert,
        const SdfPath& path) const;
 
    SdfPathExpression
    _MapPathExpressionImpl(
        bool invert,
        const SdfPathExpression &pathExpr,
        std::vector<SdfPathExpression::PathPattern> *unmappedPatterns,
        std::vector<SdfPathExpression::ExpressionReference> *unmappedRefs
        ) const;
 
    // Return a "normalized" map function created from the mappings in
    // this map function. This may return *this if this map function is
    // already in normalized form.
    //
    // A normalized map function always contains a single set of
    // source-to-target path mappings; all deferred-composition mappings
    // are composed together. The resulting map function can be used
    // for comparisons with other normalized map functions, or in
    // cases where the fully-composed set of mappings is needed.
    PcpMapFunction _GetNormalized() const;
 
    // Return number of mapping sets in this map function. A map function
    // may have more than 1 mapping set if it was composed from a
    // deferred-composition map function.
    PCP_API size_t _GetNumMappingSets() const;
 
private:
    friend PcpMapFunction *Pcp_MakeIdentity();
    friend class Pcp_MapFunctionPyAccess;
 
    // Specialize TfHashAppend for PcpMapFunction.
    template <typename HashState>
    friend inline
    void TfHashAppend(HashState& h, const PcpMapFunction& x){
        h.Append(x.Hash());
    }
 
    std::shared_ptr<_Mappings> _mappings;
    SdfLayerOffset _offset;
};
 
// Specialize hash_value for PcpMapFunction.
inline
size_t hash_value(const PcpMapFunction& x)
{
    return TfHash{}(x);
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_USD_PCP_MAP_FUNCTION_H