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_NEW_SCENE_QUERY_SYSTEM_H
++ #define PX_NEW_SCENE_QUERY_SYSTEM_H
++
++ #include "PxSceneQuerySystem.h"
++
++ #if !PX_DOXYGEN
++ namespace physx
++ {
++ #endif
++
++ /**
++ \brief A custom scene query system.
++
++ This is an example of a custom scene query system. It augments the PxSceneQuerySystem API to support an arbitrary number
++ of "pruners", instead of the usual hardcoded two.
++
++ It might not be possible to support the whole PxSceneQuerySystem API in this context. See the source code for details.
++
++ \see PxSceneQuerySystem
++ */
++ class PxCustomSceneQuerySystem : public PxSceneQuerySystem
++ {
++ public:
++ PxCustomSceneQuerySystem() {}
++ virtual ~PxCustomSceneQuerySystem() {}
++
++ /**
++ \brief Adds a pruner to the system.
++
++ The internal PhysX scene-query system uses two regular pruners (one for static shapes, one for dynamic shapes) and an optional
++ compound pruner. Our custom scene query system supports an arbitrary number of regular pruners.
++
++ This can be useful to reduce the load on each pruner, in particular during updates, when internal trees are rebuilt in the
++ background. On the other hand this implementation simply iterates over all created pruners to perform queries, so their cost
++ might increase if a large number of pruners is used.
++
++ In any case this serves as an example of how the PxSceneQuerySystem API can be used to customize scene queries.
++
++ \param[in] primaryType Desired primary (main) type for the new pruner
++ \param[in] secondaryType Secondary type when primary type is PxPruningStructureType::eDYNAMIC_AABB_TREE.
++ \param[in] preallocated Optional number of preallocated shapes in the new pruner
++
++ \return A pruner index
++
++ \see PxCustomSceneQuerySystem PxSceneQueryUpdateMode PxCustomSceneQuerySystemAdapter PxSceneDesc::sceneQuerySystem
++ */
++ virtual PxU32 addPruner(PxPruningStructureType::Enum primaryType, PxDynamicTreeSecondaryPruner::Enum secondaryType, PxU32 preallocated=0) = 0;
++
++ /**
++ \brief Start custom build-steps for all pruners
++
++ This function is used in combination with customBuildstep() and finishCustomBuildstep() to let users take control
++ of the pruners' build-step & commit calls - basically the pruners' update functions. These functions should be used
++ with the PxSceneQueryUpdateMode::eBUILD_DISABLED_COMMIT_DISABLED update mode, otherwise the build-steps will happen
++ automatically in fetchResults. For N pruners it can be more efficient to use these custom build-step functions to
++ perform the updates in parallel:
++
++ - call startCustomBuildstep() first (one synchronous call)
++ - for each pruner, call customBuildstep() (asynchronous calls from multiple threads)
++ - once it is done, call finishCustomBuildstep() to finish the update (synchronous call)
++
++ The multi-threaded update is more efficient here than what it is in PxScene, because the "flushShapes()" call is
++ also multi-threaded (while it is not in PxScene).
++
++ Note that users are responsible for locks here, and these calls should not overlap with other SQ calls. In particular
++ one should not add new objects to the SQ system or perform queries while these calls are happening.
++
++ \return The number of pruners in the system.
++
++ \see customBuildstep finishCustomBuildstep PxSceneQueryUpdateMode
++ */
++ virtual PxU32 startCustomBuildstep() = 0;
++
++ /**
++ \brief Perform a custom build-step for a given pruner.
++
++ \param[in] index Pruner index (should be between 0 and the number returned by startCustomBuildstep)
++
++ \see startCustomBuildstep finishCustomBuildstep
++ */
++ virtual void customBuildstep(PxU32 index) = 0;
++
++ /**
++ \brief Finish custom build-steps
++
++ Call this function once after all the customBuildstep() calls are done.
++
++ \see startCustomBuildstep customBuildstep
++ */
++ virtual void finishCustomBuildstep() = 0;
++ };
++
++ /**
++ \brief An adapter class to customize the object-to-pruner mapping.
++
++ In the regular PhysX code static shapes went to the static pruner, and dynamic shapes went to the
++ dynamic pruner.
++
++ This class is a replacement for this mapping when N user-defined pruners are involved.
++ */
++ class PxCustomSceneQuerySystemAdapter
++ {
++ public:
++ PxCustomSceneQuerySystemAdapter() {}
++ virtual ~PxCustomSceneQuerySystemAdapter() {}
++
++ /**
++ \brief Gets a pruner index for an actor/shape.
++
++ This user-defined function tells the system in which pruner a given actor/shape should go.
++
++ \note The returned index must be valid, i.e. it must have been previously returned to users by PxCustomSceneQuerySystem::addPruner.
++
++ \param[in] actor The actor
++ \param[in] shape The shape
++
++ \return A pruner index for this actor/shape.
++
++ \see PxRigidActor PxShape PxCustomSceneQuerySystem::addPruner
++ */
++ virtual PxU32 getPrunerIndex(const PxRigidActor& actor, const PxShape& shape) const = 0;
++
++ /**
++ \brief Pruner filtering callback.
++
++ This will be called for each query to validate whether it should process a given pruner.
++
++ \param[in] prunerIndex The index of currently processed pruner
++ \param[in] context The query context
++ \param[in] filterData The query's filter data
++ \param[in] filterCall The query's filter callback
++
++ \return True to process the pruner, false to skip it entirely
++ */
++ virtual bool processPruner(PxU32 prunerIndex, const PxQueryThreadContext* context, const PxQueryFilterData& filterData, PxQueryFilterCallback* filterCall) const = 0;
++ };
++
++ /**
++ \brief Creates a custom scene query system.
++
++ This is similar to PxCreateExternalSceneQuerySystem, except this function creates a PxCustomSceneQuerySystem object.
++ It can be plugged to PxScene the same way, via PxSceneDesc::sceneQuerySystem.
++
++ \param[in] sceneQueryUpdateMode Desired update mode
++ \param[in] contextID Context ID parameter, sent to the profiler
++ \param[in] adapter Adapter class implementing our extended API
++ \param[in] usesTreeOfPruners True to keep pruners themselves in a BVH, which might increase query performance if a lot of pruners are involved
++
++ \return A custom SQ system instance
++
++ \see PxCustomSceneQuerySystem PxSceneQueryUpdateMode PxCustomSceneQuerySystemAdapter PxSceneDesc::sceneQuerySystem
++ */
++ PxCustomSceneQuerySystem* PxCreateCustomSceneQuerySystem(PxSceneQueryUpdateMode::Enum sceneQueryUpdateMode, PxU64 contextID, const PxCustomSceneQuerySystemAdapter& adapter, bool usesTreeOfPruners=false);
++
++ #if !PX_DOXYGEN
++ } // namespace physx
++ #endif
++
++ #endif