collectionMembershipQuery.h

Go to the documentation of this file.

//
// Copyright 2019 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_USD_COLLECTION_MEMBERSHIP_QUERY_H
#define PXR_USD_USD_COLLECTION_MEMBERSHIP_QUERY_H
 
 
#include "pxr/pxr.h"
 
#include "pxr/usd/usd/common.h"
#include "pxr/usd/usd/object.h"
#include "pxr/usd/usd/primFlags.h"
 
#include "pxr/base/tf/declarePtrs.h"
#include "pxr/base/tf/hash.h"
#include "pxr/base/tf/staticTokens.h"
#include "pxr/usd/sdf/path.h"
#include "pxr/usd/sdf/pathExpression.h"
#include "pxr/usd/sdf/pathExpressionEval.h"
 
#include <unordered_map>
 
PXR_NAMESPACE_OPEN_SCOPE
 
#define USD_COLLECTION_MEMBERSHIP_QUERY_TOKENS \
    (IncludedByMembershipExpression)           \
    (ExcludedByMembershipExpression)
 
TF_DECLARE_PUBLIC_TOKENS(UsdCollectionMembershipQueryTokens,
                         USD_API, USD_COLLECTION_MEMBERSHIP_QUERY_TOKENS);
 
 
class Usd_CollectionMembershipQueryBase
{
public:
    using PathExpansionRuleMap = std::unordered_map<SdfPath,
          TfToken, SdfPath::Hash>;
 
    Usd_CollectionMembershipQueryBase() = default;
 
    Usd_CollectionMembershipQueryBase(
        const PathExpansionRuleMap& pathExpansionRuleMap,
        const SdfPathSet& includedCollections);
 
    Usd_CollectionMembershipQueryBase(
        PathExpansionRuleMap&& pathExpansionRuleMap,
        SdfPathSet&& includedCollections);
 
    Usd_CollectionMembershipQueryBase(
        const PathExpansionRuleMap& pathExpansionRuleMap,
        const SdfPathSet& includedCollections,
        const TfToken &topExpansionRule);
 
    Usd_CollectionMembershipQueryBase(
        PathExpansionRuleMap&& pathExpansionRuleMap,
        SdfPathSet&& includedCollections,
        TfToken const &topExpansionRule);
    
    bool HasExcludes() const {
        return _hasExcludes;
    }
    
 
    const PathExpansionRuleMap& GetAsPathExpansionRuleMap() const {
        return _pathExpansionRuleMap;
    }
 
    const SdfPathSet& GetIncludedCollections() const {
        return _includedCollections;
    }
 
    TfToken GetTopExpansionRule() const {
        return _topExpansionRule;
    }
 
protected:
 
    struct _Hash {
        USD_API
        size_t operator()(Usd_CollectionMembershipQueryBase const& query) const;
    };
 
    inline size_t _GetHash() const {
        return _Hash()(*this);
    }
 
    USD_API
    bool _IsPathIncludedByRuleMap(const SdfPath &path,
                                  TfToken *expansionRule=nullptr) const;
 
    USD_API
    bool _IsPathIncludedByRuleMap(const SdfPath &path,
                                  const TfToken &parentExpansionRule,
                                  TfToken *expansionRule=nullptr) const;
 
    // Return true if the _pathExpansionRuleMap is empty, meaning that we would
    // use an expression in the derived class, for example.
    USD_API
    bool _HasEmptyRuleMap() const;
 
    TfToken _topExpansionRule;
    
    PathExpansionRuleMap _pathExpansionRuleMap;
 
    SdfPathSet _includedCollections;
 
    // A cached flag indicating whether _pathExpansionRuleMap contains
    // any exclude rules.
    bool _hasExcludes=false;
};
 
USD_API
SdfPathExpression
UsdComputePathExpressionFromCollectionMembershipQueryRuleMap(
    Usd_CollectionMembershipQueryBase::PathExpansionRuleMap const &ruleMap);
 
// -------------------------------------------------------------------------- //
// UsdCollectionMembershipQuery                                               //
// -------------------------------------------------------------------------- //
template <class ExprEval>
class Usd_CollectionMembershipQuery : public Usd_CollectionMembershipQueryBase
{
public:
    using ExpressionEvaluator = ExprEval;
    
    using Usd_CollectionMembershipQueryBase::Usd_CollectionMembershipQueryBase;
 
    SdfPredicateFunctionResult
    IsPathIncluded(const SdfPath &path,
                   TfToken *expansionRule=nullptr) const {
        // If we have a rule map, go that way.  Otherwise try the expression.
        if (UsesPathExpansionRuleMap()) {
            return SdfPredicateFunctionResult::MakeVarying(
                _IsPathIncludedByRuleMap(path, expansionRule));
        }
        const SdfPredicateFunctionResult
            res = GetExpressionEvaluator().Match(path);
        if (expansionRule) {
            *expansionRule = res ?
                UsdCollectionMembershipQueryTokens->
                    IncludedByMembershipExpression : 
                UsdCollectionMembershipQueryTokens->
                    ExcludedByMembershipExpression;
        }
        return res;
    }
 
    SdfPredicateFunctionResult
    IsPathIncluded(const SdfPath &path,
                   const TfToken &parentExpansionRule,
                   TfToken *expansionRule=nullptr) const {
        // If we have a rule map, go that way.  Otherwise try the expression.
        if (UsesPathExpansionRuleMap()) {
            return SdfPredicateFunctionResult::MakeVarying(
                _IsPathIncludedByRuleMap(
                    path, parentExpansionRule, expansionRule));
        }
        const SdfPredicateFunctionResult
            res = GetExpressionEvaluator().Match(path);
        if (expansionRule) {
            *expansionRule = res ?
                UsdCollectionMembershipQueryTokens->
                    IncludedByMembershipExpression : 
                UsdCollectionMembershipQueryTokens->
                    ExcludedByMembershipExpression;
        }
        return res;
    }
 
    bool UsesPathExpansionRuleMap() const {
        return !_HasEmptyRuleMap();
    }
 
    void
    SetExpressionEvaluator(ExpressionEvaluator &&exprEval) {
        _exprEval = std::move(exprEval);
    }
 
    void
    SetExpressionEvaluator(ExpressionEvaluator const &exprEval) {
        SetExpressionEvaluator(ExpressionEvaluator { exprEval } );
    }
    
    ExpressionEvaluator const &
    GetExpressionEvaluator() const {
        return _exprEval;
    }
 
    bool HasExpression() const {
        return !_exprEval.IsEmpty();
    }
 
    bool operator==(Usd_CollectionMembershipQuery const& rhs) const {
        // Note that MembershipQuery objects that have non-empty _exprEval never
        // compare equal to each other.  This is because the evaluator objects
        // run code, and there's no good way to determine equivalence.
        return _topExpansionRule == rhs._topExpansionRule &&
            _hasExcludes == rhs._hasExcludes &&
            _pathExpansionRuleMap == rhs._pathExpansionRuleMap &&
            _includedCollections == rhs._includedCollections &&
            _exprEval.IsEmpty() == rhs._exprEval.IsEmpty();
        ;
    }
 
    bool operator!=(Usd_CollectionMembershipQuery const& rhs) const {
        return !(*this == rhs);
    }
 
    struct Hash {
        size_t operator()(Usd_CollectionMembershipQuery const& query) const {
            return TfHash::Combine(query._GetHash(), query._exprEval.IsEmpty());
        }
    };
 
    inline size_t GetHash() const {
        return Hash()(*this);
    }
    
private:
    ExpressionEvaluator _exprEval;
};
 
 
class UsdObjectCollectionExpressionEvaluator {
    struct PathToObj {
        UsdObject operator()(SdfPath const &path) const {
            return stage->GetObjectAtPath(path);
        }
        UsdStageWeakPtr stage;
    };
    
public:
    using PathExprEval = SdfPathExpressionEval<UsdObject>;
    using IncrementalSearcher =
        typename PathExprEval::IncrementalSearcher<PathToObj>;
    
    UsdObjectCollectionExpressionEvaluator() = default;
    
    USD_API
    UsdObjectCollectionExpressionEvaluator(UsdStageWeakPtr const &stage,
                                           SdfPathExpression const &expr);
 
    bool IsEmpty() const {
        return !_stage || _evaluator.IsEmpty();
    }
 
    UsdStageWeakPtr const &GetStage() const { return _stage; }
 
    USD_API
    SdfPredicateFunctionResult
    Match(SdfPath const &path) const;
 
    USD_API
    SdfPredicateFunctionResult
    Match(UsdObject const &object) const;
 
    USD_API
    IncrementalSearcher MakeIncrementalSearcher() const;
    
private:
    UsdStageWeakPtr _stage;
    PathExprEval _evaluator;
};
 
using UsdCollectionMembershipQuery =
    Usd_CollectionMembershipQuery<UsdObjectCollectionExpressionEvaluator>;
 
USD_API
std::set<UsdObject> UsdComputeIncludedObjectsFromCollection(
    const UsdCollectionMembershipQuery &query,
    const UsdStageWeakPtr &stage,
    const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate);
 
USD_API
SdfPathSet UsdComputeIncludedPathsFromCollection(
    const UsdCollectionMembershipQuery &query,
    const UsdStageWeakPtr &stage,
    const Usd_PrimFlagsPredicate &pred=UsdPrimDefaultPredicate);
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif