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