All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
bboxCache.h
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 PXR_USD_USD_GEOM_BBOX_CACHE_H
8#define PXR_USD_USD_GEOM_BBOX_CACHE_H
9
10#include "pxr/pxr.h"
11#include "pxr/usd/usdGeom/api.h"
12#include "pxr/usd/usdGeom/xformCache.h"
14#include "pxr/usd/usd/attributeQuery.h"
15#include "pxr/base/gf/bbox3d.h"
16#include "pxr/base/tf/hash.h"
17#include "pxr/base/tf/hashmap.h"
19
20#include <optional>
21
22PXR_NAMESPACE_OPEN_SCOPE
23
24
25class UsdGeomModelAPI;
26
71{
72public:
90 USDGEOM_API
92 bool useExtentsHint=false, bool ignoreVisibility=false);
93
95 USDGEOM_API
97
99 USDGEOM_API
101
111 USDGEOM_API
113
125 USDGEOM_API
127 const UsdPrim &prim,
128 const SdfPathSet &pathsToSkip,
129 const GfMatrix4d &primOverride,
130 const TfHashMap<SdfPath, GfMatrix4d, SdfPath::Hash> &ctmOverrides);
131
132
140 USDGEOM_API
142 const UsdPrim &relativeToAncestorPrim);
143
152 USDGEOM_API
154
165 USDGEOM_API
167
184 USDGEOM_API
186 const UsdPrim &prim,
187 const SdfPathSet &pathsToSkip,
188 const TfHashMap<SdfPath, GfMatrix4d, SdfPath::Hash> &ctmOverrides);
189
195 USDGEOM_API
196 bool
198 const UsdGeomPointInstancer& instancer,
199 int64_t const *instanceIdBegin,
200 size_t numIds,
201 GfBBox3d *result);
202
207 const UsdGeomPointInstancer& instancer, int64_t instanceId) {
208 GfBBox3d ret;
209 ComputePointInstanceWorldBounds(instancer, &instanceId, 1, &ret);
210 return ret;
211 }
212
223 USDGEOM_API
224 bool
226 const UsdGeomPointInstancer &instancer,
227 int64_t const *instanceIdBegin,
228 size_t numIds,
229 const UsdPrim &relativeToAncestorPrim,
230 GfBBox3d *result);
231
236 const UsdGeomPointInstancer &instancer,
237 int64_t instanceId,
238 const UsdPrim &relativeToAncestorPrim) {
239 GfBBox3d ret;
241 instancer, &instanceId, 1, relativeToAncestorPrim, &ret);
242 return ret;
243 }
244
253 USDGEOM_API
254 bool
256 const UsdGeomPointInstancer& instancer,
257 int64_t const *instanceIdBegin,
258 size_t numIds,
259 GfBBox3d *result);
260
264 const UsdGeomPointInstancer& instancer,
265 int64_t instanceId) {
266 GfBBox3d ret;
267 ComputePointInstanceLocalBounds(instancer, &instanceId, 1, &ret);
268 return ret;
269 }
270
271
282 USDGEOM_API
283 bool
285 const UsdGeomPointInstancer& instancer,
286 int64_t const *instanceIdBegin,
287 size_t numIds,
288 GfBBox3d *result);
289
294 const UsdGeomPointInstancer& instancer,
295 int64_t instanceId) {
296 GfBBox3d ret;
298 instancer, &instanceId, 1, &ret);
299 return ret;
300 }
301
303 USDGEOM_API
304 void Clear();
305
314 USDGEOM_API
315 void SetIncludedPurposes(const TfTokenVector& includedPurposes);
316
318 const TfTokenVector& GetIncludedPurposes() { return _includedPurposes; }
319
322 bool GetUseExtentsHint() const {
323 return _useExtentsHint;
324 }
325
328 bool GetIgnoreVisibility() const {
329 return _ignoreVisibility;
330 }
331
335 USDGEOM_API
337
339 UsdTimeCode GetTime() const { return _time; }
340
349 void SetBaseTime(UsdTimeCode baseTime) {
350 _baseTime = baseTime;
351 }
352
356 return _baseTime.value_or(GetTime());
357 }
358
362 _baseTime = std::nullopt;
363 }
364
367 bool HasBaseTime() const {
368 return static_cast<bool>(_baseTime);
369 }
370
371private:
372 // Worker task.
373 class _BBoxTask;
374
375 // Helper object for computing bounding boxes for instance prototypes.
376 class _PrototypeBBoxResolver;
377
378 // Map of purpose tokens to associated bboxes.
379 typedef std::map<TfToken, GfBBox3d, TfTokenFastArbitraryLessThan>
380 _PurposeToBBoxMap;
381
382 // Each individual prim will have it's own entry in the bbox cache. When
383 // instancing is involved we store the prototype prims and their children in
384 // the cache for use by each prim that instances each prototype. However,
385 // because of the way we compute and inherit purpose, we may end up needed
386 // to compute multitple different bboxes for prototypes and their children
387 // if the prims that instance them would cause these prototypes to inherit a
388 // different purpose value when the prims under the prototype don't have an
389 // authored purpose of their own.
390 //
391 // This struct is here to represent a prim and the purpose that it would
392 // inherit from the prim that instances it. It is used as the key for the
393 // map of prim's to the cached entries, allowing prims in prototypes to have
394 // more than one bbox cache entry for each distinct context needed to
395 // appropriately compute for all instances. instanceInheritablePurpose will
396 // always be empty for prims that aren't prototypes or children of
397 // prototypes, meaning that prims not in prototypes will only have one
398 // context each.
399 struct _PrimContext {
400 // The prim itself
401 UsdPrim prim;
402
403 // The purpose that would be inherited from the instancing prim if this
404 // prim does not have an explicit purpose.
405 TfToken instanceInheritablePurpose;
406
407 _PrimContext() = default;
408 explicit _PrimContext(const UsdPrim &prim_,
409 const TfToken &purpose = TfToken())
410 : prim(prim_), instanceInheritablePurpose(purpose) {};
411
412 bool operator==(const _PrimContext &rhs) const {
413 return prim == rhs.prim &&
414 instanceInheritablePurpose == rhs.instanceInheritablePurpose;
415 }
416
417 // Convenience stringify for debugging.
418 std::string ToString() const;
419 };
420
421 template<typename TransformType>
422 GfBBox3d _ComputeBoundWithOverridesHelper(
423 const UsdPrim &prim,
424 const SdfPathSet &pathsToSkip,
425 const TransformType &primOverride,
426 const TfHashMap<SdfPath, GfMatrix4d, SdfPath::Hash> &ctmOverrides);
427
428 bool
429 _ComputePointInstanceBoundsHelper(
430 const UsdGeomPointInstancer &instancer,
431 int64_t const *instanceIdBegin,
432 size_t numIds,
433 GfMatrix4d const &xform,
434 GfBBox3d *result);
435
436 // Returns true if the \p prim should be included during child bounds
437 // accumulation.
438 bool _ShouldIncludePrim(const UsdPrim& prim);
439
440 // True if \p attr or \p query may return different values given different
441 // time queries. Note that a true result implies the attribute may have no
442 // value, a default value or a single time sample value.
443 bool _IsVarying(const UsdAttribute& attr);
444 bool _IsVarying(const UsdAttributeQuery& query);
445
446 // Populate the local bbox for the requested prim, without the
447 // local-to-world transform or local transform applied. Return true when
448 // bbox volume > 0.
449 bool _Resolve(const UsdPrim& prim, _PurposeToBBoxMap *bboxes);
450
451 // Resolves a single prim. This method must be thread safe. Assumes the
452 // cache entry has been created for \p prim.
453 //
454 // \p inverseComponentCtm is used to combine all the child bboxes in
455 // component-relative space.
456 void _ResolvePrim(const _BBoxTask* task,
457 const _PrimContext& prim,
458 const GfMatrix4d &inverseComponentCtm);
459
460 struct _Entry {
461 _Entry()
462 : isComplete(false)
463 , isVarying(false)
464 , isIncluded(false)
465 { }
466
467 // The cached bboxes for the various values of purpose token.
468 _PurposeToBBoxMap bboxes;
469
470 // Queries for attributes that need to be re-computed at each
471 // time for this entry. This will be invalid for non-varying entries.
472 std::shared_ptr<UsdAttributeQuery[]> queries;
473
474 // Computed purpose info of the prim that's associated with the entry.
475 // This data includes the prim's actual computed purpose as well as
476 // whether this purpose is inheritable by child prims.
478
479 // True when data in the entry is valid.
480 bool isComplete;
481
482 // True when the entry varies over time.
483 bool isVarying;
484
485 // True when the entry is visible.
486 bool isIncluded;
487 };
488
489 // Returns the cache entry for the given \p prim if one already exists.
490 // If no entry exists, creates (but does not resolve) entries for
491 // \p prim and all of its descendents. In this case, the prototype prims
492 // whose bounding boxes need to be resolved in order to resolve \p prim
493 // will be returned in \p prototypePrimContexts.
494 _Entry* _FindOrCreateEntriesForPrim(
495 const _PrimContext& prim,
496 std::vector<_PrimContext> *prototypePrimContexts);
497
498 // Returns the combined bounding box for the currently included set of
499 // purposes given a _PurposeToBBoxMap.
500 GfBBox3d _GetCombinedBBoxForIncludedPurposes(
501 const _PurposeToBBoxMap &bboxes);
502
503 // Populates \p bbox with the bounding box computed from the authored
504 // extents hint. Based on the included purposes, the extents in the
505 // extentsHint attribute are combined together to compute the bounding box.
506 bool _GetBBoxFromExtentsHint(
507 const UsdGeomModelAPI &geomModel,
508 const UsdAttributeQuery &extentsHintQuery,
509 _PurposeToBBoxMap *bboxes);
510
511 // Returns whether the children of the given prim can be pruned
512 // from the traversal to pre-populate entries.
513 bool _ShouldPruneChildren(const UsdPrim &prim, _Entry *entry);
514
515 // Helper function for computing a prim's purpose info efficiently by
516 // using the parent entry's cached computed purpose info and caching it
517 // its cache entry.
518 // Optionally this can recursively compute and cache the purposes for any
519 // existing parent entries in the cache that haven't had their purposes
520 // computed yet.
521 template <bool IsRecursive>
522 void _ComputePurposeInfo(_Entry *entry, const _PrimContext &prim);
523
524 // Helper to determine if we should use extents hints for \p prim.
525 inline bool _UseExtentsHintForPrim(UsdPrim const &prim) const;
526
527 // Specialize TfHashAppend for TfHash
528 template <typename HashState>
529 friend void TfHashAppend(HashState& h, const _PrimContext &key)
530 {
531 h.Append(key.prim);
532 h.Append(key.instanceInheritablePurpose);
533 }
534
535 // Need hash_value for boost to key cache entries by prim context.
536 friend size_t hash_value(const _PrimContext &key) { return TfHash{}(key); }
537
538 typedef TfHash _PrimContextHash;
539 typedef TfHashMap<_PrimContext, _Entry, _PrimContextHash> _PrimBBoxHashMap;
540
541 // Finds the cache entry for the prim context if it exists.
542 _Entry *_FindEntry(const _PrimContext &primContext)
543 {
544 return TfMapLookupPtr(_bboxCache, primContext);
545 }
546
547 // Returns the cache entry for the prim context, adding it if doesn't
548 // exist.
549 _Entry *_InsertEntry(const _PrimContext &primContext)
550 {
551 return &(_bboxCache[primContext]);
552 }
553
554 WorkDispatcher _dispatcher;
555 UsdTimeCode _time;
556 std::optional<UsdTimeCode> _baseTime;
557 TfTokenVector _includedPurposes;
558 UsdGeomXformCache _ctmCache;
559 _PrimBBoxHashMap _bboxCache;
560 bool _useExtentsHint;
561 bool _ignoreVisibility;
562};
563
564
565PXR_NAMESPACE_CLOSE_SCOPE
566
567#endif // PXR_USD_USD_GEOM_BBOX_CACHE_H
Basic type: arbitrarily oriented 3D bounding box.
Definition: bbox3d.h:67
Stores a 4x4 matrix of double elements.
Definition: matrix4d.h:71
A user-extensible hashing mechanism for use with runtime hash tables.
Definition: hash.h:460
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:160
Object for efficiently making repeated queries for attribute values.
Caches bounds by recursively computing and aggregating bounds of children in world space and aggregat...
Definition: bboxCache.h:71
GfBBox3d ComputePointInstanceWorldBound(const UsdGeomPointInstancer &instancer, int64_t instanceId)
Compute the bound of the given point instance in world space.
Definition: bboxCache.h:206
bool GetUseExtentsHint() const
Returns whether authored extent hints are used to compute bounding boxes.
Definition: bboxCache.h:322
USDGEOM_API bool ComputePointInstanceRelativeBounds(const UsdGeomPointInstancer &instancer, int64_t const *instanceIdBegin, size_t numIds, const UsdPrim &relativeToAncestorPrim, GfBBox3d *result)
Compute the bounds of the given point instances in the space of an ancestor prim relativeToAncestorPr...
USDGEOM_API void SetIncludedPurposes(const TfTokenVector &includedPurposes)
Indicate the set of includedPurposes to use when resolving child bounds.
USDGEOM_API bool ComputePointInstanceWorldBounds(const UsdGeomPointInstancer &instancer, int64_t const *instanceIdBegin, size_t numIds, GfBBox3d *result)
Compute the bound of the given point instances in world space.
UsdTimeCode GetBaseTime() const
Return the base time if set, otherwise GetTime().
Definition: bboxCache.h:355
USDGEOM_API UsdGeomBBoxCache & operator=(UsdGeomBBoxCache const &other)
Copy assignment.
UsdTimeCode GetTime() const
Get the current time from which this cache is reading values.
Definition: bboxCache.h:339
bool GetIgnoreVisibility() const
Returns whether prim visibility should be ignored when computing bounding boxes.
Definition: bboxCache.h:328
bool HasBaseTime() const
Return true if this cache has a baseTime that's been explicitly set, false otherwise.
Definition: bboxCache.h:367
GfBBox3d ComputePointInstanceRelativeBound(const UsdGeomPointInstancer &instancer, int64_t instanceId, const UsdPrim &relativeToAncestorPrim)
Compute the bound of the given point instance in the space of an ancestor prim relativeToAncestorPrim...
Definition: bboxCache.h:235
USDGEOM_API bool ComputePointInstanceUntransformedBounds(const UsdGeomPointInstancer &instancer, int64_t const *instanceIdBegin, size_t numIds, GfBBox3d *result)
Computes the bound of the given point instances, but does not include the transform (if any) authored...
GfBBox3d ComputePointInstanceUntransformedBound(const UsdGeomPointInstancer &instancer, int64_t instanceId)
Computes the bound of the given point instances, but does not include the instancer's transform.
Definition: bboxCache.h:293
void ClearBaseTime()
Clear this cache's baseTime if one has been set.
Definition: bboxCache.h:361
void SetBaseTime(UsdTimeCode baseTime)
Set the base time value for this bbox cache.
Definition: bboxCache.h:349
USDGEOM_API void SetTime(UsdTimeCode time)
Use the new time when computing values and may clear any existing values cached for the previous time...
USDGEOM_API void Clear()
Clears all pre-cached values.
USDGEOM_API GfBBox3d ComputeWorldBound(const UsdPrim &prim)
Compute the bound of the given prim in world space, leveraging any pre-existing, cached bounds.
USDGEOM_API GfBBox3d ComputeUntransformedBound(const UsdPrim &prim, const SdfPathSet &pathsToSkip, const TfHashMap< SdfPath, GfMatrix4d, SdfPath::Hash > &ctmOverrides)
This is an overloaded member function, provided for convenience. It differs from the above function o...
USDGEOM_API GfBBox3d ComputeWorldBoundWithOverrides(const UsdPrim &prim, const SdfPathSet &pathsToSkip, const GfMatrix4d &primOverride, const TfHashMap< SdfPath, GfMatrix4d, SdfPath::Hash > &ctmOverrides)
Computes the bound of the prim's descendents in world space while excluding the subtrees rooted at th...
USDGEOM_API GfBBox3d ComputeRelativeBound(const UsdPrim &prim, const UsdPrim &relativeToAncestorPrim)
Compute the bound of the given prim in the space of an ancestor prim, relativeToAncestorPrim,...
USDGEOM_API bool ComputePointInstanceLocalBounds(const UsdGeomPointInstancer &instancer, int64_t const *instanceIdBegin, size_t numIds, GfBBox3d *result)
Compute the oriented bounding boxes of the given point instances.
const TfTokenVector & GetIncludedPurposes()
Get the current set of included purposes.
Definition: bboxCache.h:318
USDGEOM_API UsdGeomBBoxCache(UsdTimeCode time, TfTokenVector includedPurposes, bool useExtentsHint=false, bool ignoreVisibility=false)
Construct a new BBoxCache for a specific time and set of includedPurposes.
USDGEOM_API GfBBox3d ComputeUntransformedBound(const UsdPrim &prim)
Computes the bound of the prim's children leveraging any pre-existing, cached bounds,...
USDGEOM_API GfBBox3d ComputeLocalBound(const UsdPrim &prim)
Computes the oriented bounding box of the given prim, leveraging any pre-existing,...
GfBBox3d ComputePointInstanceLocalBound(const UsdGeomPointInstancer &instancer, int64_t instanceId)
Compute the oriented bounding boxes of the given point instances.
Definition: bboxCache.h:263
USDGEOM_API UsdGeomBBoxCache(UsdGeomBBoxCache const &other)
Copy constructor.
UsdGeomModelAPI extends the generic UsdModelAPI schema with geometry specific concepts such as cached...
Definition: modelAPI.h:137
Encodes vectorized instancing of multiple, potentially animated, prototypes (object/instance masters)...
A caching mechanism for transform matrices.
Definition: xformCache.h:41
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:117
Represent a time value, which may be either numeric, holding a double value, or a sentinel value UsdT...
Definition: timeCode.h:67
A work dispatcher runs concurrent tasks.
Definition: dispatcher.h:66
Container::mapped_type * TfMapLookupPtr(Container &map, Key const &key)
Checks if an item exists in a map or TfHashMap, without copying it.
Definition: stl.h:124
Value type containing information about a prim's computed effective purpose as well as storing whethe...
Definition: imageable.h:383
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440