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_CCT_MANAGER
15#define PX_PHYSICS_CCT_MANAGER
16/** \addtogroup character
17 @{
18*/
19
20#include "characterkinematic/PxCharacter.h"
21
22#include "PxPhysXConfig.h"
23#include "foundation/PxFlags.h"
24#include "common/PxRenderBuffer.h"
25#include "foundation/PxFoundation.h"
26#include "foundation/PxErrorCallback.h"
27
28#ifndef PX_DOXYGEN
29namespace physx
30{
31#endif
32
33class PxPhysics;
34class PxScene;
35class PxController;
36class PxControllerDesc;
37class PxObstacleContext;
38class PxControllerFilterCallback;
39
40/**
41\brief specifies debug-rendering flags
42*/
43struct PxControllerDebugRenderFlag
44{
45 enum Enum
46 {
47 eTEMPORAL_BV = (1<<0), //!< Temporal bounding volume around controllers
48 eCACHED_BV = (1<<1), //!< Cached bounding volume around controllers
49 eOBSTACLES = (1<<2), //!< User-defined obstacles
50
51 eNONE = 0,
52 eALL = 0xffffffff
53 };
54};
55
56/**
57\brief Bitfield that contains a set of raised flags defined in PxControllerDebugRenderFlag.
58
59@see PxControllerDebugRenderFlag
60*/
61typedef PxFlags<PxControllerDebugRenderFlag::Enum, PxU32> PxControllerDebugRenderFlags;
62PX_FLAGS_OPERATORS(PxControllerDebugRenderFlag::Enum, PxU32)
63
64
65/**
66\brief Manages an array of character controllers.
67
68@see PxController PxBoxController PxCapsuleController
69*/
70class PX_PHYSX_CHARACTER_API PxControllerManager
71{
72public:
73 /**
74 \brief Releases the controller manager.
75
76 \note This will release all associated controllers and obstacle contexts.
77
78 \note This function is required to be called to release foundation usage.
79
80 */
81 virtual void release() = 0;
82
83 /**
84 \brief Returns the scene the manager is adding the controllers to.
85
86 \return The associated physics scene.
87 */
88 virtual PxScene& getScene() const = 0;
89
90 /**
91 \brief Returns the number of controllers that are being managed.
92
93 \return The number of controllers.
94 */
95 virtual PxU32 getNbControllers() const = 0;
96
97 /**
98 \brief Retrieve one of the controllers in the manager.
99
100 \param index the index of the controller to return
101 \return The controller with the specified index.
102 */
103 virtual PxController* getController(PxU32 index) = 0;
104
105 /**
106 \brief Creates a new character controller.
107
108 \param[in] desc The controllers descriptor
109 \return The new controller
110
111 @see PxController PxController.release() PxControllerDesc
112 */
113 virtual PxController* createController(const PxControllerDesc& desc) = 0;
114
115 /** \deprecated */
116 PX_DEPRECATED virtual PxController* createController(PxPhysics&, PxScene*, const PxControllerDesc& desc)
117 {
118 // The SDK & scene parameters are not needed anymore
119 PxGetFoundation().getErrorCallback().reportError(PxErrorCode::eDEBUG_WARNING, "The PxControllerManager::createController prototype has changed. Please upate your code.", __FILE__, __LINE__);
120 return createController(desc);
121 }
122
123 /**
124 \brief Releases all the controllers that are being managed.
125 */
126 virtual void purgeControllers() = 0;
127
128 /**
129 \brief Retrieves debug data.
130
131 \return The render buffer filled with debug-render data
132
133 @see PxControllerManager.setDebugRenderingFlags()
134 */
135 virtual PxRenderBuffer& getRenderBuffer() = 0;
136
137 /**
138 \brief Sets debug rendering flags
139
140 \param[in] flags The debug rendering flags (combination of PxControllerDebugRenderFlags)
141
142 @see PxControllerManager.getRenderBuffer() PxControllerDebugRenderFlags
143 */
144 virtual void setDebugRenderingFlags(PxControllerDebugRenderFlags flags) = 0;
145
146 /**
147 \brief Returns the number of obstacle contexts that are being managed.
148
149 \return The number of obstacle contexts.
150 */
151 virtual PxU32 getNbObstacleContexts() const = 0;
152
153 /**
154 \brief Retrieve one of the obstacle contexts in the manager.
155
156 \param index The index of the obstacle context to retrieve.
157 \return The obstacle context with the specified index.
158 */
159 virtual PxObstacleContext* getObstacleContext(PxU32 index) = 0;
160
161 /**
162 \brief Creates an obstacle context.
163
164 \return New obstacle context
165
166 @see PxObstacleContext
167 */
168 virtual PxObstacleContext* createObstacleContext() = 0;
169
170 /**
171 \brief Computes character-character interactions.
172
173 This function is an optional helper to properly resolve interactions between characters, in case they overlap (which can happen for gameplay reasons, etc).
174
175 You should call this once per frame, before your PxController::move() calls. The function will not move the characters directly, but it will
176 compute overlap information for each character that will be used in the next move() call.
177
178 You need to provide a proper time value here so that interactions are resolved in a way that do not depend on the framerate.
179
180 If you only have one character in the scene, or if you can guarantee your characters will never overlap, then you do not need to call this function.
181
182 \note Releasing the manager will automatically release all the associated obstacle contexts.
183
184 \param[in] elapsedTime Elapsed time since last call
185 \param[in] cctFilterCb Filtering callback for CCT-vs-CCT interactions
186 */
187 virtual void computeInteractions(PxF32 elapsedTime, PxControllerFilterCallback* cctFilterCb=NULL) = 0;
188
189 /**
190 \brief Enables or disables runtime tessellation.
191
192 Large triangles can create accuracy issues in the sweep code, which in turn can lead to characters not sliding smoothly
193 against geometries, or even penetrating them. This feature allows one to reduce those issues by tessellating large
194 triangles at runtime, before performing sweeps against them. The amount of tessellation is controlled by the 'maxEdgeLength' parameter.
195 Any triangle with at least one edge length greater than the maxEdgeLength will get recursively tessellated, until resulting triangles are small enough.
196
197 This features only applies to triangle meshes, convex meshes, heightfields and boxes.
198
199 \param[in] flag True/false to enable/disable runtime tessellation.
200 \param[in] maxEdgeLength Max edge length allowed before tessellation kicks in.
201 */
202 virtual void setTessellation(bool flag, float maxEdgeLength) = 0;
203
204 /**
205 \brief Enables or disables the overlap recovery module.
206
207 The overlap recovery module can be used to depenetrate CCTs from static objects when an overlap is detected. This can happen
208 in three main cases:
209 - when the CCT is directly spawned or teleported in another object
210 - when the CCT algorithm fails due to limited FPU accuracy
211 - when the "up vector" is modified, making the rotated CCT shape overlap surrounding objects
212
213 When activated, the CCT module will automatically try to resolve the penetration, and move the CCT to a safe place where it does
214 not overlap other objects anymore. This only concerns static objects, dynamic objects are ignored by the recovery module.
215
216 When the recovery module is not activated, it is possible for the CCTs to go through static objects. By default, the recovery
217 module is enabled.
218
219 The recovery module currently works with all geometries except heightfields.
220
221 \param[in] flag True/false to enable/disable overlap recovery module.
222 */
223 virtual void setOverlapRecoveryModule(bool flag) = 0;
224
225 /**
226 \brief Enables or disables the precise sweeps.
227
228 Precise sweeps are more accurate, but also potentially slower than regular sweeps.
229
230 By default, precise sweeps are enabled.
231
232 \param[in] flag True/false to enable/disable precise sweeps.
233 */
234 virtual void setPreciseSweeps(bool flag) = 0;
235
236 /**
237 \brief Enables or disables vertical sliding against ceilings.
238
239 Geometry is seen as "ceilings" when the following condition is met:
240
241 dot product(contact normal, up direction)<0.0f
242
243 This flag controls whether characters should slide vertically along the geometry in that case.
244
245 By default, sliding is allowed.
246
247 \param[in] flag True/false to enable/disable sliding.
248 */
249 virtual void setPreventVerticalSlidingAgainstCeiling(bool flag) = 0;
250
251 /**
252 \brief Shift the origin of the character controllers and obstacle objects by the specified vector.
253
254 The positions of all character controllers, obstacle objects and the corresponding data structures will get adjusted to reflect the shifted origin location
255 (the shift vector will get subtracted from all character controller and obstacle object positions).
256
257 \note It is the user's responsibility to keep track of the summed total origin shift and adjust all input/output to/from PhysXCharacterKinematic accordingly.
258
259 \note This call will not automatically shift the PhysX scene and its objects. You need to call PxScene::shiftOrigin() seperately to keep the systems in sync.
260
261 \param[in] shift Translation vector to shift the origin by.
262 */
263 virtual void shiftOrigin(const PxVec3& shift) = 0;
264
265protected:
266 PxControllerManager() {}
267 virtual ~PxControllerManager() {}
268};
269
270#ifndef PX_DOXYGEN
271} // namespace physx
272#endif
273
274 /**
275 \brief Creates the controller manager.
276
277 \param[in] scene PhysX scene.
278 \param[in] lockingEnabled Enables/disables internal locking.
279
280 The character controller is informed by #PxDeletionListener::onRelease() when actors or shapes are released, and updates its internal
281 caches accordingly. If character controller movement or a call to #PxControllerManager::shiftOrigin() may overlap with actor/shape releases,
282 internal data structures must be guarded against concurrent access.
283
284 Locking guarantees thread safety in such scenarios.
285
286 \note locking may result in significant slowdown for release of actors or shapes.
287
288 By default, locking is disabled.
289 */
290PX_C_EXPORT PX_PHYSX_CHARACTER_API physx::PxControllerManager* PX_CALL_CONV PxCreateControllerManager(physx::PxScene& scene, bool lockingEnabled = false);
291
292/** @} */
293#endif //PX_PHYSICS_CCT_MANAGER
294