Revision control
++ // Copyright (c) 2001-2004 NovodeX AG. All rights reserved.
++ // Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved.
++ // SPDX-FileCopyrightText: Copyright (c) 2008-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
++ // SPDX-License-Identifier: Apache-2.0
++
++ #ifndef PX_SCENE_QUERY_DESC_H
++ #define PX_SCENE_QUERY_DESC_H
++
++ #include "PxPhysXConfig.h"
++ #include "geometry/PxBVHBuildStrategy.h"
++
++ #if !PX_DOXYGEN
++ namespace physx
++ {
++ #endif
++
++ class PxSceneQuerySystem;
++
++ /**
++ \brief Pruning structure used to accelerate scene queries.
++
++ eNONE uses a simple data structure that consumes less memory than the alternatives,
++ but generally has slower query performance.
++
++ eDYNAMIC_AABB_TREE usually provides the fastest queries. However there is a
++ constant per-frame management cost associated with this structure. How much work should
++ be done per frame can be tuned via the #PxSceneQueryDesc::dynamicTreeRebuildRateHint
++ parameter.
++
++ eSTATIC_AABB_TREE is typically used for static objects. It is the same as the
++ dynamic AABB tree, without the per-frame overhead. This can be a good choice for static
++ objects, if no static objects are added, moved or removed after the scene has been
++ created. If there is no such guarantee (e.g. when streaming parts of the world in and out),
++ then the dynamic version is a better choice even for static objects.
++ */
++ struct PxPruningStructureType
++ {
++ enum Enum
++ {
++ eNONE, //!< Using a simple data structure
++ eDYNAMIC_AABB_TREE, //!< Using a dynamic AABB tree
++ eSTATIC_AABB_TREE, //!< Using a static AABB tree
++
++ eLAST
++ };
++ };
++
++ /**
++ \brief Secondary pruning structure used for newly added objects in dynamic trees.
++
++ Dynamic trees (PxPruningStructureType::eDYNAMIC_AABB_TREE) are slowly rebuilt
++ over several frames. A secondary pruning structure holds and manages objects
++ added to the scene while this rebuild is in progress.
++
++ eNONE ignores newly added objects. This means that for a number of frames (roughly
++ defined by PxSceneQueryDesc::dynamicTreeRebuildRateHint) newly added objects will
++ be ignored by scene queries. This can be acceptable when streaming large worlds, e.g.
++ when the objects added at the boundaries of the game world don't immediately need to be
++ visible from scene queries (it would be equivalent to streaming that data in a few frames
++ later). The advantage of this approach is that there is no CPU cost associated with
++ inserting the new objects in the scene query data structures, and no extra runtime cost
++ when performing queries.
++
++ eBUCKET uses a structure similar to PxPruningStructureType::eNONE. Insertion is fast but
++ query cost can be high.
++
++ eINCREMENTAL uses an incremental AABB-tree, with no direct PxPruningStructureType equivalent.
++ Query time is fast but insertion cost can be high.
++
++ eBVH uses a PxBVH structure. This usually offers the best overall performance.
++ */
++ struct PxDynamicTreeSecondaryPruner
++ {
++ enum Enum
++ {
++ eNONE, //!< no secondary pruner, new objects aren't visible to SQ for a few frames
++ eBUCKET , //!< bucket-based secondary pruner, faster updates, slower query time
++ eINCREMENTAL, //!< incremental-BVH secondary pruner, faster query time, slower updates
++ eBVH, //!< PxBVH-based secondary pruner, good overall performance
++
++ eLAST
++ };
++ };
++
++ /**
++ \brief Scene query update mode
++
++ This enum controls what work is done when the scene query system is updated. The updates traditionally happen when PxScene::fetchResults
++ is called. This function then calls PxSceneQuerySystem::finalizeUpdates, where the update mode is used.
++
++ fetchResults/finalizeUpdates will sync changed bounds during simulation and update the scene query bounds in pruners, this work is mandatory.
++
++ eBUILD_ENABLED_COMMIT_ENABLED does allow to execute the new AABB tree build step during fetchResults/finalizeUpdates, additionally
++ the pruner commit is called where any changes are applied. During commit PhysX refits the dynamic scene query tree and if a new tree
++ was built and the build finished the tree is swapped with current AABB tree.
++
++ eBUILD_ENABLED_COMMIT_DISABLED does allow to execute the new AABB tree build step during fetchResults/finalizeUpdates. Pruner commit
++ is not called, this means that refit will then occur during the first scene query following fetchResults/finalizeUpdates, or may be forced
++ by the method PxScene::flushQueryUpdates() / PxSceneQuerySystemBase::flushUpdates().
++
++ eBUILD_DISABLED_COMMIT_DISABLED no further scene query work is executed. The scene queries update needs to be called manually, see
++ PxScene::sceneQueriesUpdate (see that function's doc for the equivalent PxSceneQuerySystem sequence). It is recommended to call
++ PxScene::sceneQueriesUpdate right after fetchResults/finalizeUpdates as the pruning structures are not updated.
++ */
++ struct PxSceneQueryUpdateMode
++ {
++ enum Enum
++ {
++ eBUILD_ENABLED_COMMIT_ENABLED, //!< Both scene query build and commit are executed.
++ eBUILD_ENABLED_COMMIT_DISABLED, //!< Scene query build only is executed.
++ eBUILD_DISABLED_COMMIT_DISABLED //!< No work is done, no update of scene queries
++ };
++ };
++
++ /**
++ \brief Descriptor class for scene query system. See #PxSceneQuerySystem.
++ */
++ class PxSceneQueryDesc
++ {
++ public:
++
++ /**
++ \brief Defines the structure used to store static objects (PxRigidStatic actors).
++
++ There are usually a lot more static actors than dynamic actors in a scene, so they are stored
++ in a separate structure. The idea is that when dynamic actors move each frame, the static structure
++ remains untouched and does not need updating.
++
++ <b>Default:</b> PxPruningStructureType::eDYNAMIC_AABB_TREE
++
++ \note Only PxPruningStructureType::eSTATIC_AABB_TREE and PxPruningStructureType::eDYNAMIC_AABB_TREE are allowed here.
++
++ \see PxPruningStructureType PxSceneSQSystem.getStaticStructure()
++ */
++ PxPruningStructureType::Enum staticStructure;
++
++ /**
++ \brief Defines the structure used to store dynamic objects (non-PxRigidStatic actors).
++
++ <b>Default:</b> PxPruningStructureType::eDYNAMIC_AABB_TREE
++
++ \see PxPruningStructureType PxSceneSQSystem.getDynamicStructure()
++ */
++ PxPruningStructureType::Enum dynamicStructure;
++
++ /**
++ \brief Hint for how much work should be done per simulation frame to rebuild the pruning structures.
++
++ This parameter gives a hint on the distribution of the workload for rebuilding the dynamic AABB tree
++ pruning structure #PxPruningStructureType::eDYNAMIC_AABB_TREE. It specifies the desired number of simulation frames
++ the rebuild process should take. Higher values will decrease the workload per frame but the pruning
++ structure will get more and more outdated the longer the rebuild takes (which can make
++ scene queries less efficient).
++
++ \note Only used for #PxPruningStructureType::eDYNAMIC_AABB_TREE pruning structures.
++
++ \note Both staticStructure & dynamicStructure can use a PxPruningStructureType::eDYNAMIC_AABB_TREE, in which case
++ this parameter is used for both.
++
++ \note This parameter gives only a hint. The rebuild process might still take more or less time depending on the
++ number of objects involved.
++
++ <b>Range:</b> [4, PX_MAX_U32)<br>
++ <b>Default:</b> 100
++
++ \see PxSceneQuerySystemBase.setDynamicTreeRebuildRateHint() PxSceneQuerySystemBase.getDynamicTreeRebuildRateHint()
++ */
++ PxU32 dynamicTreeRebuildRateHint;
++
++ /**
++ \brief Secondary pruner for dynamic tree.
++
++ This is used for PxPruningStructureType::eDYNAMIC_AABB_TREE structures, to control how objects added to the system
++ at runtime are managed.
++
++ \note Both staticStructure & dynamicStructure can use a PxPruningStructureType::eDYNAMIC_AABB_TREE, in which case
++ this parameter is used for both.
++
++ <b>Default:</b> PxDynamicTreeSecondaryPruner::eINCREMENTAL
++
++ \see PxDynamicTreeSecondaryPruner
++ */
++ PxDynamicTreeSecondaryPruner::Enum dynamicTreeSecondaryPruner;
++
++ /**
++ \brief Build strategy for PxSceneQueryDesc::staticStructure.
++
++ This parameter is used to refine / control the build strategy of PxSceneQueryDesc::staticStructure. This is only
++ used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.
++
++ <b>Default:</b> PxBVHBuildStrategy::eFAST
++
++ \see PxBVHBuildStrategy PxSceneQueryDesc::staticStructure
++ */
++ PxBVHBuildStrategy::Enum staticBVHBuildStrategy;
++
++ /**
++ \brief Build strategy for PxSceneQueryDesc::dynamicStructure.
++
++ This parameter is used to refine / control the build strategy of PxSceneQueryDesc::dynamicStructure. This is only
++ used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.
++
++ <b>Default:</b> PxBVHBuildStrategy::eFAST
++
++ \see PxBVHBuildStrategy PxSceneQueryDesc::dynamicStructure
++ */
++ PxBVHBuildStrategy::Enum dynamicBVHBuildStrategy;
++
++ /**
++ \brief Number of objects per node for PxSceneQueryDesc::staticStructure.
++
++ This parameter is used to refine / control the number of objects per node for PxSceneQueryDesc::staticStructure.
++ This is only used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.
++
++ This parameter has an impact on how quickly the structure gets built, and on the per-frame cost of maintaining
++ the structure. Increasing this value gives smaller AABB-trees that use less memory, are faster to build and
++ update, but it can lead to slower queries.
++
++ <b>Default:</b> 4
++
++ \see PxSceneQueryDesc::staticStructure
++ */
++ PxU32 staticNbObjectsPerNode;
++
++ /**
++ \brief Number of objects per node for PxSceneQueryDesc::dynamicStructure.
++
++ This parameter is used to refine / control the number of objects per node for PxSceneQueryDesc::dynamicStructure.
++ This is only used with PxPruningStructureType::eDYNAMIC_AABB_TREE and PxPruningStructureType::eSTATIC_AABB_TREE.
++
++ This parameter has an impact on how quickly the structure gets built, and on the per-frame cost of maintaining
++ the structure. Increasing this value gives smaller AABB-trees that use less memory, are faster to build and
++ update, but it can lead to slower queries.
++
++ <b>Default:</b> 4
++
++ \see PxSceneQueryDesc::dynamicStructure
++ */
++ PxU32 dynamicNbObjectsPerNode;
++
++ /**
++ \brief Defines the scene query update mode.
++
++ <b>Default:</b> PxSceneQueryUpdateMode::eBUILD_ENABLED_COMMIT_ENABLED
++
++ \see PxSceneQuerySystemBase.setUpdateMode() PxSceneQuerySystemBase.getUpdateMode()
++ */
++ PxSceneQueryUpdateMode::Enum sceneQueryUpdateMode;
++
++ public:
++ /**
++ \brief constructor sets to default.
++ */
++ PX_INLINE PxSceneQueryDesc();
++
++ /**
++ \brief (re)sets the structure to the default.
++ */
++ PX_INLINE void setToDefault();
++
++ /**
++ \brief Returns true if the descriptor is valid.
++ \return true if the current settings are valid.
++ */
++ PX_INLINE bool isValid() const;
++ };
++
++ PX_INLINE PxSceneQueryDesc::PxSceneQueryDesc():
++ staticStructure (PxPruningStructureType::eDYNAMIC_AABB_TREE),
++ dynamicStructure (PxPruningStructureType::eDYNAMIC_AABB_TREE),
++ dynamicTreeRebuildRateHint (100),
++ dynamicTreeSecondaryPruner (PxDynamicTreeSecondaryPruner::eINCREMENTAL),
++ staticBVHBuildStrategy (PxBVHBuildStrategy::eFAST),
++ dynamicBVHBuildStrategy (PxBVHBuildStrategy::eFAST),
++ staticNbObjectsPerNode (4),
++ dynamicNbObjectsPerNode (4),
++ sceneQueryUpdateMode (PxSceneQueryUpdateMode::eBUILD_ENABLED_COMMIT_ENABLED)
++ {
++ }
++
++ PX_INLINE void PxSceneQueryDesc::setToDefault()
++ {
++ *this = PxSceneQueryDesc();
++ }
++
++ PX_INLINE bool PxSceneQueryDesc::isValid() const
++ {
++ if(staticStructure!=PxPruningStructureType::eSTATIC_AABB_TREE && staticStructure!=PxPruningStructureType::eDYNAMIC_AABB_TREE)
++ return false;
++
++ if(dynamicTreeRebuildRateHint < 4)
++ return false;
++
++ return true;
++ }
++
++ #if !PX_DOXYGEN
++ } // namespace physx
++ #endif
++
++ #endif