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