1//
2// Redistribution and use in source and binary forms, with or without
3// modification, are permitted provided that the following conditions
4// are met:
5// * Redistributions of source code must retain the above copyright
6// notice, this list of conditions and the following disclaimer.
7// * Redistributions in binary form must reproduce the above copyright
8// notice, this list of conditions and the following disclaimer in the
9// documentation and/or other materials provided with the distribution.
10// * Neither the name of NVIDIA CORPORATION nor the names of its
11// contributors may be used to endorse or promote products derived
12// from this software without specific prior written permission.
13//
14// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
15// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
17// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
18// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
19// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
20// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
21// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
22// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
24// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25//
26// Copyright (c) 2008-2021 NVIDIA Corporation. All rights reserved.
27// Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved.
28// Copyright (c) 2001-2004 NovodeX AG. All rights reserved.
29
30
31#ifndef PX_PHYSICS_BROAD_PHASE_H
32#define PX_PHYSICS_BROAD_PHASE_H
33/** \addtogroup physics
34@{
35*/
36
37#include "PxPhysXConfig.h"
38#include "foundation/PxBounds3.h"
39
40#if !PX_DOXYGEN
41namespace physx
42{
43#endif
44
45 class PxActor;
46
47 /**
48 \brief Broad phase algorithm used in the simulation
49
50 eSAP is a good generic choice with great performance when many objects are sleeping. Performance
51 can degrade significantly though, when all objects are moving, or when large numbers of objects
52 are added to or removed from the broad phase. This algorithm does not need world bounds to be
53 defined in order to work.
54
55 eMBP is an alternative broad phase algorithm that does not suffer from the same performance
56 issues as eSAP when all objects are moving or when inserting large numbers of objects. However
57 its generic performance when many objects are sleeping might be inferior to eSAP, and it requires
58 users to define world bounds in order to work.
59
60 eABP is a revisited implementation of MBP, which automatically manages broad-phase regions.
61 It offers the convenience of eSAP (no need to define world bounds or regions) and the performance
62 of eMBP when a lot of objects are moving. While eSAP can remain faster when most objects are
63 sleeping and eMBP can remain faster when it uses a large number of properly-defined regions,
64 eABP often gives the best performance on average and the best memory usage.
65 */
66 struct PxBroadPhaseType
67 {
68 enum Enum
69 {
70 eSAP, //!< 3-axes sweep-and-prune
71 eMBP, //!< Multi box pruning
72 eABP, //!< Automatic box pruning
73 eGPU,
74
75 eLAST
76 };
77 };
78
79 /**
80 \brief Broad-phase callback to receive broad-phase related events.
81
82 Each broadphase callback object is associated with a PxClientID. It is possible to register different
83 callbacks for different clients. The callback functions are called this way:
84 - for shapes/actors, the callback assigned to the actors' clients are used
85 - for aggregates, the callbacks assigned to clients from aggregated actors are used
86
87 \note SDK state should not be modified from within the callbacks. In particular objects should not
88 be created or destroyed. If state modification is needed then the changes should be stored to a buffer
89 and performed after the simulation step.
90
91 <b>Threading:</b> It is not necessary to make this class thread safe as it will only be called in the context of the
92 user thread.
93
94 @see PxSceneDesc PxScene.setBroadPhaseCallback() PxScene.getBroadPhaseCallback()
95 */
96 class PxBroadPhaseCallback
97 {
98 public:
99 virtual ~PxBroadPhaseCallback() {}
100
101 /**
102 \brief Out-of-bounds notification.
103
104 This function is called when an object leaves the broad-phase.
105
106 \param[in] shape Shape that left the broad-phase bounds
107 \param[in] actor Owner actor
108 */
109 virtual void onObjectOutOfBounds(PxShape& shape, PxActor& actor) = 0;
110
111 /**
112 \brief Out-of-bounds notification.
113
114 This function is called when an aggregate leaves the broad-phase.
115
116 \param[in] aggregate Aggregate that left the broad-phase bounds
117 */
118 virtual void onObjectOutOfBounds(PxAggregate& aggregate) = 0;
119 };
120
121 /**
122 \brief "Region of interest" for the broad-phase.
123
124 This is currently only used for the PxBroadPhaseType::eMBP broad-phase, which requires zones or regions to be defined
125 when the simulation starts in order to work. Regions can overlap and be added or removed at runtime, but at least one
126 region needs to be defined when the scene is created.
127
128 If objects that do no overlap any region are inserted into the scene, they will not be added to the broad-phase and
129 thus collisions will be disabled for them. A PxBroadPhaseCallback out-of-bounds notification will be sent for each one
130 of those objects.
131
132 The total number of regions is limited by PxBroadPhaseCaps::maxNbRegions.
133
134 The number of regions has a direct impact on performance and memory usage, so it is recommended to experiment with
135 various settings to find the best combination for your game. A good default setup is to start with global bounds
136 around the whole world, and subdivide these bounds into 4*4 regions. The PxBroadPhaseExt::createRegionsFromWorldBounds
137 function can do that for you.
138
139 @see PxBroadPhaseCallback PxBroadPhaseExt.createRegionsFromWorldBounds
140 */
141 struct PxBroadPhaseRegion
142 {
143 PxBounds3 bounds; //!< Region's bounds
144 void* userData; //!< Region's user-provided data
145 };
146
147 /**
148 \brief Information & stats structure for a region
149 */
150 struct PxBroadPhaseRegionInfo
151 {
152 PxBroadPhaseRegion region; //!< User-provided region data
153 PxU32 nbStaticObjects; //!< Number of static objects in the region
154 PxU32 nbDynamicObjects; //!< Number of dynamic objects in the region
155 bool active; //!< True if region is currently used, i.e. it has not been removed
156 bool overlap; //!< True if region overlaps other regions (regions that are just touching are not considering overlapping)
157 };
158
159 /**
160 \brief Caps class for broad phase.
161 */
162 struct PxBroadPhaseCaps
163 {
164 PxU32 maxNbRegions; //!< Max number of regions supported by the broad-phase
165 PxU32 maxNbObjects; //!< Max number of objects supported by the broad-phase
166 bool needsPredefinedBounds; //!< If true, broad-phase needs 'regions' to work
167 };
168
169#if !PX_DOXYGEN
170} // namespace physx
171#endif
172
173/** @} */
174#endif
175

source code of qtquick3dphysics/src/3rdparty/PhysX/include/PxBroadPhase.h