HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
modelAPI.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_MODELAPI_H
8 #define USDGEOM_GENERATED_MODELAPI_H
9 
10 /// \file usdGeom/modelAPI.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usdGeom/api.h"
15 #include "pxr/usd/usd/prim.h"
16 #include "pxr/usd/usd/stage.h"
17 #include "pxr/usd/usdGeom/tokens.h"
18 
22 
23 #include "pxr/base/vt/value.h"
24 
25 #include "pxr/base/gf/vec3d.h"
26 #include "pxr/base/gf/vec3f.h"
27 #include "pxr/base/gf/matrix4d.h"
28 
29 #include "pxr/base/tf/token.h"
30 #include "pxr/base/tf/type.h"
31 
33 
34 class SdfAssetPath;
35 
36 // -------------------------------------------------------------------------- //
37 // GEOMMODELAPI //
38 // -------------------------------------------------------------------------- //
39 
40 /// \class UsdGeomModelAPI
41 ///
42 /// UsdGeomModelAPI extends the generic UsdModelAPI schema with
43 /// geometry specific concepts such as cached extents for the entire model,
44 /// constraint targets, and geometry-inspired extensions to the payload
45 /// lofting process.
46 ///
47 /// As described in GetExtentsHint() below, it is useful to cache extents
48 /// at the model level. UsdGeomModelAPI provides schema for computing and
49 /// storing these cached extents, which can be consumed by UsdGeomBBoxCache to
50 /// provide fast access to precomputed extents that will be used as the model's
51 /// bounds ( see UsdGeomBBoxCache::UsdGeomBBoxCache() ).
52 ///
53 /// \section UsdGeomModelAPI_drawMode Draw Modes
54 ///
55 /// Draw modes provide optional alternate imaging behavior for USD subtrees with
56 /// kind model. \em model:drawMode (which is inheritable) and
57 /// \em model:applyDrawMode (which is not) are resolved into a decision to stop
58 /// traversing the scene graph at a certain point, and replace a USD subtree
59 /// with proxy geometry.
60 ///
61 /// The value of \em model:drawMode determines the type of proxy geometry:
62 /// - \em origin - Draw the model-space basis vectors of the replaced prim.
63 /// - \em bounds - Draw the model-space bounding box of the replaced prim.
64 /// - \em cards - Draw textured quads as a placeholder for the replaced prim.
65 /// - \em default - An explicit opinion to draw the USD subtree as normal.
66 /// - \em inherited - Defer to the parent opinion.
67 ///
68 /// \em model:drawMode falls back to _inherited_ so that a whole scene,
69 /// a large group, or all prototypes of a model hierarchy PointInstancer can
70 /// be assigned a draw mode with a single attribute edit. If no draw mode is
71 /// explicitly set in a hierarchy, the resolved value is _default_.
72 ///
73 /// \em model:applyDrawMode is meant to be written when an asset is authored,
74 /// and provides flexibility for different asset types. For example,
75 /// a character assembly (composed of character, clothes, etc) might have
76 /// \em model:applyDrawMode set at the top of the subtree so the whole group
77 /// can be drawn as a single card object. An effects subtree might have
78 /// \em model:applyDrawMode set at a lower level so each particle
79 /// group draws individually.
80 ///
81 /// Models of kind component are automatically treated as if
82 /// \em model:applyDrawMode were true if \em model:applyDrawMode is not
83 /// authored on the component prim. A component prim will be drawn drawn with a
84 /// simplified representation when the prim has kind component,
85 /// \em model:applyDrawMode is not authored (or authored to be true), and the
86 /// resolved (i.e. inherited down namespace) value for \em model:drawMode is
87 /// not _default_. If you don't want component prims to use the resolved
88 /// non-default drawMode, you must apply the UsdGeomModelAPI schema on the prim
89 /// and explicitly set \em model:applyDrawMode to false.
90 ///
91 /// \section UsdGeomModelAPI_cardGeometry Cards Geometry
92 ///
93 /// The specific geometry used in cards mode is controlled by the
94 /// \em model:cardGeometry attribute:
95 /// - \em cross - Generate a quad normal to each basis direction and negative.
96 /// Locate each quad so that it bisects the model extents.
97 /// - \em box - Generate a quad normal to each basis direction and negative.
98 /// Locate each quad on a face of the model extents, facing out.
99 /// - \em fromTexture - Generate a quad for each supplied texture from
100 /// attributes stored in that texture's metadata.
101 ///
102 /// For \em cross and \em box mode, the extents are calculated for purposes
103 /// \em default, \em proxy, and \em render, at their earliest authored time.
104 /// If the model has no textures, all six card faces are rendered using
105 /// \em model:drawModeColor. If one or more textures are present, only axes
106 /// with one or more textures assigned are drawn. For each axis, if both
107 /// textures (positive and negative) are specified, they'll be used on the
108 /// corresponding card faces; if only one texture is specified, it will be
109 /// mapped to the opposite card face after being flipped on the texture's
110 /// s-axis. Any card faces with invalid asset paths will be drawn with
111 /// \em model:drawModeColor.
112 ///
113 /// Both \em model:cardGeometry and \em model:drawModeColor should be
114 /// authored on the prim where the draw mode takes effect, since these
115 /// attributes are not inherited.
116 ///
117 /// For \em fromTexture mode, only card faces with valid textures assigned
118 /// are drawn. The geometry is generated by pulling the \em worldtoscreen
119 /// attribute out of texture metadata. This is expected to be a 4x4 matrix
120 /// mapping the model-space position of the card quad to the clip-space quad
121 /// with corners (-1,-1,0) and (1,1,0). The card vertices are generated by
122 /// transforming the clip-space corners by the inverse of \em worldtoscreen.
123 /// Textures are mapped so that (s) and (t) map to (+x) and (+y) in clip space.
124 /// If the metadata cannot be read in the right format, or the matrix can't
125 /// be inverted, the card face is not drawn.
126 ///
127 /// All card faces are drawn and textured as single-sided.
128 ///
129 /// \todo CreatePayload()
130 ///
131 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
132 /// that are text/tokens, the actual token is published and defined in \ref UsdGeomTokens.
133 /// So to set an attribute to the value "rightHanded", use UsdGeomTokens->rightHanded
134 /// as the value.
135 ///
137 {
138 public:
139  /// Compile time constant representing what kind of schema this class is.
140  ///
141  /// \sa UsdSchemaKind
143 
144  /// Construct a UsdGeomModelAPI on UsdPrim \p prim .
145  /// Equivalent to UsdGeomModelAPI::Get(prim.GetStage(), prim.GetPath())
146  /// for a \em valid \p prim, but will not immediately throw an error for
147  /// an invalid \p prim
148  explicit UsdGeomModelAPI(const UsdPrim& prim=UsdPrim())
149  : UsdAPISchemaBase(prim)
150  {
151  }
152 
153  /// Construct a UsdGeomModelAPI on the prim held by \p schemaObj .
154  /// Should be preferred over UsdGeomModelAPI(schemaObj.GetPrim()),
155  /// as it preserves SchemaBase state.
156  explicit UsdGeomModelAPI(const UsdSchemaBase& schemaObj)
157  : UsdAPISchemaBase(schemaObj)
158  {
159  }
160 
161  /// Destructor.
163  virtual ~UsdGeomModelAPI();
164 
165  /// Return a vector of names of all pre-declared attributes for this schema
166  /// class and all its ancestor classes. Does not include attributes that
167  /// may be authored by custom/extended methods of the schemas involved.
169  static const TfTokenVector &
170  GetSchemaAttributeNames(bool includeInherited=true);
171 
172  /// Return a UsdGeomModelAPI holding the prim adhering to this
173  /// schema at \p path on \p stage. If no prim exists at \p path on
174  /// \p stage, or if the prim at that path does not adhere to this schema,
175  /// return an invalid schema object. This is shorthand for the following:
176  ///
177  /// \code
178  /// UsdGeomModelAPI(stage->GetPrimAtPath(path));
179  /// \endcode
180  ///
182  static UsdGeomModelAPI
183  Get(const UsdStagePtr &stage, const SdfPath &path);
184 
185 
186  /// Returns true if this <b>single-apply</b> API schema can be applied to
187  /// the given \p prim. If this schema can not be a applied to the prim,
188  /// this returns false and, if provided, populates \p whyNot with the
189  /// reason it can not be applied.
190  ///
191  /// Note that if CanApply returns false, that does not necessarily imply
192  /// that calling Apply will fail. Callers are expected to call CanApply
193  /// before calling Apply if they want to ensure that it is valid to
194  /// apply a schema.
195  ///
196  /// \sa UsdPrim::GetAppliedSchemas()
197  /// \sa UsdPrim::HasAPI()
198  /// \sa UsdPrim::CanApplyAPI()
199  /// \sa UsdPrim::ApplyAPI()
200  /// \sa UsdPrim::RemoveAPI()
201  ///
203  static bool
204  CanApply(const UsdPrim &prim, std::string *whyNot=nullptr);
205 
206  /// Applies this <b>single-apply</b> API schema to the given \p prim.
207  /// This information is stored by adding "GeomModelAPI" to the
208  /// token-valued, listOp metadata \em apiSchemas on the prim.
209  ///
210  /// \return A valid UsdGeomModelAPI object is returned upon success.
211  /// An invalid (or empty) UsdGeomModelAPI object is returned upon
212  /// failure. See \ref UsdPrim::ApplyAPI() for conditions
213  /// resulting in failure.
214  ///
215  /// \sa UsdPrim::GetAppliedSchemas()
216  /// \sa UsdPrim::HasAPI()
217  /// \sa UsdPrim::CanApplyAPI()
218  /// \sa UsdPrim::ApplyAPI()
219  /// \sa UsdPrim::RemoveAPI()
220  ///
222  static UsdGeomModelAPI
223  Apply(const UsdPrim &prim);
224 
225 protected:
226  /// Returns the kind of schema this class belongs to.
227  ///
228  /// \sa UsdSchemaKind
230  UsdSchemaKind _GetSchemaKind() const override;
231 
232 private:
233  // needs to invoke _GetStaticTfType.
234  friend class UsdSchemaRegistry;
236  static const TfType &_GetStaticTfType();
237 
238  static bool _IsTypedSchema();
239 
240  // override SchemaBase virtuals.
242  const TfType &_GetTfType() const override;
243 
244 public:
245  // --------------------------------------------------------------------- //
246  // MODELDRAWMODE
247  // --------------------------------------------------------------------- //
248  /// Alternate imaging mode; applied to this prim or child prims
249  /// where \em model:applyDrawMode is true, or where the prim
250  /// has kind \em component and \em model:applyDrawMode is not
251  /// authored. See \ref UsdGeomModelAPI_drawMode
252  /// for mode descriptions.
253  ///
254  /// | ||
255  /// | -- | -- |
256  /// | Declaration | `uniform token model:drawMode = "inherited"` |
257  /// | C++ Type | TfToken |
258  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
259  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
260  /// | \ref UsdGeomTokens "Allowed Values" | origin, bounds, cards, default, inherited |
263 
264  /// See GetModelDrawModeAttr(), 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 CreateModelDrawModeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
271 
272 public:
273  // --------------------------------------------------------------------- //
274  // MODELAPPLYDRAWMODE
275  // --------------------------------------------------------------------- //
276  /// If true, and the resolved value of \em model:drawMode is
277  /// non-default, apply an alternate imaging mode to this prim. See
278  /// \ref UsdGeomModelAPI_drawMode.
279  ///
280  /// | ||
281  /// | -- | -- |
282  /// | Declaration | `uniform bool model:applyDrawMode = 0` |
283  /// | C++ Type | bool |
284  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Bool |
285  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
288 
289  /// See GetModelApplyDrawModeAttr(), and also
290  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
291  /// If specified, author \p defaultValue as the attribute's default,
292  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
293  /// the default for \p writeSparsely is \c false.
295  UsdAttribute CreateModelApplyDrawModeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
296 
297 public:
298  // --------------------------------------------------------------------- //
299  // MODELDRAWMODECOLOR
300  // --------------------------------------------------------------------- //
301  /// The base color of imaging prims inserted for alternate
302  /// imaging modes. For \em origin and \em bounds modes, this
303  /// controls line color; for \em cards mode, this controls the
304  /// fallback quad color.
305  ///
306  /// | ||
307  /// | -- | -- |
308  /// | Declaration | `uniform float3 model:drawModeColor = (0.18, 0.18, 0.18)` |
309  /// | C++ Type | GfVec3f |
310  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float3 |
311  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
314 
315  /// See GetModelDrawModeColorAttr(), and also
316  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
317  /// If specified, author \p defaultValue as the attribute's default,
318  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
319  /// the default for \p writeSparsely is \c false.
321  UsdAttribute CreateModelDrawModeColorAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
322 
323 public:
324  // --------------------------------------------------------------------- //
325  // MODELCARDGEOMETRY
326  // --------------------------------------------------------------------- //
327  /// The geometry to generate for imaging prims inserted for \em
328  /// cards imaging mode. See \ref UsdGeomModelAPI_cardGeometry for
329  /// geometry descriptions.
330  ///
331  /// | ||
332  /// | -- | -- |
333  /// | Declaration | `uniform token model:cardGeometry = "cross"` |
334  /// | C++ Type | TfToken |
335  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
336  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
337  /// | \ref UsdGeomTokens "Allowed Values" | cross, box, fromTexture |
340 
341  /// See GetModelCardGeometryAttr(), and also
342  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
343  /// If specified, author \p defaultValue as the attribute's default,
344  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
345  /// the default for \p writeSparsely is \c false.
347  UsdAttribute CreateModelCardGeometryAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
348 
349 public:
350  // --------------------------------------------------------------------- //
351  // MODELCARDTEXTUREXPOS
352  // --------------------------------------------------------------------- //
353  /// In \em cards imaging mode, the texture applied to the X+ quad.
354  /// The texture axes (s,t) are mapped to model-space axes (-y, -z).
355  ///
356  /// | ||
357  /// | -- | -- |
358  /// | Declaration | `asset model:cardTextureXPos` |
359  /// | C++ Type | SdfAssetPath |
360  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Asset |
363 
364  /// See GetModelCardTextureXPosAttr(), and also
365  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
366  /// If specified, author \p defaultValue as the attribute's default,
367  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
368  /// the default for \p writeSparsely is \c false.
370  UsdAttribute CreateModelCardTextureXPosAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
371 
372 public:
373  // --------------------------------------------------------------------- //
374  // MODELCARDTEXTUREYPOS
375  // --------------------------------------------------------------------- //
376  /// In \em cards imaging mode, the texture applied to the Y+ quad.
377  /// The texture axes (s,t) are mapped to model-space axes (x, -z).
378  ///
379  /// | ||
380  /// | -- | -- |
381  /// | Declaration | `asset model:cardTextureYPos` |
382  /// | C++ Type | SdfAssetPath |
383  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Asset |
386 
387  /// See GetModelCardTextureYPosAttr(), and also
388  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
389  /// If specified, author \p defaultValue as the attribute's default,
390  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
391  /// the default for \p writeSparsely is \c false.
393  UsdAttribute CreateModelCardTextureYPosAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
394 
395 public:
396  // --------------------------------------------------------------------- //
397  // MODELCARDTEXTUREZPOS
398  // --------------------------------------------------------------------- //
399  /// In \em cards imaging mode, the texture applied to the Z+ quad.
400  /// The texture axes (s,t) are mapped to model-space axes (x, -y).
401  ///
402  /// | ||
403  /// | -- | -- |
404  /// | Declaration | `asset model:cardTextureZPos` |
405  /// | C++ Type | SdfAssetPath |
406  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Asset |
409 
410  /// See GetModelCardTextureZPosAttr(), and also
411  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
412  /// If specified, author \p defaultValue as the attribute's default,
413  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
414  /// the default for \p writeSparsely is \c false.
416  UsdAttribute CreateModelCardTextureZPosAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
417 
418 public:
419  // --------------------------------------------------------------------- //
420  // MODELCARDTEXTUREXNEG
421  // --------------------------------------------------------------------- //
422  /// In \em cards imaging mode, the texture applied to the X- quad.
423  /// The texture axes (s,t) are mapped to model-space axes (y, -z).
424  ///
425  /// | ||
426  /// | -- | -- |
427  /// | Declaration | `asset model:cardTextureXNeg` |
428  /// | C++ Type | SdfAssetPath |
429  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Asset |
432 
433  /// See GetModelCardTextureXNegAttr(), and also
434  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
435  /// If specified, author \p defaultValue as the attribute's default,
436  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
437  /// the default for \p writeSparsely is \c false.
439  UsdAttribute CreateModelCardTextureXNegAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
440 
441 public:
442  // --------------------------------------------------------------------- //
443  // MODELCARDTEXTUREYNEG
444  // --------------------------------------------------------------------- //
445  /// In \em cards imaging mode, the texture applied to the Y- quad.
446  /// The texture axes (s,t) are mapped to model-space axes (-x, -z).
447  ///
448  /// | ||
449  /// | -- | -- |
450  /// | Declaration | `asset model:cardTextureYNeg` |
451  /// | C++ Type | SdfAssetPath |
452  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Asset |
455 
456  /// See GetModelCardTextureYNegAttr(), and also
457  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
458  /// If specified, author \p defaultValue as the attribute's default,
459  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
460  /// the default for \p writeSparsely is \c false.
462  UsdAttribute CreateModelCardTextureYNegAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
463 
464 public:
465  // --------------------------------------------------------------------- //
466  // MODELCARDTEXTUREZNEG
467  // --------------------------------------------------------------------- //
468  /// In \em cards imaging mode, the texture applied to the Z- quad.
469  /// The texture axes (s,t) are mapped to model-space axes (-x, -y).
470  ///
471  /// | ||
472  /// | -- | -- |
473  /// | Declaration | `asset model:cardTextureZNeg` |
474  /// | C++ Type | SdfAssetPath |
475  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Asset |
478 
479  /// See GetModelCardTextureZNegAttr(), and also
480  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
481  /// If specified, author \p defaultValue as the attribute's default,
482  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
483  /// the default for \p writeSparsely is \c false.
485  UsdAttribute CreateModelCardTextureZNegAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
486 
487 public:
488  // ===================================================================== //
489  // Feel free to add custom code below this line, it will be preserved by
490  // the code generator.
491  //
492  // Just remember to:
493  // - Close the class declaration with };
494  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
495  // - Close the include guard with #endif
496  // ===================================================================== //
497  // --(BEGIN CUSTOM CODE)--
498 
499  /// \anchor UsdGeomModelAPIExtentsHint
500  /// \name Model Extents Hint API
501  ///
502  /// Methods for querying, authoring and computing the model's
503  /// "extentsHint".
504  /// @{
505 
506  /// Retrieve the authored value (if any) of this model's "extentsHint"
507  ///
508  /// Persistent caching of bounds in USD is a potentially perilous endeavor,
509  /// given that:
510  /// \li It is very easy to add overrides in new super-layers that
511  /// invalidate the cached bounds, and no practical way to automatically
512  /// detect when this happens
513  /// \li It is possible for references to be allowed to "float", so that
514  /// asset updates can flow directly into cached scenes. Such changes in
515  /// referenced scene description can also invalidate cached bounds in
516  /// referencing layers.
517  ///
518  /// For these reasons, as a general rule, we only persistently cache
519  /// leaf gprim extents in object space. However, even with cached gprim
520  /// extents, computing bounds can be expensive. Since model-level bounds
521  /// are so useful to many graphics applications, we make an exception,
522  /// with some caveats. The "extentsHint" should be considered entirely
523  /// optional (whereas gprim extent is not); if authored, it should
524  /// contains the extents for various values of gprim purposes.
525  /// The extents for different values of purpose are stored in a linear Vec3f
526  /// array as pairs of GfVec3f values in the order specified by
527  /// UsdGeomImageable::GetOrderedPurposeTokens(). This list is trimmed to
528  /// only include non-empty extents. i.e., if a model has only default and
529  /// render geoms, then it will only have 4 GfVec3f values in its
530  /// extentsHint array. We do not skip over zero extents, so if a model
531  /// has only default and proxy geom, we will author six GfVec3f's, the
532  /// middle two representing an zero extent for render geometry.
533  ///
534  /// A UsdGeomBBoxCache can be configured to first consult the cached
535  /// extents when evaluating model roots, rather than descending into the
536  /// models for the full computation. This is not the default behavior,
537  /// and gives us a convenient way to validate that the cached
538  /// extentsHint is still valid.
539  ///
540  /// \return \c true if a value was fetched; \c false if no value was
541  /// authored, or on error. It is an error to make this query of a prim
542  /// that is not a model root.
543  ///
544  /// \sa UsdGeomImageable::GetPurposeAttr(),
545  /// UsdGeomImageable::GetOrderedPurposeTokens()
546  ///
548  bool GetExtentsHint(VtVec3fArray *extents,
549  const UsdTimeCode &time = UsdTimeCode::Default()) const;
550 
551  /// Authors the extentsHint array for this model at the given time.
552  ///
553  /// \sa GetExtentsHint()
554  ///
556  bool SetExtentsHint(VtVec3fArray const &extents,
557  const UsdTimeCode &time = UsdTimeCode::Default()) const;
558 
559  /// Returns the custom 'extentsHint' attribute if it exits.
562 
563  /// Compute a value suitable for passing to SetExtentsHint().
564  ///
565  /// If this model is a UsdGeomBoundable, call
566  /// UsdGeomBoundable::ComputeExtentFromPlugins() with the \p bboxCache 's
567  /// time code. If that function returns true, then populate the returned
568  /// array with the min and max repeated according to the number of tokens in
569  /// UsdGeomImageable::GetOrderedPurposeTokens(). Otherwise return an array
570  /// with a single empty range.
571  ///
572  /// If this model is not a UsdGeomBoundable, populate the return value by
573  /// calling UsdGeomBBoxCache::ComputeUntransformedBound() (and
574  /// GfBBox3d::ComputeAlignedBox() on that result) for each token in
575  /// UsdGeomImageable::GetOrderedPurposeTokens().
576  ///
577  /// In either case the, Nth successive pair of entries in the returned array
578  /// will be the min and max coordinates of the extent corresponding to the
579  /// Nth token in UsdGeomImageable::GetOrderedPurposeTokens(), except
580  /// trailing empty boxes are omitted, unless all boxes are empty in which
581  /// case the result is a single empty box.
582  ///
583  /// For example, if GetOrderedPurposeTokens() is [default, render, proxy,
584  /// guide] and this function returns [(0,0,0), (1,1,1), (+FLT_MAX),
585  /// (-FLT_MIN), (0,0,0), (1,1,1)] then this means that the computed extents
586  /// for 'default' and 'proxy' purpose are [(0,0,0), (1,1,1)] and the extents
587  /// for 'render' and 'guide' purposes are empty.
588  ///
589  /// This function modifies \p bboxCache's included purposes.
590  ///
591  /// \note \p bboxCache must not be used concurrently during the execution of
592  /// this function.
594  VtVec3fArray ComputeExtentsHint(UsdGeomBBoxCache& bboxCache) const;
595 
596  /// @}
597 
598  /// \anchor UsdGeomModelAPIConstraintTargets
599  /// \name Model Constraint Targets API
600  ///
601  /// Methods for adding and listing constraint targets.
602  ///
603  /// @{
604 
605  /// Get the constraint target with the given name, \p constraintName.
606  ///
607  /// If the requested constraint target does not exist, then an invalid
608  /// UsdConstraintTarget object is returned.
609  ///
612  const std::string &constraintName) const;
613 
614  /// Creates a new constraint target with the given name, \p constraintName.
615  ///
616  /// If the constraint target already exists, then the existing target is
617  /// returned. If it does not exist, a new one is created and returned.
618  ///
621  const std::string &constraintName) const;
622 
623  /// Returns all the constraint targets belonging to the model.
624  ///
625  /// Only valid constraint targets in the "constraintTargets" namespace
626  /// are returned by this method.
627  ///
629  std::vector<UsdGeomConstraintTarget> GetConstraintTargets() const;
630 
631  /// @}
632 
633  /// Calculate the effective model:drawMode of this prim.
634  ///
635  /// If the draw mode is authored on this prim, it's used. Otherwise,
636  /// the fallback value is "inherited", which defers to the parent opinion.
637  /// The first non-inherited opinion found walking from this prim towards
638  /// the root is used. If the attribute isn't set on any ancestors, we
639  /// return "default" (meaning, disable "drawMode" geometry).
640  ///
641  /// If this function is being called in a traversal context to compute
642  /// the draw mode of an entire hierarchy of prims, it would be beneficial
643  /// to cache and pass in the computed parent draw-mode via the
644  /// \p parentDrawMode parameter. This avoids repeated upward traversal to
645  /// look for ancestor opinions.
646  ///
647  /// When \p parentDrawMode is empty (or unspecified), this function does
648  /// an upward traversal to find the closest ancestor with an authored
649  /// model:drawMode.
650  ///
651  /// \sa GetModelDrawModeAttr()
653  TfToken ComputeModelDrawMode(const TfToken &parentDrawMode=TfToken()) const;
654 };
655 
656 
658 
659 #endif
virtual USDGEOM_API ~UsdGeomModelAPI()
Destructor.
USDGEOM_API UsdAttribute GetModelCardGeometryAttr() const
static constexpr UsdTimeCode Default()
Definition: timeCode.h:113
GT_API const UT_StringHolder time
Single Apply API schema.
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
UsdGeomModelAPI(const UsdPrim &prim=UsdPrim())
Definition: modelAPI.h:148
USDGEOM_API UsdAttribute CreateModelDrawModeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute CreateModelCardTextureXNegAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute CreateModelDrawModeColorAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute CreateModelCardTextureZPosAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute GetModelCardTextureYPosAttr() const
static USDGEOM_API bool CanApply(const UsdPrim &prim, std::string *whyNot=nullptr)
USDGEOM_API UsdAttribute CreateModelCardTextureYPosAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API TfToken ComputeModelDrawMode(const TfToken &parentDrawMode=TfToken()) const
UsdGeomModelAPI(const UsdSchemaBase &schemaObj)
Definition: modelAPI.h:156
USDGEOM_API UsdAttribute CreateModelCardTextureZNegAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute GetModelApplyDrawModeAttr() const
USDGEOM_API UsdSchemaKind _GetSchemaKind() const override
Definition: token.h:70
USDGEOM_API UsdAttribute GetModelCardTextureZPosAttr() const
USDGEOM_API UsdAttribute GetModelCardTextureXPosAttr() const
static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: prim.h:116
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
Definition: path.h:273
USDGEOM_API UsdAttribute CreateModelCardGeometryAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute GetModelCardTextureXNegAttr() const
USDGEOM_API bool SetExtentsHint(VtVec3fArray const &extents, const UsdTimeCode &time=UsdTimeCode::Default()) const
USDGEOM_API std::vector< UsdGeomConstraintTarget > GetConstraintTargets() const
UsdSchemaKind
Definition: common.h:112
USDGEOM_API UsdAttribute GetModelDrawModeAttr() const
static USDGEOM_API UsdGeomModelAPI Get(const UsdStagePtr &stage, const SdfPath &path)
USDGEOM_API UsdAttribute GetExtentsHintAttr() const
Returns the custom 'extentsHint' attribute if it exits.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
USDGEOM_API UsdAttribute GetModelDrawModeColorAttr() const
USDGEOM_API UsdGeomConstraintTarget GetConstraintTarget(const std::string &constraintName) const
USDGEOM_API UsdAttribute GetModelCardTextureYNegAttr() const
static const UsdSchemaKind schemaKind
Definition: modelAPI.h:142
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
USDGEOM_API VtVec3fArray ComputeExtentsHint(UsdGeomBBoxCache &bboxCache) const
Definition: type.h:47
USDGEOM_API bool GetExtentsHint(VtVec3fArray *extents, const UsdTimeCode &time=UsdTimeCode::Default()) const
#define USDGEOM_API
Definition: api.h:23
USDGEOM_API UsdGeomConstraintTarget CreateConstraintTarget(const std::string &constraintName) const
USDGEOM_API UsdAttribute CreateModelCardTextureYNegAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute CreateModelApplyDrawModeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Definition: value.h:146
USDGEOM_API UsdAttribute GetModelCardTextureZNegAttr() const
static USDGEOM_API UsdGeomModelAPI Apply(const UsdPrim &prim)
USDGEOM_API UsdAttribute CreateModelCardTextureXPosAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const