HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
subset.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 USDGEOM_GENERATED_SUBSET_H
25 #define USDGEOM_GENERATED_SUBSET_H
26 
27 /// \file usdGeom/subset.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdGeom/api.h"
31 #include "pxr/usd/usd/typed.h"
32 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/stage.h"
34 #include "pxr/usd/usdGeom/tokens.h"
35 
36 #include "pxr/base/tf/token.h"
38 
39 
40 #include "pxr/base/vt/value.h"
41 
42 #include "pxr/base/gf/vec3d.h"
43 #include "pxr/base/gf/vec3f.h"
44 #include "pxr/base/gf/matrix4d.h"
45 
46 #include "pxr/base/tf/token.h"
47 #include "pxr/base/tf/type.h"
48 
50 
51 class SdfAssetPath;
52 
53 // -------------------------------------------------------------------------- //
54 // GEOMSUBSET //
55 // -------------------------------------------------------------------------- //
56 
57 /// \class UsdGeomSubset
58 ///
59 /// Encodes a subset of a piece of geometry (i.e. a UsdGeomImageable)
60 /// as a set of indices. Currently only supports encoding of face-subsets, but
61 /// could be extended in the future to support subsets representing edges,
62 /// segments, points etc.
63 ///
64 /// To apply to a geometric prim, a GeomSubset prim must be defined as a
65 /// child of it in namespace. This restriction makes it easy and efficient
66 /// to discover subsets of a prim. We might want to relax this restriction if
67 /// it's common to have multiple <b>families</b> of subsets on a gprim and if
68 /// it's useful to be able to organize subsets belonging to a </b>family</b>
69 /// under a common scope. See 'familyName' attribute for more info on defining
70 /// a family of subsets.
71 ///
72 /// Note that a GeomSubset isn't an imageable (i.e. doesn't derive from
73 /// UsdGeomImageable). So, you can't author <b>visibility</b> for it or
74 /// override its <b>purpose</b>.
75 ///
76 /// Materials are bound to GeomSubsets just as they are for regular
77 /// geometry using API available in UsdShade (UsdShadeMaterial::Bind).
78 ///
79 ///
80 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
81 /// that are text/tokens, the actual token is published and defined in \ref UsdGeomTokens.
82 /// So to set an attribute to the value "rightHanded", use UsdGeomTokens->rightHanded
83 /// as the value.
84 ///
85 class UsdGeomSubset : public UsdTyped
86 {
87 public:
88  /// Compile time constant representing what kind of schema this class is.
89  ///
90  /// \sa UsdSchemaType
92 
93  /// Construct a UsdGeomSubset on UsdPrim \p prim .
94  /// Equivalent to UsdGeomSubset::Get(prim.GetStage(), prim.GetPath())
95  /// for a \em valid \p prim, but will not immediately throw an error for
96  /// an invalid \p prim
97  explicit UsdGeomSubset(const UsdPrim& prim=UsdPrim())
98  : UsdTyped(prim)
99  {
100  }
101 
102  /// Construct a UsdGeomSubset on the prim held by \p schemaObj .
103  /// Should be preferred over UsdGeomSubset(schemaObj.GetPrim()),
104  /// as it preserves SchemaBase state.
105  explicit UsdGeomSubset(const UsdSchemaBase& schemaObj)
106  : UsdTyped(schemaObj)
107  {
108  }
109 
110  /// Destructor.
112  virtual ~UsdGeomSubset();
113 
114  /// Return a vector of names of all pre-declared attributes for this schema
115  /// class and all its ancestor classes. Does not include attributes that
116  /// may be authored by custom/extended methods of the schemas involved.
118  static const TfTokenVector &
119  GetSchemaAttributeNames(bool includeInherited=true);
120 
121  /// Return a UsdGeomSubset holding the prim adhering to this
122  /// schema at \p path on \p stage. If no prim exists at \p path on
123  /// \p stage, or if the prim at that path does not adhere to this schema,
124  /// return an invalid schema object. This is shorthand for the following:
125  ///
126  /// \code
127  /// UsdGeomSubset(stage->GetPrimAtPath(path));
128  /// \endcode
129  ///
131  static UsdGeomSubset
132  Get(const UsdStagePtr &stage, const SdfPath &path);
133 
134  /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path
135  /// is defined (according to UsdPrim::IsDefined()) on this stage.
136  ///
137  /// If a prim adhering to this schema at \p path is already defined on this
138  /// stage, return that prim. Otherwise author an \a SdfPrimSpec with
139  /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for
140  /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s
141  /// with \p specifier == \a SdfSpecifierDef and empty typeName at the
142  /// current EditTarget for any nonexistent, or existing but not \a Defined
143  /// ancestors.
144  ///
145  /// The given \a path must be an absolute prim path that does not contain
146  /// any variant selections.
147  ///
148  /// If it is impossible to author any of the necessary PrimSpecs, (for
149  /// example, in case \a path cannot map to the current UsdEditTarget's
150  /// namespace) issue an error and return an invalid \a UsdPrim.
151  ///
152  /// Note that this method may return a defined prim whose typeName does not
153  /// specify this schema class, in case a stronger typeName opinion overrides
154  /// the opinion at the current EditTarget.
155  ///
157  static UsdGeomSubset
158  Define(const UsdStagePtr &stage, const SdfPath &path);
159 
160 protected:
161  /// Returns the type of schema this class belongs to.
162  ///
163  /// \sa UsdSchemaType
165  UsdSchemaType _GetSchemaType() const override;
166 
167 private:
168  // needs to invoke _GetStaticTfType.
169  friend class UsdSchemaRegistry;
171  static const TfType &_GetStaticTfType();
172 
173  static bool _IsTypedSchema();
174 
175  // override SchemaBase virtuals.
177  const TfType &_GetTfType() const override;
178 
179 public:
180  // --------------------------------------------------------------------- //
181  // ELEMENTTYPE
182  // --------------------------------------------------------------------- //
183  /// The type of element that the indices target. Currently only
184  /// allows "face" and defaults to it.
185  ///
186  /// | ||
187  /// | -- | -- |
188  /// | Declaration | `uniform token elementType = "face"` |
189  /// | C++ Type | TfToken |
190  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
191  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
192  /// | \ref UsdGeomTokens "Allowed Values" | face |
195 
196  /// See GetElementTypeAttr(), and also
197  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
198  /// If specified, author \p defaultValue as the attribute's default,
199  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
200  /// the default for \p writeSparsely is \c false.
202  UsdAttribute CreateElementTypeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
203 
204 public:
205  // --------------------------------------------------------------------- //
206  // INDICES
207  // --------------------------------------------------------------------- //
208  /// The set of indices included in this subset. The indices need not
209  /// be sorted, but the same index should not appear more than once.
210  ///
211  /// | ||
212  /// | -- | -- |
213  /// | Declaration | `int[] indices = []` |
214  /// | C++ Type | VtArray<int> |
215  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->IntArray |
218 
219  /// See GetIndicesAttr(), and also
220  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
221  /// If specified, author \p defaultValue as the attribute's default,
222  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
223  /// the default for \p writeSparsely is \c false.
225  UsdAttribute CreateIndicesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
226 
227 public:
228  // --------------------------------------------------------------------- //
229  // FAMILYNAME
230  // --------------------------------------------------------------------- //
231  /// The name of the family of subsets that this subset belongs to.
232  /// This is optional and is primarily useful when there are multiple
233  /// families of subsets under a geometric prim. In some cases, this could
234  /// also be used for achieving proper roundtripping of subset data between
235  /// DCC apps.
236  /// When multiple subsets belonging to a prim have the same familyName, they
237  /// are said to belong to the family. A <i>familyType</i> value can be
238  /// encoded on the owner of a family of subsets as a token using the static
239  /// method UsdGeomSubset::SetFamilyType(). "familyType" can have one of the
240  /// following values:
241  /// <ul><li><b>UsdGeomTokens->partition</b>: implies that every element of
242  /// the whole geometry appears exactly once in only one of the subsets
243  /// belonging to the family.</li>
244  /// <li><b>UsdGeomTokens->nonOverlapping</b>: an element that appears in one
245  /// subset may not appear in any other subset belonging to the family.</li>
246  /// <li><b>UsdGeomTokens->unrestricted</b>: implies that there are no
247  /// restrictions w.r.t. the membership of elements in the subsets. They
248  /// could be overlapping and the union of all subsets in the family may
249  /// not represent the whole.</li>
250  /// </ul>
251  /// \note The validity of subset data is not enforced by the authoring
252  /// APIs, however they can be checked using UsdGeomSubset::ValidateFamily().
253  ///
254  ///
255  /// | ||
256  /// | -- | -- |
257  /// | Declaration | `uniform token familyName = ""` |
258  /// | C++ Type | TfToken |
259  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
260  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
263 
264  /// See GetFamilyNameAttr(), and also
265  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
266  /// If specified, author \p defaultValue as the attribute's default,
267  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
268  /// the default for \p writeSparsely is \c false.
270  UsdAttribute CreateFamilyNameAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
271 
272 public:
273  // ===================================================================== //
274  // Feel free to add custom code below this line, it will be preserved by
275  // the code generator.
276  //
277  // Just remember to:
278  // - Close the class declaration with };
279  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
280  // - Close the include guard with #endif
281  // ===================================================================== //
282  // --(BEGIN CUSTOM CODE)--
283 
284  /// Creates a new GeomSubset below the given \p geom with the given
285  /// name, \p subsetName, element type, \p elementType and \p indices.
286  ///
287  /// If a subset named \p subsetName already exists below \p geom, then
288  /// this updates its attributes with the values of the provided arguments
289  /// (indices value at time 'default' will be updated) and returns it.
290  ///
291  /// The family type is set / updated on \p geom only if a non-empty value
292  /// is passed in for \p familyType and \p familyName.
295  const UsdGeomImageable &geom,
296  const TfToken &subsetName,
297  const TfToken &elementType,
298  const VtIntArray &indices,
299  const TfToken &familyName=TfToken(),
300  const TfToken &familyType=TfToken());
301 
302  /// Creates a new GeomSubset below the given imageable, \p geom with the
303  /// given name, \p subsetName, element type, \p elementType and \p indices.
304  ///
305  /// If a subset named \p subsetName already exists below \p geom, then
306  /// this creates a new subset by appending a suitable index as suffix to
307  /// \p subsetName (eg, subsetName_1) to avoid name collisions.
308  ///
309  /// The family type is set / updated on \p geom only if a non-empty value
310  /// is passed in for \p familyType and \p familyName.
313  const UsdGeomImageable &geom,
314  const TfToken &subsetName,
315  const TfToken &elementType,
316  const VtIntArray &indices,
317  const TfToken &familyName=TfToken(),
318  const TfToken &familyType=TfToken());
319 
320  /// Returns all the GeomSubsets defined on the given imageable, \p geom.
322  static std::vector<UsdGeomSubset> GetAllGeomSubsets(
323  const UsdGeomImageable &geom);
324 
325  /// Returns all the GeomSubsets of the given \p elementType belonging to
326  /// the specified family, \p familyName on the given imageable, \p geom.
327  /// If \p elementType is empty, then subsets containing all element types
328  /// are returned.
329  /// If \p familyName is left empty, then all subsets of the specified
330  /// \p elementType will be returned.
332  static std::vector<UsdGeomSubset> GetGeomSubsets(
333  const UsdGeomImageable &geom,
334  const TfToken &elementType=TfToken(),
335  const TfToken &familyName=TfToken());
336 
337  /// Returns the names of all the families of GeomSubsets defined on the given
338  /// imageable, \p geom.
341  const UsdGeomImageable &geom);
342 
343  /// This method is used to encode the type of family that the GeomSubsets
344  /// on the given geometric prim \p geom, with the given family name,
345  /// \p familyName belong to.
346  ///
347  /// See \ref UsdGeomSubset::GetFamilyNameAttr for the possible values for
348  /// \p familyType.
349  ///
350  /// When a family of GeomSubsets is tagged as a UsdGeomTokens->partition or
351  /// UsdGeomTokens->nonOverlapping, the validity of the data (i.e.
352  /// mutual exclusivity and/or wholeness) is not enforced by the authoring
353  /// APIs. Use ValidateFamily() to validate the data in a family of
354  /// GeomSubsets.
355  ///
356  /// \return Returns false upon failure to create or set the appropriate
357  /// attribute on \p geom.
359  static bool SetFamilyType(
360  const UsdGeomImageable &geom,
361  const TfToken &familyName,
362  const TfToken &familyType);
363 
364  /// Returns the type of family that the GeomSubsets on the given geometric
365  /// prim \p geom, with the given family name, \p familyName belong to.
366  ///
367  /// This only returns the token that's encoded on \p geom and does not perform
368  /// any actual validation on the family of GeomSubsets. Please use
369  /// ValidateFamily() for such validation.
370  ///
371  /// When familyType is not set on \p geom, the fallback value
372  /// UsdTokens->unrestricted is returned.
374  static TfToken GetFamilyType(
375  const UsdGeomImageable &geom,
376  const TfToken &familyName);
377 
378  /// Utility for getting the list of indices that are not assigned to any of
379  /// the GeomSubsets in \p subsets at the timeCode, \p time, given the
380  /// element count (total number of indices in the array being subdivided),
381  /// \p elementCount.
383  static VtIntArray GetUnassignedIndices(
384  const std::vector<UsdGeomSubset> &subsets,
385  const size_t elementCount,
387 
388  /// Validates the data in the given set of GeomSubsets, \p subsets, given
389  /// the total number of elements in the array being subdivided,
390  /// \p elementCount and the \p familyType that the subsets belong to.
391  ///
392  /// For proper validation of indices in \p subsets, all of the GeomSubsets
393  /// must have the same 'elementType'.
394  ///
395  /// If one or more subsets contain invalid data, then false is returned and
396  /// \p reason is populated with a string explaining the reason why it is
397  /// invalid.
398  ///
399  /// The python version of this method returns a tuple containing
400  /// a (bool, string), where the bool has the validity of the subsets and
401  /// the string contains the reason (if they're invalid).
402  ///
404  static bool ValidateSubsets(
405  const std::vector<UsdGeomSubset> &subsets,
406  const size_t elementCount,
407  const TfToken &familyType,
408  std::string * const reason);
409 
410  /// Validates whether the family of subsets identified by the given
411  /// \p familyName and \p elementType on the given imageable, \p geom contain
412  /// valid data. If the family is designated as a partition or as
413  /// non-overlapping using SetFamilyType(), then the validity of the data
414  /// is checked. If the familyType is "unrestricted", then this performs only
415  /// bounds checking of the values in the "indices" arrays.
416  ///
417  /// If \p reason is not NULL, then it is populated with a string explaining
418  /// why the family is invalid, if it is invalid.
419  ///
420  /// The python version of this method returns a tuple containing
421  /// a (bool, string), where the bool has the validity of the family and
422  /// the string contains the reason (if it's invalid).
423  ///
425  static bool ValidateFamily(
426  const UsdGeomImageable &geom,
427  const TfToken &elementType,
428  const TfToken &familyName,
429  std::string * const reason);
430 };
431 
433 
434 #endif
USDGEOM_API UsdAttribute GetIndicesAttr() const
static USDGEOM_API std::vector< UsdGeomSubset > GetAllGeomSubsets(const UsdGeomImageable &geom)
Returns all the GeomSubsets defined on the given imageable, geom.
static USDGEOM_API UsdGeomSubset CreateUniqueGeomSubset(const UsdGeomImageable &geom, const TfToken &subsetName, const TfToken &elementType, const VtIntArray &indices, const TfToken &familyName=TfToken(), const TfToken &familyType=TfToken())
UsdGeomSubset(const UsdPrim &prim=UsdPrim())
Definition: subset.h:97
static constexpr UsdTimeCode EarliestTime()
Definition: timeCode.h:102
GT_API const UT_StringHolder time
static USDGEOM_API bool ValidateFamily(const UsdGeomImageable &geom, const TfToken &elementType, const TfToken &familyName, std::string *const reason)
UsdGeomSubset(const UsdSchemaBase &schemaObj)
Definition: subset.h:105
static const UsdSchemaType schemaType
Definition: subset.h:91
USDGEOM_API UsdAttribute GetElementTypeAttr() const
Represents a concrete typed schema.
USDGEOM_API UsdAttribute CreateFamilyNameAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute GetFamilyNameAttr() const
Definition: token.h:87
GLuint GLuint GLsizei GLenum const void * indices
Definition: glew.h:1253
static USDGEOM_API TfToken GetFamilyType(const UsdGeomImageable &geom, const TfToken &familyName)
UsdSchemaType
Definition: common.h:127
Definition: prim.h:132
Definition: typed.h:47
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:446
Definition: path.h:288
USDGEOM_API UsdSchemaType _GetSchemaType() const override
static USDGEOM_API bool SetFamilyType(const UsdGeomImageable &geom, const TfToken &familyName, const TfToken &familyType)
GLsizei const GLchar *const * path
Definition: glew.h:6461
static USDGEOM_API UsdGeomSubset CreateGeomSubset(const UsdGeomImageable &geom, const TfToken &subsetName, const TfToken &elementType, const VtIntArray &indices, const TfToken &familyName=TfToken(), const TfToken &familyType=TfToken())
static USDGEOM_API TfToken::Set GetAllGeomSubsetFamilyNames(const UsdGeomImageable &geom)
USDGEOM_API UsdAttribute CreateIndicesAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
GLsizei const GLchar *const * string
Definition: glew.h:1844
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
static USDGEOM_API bool ValidateSubsets(const std::vector< UsdGeomSubset > &subsets, const size_t elementCount, const TfToken &familyType, std::string *const reason)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: type.h:64
USDGEOM_API UsdAttribute CreateElementTypeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
static USDGEOM_API UsdGeomSubset Get(const UsdStagePtr &stage, const SdfPath &path)
#define USDGEOM_API
Definition: api.h:40
static USDGEOM_API UsdGeomSubset Define(const UsdStagePtr &stage, const SdfPath &path)
static USDGEOM_API VtIntArray GetUnassignedIndices(const std::vector< UsdGeomSubset > &subsets, const size_t elementCount, const UsdTimeCode &time=UsdTimeCode::EarliestTime())
virtual USDGEOM_API ~UsdGeomSubset()
Destructor.
Definition: value.h:174
std::set< TfToken, TfTokenFastArbitraryLessThan > Set
Definition: token.h:183
static USDGEOM_API std::vector< UsdGeomSubset > GetGeomSubsets(const UsdGeomImageable &geom, const TfToken &elementType=TfToken(), const TfToken &familyName=TfToken())