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