materialBindingAPI.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 USDSHADE_GENERATED_MATERIALBINDINGAPI_H
#define USDSHADE_GENERATED_MATERIALBINDINGAPI_H


#include "pxr/pxr.h"
#include "pxr/usd/usdShade/api.h"
#include "pxr/usd/usd/apiSchemaBase.h"
#include "pxr/usd/usd/prim.h"
#include "pxr/usd/usd/stage.h"
#include "pxr/usd/usdShade/tokens.h"

#include "pxr/usd/usd/collectionAPI.h"
#include "pxr/usd/usdGeom/subset.h"
#include "pxr/usd/usdShade/material.h"
#include <tbb/concurrent_unordered_map.h>

#include "pxr/base/vt/value.h"

#include "pxr/base/gf/vec3d.h"
#include "pxr/base/gf/vec3f.h"
#include "pxr/base/gf/matrix4d.h"

#include "pxr/base/tf/token.h"
#include "pxr/base/tf/type.h"

PXR_NAMESPACE_OPEN_SCOPE

class SdfAssetPath;

// -------------------------------------------------------------------------- //
// MATERIALBINDINGAPI                                                         //
// -------------------------------------------------------------------------- //

class UsdShadeMaterialBindingAPI : public UsdAPISchemaBase
{
public:
    static const UsdSchemaKind schemaKind = UsdSchemaKind::SingleApplyAPI;

    explicit UsdShadeMaterialBindingAPI(const UsdPrim& prim=UsdPrim())
        : UsdAPISchemaBase(prim)
    {
    }

    explicit UsdShadeMaterialBindingAPI(const UsdSchemaBase& schemaObj)
        : UsdAPISchemaBase(schemaObj)
    {
    }

    USDSHADE_API
    virtual ~UsdShadeMaterialBindingAPI();

    USDSHADE_API
    static const TfTokenVector &
    GetSchemaAttributeNames(bool includeInherited=true);

    USDSHADE_API
    static UsdShadeMaterialBindingAPI
    Get(const UsdStagePtr &stage, const SdfPath &path);


    USDSHADE_API
    static bool 
    CanApply(const UsdPrim &prim, std::string *whyNot=nullptr);

    USDSHADE_API
    static UsdShadeMaterialBindingAPI 
    Apply(const UsdPrim &prim);

protected:
    USDSHADE_API
    UsdSchemaKind _GetSchemaKind() const override;

private:
    // needs to invoke _GetStaticTfType.
    friend class UsdSchemaRegistry;
    USDSHADE_API
    static const TfType &_GetStaticTfType();

    static bool _IsTypedSchema();

    // override SchemaBase virtuals.
    USDSHADE_API
    const TfType &_GetTfType() const override;

public:
    // ===================================================================== //
    // Feel free to add custom code below this line, it will be preserved by 
    // the code generator. 
    //
    // Just remember to: 
    //  - Close the class declaration with }; 
    //  - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
    //  - Close the include guard with #endif
    // ===================================================================== //
    // --(BEGIN CUSTOM CODE)--

        
    USDSHADE_API
    UsdRelationship GetDirectBindingRel(
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
    
    USDSHADE_API
    UsdRelationship GetCollectionBindingRel(
        const TfToken &bindingName,
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;

    USDSHADE_API
    std::vector<UsdRelationship> GetCollectionBindingRels(
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;

    class DirectBinding {
    public:
        DirectBinding() 
        {}

        USDSHADE_API
        explicit DirectBinding(const UsdRelationship &bindingRel);

        USDSHADE_API
        UsdShadeMaterial GetMaterial() const;

        const SdfPath &GetMaterialPath() const {
            return _materialPath;
        }

        const UsdRelationship &GetBindingRel() const {
            return _bindingRel;
        }

        const TfToken &GetMaterialPurpose() const {
            return _materialPurpose;
        }

        bool IsBound() const {
            return _isBound;
        }

    private:
        // The path to the material that is bound to.
        SdfPath _materialPath; 
        
        // The binding relationship.
        UsdRelationship _bindingRel;

        // The purpose of the material binding.
        TfToken _materialPurpose;

        // Store if there was a binding here.  This allows us to distinguish if
        // a direct binding is purposefully empty.
        bool _isBound;
    };

    class CollectionBinding {
    public:
        CollectionBinding() 
        {}

        USDSHADE_API
        explicit CollectionBinding(const UsdRelationship &collBindingRel);

        USDSHADE_API
        UsdShadeMaterial GetMaterial() const;

        USDSHADE_API
        UsdCollectionAPI GetCollection() const;

        USDSHADE_API
        static bool IsCollectionBindingRel(const UsdRelationship &bindingRel);
        
        bool IsValid() const {
            return CollectionBinding::IsCollectionBindingRel(_bindingRel) 
                && !GetMaterialPath().IsEmpty();
        }
        const SdfPath &GetCollectionPath() const { 
            return _collectionPath;
        }

        const SdfPath &GetMaterialPath() const { 
            return _materialPath;
        }

        const UsdRelationship &GetBindingRel() const {
            return _bindingRel;
        }

    private:
        // The collection being bound.
        SdfPath _collectionPath;

        // The material that is bound to. 
        SdfPath _materialPath;

        // The relationship that binds the collection to the material.
        UsdRelationship _bindingRel;
    };

    using CollectionBindingVector = std::vector<CollectionBinding>;

    USDSHADE_API
    DirectBinding GetDirectBinding(
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;

    USDSHADE_API
    CollectionBindingVector GetCollectionBindings(
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
    
    USDSHADE_API
    static TfToken GetMaterialBindingStrength(
        const UsdRelationship &bindingRel);


    USDSHADE_API
    static bool SetMaterialBindingStrength(
        const UsdRelationship &bindingRel,
        const TfToken &bindingStrength);



    USDSHADE_API
    bool Bind(
        const UsdShadeMaterial &material,
        const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength,
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;

    USDSHADE_API
    bool Bind(
        const UsdCollectionAPI &collection, 
        const UsdShadeMaterial &material,
        const TfToken &bindingName=TfToken(),
        const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength,
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;

    USDSHADE_API
    bool UnbindDirectBinding(
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;

    USDSHADE_API
    bool UnbindCollectionBinding(
        const TfToken &bindingName, 
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;

    USDSHADE_API
    bool UnbindAllBindings() const;

    USDSHADE_API
    bool RemovePrimFromBindingCollection(
        const UsdPrim &prim, 
        const TfToken &bindingName,
        const TfToken &materialPurpose) const;

    USDSHADE_API
    bool AddPrimToBindingCollection(
        const UsdPrim &prim, 
        const TfToken &bindingName,
        const TfToken &materialPurpose) const;



    using CollectionQueryCache = 
        tbb::concurrent_unordered_map<SdfPath, 
            std::unique_ptr<UsdCollectionAPI::MembershipQuery>, SdfPath::Hash>;

    using DirectBindingPtr = std::unique_ptr<DirectBinding>;

    struct BindingsAtPrim {
        USDSHADE_API
        BindingsAtPrim(const UsdPrim &prim, const TfToken &materialPurpose);

        DirectBindingPtr directBinding;
         
        CollectionBindingVector restrictedPurposeCollBindings;

        CollectionBindingVector allPurposeCollBindings;
    };

    friend struct BindingsAtPrim;

    using BindingsCache = tbb::concurrent_unordered_map<SdfPath,
            std::unique_ptr<BindingsAtPrim>, SdfPath::Hash>;

    USDSHADE_API
    static TfTokenVector GetMaterialPurposes();

    USDSHADE_API
    static const SdfPath GetResolvedTargetPathFromBindingRel(
            const UsdRelationship &bindingRel);

    USDSHADE_API
    UsdShadeMaterial ComputeBoundMaterial(
        BindingsCache *bindingsCache,
        CollectionQueryCache *collectionQueryCache,
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose,
        UsdRelationship *bindingRel=nullptr) const;

    USDSHADE_API
    UsdShadeMaterial ComputeBoundMaterial(
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose,
        UsdRelationship *bindingRel=nullptr) const;

    USDSHADE_API
    static std::vector<UsdShadeMaterial> ComputeBoundMaterials(
        const std::vector<UsdPrim> &prims, 
        const TfToken &materialPurpose=UsdShadeTokens->allPurpose,
        std::vector<UsdRelationship> *bindingRels=nullptr);

        
    // --------------------------------------------------------------------- //

    USDSHADE_API
    UsdGeomSubset CreateMaterialBindSubset(
        const TfToken &subsetName,
        const VtIntArray &indices,
        const TfToken &elementType=UsdGeomTokens->face);

    USDSHADE_API
    std::vector<UsdGeomSubset> GetMaterialBindSubsets();
    
    USDSHADE_API
    bool SetMaterialBindSubsetsFamilyType(const TfToken &familyType);

    USDSHADE_API
    TfToken GetMaterialBindSubsetsFamilyType();

    USDSHADE_API
    static bool CanContainPropertyName(const TfToken &name);


private:

    UsdRelationship _CreateDirectBindingRel(
        const TfToken &materialPurpose) const;
    
    UsdRelationship _CreateCollectionBindingRel(
        const TfToken &bindingName,
        const TfToken &materialPurpose) const;

    // Helper method for getting collection bindings when the set of all 
    // collection binding relationship names for the required purpose is 
    // known.
    CollectionBindingVector _GetCollectionBindings(
        const TfTokenVector &collBindingPropertyNames) const;
};

PXR_NAMESPACE_CLOSE_SCOPE

#endif