materialBindingAPI.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef USDSHADE_GENERATED_MATERIALBINDINGAPI_H
25 #define USDSHADE_GENERATED_MATERIALBINDINGAPI_H
26 
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdShade/api.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
35 
37 #include "pxr/usd/usdGeom/subset.h"
39 #include <tbb/concurrent_unordered_map.h>
40 
41 #include "pxr/base/vt/value.h"
42 
43 #include "pxr/base/gf/vec3d.h"
44 #include "pxr/base/gf/vec3f.h"
45 #include "pxr/base/gf/matrix4d.h"
46 
47 #include "pxr/base/tf/token.h"
48 #include "pxr/base/tf/type.h"
49 
50 PXR_NAMESPACE_OPEN_SCOPE
51 
52 class SdfAssetPath;
53 
54 // -------------------------------------------------------------------------- //
55 // MATERIALBINDINGAPI //
56 // -------------------------------------------------------------------------- //
57 
152 {
153 public:
158 
164  : UsdAPISchemaBase(prim)
165  {
166  }
167 
171  explicit UsdShadeMaterialBindingAPI(const UsdSchemaBase& schemaObj)
172  : UsdAPISchemaBase(schemaObj)
173  {
174  }
175 
177  USDSHADE_API
178  virtual ~UsdShadeMaterialBindingAPI();
179 
183  USDSHADE_API
184  static const TfTokenVector &
185  GetSchemaAttributeNames(bool includeInherited=true);
186 
196  USDSHADE_API
198  Get(const UsdStagePtr &stage, const SdfPath &path);
199 
200 
217  USDSHADE_API
218  static bool
219  CanApply(const UsdPrim &prim, std::string *whyNot=nullptr);
220 
236  USDSHADE_API
238  Apply(const UsdPrim &prim);
239 
240 protected:
244  USDSHADE_API
245  UsdSchemaKind _GetSchemaKind() const override;
246 
247 private:
248  // needs to invoke _GetStaticTfType.
249  friend class UsdSchemaRegistry;
250  USDSHADE_API
251  static const TfType &_GetStaticTfType();
252 
253  static bool _IsTypedSchema();
254 
255  // override SchemaBase virtuals.
256  USDSHADE_API
257  const TfType &_GetTfType() const override;
258 
259 public:
260  // ===================================================================== //
261  // Feel free to add custom code below this line, it will be preserved by
262  // the code generator.
263  //
264  // Just remember to:
265  // - Close the class declaration with };
266  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
267  // - Close the include guard with #endif
268  // ===================================================================== //
269  // --(BEGIN CUSTOM CODE)--
270 
278 
284  USDSHADE_API
286  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
287 
294  USDSHADE_API
296  const TfToken &bindingName,
297  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
298 
307  USDSHADE_API
308  std::vector<UsdRelationship> GetCollectionBindingRels(
309  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
310 
314  public:
318  {}
319 
320  USDSHADE_API
321  explicit DirectBinding(const UsdRelationship &bindingRel);
322 
324  USDSHADE_API
326 
329  const SdfPath &GetMaterialPath() const {
330  return _materialPath;
331  }
332 
336  return _bindingRel;
337  }
338 
340  const TfToken &GetMaterialPurpose() const {
341  return _materialPurpose;
342  }
343 
344  private:
345  // The path to the material that is bound to.
346  SdfPath _materialPath;
347 
348  // The binding relationship.
349  UsdRelationship _bindingRel;
350 
351  // The purpose of the material binding.
352  TfToken _materialPurpose;
353  };
354 
359  public:
363  {}
364 
369  USDSHADE_API
370  explicit CollectionBinding(const UsdRelationship &collBindingRel);
371 
374  USDSHADE_API
376 
379  USDSHADE_API
381 
383  USDSHADE_API
384  static bool IsCollectionBindingRel(const UsdRelationship &bindingRel);
385 
388  bool IsValid() const {
389  return CollectionBinding::IsCollectionBindingRel(_bindingRel)
390  && !GetMaterialPath().IsEmpty();
391  }
393  const SdfPath &GetCollectionPath() const {
394  return _collectionPath;
395  }
396 
398  const SdfPath &GetMaterialPath() const {
399  return _materialPath;
400  }
401 
405  return _bindingRel;
406  }
407 
408  private:
409  // The collection being bound.
410  SdfPath _collectionPath;
411 
412  // The material that is bound to.
413  SdfPath _materialPath;
414 
415  // The relationship that binds the collection to the material.
416  UsdRelationship _bindingRel;
417  };
418 
419  using CollectionBindingVector = std::vector<CollectionBinding>;
420 
431  USDSHADE_API
432  DirectBinding GetDirectBinding(
433  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
434 
456  USDSHADE_API
457  CollectionBindingVector GetCollectionBindings(
458  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
459 
466  USDSHADE_API
468  const UsdRelationship &bindingRel);
469 
479 
483  USDSHADE_API
484  static bool SetMaterialBindingStrength(
485  const UsdRelationship &bindingRel,
486  const TfToken &bindingStrength);
487 
489 
497 
517  USDSHADE_API
518  bool Bind(
519  const UsdShadeMaterial &material,
520  const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength,
521  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
522 
557  USDSHADE_API
558  bool Bind(
559  const UsdCollectionAPI &collection,
560  const UsdShadeMaterial &material,
561  const TfToken &bindingName=TfToken(),
562  const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength,
563  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
564 
568  USDSHADE_API
569  bool UnbindDirectBinding(
570  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
571 
580  USDSHADE_API
582  const TfToken &bindingName,
583  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
584 
586  USDSHADE_API
587  bool UnbindAllBindings() const;
588 
602  USDSHADE_API
604  const UsdPrim &prim,
605  const TfToken &bindingName,
606  const TfToken &materialPurpose) const;
607 
619  USDSHADE_API
621  const UsdPrim &prim,
622  const TfToken &bindingName,
623  const TfToken &materialPurpose) const;
624 
626 
673 
678  using CollectionQueryCache =
679  tbb::concurrent_unordered_map<SdfPath,
680  std::unique_ptr<UsdCollectionAPI::MembershipQuery>, SdfPath::Hash>;
681 
683  using DirectBindingPtr = std::unique_ptr<DirectBinding>;
684 
685  struct BindingsAtPrim {
689  USDSHADE_API
690  BindingsAtPrim(const UsdPrim &prim, const TfToken &materialPurpose);
691 
695  DirectBindingPtr directBinding;
696 
699  CollectionBindingVector restrictedPurposeCollBindings;
700 
702  CollectionBindingVector allPurposeCollBindings;
703  };
704 
706  friend struct BindingsAtPrim;
707 
712  using BindingsCache = tbb::concurrent_unordered_map<SdfPath,
713  std::unique_ptr<BindingsAtPrim>, SdfPath::Hash>;
714 
716  USDSHADE_API
718 
720  USDSHADE_API
722  const UsdRelationship &bindingRel);
723 
773  USDSHADE_API
775  BindingsCache *bindingsCache,
776  CollectionQueryCache *collectionQueryCache,
777  const TfToken &materialPurpose=UsdShadeTokens->allPurpose,
778  UsdRelationship *bindingRel=nullptr) const;
779 
796  USDSHADE_API
798  const TfToken &materialPurpose=UsdShadeTokens->allPurpose,
799  UsdRelationship *bindingRel=nullptr) const;
800 
815  USDSHADE_API
816  static std::vector<UsdShadeMaterial> ComputeBoundMaterials(
817  const std::vector<UsdPrim> &prims,
818  const TfToken &materialPurpose=UsdShadeTokens->allPurpose,
819  std::vector<UsdRelationship> *bindingRels=nullptr);
820 
822 
823  // --------------------------------------------------------------------- //
875 
890  USDSHADE_API
892  const TfToken &subsetName,
893  const VtIntArray &indices,
894  const TfToken &elementType=UsdGeomTokens->face);
895 
898  USDSHADE_API
899  std::vector<UsdGeomSubset> GetMaterialBindSubsets();
900 
914  USDSHADE_API
915  bool SetMaterialBindSubsetsFamilyType(const TfToken &familyType);
916 
925  USDSHADE_API
927 
930  USDSHADE_API
931  static bool CanContainPropertyName(const TfToken &name);
932 
934 
935 private:
936 
937  UsdRelationship _CreateDirectBindingRel(
938  const TfToken &materialPurpose) const;
939 
940  UsdRelationship _CreateCollectionBindingRel(
941  const TfToken &bindingName,
942  const TfToken &materialPurpose) const;
943 
944  // Helper method for getting collection bindings when the set of all
945  // collection binding relationship names for the required purpose is
946  // known.
947  CollectionBindingVector _GetCollectionBindings(
948  const TfTokenVector &collBindingPropertyNames) const;
949 };
950 
951 PXR_NAMESPACE_CLOSE_SCOPE
952 
953 #endif
USDSHADE_API bool RemovePrimFromBindingCollection(const UsdPrim &prim, const TfToken &bindingName, const TfToken &materialPurpose) const
Removes the specified prim from the collection targeted by the binding relationship corresponding to ...
const TfToken & GetMaterialPurpose() const
Returns the purpose of the direct binding.
USDSHADE_API std::vector< UsdGeomSubset > GetMaterialBindSubsets()
Returns all the existing GeomSubsets with familyName=UsdShadeTokens->materialBind below this prim.
static USDSHADE_API bool SetMaterialBindingStrength(const UsdRelationship &bindingRel, const TfToken &bindingStrength)
Sets the 'bindMaterialAs' token-valued metadata on the given binding relationship.
static USDSHADE_API TfTokenVector GetMaterialPurposes()
Returns a vector of the possible values for the 'material purpose'.
This struct is used to represent a collection-based material binding, which contains two objects - a ...
tbb::concurrent_unordered_map< SdfPath, std::unique_ptr< UsdCollectionAPI::MembershipQuery >, SdfPath::Hash > CollectionQueryCache
An unordered list of collection paths mapped to the associated collection's MembershipQuery object.
const SdfPath & GetMaterialPath() const
Returns the path to the material that is bound to by this binding.
static USDSHADE_API std::vector< UsdShadeMaterial > ComputeBoundMaterials(const std::vector< UsdPrim > &prims, const TfToken &materialPurpose=UsdShadeTokens->allPurpose, std::vector< UsdRelationship > *bindingRels=nullptr)
Static API for efficiently and concurrently computing the resolved material bindings for a vector of ...
static USDSHADE_API TfToken GetMaterialBindingStrength(const UsdRelationship &bindingRel)
Resolves the 'bindMaterialAs' token-valued metadata on the given binding relationship and returns it.
The base class for all API schemas.
const SdfPath & GetCollectionPath() const
Returns the path to the collection that is bound by this binding.
USDSHADE_API UsdCollectionAPI GetCollection() const
Constructs and returns the CollectionAPI object for the collection that is bound by this collection-b...
USDSHADE_API bool Bind(const UsdShadeMaterial &material, const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength, const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
Authors a direct binding to the given material on this prim.
tbb::concurrent_unordered_map< SdfPath, std::unique_ptr< BindingsAtPrim >, SdfPath::Hash > BindingsCache
An unordered list of prim-paths mapped to the corresponding set of bindings at the associated prim.
USDSHADE_API UsdRelationship GetCollectionBindingRel(const TfToken &bindingName, const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
Returns the collection-based material-binding relationship with the given bindingName and materialPur...
DirectBinding()
Default constructor initializes a DirectBinding object with invalid material and bindingRel data memb...
UsdSchemaKind
An enum representing which kind of schema a given schema class belongs to.
Definition: common.h:127
UsdShadeMaterialBindingAPI is an API schema that provides an interface for binding materials to prims...
USDSHADE_API DirectBinding GetDirectBinding(const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
Computes and returns the direct binding for the given material purpose on this prim.
Single Apply API schema.
const UsdRelationship & GetBindingRel() const
Returns the binding-relationship that represents this direct binding.
USDSHADE_API std::vector< UsdRelationship > GetCollectionBindingRels(const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
Returns the list of collection-based material binding relationships on this prim for the given materi...
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
bool IsValid() const
Returns true if the CollectionBinding points to a non-empty material path and collection.
This is a general purpose API schema, used to describe a collection of heterogeneous objects within t...
USDGEOM_API TfStaticData< UsdGeomTokensType > UsdGeomTokens
A global variable with static, efficient TfTokens for use in all public USD API.
static USDSHADE_API UsdShadeMaterialBindingAPI Get(const UsdStagePtr &stage, const SdfPath &path)
Return a UsdShadeMaterialBindingAPI holding the prim adhering to this schema at path on stage.
USDSHADE_API bool UnbindAllBindings() const
Unbinds all direct and collection-based bindings on this prim.
USDSHADE_API bool SetMaterialBindSubsetsFamilyType(const TfToken &familyType)
Author the familyType of the "materialBind" family of GeomSubsets on this prim.
USDSHADE_API UsdShadeMaterial GetMaterial() const
Constructs and returns the material object that this collection-based binding binds to.
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:134
static USDSHADE_API UsdShadeMaterialBindingAPI Apply(const UsdPrim &prim)
Applies this single-apply API schema to the given prim.
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
USDSHADE_API UsdSchemaKind _GetSchemaKind() const override
Returns the kind of schema this class belongs to.
static const UsdSchemaKind schemaKind
Compile time constant representing what kind of schema this class is.
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:290
USDSHADE_API CollectionBindingVector GetCollectionBindings(const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
Returns all the collection-based bindings on this prim for the given material purpose.
USDSHADE_API TfStaticData< UsdShadeTokensType > UsdShadeTokens
A global variable with static, efficient TfTokens for use in all public USD API.
std::unique_ptr< DirectBinding > DirectBindingPtr
Alias for a unique_ptr to a DirectBinding object.
USDSHADE_API UsdRelationship GetDirectBindingRel(const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
Returns the direct material-binding relationship on this prim for the given material purpose.
static USDSHADE_API bool CanApply(const UsdPrim &prim, std::string *whyNot=nullptr)
Returns true if this single-apply API schema can be applied to the given prim.
CollectionBinding()
Default constructor initializes a CollectionBinding object with invalid collection,...
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:128
virtual USDSHADE_API ~UsdShadeMaterialBindingAPI()
Destructor.
Contains an asset path and an optional resolved path.
Definition: assetPath.h:47
Encodes a subset of a piece of geometry (i.e.
Definition: subset.h:85
USDSHADE_API UsdShadeMaterial ComputeBoundMaterial(BindingsCache *bindingsCache, CollectionQueryCache *collectionQueryCache, const TfToken &materialPurpose=UsdShadeTokens->allPurpose, UsdRelationship *bindingRel=nullptr) const
Computes the resolved bound material for this prim, for the given material purpose.
static USDSHADE_API bool IsCollectionBindingRel(const UsdRelationship &bindingRel)
Checks if the bindingRel identifies a collection.
UsdShadeMaterialBindingAPI(const UsdSchemaBase &schemaObj)
Construct a UsdShadeMaterialBindingAPI on the prim held by schemaObj .
USDSHADE_API UsdShadeMaterial GetMaterial() const
Gets the material object that this direct binding binds to.
USDSHADE_API bool AddPrimToBindingCollection(const UsdPrim &prim, const TfToken &bindingName, const TfToken &materialPurpose) const
Adds the specified prim to the collection targeted by the binding relationship corresponding to given...
friend struct BindingsAtPrim
BindingsAtPrim needs to invoke private _GetCollectionBindings().
TfType represents a dynamic runtime type.
Definition: type.h:64
Singleton registry that provides access to schema type information and the prim definitions for regis...
A Material provides a container into which multiple "render targets" can add data that defines a "sha...
Definition: material.h:111
UsdShadeMaterialBindingAPI(const UsdPrim &prim=UsdPrim())
Construct a UsdShadeMaterialBindingAPI on UsdPrim prim .
The base class for all schema types in Usd.
Definition: schemaBase.h:56
USDSHADE_API UsdGeomSubset CreateMaterialBindSubset(const TfToken &subsetName, const VtIntArray &indices, const TfToken &elementType=UsdGeomTokens->face)
Creates a GeomSubset named subsetName with element type, elementType and familyName materialBind belo...
USDSHADE_API bool UnbindDirectBinding(const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
Unbinds the direct binding for the given material purpose (materialPurpose) on this prim.
bool IsEmpty() const noexcept
Returns true if this is the empty path (SdfPath::EmptyPath()).
Definition: path.h:419
USDSHADE_API bool UnbindCollectionBinding(const TfToken &bindingName, const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const
Unbinds the collection-based binding with the given bindingName, for the given materialPurpose on thi...
static USDSHADE_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Return a vector of names of all pre-declared attributes for this schema class and all its ancestor cl...
static USDSHADE_API const SdfPath GetResolvedTargetPathFromBindingRel(const UsdRelationship &bindingRel)
returns the path of the resolved target identified by bindingRel.
const UsdRelationship & GetBindingRel() const
Returns the binding-relationship that represents this collection- based binding.
const SdfPath & GetMaterialPath() const
Returns the path to the material that is bound to by this direct binding.
USDSHADE_API TfToken GetMaterialBindSubsetsFamilyType()
Returns the familyType of the family of "materialBind" GeomSubsets on this prim.
static USDSHADE_API bool CanContainPropertyName(const TfToken &name)
Test whether a given name contains the "material:binding:" prefix.
This class represents a direct material binding.
TfToken class for efficient string referencing and hashing, plus conversions to and from stl string c...