1/*
2 * Copyright (c) 2008-2015, NVIDIA CORPORATION. All rights reserved.
3 *
4 * NVIDIA CORPORATION and its licensors retain all intellectual property
5 * and proprietary rights in and to this software, related documentation
6 * and any modifications thereto. Any use, reproduction, disclosure or
7 * distribution of this software and related documentation without an express
8 * license agreement from NVIDIA CORPORATION is strictly prohibited.
9 */
10// Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved.
11// Copyright (c) 2001-2004 NovodeX AG. All rights reserved.
12
13
14#ifndef PX_PHYSICS_BROAD_PHASE_H
15#define PX_PHYSICS_BROAD_PHASE_H
16/** \addtogroup physics
17@{
18*/
19
20#include "PxPhysXConfig.h"
21#include "foundation/PxBounds3.h"
22
23#ifndef PX_DOXYGEN
24namespace physx
25{
26#endif
27
28 class PxActor;
29
30 /**
31 \brief Broad phase algorithm used in the simulation
32
33 eSAP is a good generic choice with great performance when many objects are sleeping. Performance
34 can degrade significantly though, when all objects are moving, or when large numbers of objects
35 are added to or removed from the broad phase. This algorithm does not need world bounds to be
36 defined in order to work.
37
38 eMBP is an alternative broad phase algorithm that does not suffer from the same performance
39 issues as eSAP when all objects are moving or when inserting large numbers of objects. However
40 its generic performance when many objects are sleeping might be inferior to eSAP, and it requires
41 users to define world bounds in order to work.
42 */
43 struct PxBroadPhaseType
44 {
45 enum Enum
46 {
47 eSAP, //!< 3-axes sweep-and-prune
48 eMBP, //!< Multi box pruning
49
50 eLAST
51 };
52 };
53
54 /**
55 \brief Broad-phase callback to receive broad-phase related events.
56
57 Each broadphase callback object is associated with a PxClientID. It is possible to register different
58 callbacks for different clients. The callback functions are called this way:
59 - for shapes/actors, the callback assigned to the actors' clients are used
60 - for aggregates, the callbacks assigned to clients from aggregated actors are used
61
62 \note SDK state should not be modified from within the callbacks. In particular objects should not
63 be created or destroyed. If state modification is needed then the changes should be stored to a buffer
64 and performed after the simulation step.
65
66 <b>Threading:</b> It is not necessary to make this class thread safe as it will only be called in the context of the
67 user thread.
68
69 @see PxSceneDesc PxScene.setBroadPhaseCallback() PxScene.getBroadPhaseCallback()
70 */
71 class PxBroadPhaseCallback
72 {
73 public:
74 virtual ~PxBroadPhaseCallback() {}
75
76 /**
77 \brief Out-of-bounds notification.
78
79 This function is called when an object leaves the broad-phase.
80
81 \param[in] shape Shape that left the broad-phase bounds
82 \param[in] actor Owner actor
83 */
84 virtual void onObjectOutOfBounds(PxShape& shape, PxActor& actor) = 0;
85
86 /**
87 \brief Out-of-bounds notification.
88
89 This function is called when an aggregate leaves the broad-phase.
90
91 \param[in] aggregate Aggregate that left the broad-phase bounds
92 */
93 virtual void onObjectOutOfBounds(PxAggregate& aggregate) = 0;
94 };
95
96 /**
97 \brief "Region of interest" for the broad-phase.
98
99 This is currently only used for the PxBroadPhaseType::eMBP broad-phase, which requires zones or regions to be defined
100 when the simulation starts in order to work. Regions can overlap and be added or removed at runtime, but at least one
101 region needs to be defined when the scene is created.
102
103 If objects that do no overlap any region are inserted into the scene, they will not be added to the broad-phase and
104 thus collisions will be disabled for them. A PxBroadPhaseCallback out-of-bounds notification will be sent for each one
105 of those objects.
106
107 The total number of regions is limited by PxBroadPhaseCaps::maxNbRegions.
108
109 The number of regions has a direct impact on performance and memory usage, so it is recommended to experiment with
110 various settings to find the best combination for your game. A good default setup is to start with global bounds
111 around the whole world, and subdivide these bounds into 4*4 regions. The PxBroadPhaseExt::createRegionsFromWorldBounds
112 function can do that for you.
113
114 @see PxBroadPhaseCallback PxBroadPhaseExt.createRegionsFromWorldBounds
115 */
116 struct PxBroadPhaseRegion
117 {
118 PxBounds3 bounds; //!< Region's bounds
119 void* userData; //!< Region's user-provided data
120 };
121
122 /**
123 \brief Information & stats structure for a region
124 */
125 struct PxBroadPhaseRegionInfo
126 {
127 PxBroadPhaseRegion region; //!< User-provided region data
128 PxU32 nbStaticObjects; //!< Number of static objects in the region
129 PxU32 nbDynamicObjects; //!< Number of dynamic objects in the region
130 bool active; //!< True if region is currently used, i.e. it has not been removed
131 bool overlap; //!< True if region overlaps other regions (regions that are just touching are not considering overlapping)
132 };
133
134 /**
135 \brief Caps class for broad phase.
136 */
137 struct PxBroadPhaseCaps
138 {
139 PxU32 maxNbRegions; //!< Max number of regions supported by the broad-phase
140 PxU32 maxNbObjects; //!< Max number of objects supported by the broad-phase
141 bool needsPredefinedBounds; //!< If true, broad-phase needs 'regions' to work
142 };
143
144#ifndef PX_DOXYGEN
145} // namespace physx
146#endif
147
148/** @} */
149#endif
150