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 terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef USDGEOM_GENERATED_SUBSET_H
8 #define USDGEOM_GENERATED_SUBSET_H
9 
10 /// \file usdGeom/subset.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usdGeom/api.h"
14 #include "pxr/usd/usd/typed.h"
15 #include "pxr/usd/usd/prim.h"
16 #include "pxr/usd/usd/stage.h"
17 #include "pxr/usd/usdGeom/tokens.h"
18 
19 #include "pxr/base/tf/token.h"
21 #include "pxr/usd/usdGeom/mesh.h"
24 
25 
26 #include "pxr/base/vt/value.h"
27 
28 #include "pxr/base/gf/vec3d.h"
29 #include "pxr/base/gf/vec3f.h"
30 #include "pxr/base/gf/matrix4d.h"
31 
32 #include "pxr/base/tf/token.h"
33 #include "pxr/base/tf/type.h"
34 
36 
37 class SdfAssetPath;
38 
39 // -------------------------------------------------------------------------- //
40 // GEOMSUBSET //
41 // -------------------------------------------------------------------------- //
42 
43 /// \class UsdGeomSubset
44 ///
45 /// Encodes a subset of a piece of geometry (i.e. a UsdGeomImageable)
46 /// as a set of indices. Currently supports encoding subsets of faces,
47 /// points, edges, segments, and tetrahedrons.
48 ///
49 /// To apply to a geometric prim, a GeomSubset prim must be the prim's direct
50 /// child in namespace, and possess a concrete defining specifier (i.e. def).
51 /// This restriction makes it easy and efficient to discover subsets of a prim.
52 /// We might want to relax this restriction if it's common to have multiple
53 /// <b>families</b> of subsets on a gprim and if it's useful to be able to
54 /// organize subsets belonging to a <b>family</b> under a common scope. See
55 /// 'familyName' attribute for more info on defining a family of subsets.
56 ///
57 /// Note that a GeomSubset isn't an imageable (i.e. doesn't derive from
58 /// UsdGeomImageable). So, you can't author <b>visibility</b> for it or
59 /// override its <b>purpose</b>.
60 ///
61 /// Materials are bound to GeomSubsets just as they are for regular
62 /// geometry using API available in UsdShade (UsdShadeMaterial::Bind).
63 ///
64 ///
65 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
66 /// that are text/tokens, the actual token is published and defined in \ref UsdGeomTokens.
67 /// So to set an attribute to the value "rightHanded", use UsdGeomTokens->rightHanded
68 /// as the value.
69 ///
70 class UsdGeomSubset : public UsdTyped
71 {
72 public:
73  /// Compile time constant representing what kind of schema this class is.
74  ///
75  /// \sa UsdSchemaKind
77 
78  /// Construct a UsdGeomSubset on UsdPrim \p prim .
79  /// Equivalent to UsdGeomSubset::Get(prim.GetStage(), prim.GetPath())
80  /// for a \em valid \p prim, but will not immediately throw an error for
81  /// an invalid \p prim
82  explicit UsdGeomSubset(const UsdPrim& prim=UsdPrim())
83  : UsdTyped(prim)
84  {
85  }
86 
87  /// Construct a UsdGeomSubset on the prim held by \p schemaObj .
88  /// Should be preferred over UsdGeomSubset(schemaObj.GetPrim()),
89  /// as it preserves SchemaBase state.
90  explicit UsdGeomSubset(const UsdSchemaBase& schemaObj)
91  : UsdTyped(schemaObj)
92  {
93  }
94 
95  /// Destructor.
97  virtual ~UsdGeomSubset();
98 
99  /// Return a vector of names of all pre-declared attributes for this schema
100  /// class and all its ancestor classes. Does not include attributes that
101  /// may be authored by custom/extended methods of the schemas involved.
103  static const TfTokenVector &
104  GetSchemaAttributeNames(bool includeInherited=true);
105 
106  /// Return a UsdGeomSubset holding the prim adhering to this
107  /// schema at \p path on \p stage. If no prim exists at \p path on
108  /// \p stage, or if the prim at that path does not adhere to this schema,
109  /// return an invalid schema object. This is shorthand for the following:
110  ///
111  /// \code
112  /// UsdGeomSubset(stage->GetPrimAtPath(path));
113  /// \endcode
114  ///
116  static UsdGeomSubset
117  Get(const UsdStagePtr &stage, const SdfPath &path);
118 
119  /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path
120  /// is defined (according to UsdPrim::IsDefined()) on this stage.
121  ///
122  /// If a prim adhering to this schema at \p path is already defined on this
123  /// stage, return that prim. Otherwise author an \a SdfPrimSpec with
124  /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for
125  /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s
126  /// with \p specifier == \a SdfSpecifierDef and empty typeName at the
127  /// current EditTarget for any nonexistent, or existing but not \a Defined
128  /// ancestors.
129  ///
130  /// The given \a path must be an absolute prim path that does not contain
131  /// any variant selections.
132  ///
133  /// If it is impossible to author any of the necessary PrimSpecs, (for
134  /// example, in case \a path cannot map to the current UsdEditTarget's
135  /// namespace) issue an error and return an invalid \a UsdPrim.
136  ///
137  /// Note that this method may return a defined prim whose typeName does not
138  /// specify this schema class, in case a stronger typeName opinion overrides
139  /// the opinion at the current EditTarget.
140  ///
142  static UsdGeomSubset
143  Define(const UsdStagePtr &stage, const SdfPath &path);
144 
145 protected:
146  /// Returns the kind of schema this class belongs to.
147  ///
148  /// \sa UsdSchemaKind
150  UsdSchemaKind _GetSchemaKind() const override;
151 
152 private:
153  // needs to invoke _GetStaticTfType.
154  friend class UsdSchemaRegistry;
156  static const TfType &_GetStaticTfType();
157 
158  static bool _IsTypedSchema();
159 
160  // override SchemaBase virtuals.
162  const TfType &_GetTfType() const override;
163 
164 public:
165  // --------------------------------------------------------------------- //
166  // ELEMENTTYPE
167  // --------------------------------------------------------------------- //
168  /// The type of element that the indices target. "elementType" can
169  /// have one of the following values:
170  /// <ul><li><b>face</b>: Identifies faces on a Gprim's surface. For a
171  /// UsdGeomMesh, each element of the _indices_ attribute would refer to
172  /// an element of the Mesh's _faceCounts_ attribute. For a UsdGeomTetMesh,
173  /// each element of the _indices_ attribute would refer to an element of
174  /// the Mesh's _surfaceFaceVertexIndices_ attribute.</li>
175  /// <li><b>point</b>: for any UsdGeomPointBased, each
176  /// element of the _indices_ attribute would refer to an element of the
177  /// Mesh's _points_ attribute</li>
178  /// <li><b>edge</b>: for any UsdGeomMesh, each pair of elements
179  /// in the _indices_ attribute would refer to a pair of points of the
180  /// Mesh's _points_ attribute that are connected as an implicit edge on the
181  /// Mesh. These edges are derived from the Mesh's _faceVertexIndices_
182  /// attribute. Edges are not currently defined for a UsdGeomTetMesh, but
183  /// could be derived from all tetrahedron edges or surface face edges only
184  /// if a specific use-case arises.</li>
185  /// <li><b>segment</b>: for any Curve, each pair of elements
186  /// in the _indices_ attribute would refer to a pair of indices
187  /// (_curveIndex_, _segmentIndex_) where _curveIndex_ is the position of
188  /// the specified curve in the Curve's _curveVertexCounts_ attribute, and
189  /// _segmentIndex_ is the index of the segment within that curve.</li>
190  /// <li><b>tetrahedron</b>: for any UsdGeomTetMesh, each element of the
191  /// _indices_ attribute would refer to an element of the TetMesh's
192  /// _tetVertexIndices_ attribute.
193  /// </li></ul>
194  ///
195  /// | ||
196  /// | -- | -- |
197  /// | Declaration | `uniform token elementType = "face"` |
198  /// | C++ Type | TfToken |
199  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
200  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
201  /// | \ref UsdGeomTokens "Allowed Values" | face, point, edge, segment, tetrahedron |
204 
205  /// See GetElementTypeAttr(), and also
206  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
207  /// If specified, author \p defaultValue as the attribute's default,
208  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
209  /// the default for \p writeSparsely is \c false.
211  UsdAttribute CreateElementTypeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
212 
213 public:
214  // --------------------------------------------------------------------- //
215  // INDICES
216  // --------------------------------------------------------------------- //
217  /// The set of indices included in this subset. The indices need not
218  /// be sorted, but the same index should not appear more than once. Indices
219  /// are invalid if outside the range [0, elementCount) for the given time on
220  /// the parent geometric prim.
221  ///
222  /// | ||
223  /// | -- | -- |
224  /// | Declaration | `int[] indices = []` |
225  /// | C++ Type | VtArray<int> |
226  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->IntArray |
229 
230  /// See GetIndicesAttr(), and also
231  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
232  /// If specified, author \p defaultValue as the attribute's default,
233  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
234  /// the default for \p writeSparsely is \c false.
236  UsdAttribute CreateIndicesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
237 
238 public:
239  // --------------------------------------------------------------------- //
240  // FAMILYNAME
241  // --------------------------------------------------------------------- //
242  /// The name of the family of subsets that this subset belongs to.
243  /// This is optional and is primarily useful when there are multiple
244  /// families of subsets under a geometric prim. In some cases, this could
245  /// also be used for achieving proper roundtripping of subset data between
246  /// DCC apps.
247  /// When multiple subsets belonging to a prim have the same familyName, they
248  /// are said to belong to the family. A <i>familyType</i> value can be
249  /// encoded on the owner of a family of subsets as a token using the static
250  /// method UsdGeomSubset::SetFamilyType(). "familyType" can have one of the
251  /// following values:
252  /// <ul><li><b>UsdGeomTokens->partition</b>: implies that every element of
253  /// the whole geometry appears exactly once in only one of the subsets
254  /// belonging to the family.</li>
255  /// <li><b>UsdGeomTokens->nonOverlapping</b>: an element that appears in one
256  /// subset may not appear in any other subset belonging to the family, and
257  /// appears only once in the subset in which it appears.</li>
258  /// <li><b>UsdGeomTokens->unrestricted</b>: implies that there are no
259  /// restrictions w.r.t. the membership of elements in the subsets. They
260  /// could be overlapping and the union of all subsets in the family may
261  /// not represent the whole.</li>
262  /// </ul>
263  /// \note The validity of subset data is not enforced by the authoring
264  /// APIs, however they can be checked using UsdGeomSubset::ValidateFamily().
265  ///
266  ///
267  /// | ||
268  /// | -- | -- |
269  /// | Declaration | `uniform token familyName = ""` |
270  /// | C++ Type | TfToken |
271  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
272  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
275 
276  /// See GetFamilyNameAttr(), and also
277  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
278  /// If specified, author \p defaultValue as the attribute's default,
279  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
280  /// the default for \p writeSparsely is \c false.
282  UsdAttribute CreateFamilyNameAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
283 
284 public:
285  // ===================================================================== //
286  // Feel free to add custom code below this line, it will be preserved by
287  // the code generator.
288  //
289  // Just remember to:
290  // - Close the class declaration with };
291  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
292  // - Close the include guard with #endif
293  // ===================================================================== //
294  // --(BEGIN CUSTOM CODE)--
295 
296  /// Creates a new GeomSubset below the given \p geom with the given
297  /// name, \p subsetName, element type, \p elementType and \p indices.
298  ///
299  /// If a subset named \p subsetName already exists below \p geom, then
300  /// this updates its attributes with the values of the provided arguments
301  /// (indices value at time 'default' will be updated) and returns it.
302  ///
303  /// The family type is set / updated on \p geom only if a non-empty value
304  /// is passed in for \p familyType and \p familyName.
307  const UsdGeomImageable &geom,
308  const TfToken &subsetName,
309  const TfToken &elementType,
310  const VtIntArray &indices,
311  const TfToken &familyName=TfToken(),
312  const TfToken &familyType=TfToken());
313 
314  /// Creates a new GeomSubset below the given imageable, \p geom with the
315  /// given name, \p subsetName, element type, \p elementType and \p indices.
316  ///
317  /// If a subset named \p subsetName already exists below \p geom, then
318  /// this creates a new subset by appending a suitable index as suffix to
319  /// \p subsetName (eg, subsetName_1) to avoid name collisions.
320  ///
321  /// The family type is set / updated on \p geom only if a non-empty value
322  /// is passed in for \p familyType and \p familyName.
325  const UsdGeomImageable &geom,
326  const TfToken &subsetName,
327  const TfToken &elementType,
328  const VtIntArray &indices,
329  const TfToken &familyName=TfToken(),
330  const TfToken &familyType=TfToken());
331 
332  /// Returns all the GeomSubsets defined on the given imageable, \p geom.
334  static std::vector<UsdGeomSubset> GetAllGeomSubsets(
335  const UsdGeomImageable &geom);
336 
337  /// Returns all the GeomSubsets of the given \p elementType belonging to
338  /// the specified family, \p familyName on the given imageable, \p geom.
339  /// If \p elementType is empty, then subsets containing all element types
340  /// are returned.
341  /// If \p familyName is left empty, then all subsets of the specified
342  /// \p elementType will be returned.
344  static std::vector<UsdGeomSubset> GetGeomSubsets(
345  const UsdGeomImageable &geom,
346  const TfToken &elementType=TfToken(),
347  const TfToken &familyName=TfToken());
348 
349  /// Returns the names of all the families of GeomSubsets defined on the given
350  /// imageable, \p geom.
353  const UsdGeomImageable &geom);
354 
355  /// This method is used to encode the type of family that the GeomSubsets
356  /// on the given geometric prim \p geom, with the given family name,
357  /// \p familyName belong to.
358  ///
359  /// See \ref UsdGeomSubset::GetFamilyNameAttr for the possible values for
360  /// \p familyType.
361  ///
362  /// When a family of GeomSubsets is tagged as a UsdGeomTokens->partition or
363  /// UsdGeomTokens->nonOverlapping, the validity of the data (i.e.
364  /// mutual exclusivity and/or wholeness) is not enforced by the authoring
365  /// APIs. Use ValidateFamily() to validate the data in a family of
366  /// GeomSubsets.
367  ///
368  /// \return Returns false upon failure to create or set the appropriate
369  /// attribute on \p geom.
371  static bool SetFamilyType(
372  const UsdGeomImageable &geom,
373  const TfToken &familyName,
374  const TfToken &familyType);
375 
376  /// Returns the type of family that the GeomSubsets on the given geometric
377  /// prim \p geom, with the given family name, \p familyName belong to.
378  ///
379  /// This only returns the token that's encoded on \p geom and does not perform
380  /// any actual validation on the family of GeomSubsets. Please use
381  /// ValidateFamily() for such validation.
382  ///
383  /// When familyType is not set on \p geom, the fallback value
384  /// UsdTokens->unrestricted is returned.
386  static TfToken GetFamilyType(
387  const UsdGeomImageable &geom,
388  const TfToken &familyName);
389 
390  /// Utility for getting the list of indices that are not assigned to any of
391  /// the GeomSubsets in the \p familyName family on the given \p geom at the
392  /// timeCode, \p time, given the element count (total number of indices in
393  /// the array being subdivided).
394  ///
395  /// For \p elementType UsdGeomTokens->edge, the output array of indices
396  /// should be interpreted in pairs, as each sequential pair of indices
397  /// corresponds to an edge between the two points. Each edge will be in
398  /// the order (lowIndex, highIndex).
399  ///
400  /// If the \p elementType is not applicable to the given \p geom, an empty
401  /// array is returned and a coding error is issued.
403  static VtIntArray GetUnassignedIndices(
404  const UsdGeomImageable &geom,
405  const TfToken &elementType,
406  const TfToken &familyName,
408 
409  /// \deprecated Please use GetUnassignedIndices(geom, elementType,
410  /// familyName, time) instead.
411  /// Utility for getting the list of indices that are not assigned to any of
412  /// the GeomSubsets in \p subsets at the timeCode, \p time, given the
413  /// element count (total number of indices in the array being subdivided),
414  /// \p elementCount.
416  static VtIntArray GetUnassignedIndices(
417  const std::vector<UsdGeomSubset> &subsets,
418  const size_t elementCount,
420 
421  /// \deprecated Please use UsdGeomSubset::ValidateFamily instead.
422  /// Validates the data in the given set of GeomSubsets, \p subsets, given
423  /// the total number of elements in the array being subdivided,
424  /// \p elementCount and the \p familyType that the subsets belong to.
425  ///
426  /// For proper validation of indices in \p subsets, all of the GeomSubsets
427  /// must have the same 'elementType'.
428  ///
429  /// If one or more subsets contain invalid data, then false is returned and
430  /// \p reason is populated with a string explaining the reason why it is
431  /// invalid.
432  ///
433  /// The python version of this method returns a tuple containing
434  /// a (bool, string), where the bool has the validity of the subsets and
435  /// the string contains the reason (if they're invalid).
436  ///
438  static bool ValidateSubsets(
439  const std::vector<UsdGeomSubset> &subsets,
440  const size_t elementCount,
441  const TfToken &familyType,
442  std::string * const reason);
443 
444  /// Validates whether the family of subsets identified by the given
445  /// \p familyName and \p elementType on the given imageable, \p geom contain
446  /// valid data. If the family is designated as a partition or as
447  /// non-overlapping using SetFamilyType(), then the validity of the data
448  /// is checked. If the familyType is "unrestricted", then this performs only
449  /// bounds checking of the values in the "indices" arrays.
450  ///
451  /// If \p reason is not NULL, then it is populated with a string explaining
452  /// why the family is invalid, if it is invalid.
453  ///
454  /// The python version of this method returns a tuple containing
455  /// a (bool, string), where the bool has the validity of the family and
456  /// the string contains the reason (if it's invalid).
457  ///
459  static bool ValidateFamily(
460  const UsdGeomImageable &geom,
461  const TfToken &elementType,
462  const TfToken &familyName,
463  std::string * const reason);
464 
465 private:
466  /// Utility to get index pairs at time \p t from the indices attribute
467  /// where every sequential pair of indices is interpreted as an edge or segment.
468  /// If \p preserveOrder is true (used for segments), the pairs are directly
469  /// interpreted from the indices attribute with no order modification. If
470  /// \p preserveOrder is false (used for edges), returned pairs are stored in
471  /// the order (lowIndex, highIndex). Assumes the elementType is edge or segment.
472  VtVec2iArray _GetIndexPairs(const UsdTimeCode t, bool preserveOrder) const;
473 };
474 
476 
477 #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.
GLsizei GLenum const void * indices
Definition: glcorearb.h:406
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:82
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)
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
UsdGeomSubset(const UsdSchemaBase &schemaObj)
Definition: subset.h:90
USDGEOM_API UsdAttribute GetElementTypeAttr() const
USDGEOM_API UsdAttribute CreateFamilyNameAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute GetFamilyNameAttr() const
Definition: token.h:70
Represents a concrete typed schema.
static USDGEOM_API TfToken GetFamilyType(const UsdGeomImageable &geom, const TfToken &familyName)
Definition: prim.h:116
Definition: typed.h:44
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
Definition: path.h:273
GLdouble t
Definition: glad.h:2397
static USDGEOM_API bool SetFamilyType(const UsdGeomImageable &geom, const TfToken &familyName, const TfToken &familyType)
UsdSchemaKind
Definition: common.h:112
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
static USDGEOM_API VtIntArray GetUnassignedIndices(const UsdGeomImageable &geom, const TfToken &elementType, const TfToken &familyName, const UsdTimeCode &time=UsdTimeCode::EarliestTime())
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
USDGEOM_API UsdSchemaKind _GetSchemaKind() const override
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:74
static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: type.h:47
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:23
static USDGEOM_API UsdGeomSubset Define(const UsdStagePtr &stage, const SdfPath &path)
virtual USDGEOM_API ~UsdGeomSubset()
Destructor.
Definition: value.h:146
std::set< TfToken, TfTokenFastArbitraryLessThan > Set
Definition: token.h:166
static USDGEOM_API std::vector< UsdGeomSubset > GetGeomSubsets(const UsdGeomImageable &geom, const TfToken &elementType=TfToken(), const TfToken &familyName=TfToken())
static const UsdSchemaKind schemaKind
Definition: subset.h:76