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 
384  bool IsValid() const {
385  return GetCollection() && GetMaterial();
386  }
388  const SdfPath &GetCollectionPath() const {
389  return _collectionPath;
390  }
391 
393  const SdfPath &GetMaterialPath() const {
394  return _materialPath;
395  }
396 
400  return _bindingRel;
401  }
402 
403  private:
404  // The collection being bound.
405  SdfPath _collectionPath;
406 
407  // The material that is bound to.
408  SdfPath _materialPath;
409 
410  // The relationship that binds the collection to the material.
411  UsdRelationship _bindingRel;
412  };
413 
414  using CollectionBindingVector = std::vector<CollectionBinding>;
415 
426  USDSHADE_API
427  DirectBinding GetDirectBinding(
428  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
429 
451  USDSHADE_API
452  CollectionBindingVector GetCollectionBindings(
453  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
454 
461  USDSHADE_API
463  const UsdRelationship &bindingRel);
464 
474 
478  USDSHADE_API
479  static bool SetMaterialBindingStrength(
480  const UsdRelationship &bindingRel,
481  const TfToken &bindingStrength);
482 
484 
492 
512  USDSHADE_API
513  bool Bind(
514  const UsdShadeMaterial &material,
515  const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength,
516  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
517 
552  USDSHADE_API
553  bool Bind(
554  const UsdCollectionAPI &collection,
555  const UsdShadeMaterial &material,
556  const TfToken &bindingName=TfToken(),
557  const TfToken &bindingStrength=UsdShadeTokens->fallbackStrength,
558  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
559 
563  USDSHADE_API
564  bool UnbindDirectBinding(
565  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
566 
571  USDSHADE_API
573  const TfToken &bindingName,
574  const TfToken &materialPurpose=UsdShadeTokens->allPurpose) const;
575 
577  USDSHADE_API
578  bool UnbindAllBindings() const;
579 
593  USDSHADE_API
595  const UsdPrim &prim,
596  const TfToken &bindingName,
597  const TfToken &materialPurpose) const;
598 
610  USDSHADE_API
612  const UsdPrim &prim,
613  const TfToken &bindingName,
614  const TfToken &materialPurpose) const;
615 
617 
664 
669  using CollectionQueryCache =
670  tbb::concurrent_unordered_map<SdfPath,
671  std::unique_ptr<UsdCollectionAPI::MembershipQuery>, SdfPath::Hash>;
672 
674  using DirectBindingPtr = std::unique_ptr<DirectBinding>;
675 
676  struct BindingsAtPrim {
680  USDSHADE_API
681  BindingsAtPrim(const UsdPrim &prim, const TfToken &materialPurpose);
682 
686  DirectBindingPtr directBinding;
687 
690  CollectionBindingVector restrictedPurposeCollBindings;
691 
693  CollectionBindingVector allPurposeCollBindings;
694  };
695 
697  friend struct BindingsAtPrim;
698 
703  using BindingsCache = tbb::concurrent_unordered_map<SdfPath,
704  std::unique_ptr<BindingsAtPrim>, SdfPath::Hash>;
705 
746  USDSHADE_API
748  BindingsCache *bindingsCache,
749  CollectionQueryCache *collectionQueryCache,
750  const TfToken &materialPurpose=UsdShadeTokens->allPurpose,
751  UsdRelationship *bindingRel=nullptr) const;
752 
769  USDSHADE_API
771  const TfToken &materialPurpose=UsdShadeTokens->allPurpose,
772  UsdRelationship *bindingRel=nullptr) const;
773 
788  USDSHADE_API
789  static std::vector<UsdShadeMaterial> ComputeBoundMaterials(
790  const std::vector<UsdPrim> &prims,
791  const TfToken &materialPurpose=UsdShadeTokens->allPurpose,
792  std::vector<UsdRelationship> *bindingRels=nullptr);
793 
795 
796  // --------------------------------------------------------------------- //
848 
863  USDSHADE_API
865  const TfToken &subsetName,
866  const VtIntArray &indices,
867  const TfToken &elementType=UsdGeomTokens->face);
868 
871  USDSHADE_API
872  std::vector<UsdGeomSubset> GetMaterialBindSubsets();
873 
887  USDSHADE_API
888  bool SetMaterialBindSubsetsFamilyType(const TfToken &familyType);
889 
898  USDSHADE_API
900 
903  USDSHADE_API
904  static bool CanContainPropertyName(const TfToken &name);
905 
907 
908 private:
909 
910  UsdRelationship _CreateDirectBindingRel(
911  const TfToken &materialPurpose) const;
912 
913  UsdRelationship _CreateCollectionBindingRel(
914  const TfToken &bindingName,
915  const TfToken &materialPurpose) const;
916 
917  // Helper method for getting collection bindings when the set of all
918  // collection binding relationship names for the required purpose is
919  // known.
920  CollectionBindingVector _GetCollectionBindings(
921  const TfTokenVector &collBindingPropertyNames) const;
922 };
923 
924 PXR_NAMESPACE_CLOSE_SCOPE
925 
926 #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.
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 valid material 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:132
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:288
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
This is an overloaded member function, provided for convenience. It differs from the above function o...
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.
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...
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...