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 BP_BROADPHASE_H
32#define BP_BROADPHASE_H
33
34#include "foundation/PxUnionCast.h"
35#include "PxBroadPhase.h"
36#include "BpAABBManager.h"
37
38namespace physx
39{
40class PxcScratchAllocator;
41
42namespace Bp
43{
44
45class BroadPhaseUpdateData;
46
47
48/**
49\brief Base broad phase class. Functions only relevant to MBP.
50*/
51class BroadPhaseBase
52{
53 public:
54 BroadPhaseBase() {}
55 virtual ~BroadPhaseBase() {}
56
57 /**
58 \brief Gets broad-phase caps.
59
60 \param[out] caps Broad-phase caps
61 \return True if success
62 */
63 virtual bool getCaps(PxBroadPhaseCaps& caps) const
64 {
65 caps.maxNbRegions = 0;
66 caps.maxNbObjects = 0;
67 caps.needsPredefinedBounds = false;
68 return true;
69 }
70
71 /**
72 \brief Returns number of regions currently registered in the broad-phase.
73
74 \return Number of regions
75 */
76 virtual PxU32 getNbRegions() const
77 {
78 return 0;
79 }
80
81 /**
82 \brief Gets broad-phase regions.
83
84 \param[out] userBuffer Returned broad-phase regions
85 \param[in] bufferSize Size of userBuffer
86 \param[in] startIndex Index of first desired region, in [0 ; getNbRegions()[
87 \return Number of written out regions
88 */
89 virtual PxU32 getRegions(PxBroadPhaseRegionInfo* userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const
90 {
91 PX_UNUSED(userBuffer);
92 PX_UNUSED(bufferSize);
93 PX_UNUSED(startIndex);
94 return 0;
95 }
96
97 /**
98 \brief Adds a new broad-phase region.
99
100 The bounds for the new region must be non-empty, otherwise an error occurs and the call is ignored.
101
102 The total number of regions is limited to 256. If that number is exceeded, the call is ignored.
103
104 The newly added region will be automatically populated with already existing SDK objects that touch it, if the
105 'populateRegion' parameter is set to true. Otherwise the newly added region will be empty, and it will only be
106 populated with objects when those objects are added to the simulation, or updated if they already exist.
107
108 Using 'populateRegion=true' has a cost, so it is best to avoid it if possible. In particular it is more efficient
109 to create the empty regions first (with populateRegion=false) and then add the objects afterwards (rather than
110 the opposite).
111
112 Objects automatically move from one region to another during their lifetime. The system keeps tracks of what
113 regions a given object is in. It is legal for an object to be in an arbitrary number of regions. However if an
114 object leaves all regions, or is created outside of all regions, several things happen:
115 - collisions get disabled for this object
116 - if a PxBroadPhaseCallback object is provided, an "out-of-bounds" event is generated via that callback
117 - if a PxBroadPhaseCallback object is not provided, a warning/error message is sent to the error stream
118
119 If an object goes out-of-bounds and user deletes it during the same frame, neither the out-of-bounds event nor the
120 error message is generated.
121
122 If an out-of-bounds object, whose collisions are disabled, re-enters a valid broadphase region, then collisions
123 are re-enabled for that object.
124
125 \param[in] region User-provided region data
126 \param[in] populateRegion True to automatically populate the newly added region with existing objects touching it
127
128 \return Handle for newly created region, or 0xffffffff in case of failure.
129 */
130 virtual PxU32 addRegion(const PxBroadPhaseRegion& region, bool populateRegion, const PxBounds3* boundsArray, const PxReal* contactDistance)
131 {
132 PX_UNUSED(region);
133 PX_UNUSED(populateRegion);
134 PX_UNUSED(boundsArray);
135 PX_UNUSED(contactDistance);
136 return 0xffffffff;
137 }
138
139 /**
140 \brief Removes a new broad-phase region.
141
142 If the region still contains objects, and if those objects do not overlap any region any more, they are not
143 automatically removed from the simulation. Instead, the PxBroadPhaseCallback::onObjectOutOfBounds notification
144 is used for each object. Users are responsible for removing the objects from the simulation if this is the
145 desired behavior.
146
147 If the handle is invalid, or if a valid handle is removed twice, an error message is sent to the error stream.
148
149 \param[in] handle Region's handle, as returned by PxScene::addBroadPhaseRegion.
150 \return True if success
151 */
152 virtual bool removeRegion(PxU32 handle)
153 {
154 PX_UNUSED(handle);
155 return false;
156 }
157
158 /*
159 \brief Return the number of objects that are not in any region.
160 */
161 virtual PxU32 getNbOutOfBoundsObjects() const
162 {
163 return 0;
164 }
165
166 /*
167 \brief Return an array of objects that are not in any region.
168 */
169 virtual const PxU32* getOutOfBoundsObjects() const
170 {
171 return NULL;
172 }
173};
174
175
176/*
177\brief Structure used to report created and deleted broadphase pairs
178\note The indices mVolA and mVolB correspond to the bounds indices
179BroadPhaseUpdateData::mCreated used by BroadPhase::update
180@see BroadPhase::getCreatedPairs, BroadPhase::getDeletedPairs
181*/
182struct BroadPhasePair
183{
184 BroadPhasePair(ShapeHandle volA, ShapeHandle volB) :
185 mVolA (PxMin(a: volA, b: volB)),
186 mVolB (PxMax(a: volA, b: volB))
187 {
188 }
189 BroadPhasePair() :
190 mVolA (BP_INVALID_BP_HANDLE),
191 mVolB (BP_INVALID_BP_HANDLE)
192 {
193 }
194
195 ShapeHandle mVolA; // NB: mVolA < mVolB
196 ShapeHandle mVolB;
197};
198
199class BroadPhase : public BroadPhaseBase
200{
201public:
202
203 virtual PxBroadPhaseType::Enum getType() const = 0;
204
205 /**
206 \brief Instantiate a BroadPhase instance.
207 \param[in] bpType - the bp type (either mbp or sap). This is typically specified in PxSceneDesc.
208 \param[in] maxNbRegions is the expected maximum number of broad-phase regions.
209 \param[in] maxNbBroadPhaseOverlaps is the expected maximum number of broad-phase overlaps.
210 \param[in] maxNbStaticShapes is the expected maximum number of static shapes.
211 \param[in] maxNbDynamicShapes is the expected maximum number of dynamic shapes.
212 \param[in] contextID is the context ID parameter sent to the profiler
213 \return The instantiated BroadPhase.
214 \note maxNbRegions is only used if mbp is the chosen broadphase (PxBroadPhaseType::eMBP)
215 \note maxNbRegions, maxNbBroadPhaseOverlaps, maxNbStaticShapes and maxNbDynamicShapes are typically specified in PxSceneLimits
216 */
217 static BroadPhase* create(
218 const PxBroadPhaseType::Enum bpType,
219 const PxU32 maxNbRegions,
220 const PxU32 maxNbBroadPhaseOverlaps,
221 const PxU32 maxNbStaticShapes,
222 const PxU32 maxNbDynamicShapes,
223 PxU64 contextID);
224
225
226 /**
227 \brief Shutdown of the broadphase.
228 */
229 virtual void destroy() = 0;
230
231 /**
232 \brief Update the broadphase and compute the lists of created/deleted pairs.
233
234 \param[in] numCpuTasks the number of cpu tasks that can be used for the broadphase update.
235
236 \param[in] scratchAllocator - a PxcScratchAllocator instance used for temporary memory allocations.
237 This must be non-null.
238
239 \param[in] updateData a description of changes to the collection of aabbs since the last broadphase update.
240 The changes detail the indices of the bounds that have been added/updated/removed as well as an array of all
241 bound coordinates and an array of group ids used to filter pairs with the same id.
242 @see BroadPhaseUpdateData
243
244 \param[in] continuation the task that is in the queue to be executed immediately after the broadphase has completed its update. NULL is not supported.
245 \param[in] nPhaseUnlockTask this task will have its ref count decremented when it is safe to permit NP to run in parallel with BP. NULL is supported.
246
247 \note In PX_CHECKED and PX_DEBUG build configurations illegal input data (that does not conform to the BroadPhaseUpdateData specifications) triggers
248 a special code-path that entirely bypasses the broadphase and issues a warning message to the error stream. No guarantees can be made about the
249 correctness/consistency of broadphase behavior with illegal input data in PX_RELEASE and PX_PROFILE configs because validity checks are not active
250 in these builds.
251 */
252
253 virtual void update(const PxU32 numCpuTasks, PxcScratchAllocator* scratchAllocator, const BroadPhaseUpdateData& updateData, physx::PxBaseTask* continuation, physx::PxBaseTask* nPhaseUnlockTask) = 0;
254
255 /**
256 \brief Fetch the results of any asynchronous broad phase work.
257 */
258 virtual void fetchBroadPhaseResults(physx::PxBaseTask* nPhaseUnlockTask) = 0;
259
260 /*
261 \brief Return the number of created aabb overlap pairs computed in the execution of update() that has just completed.
262 */
263 virtual PxU32 getNbCreatedPairs() const = 0;
264
265 /*
266 \brief Return the array of created aabb overlap pairs computed in the execution of update() that has just completed.
267 Note that each overlap pair is reported only on the frame when the overlap first occurs. The overlap persists
268 until the pair appears in the list of deleted pairs or either of the bounds in the pair is removed from the broadphase.
269 A created overlap must involve at least one of the bounds of the overlap pair appearing in either the created or updated list.
270 It is impossible for the same pair to appear simultaneously in the list of created and deleted overlap pairs.
271 An overlap is defined as a pair of bounds that overlap on all three axes; that is when maxA > minB and maxB > minA for all three axes.
272 The rule that minima(maxima) are even(odd) (see BroadPhaseUpdateData) removes the ambiguity of touching bounds.
273
274 */
275 virtual BroadPhasePair* getCreatedPairs() = 0;
276
277 /**
278 \brief Return the number of deleted overlap pairs computed in the execution of update() that has just completed.
279 */
280 virtual PxU32 getNbDeletedPairs() const = 0;
281
282 /**
283 \brief Return the number of deleted overlap pairs computed in the execution of update() that has just completed.
284 Note that a deleted pair can only be reported if that pair has already appeared in the list of created pairs in an earlier update.
285 A lost overlap occurs when a pair of bounds previously overlapped on all three axes but have now separated on at least one axis.
286 A lost overlap must involve at least one of the bounds of the lost overlap pair appearing in the updated list.
287 Lost overlaps arising from removal of bounds from the broadphase do not appear in the list of deleted pairs.
288 It is impossible for the same pair to appear simultaneously in the list of created and deleted pairs.
289 The test for overlap is conservative throughout, meaning that deleted pairs do not include touching pairs.
290 */
291 virtual BroadPhasePair* getDeletedPairs() = 0;
292
293 /**
294 \brief After the broadphase has completed its update() function and the created/deleted pairs have been queried
295 with getCreatedPairs/getDeletedPairs it is desirable to free any memory that was temporarily acquired for the update but is
296 is no longer required post-update. This can be achieved with the function freeBuffers().
297 */
298 virtual void freeBuffers() = 0;
299
300 /**
301 \brief Adjust internal structures after all bounds have been adjusted due to a scene origin shift.
302 */
303 virtual void shiftOrigin(const PxVec3& shift, const PxBounds3* boundsArray, const PxReal* contactDistances) = 0;
304
305 /**
306 \brief Test that the created/updated/removed lists obey the rules that
307 1. object ids can only feature in the created list if they have never been previously added or if they were previously removed.
308 2. object ids can only be added to the updated list if they have been previously added without being removed.
309 3. objects ids can only be added to the removed list if they have been previously added without being removed.
310 */
311#if PX_CHECKED
312 virtual bool isValid(const BroadPhaseUpdateData& updateData) const = 0;
313#endif
314
315 virtual BroadPhasePair* getBroadPhasePairs() const = 0;
316
317 virtual void deletePairs() = 0;
318
319 // PT: for unit-testing the non-GPU versions
320 virtual void singleThreadedUpdate(PxcScratchAllocator* /*scratchAllocator*/, const BroadPhaseUpdateData& /*updateData*/){}
321};
322
323} //namespace Bp
324
325} //namespace physx
326
327#endif //BP_BROADPHASE_H
328

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