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 | #ifndef PX_PHYSICS_CCT_CONTROLLER |
31 | #define PX_PHYSICS_CCT_CONTROLLER |
32 | /** \addtogroup character |
33 | @{ |
34 | */ |
35 | |
36 | #include "characterkinematic/PxExtended.h" |
37 | #include "characterkinematic/PxControllerObstacles.h" |
38 | #include "PxQueryFiltering.h" |
39 | #include "foundation/PxErrorCallback.h" |
40 | |
41 | #if !PX_DOXYGEN |
42 | namespace physx |
43 | { |
44 | #endif |
45 | |
46 | /** |
47 | \brief The type of controller, eg box, sphere or capsule. |
48 | */ |
49 | struct PxControllerShapeType |
50 | { |
51 | enum Enum |
52 | { |
53 | /** |
54 | \brief A box controller. |
55 | |
56 | @see PxBoxController PxBoxControllerDesc |
57 | */ |
58 | eBOX, |
59 | |
60 | /** |
61 | \brief A capsule controller |
62 | |
63 | @see PxCapsuleController PxCapsuleControllerDesc |
64 | */ |
65 | eCAPSULE, |
66 | |
67 | eFORCE_DWORD = 0x7fffffff |
68 | }; |
69 | }; |
70 | |
71 | class PxShape; |
72 | class PxScene; |
73 | class PxController; |
74 | class PxRigidDynamic; |
75 | class PxMaterial; |
76 | struct PxFilterData; |
77 | class PxQueryFilterCallback; |
78 | class PxControllerBehaviorCallback; |
79 | class PxObstacleContext; |
80 | class PxObstacle; |
81 | |
82 | /** |
83 | \brief specifies how a CCT interacts with non-walkable parts. |
84 | |
85 | This is only used when slopeLimit is non zero. It is currently enabled for static actors only, and not supported for spheres or capsules. |
86 | */ |
87 | struct PxControllerNonWalkableMode |
88 | { |
89 | enum Enum |
90 | { |
91 | ePREVENT_CLIMBING, //!< Stops character from climbing up non-walkable slopes, but doesn't move it otherwise |
92 | ePREVENT_CLIMBING_AND_FORCE_SLIDING //!< Stops character from climbing up non-walkable slopes, and forces it to slide down those slopes |
93 | }; |
94 | }; |
95 | |
96 | /** |
97 | \brief specifies which sides a character is colliding with. |
98 | */ |
99 | struct PxControllerCollisionFlag |
100 | { |
101 | enum Enum |
102 | { |
103 | eCOLLISION_SIDES = (1<<0), //!< Character is colliding to the sides. |
104 | eCOLLISION_UP = (1<<1), //!< Character has collision above. |
105 | eCOLLISION_DOWN = (1<<2) //!< Character has collision below. |
106 | }; |
107 | }; |
108 | |
109 | /** |
110 | \brief Bitfield that contains a set of raised flags defined in PxControllerCollisionFlag. |
111 | |
112 | @see PxControllerCollisionFlag |
113 | */ |
114 | typedef PxFlags<PxControllerCollisionFlag::Enum, PxU8> PxControllerCollisionFlags; |
115 | PX_FLAGS_OPERATORS(PxControllerCollisionFlag::Enum, PxU8) |
116 | |
117 | /** |
118 | \brief Describes a controller's internal state. |
119 | */ |
120 | struct PxControllerState |
121 | { |
122 | PxVec3 deltaXP; //!< delta position vector for the object the CCT is standing/riding on. Not always match the CCT delta when variable timesteps are used. |
123 | PxShape* touchedShape; //!< Shape on which the CCT is standing |
124 | PxRigidActor* touchedActor; //!< Actor owning 'touchedShape' |
125 | ObstacleHandle touchedObstacleHandle; // Obstacle on which the CCT is standing |
126 | PxU32 collisionFlags; //!< Last known collision flags (PxControllerCollisionFlag) |
127 | bool standOnAnotherCCT; //!< Are we standing on another CCT? |
128 | bool standOnObstacle; //!< Are we standing on a user-defined obstacle? |
129 | bool isMovingUp; //!< is CCT moving up or not? (i.e. explicit jumping) |
130 | }; |
131 | |
132 | /** |
133 | \brief Describes a controller's internal statistics. |
134 | */ |
135 | struct PxControllerStats |
136 | { |
137 | PxU16 nbIterations; |
138 | PxU16 nbFullUpdates; |
139 | PxU16 nbPartialUpdates; |
140 | PxU16 nbTessellation; |
141 | }; |
142 | |
143 | /** |
144 | \brief Describes a generic CCT hit. |
145 | */ |
146 | struct PxControllerHit |
147 | { |
148 | PxController* controller; //!< Current controller |
149 | PxExtendedVec3 worldPos; //!< Contact position in world space |
150 | PxVec3 worldNormal; //!< Contact normal in world space |
151 | PxVec3 dir; //!< Motion direction |
152 | PxF32 length; //!< Motion length |
153 | }; |
154 | |
155 | /** |
156 | \brief Describes a hit between a CCT and a shape. Passed to onShapeHit() |
157 | |
158 | @see PxUserControllerHitReport.onShapeHit() |
159 | */ |
160 | struct PxControllerShapeHit : public PxControllerHit |
161 | { |
162 | PxShape* shape; //!< Touched shape |
163 | PxRigidActor* actor; //!< Touched actor |
164 | PxU32 triangleIndex; //!< touched triangle index (only for meshes/heightfields) |
165 | }; |
166 | |
167 | /** |
168 | \brief Describes a hit between a CCT and another CCT. Passed to onControllerHit(). |
169 | |
170 | @see PxUserControllerHitReport.onControllerHit() |
171 | */ |
172 | struct PxControllersHit : public PxControllerHit |
173 | { |
174 | PxController* other; //!< Touched controller |
175 | }; |
176 | |
177 | /** |
178 | \brief Describes a hit between a CCT and a user-defined obstacle. Passed to onObstacleHit(). |
179 | |
180 | @see PxUserControllerHitReport.onObstacleHit() PxObstacleContext |
181 | */ |
182 | struct PxControllerObstacleHit : public PxControllerHit |
183 | { |
184 | const void* userData; |
185 | }; |
186 | |
187 | /** |
188 | \brief User callback class for character controller events. |
189 | |
190 | \note Character controller hit reports are only generated when move is called. |
191 | |
192 | @see PxControllerDesc.callback |
193 | */ |
194 | class PxUserControllerHitReport |
195 | { |
196 | public: |
197 | |
198 | /** |
199 | \brief Called when current controller hits a shape. |
200 | |
201 | This is called when the CCT moves and hits a shape. This will not be called when a moving shape hits a non-moving CCT. |
202 | |
203 | \param[in] hit Provides information about the hit. |
204 | |
205 | @see PxControllerShapeHit |
206 | */ |
207 | virtual void onShapeHit(const PxControllerShapeHit& hit) = 0; |
208 | |
209 | /** |
210 | \brief Called when current controller hits another controller. |
211 | |
212 | \param[in] hit Provides information about the hit. |
213 | |
214 | @see PxControllersHit |
215 | */ |
216 | virtual void onControllerHit(const PxControllersHit& hit) = 0; |
217 | |
218 | /** |
219 | \brief Called when current controller hits a user-defined obstacle. |
220 | |
221 | \param[in] hit Provides information about the hit. |
222 | |
223 | @see PxControllerObstacleHit PxObstacleContext |
224 | */ |
225 | virtual void onObstacleHit(const PxControllerObstacleHit& hit) = 0; |
226 | |
227 | protected: |
228 | virtual ~PxUserControllerHitReport(){} |
229 | }; |
230 | |
231 | |
232 | /** |
233 | \brief Dedicated filtering callback for CCT vs CCT. |
234 | |
235 | This controls collisions between CCTs (one CCT vs anoter CCT). |
236 | |
237 | To make each CCT collide against all other CCTs, just return true - or simply avoid defining a callback. |
238 | To make each CCT freely go through all other CCTs, just return false. |
239 | Otherwise create a custom filtering logic in this callback. |
240 | |
241 | @see PxControllerFilters |
242 | */ |
243 | class PxControllerFilterCallback |
244 | { |
245 | public: |
246 | virtual ~PxControllerFilterCallback(){} |
247 | |
248 | /** |
249 | \brief Filtering method for CCT-vs-CCT. |
250 | |
251 | \param[in] a First CCT |
252 | \param[in] b Second CCT |
253 | \return true to keep the pair, false to filter it out |
254 | */ |
255 | virtual bool filter(const PxController& a, const PxController& b) = 0; |
256 | }; |
257 | |
258 | /** |
259 | \brief Filtering data for "move" call. |
260 | |
261 | This class contains all filtering-related parameters for the PxController::move() call. |
262 | |
263 | Collisions between a CCT and the world are filtered using the mFilterData, mFilterCallback and mFilterFlags |
264 | members. These parameters are internally passed to PxScene::overlap() to find objects touched by the CCT. |
265 | Please refer to the PxScene::overlap() documentation for details. |
266 | |
267 | Collisions between a CCT and another CCT are filtered using the mCCTFilterCallback member. If this filter |
268 | callback is not defined, none of the CCT-vs-CCT collisions are filtered, and each CCT will collide against |
269 | all other CCTs. |
270 | |
271 | \note PxQueryFlag::eANY_HIT and PxQueryFlag::eNO_BLOCK are ignored in mFilterFlags. |
272 | |
273 | @see PxController.move() PxControllerFilterCallback |
274 | */ |
275 | class PxControllerFilters |
276 | { |
277 | public: |
278 | |
279 | PX_INLINE PxControllerFilters(const PxFilterData* filterData=NULL, PxQueryFilterCallback* cb=NULL, PxControllerFilterCallback* cctFilterCb=NULL) : |
280 | mFilterData (filterData), |
281 | mFilterCallback (cb), |
282 | mFilterFlags (PxQueryFlag::eSTATIC|PxQueryFlag::eDYNAMIC|PxQueryFlag::ePREFILTER), |
283 | mCCTFilterCallback (cctFilterCb) |
284 | {} |
285 | |
286 | // CCT-vs-shapes: |
287 | const PxFilterData* mFilterData; //!< Data for internal PxQueryFilterData structure. Passed to PxScene::overlap() call. |
288 | //!< This can be NULL, in which case a default PxFilterData is used. |
289 | PxQueryFilterCallback* mFilterCallback; //!< Custom filter logic (can be NULL). Passed to PxScene::overlap() call. |
290 | PxQueryFlags mFilterFlags; //!< Flags for internal PxQueryFilterData structure. Passed to PxScene::overlap() call. |
291 | // CCT-vs-CCT: |
292 | PxControllerFilterCallback* mCCTFilterCallback; //!< CCT-vs-CCT filter callback. If NULL, all CCT-vs-CCT collisions are kept. |
293 | }; |
294 | |
295 | /** |
296 | \brief Descriptor class for a character controller. |
297 | |
298 | @see PxBoxController PxCapsuleController |
299 | */ |
300 | class PxControllerDesc |
301 | { |
302 | public: |
303 | |
304 | /** |
305 | \brief returns true if the current settings are valid |
306 | |
307 | \return True if the descriptor is valid. |
308 | */ |
309 | PX_INLINE virtual bool isValid() const; |
310 | |
311 | /** |
312 | \brief Returns the character controller type |
313 | |
314 | \return The controllers type. |
315 | |
316 | @see PxControllerType PxCapsuleControllerDesc PxBoxControllerDesc |
317 | */ |
318 | PX_INLINE PxControllerShapeType::Enum getType() const { return mType; } |
319 | |
320 | /** |
321 | \brief The position of the character |
322 | |
323 | \note The character's initial position must be such that it does not overlap the static geometry. |
324 | |
325 | <b>Default:</b> Zero |
326 | */ |
327 | PxExtendedVec3 position; |
328 | |
329 | /** |
330 | \brief Specifies the 'up' direction |
331 | |
332 | In order to provide stepping functionality the SDK must be informed about the up direction. |
333 | |
334 | <b>Default:</b> (0, 1, 0) |
335 | |
336 | */ |
337 | PxVec3 upDirection; |
338 | |
339 | /** |
340 | \brief The maximum slope which the character can walk up. |
341 | |
342 | In general it is desirable to limit where the character can walk, in particular it is unrealistic |
343 | for the character to be able to climb arbitary slopes. |
344 | |
345 | The limit is expressed as the cosine of desired limit angle. A value of 0 disables this feature. |
346 | |
347 | \warning It is currently enabled for static actors only (not for dynamic/kinematic actors), and not supported for spheres or capsules. |
348 | |
349 | <b>Default:</b> 0.707 |
350 | |
351 | @see upDirection invisibleWallHeight maxJumpHeight |
352 | */ |
353 | PxF32 slopeLimit; |
354 | |
355 | /** |
356 | \brief Height of invisible walls created around non-walkable triangles |
357 | |
358 | The library can automatically create invisible walls around non-walkable triangles defined |
359 | by the 'slopeLimit' parameter. This defines the height of those walls. If it is 0.0, then |
360 | no extra triangles are created. |
361 | |
362 | <b>Default:</b> 0.0 |
363 | |
364 | @see upDirection slopeLimit maxJumpHeight |
365 | */ |
366 | PxF32 invisibleWallHeight; |
367 | |
368 | /** |
369 | \brief Maximum height a jumping character can reach |
370 | |
371 | This is only used if invisible walls are created ('invisibleWallHeight' is non zero). |
372 | |
373 | When a character jumps, the non-walkable triangles he might fly over are not found |
374 | by the collision queries (since the character's bounding volume does not touch them). |
375 | Thus those non-walkable triangles do not create invisible walls, and it is possible |
376 | for a jumping character to land on a non-walkable triangle, while he wouldn't have |
377 | reached that place by just walking. |
378 | |
379 | The 'maxJumpHeight' variable is used to extend the size of the collision volume |
380 | downward. This way, all the non-walkable triangles are properly found by the collision |
381 | queries and it becomes impossible to 'jump over' invisible walls. |
382 | |
383 | If the character in your game can not jump, it is safe to use 0.0 here. Otherwise it |
384 | is best to keep this value as small as possible, since a larger collision volume |
385 | means more triangles to process. |
386 | |
387 | <b>Default:</b> 0.0 |
388 | |
389 | @see upDirection slopeLimit invisibleWallHeight |
390 | */ |
391 | PxF32 maxJumpHeight; |
392 | |
393 | /** |
394 | \brief The contact offset used by the controller. |
395 | |
396 | Specifies a skin around the object within which contacts will be generated. |
397 | Use it to avoid numerical precision issues. |
398 | |
399 | This is dependant on the scale of the users world, but should be a small, positive |
400 | non zero value. |
401 | |
402 | <b>Default:</b> 0.1 |
403 | */ |
404 | PxF32 contactOffset; |
405 | |
406 | /** |
407 | \brief Defines the maximum height of an obstacle which the character can climb. |
408 | |
409 | A small value will mean that the character gets stuck and cannot walk up stairs etc, |
410 | a value which is too large will mean that the character can climb over unrealistically |
411 | high obstacles. |
412 | |
413 | <b>Default:</b> 0.5 |
414 | |
415 | @see upDirection |
416 | */ |
417 | PxF32 stepOffset; |
418 | |
419 | /** |
420 | \brief Density of underlying kinematic actor |
421 | |
422 | The CCT creates a PhysX's kinematic actor under the hood. This controls its density. |
423 | |
424 | <b>Default:</b> 10.0 |
425 | */ |
426 | PxF32 density; |
427 | |
428 | /** |
429 | \brief Scale coefficient for underlying kinematic actor |
430 | |
431 | The CCT creates a PhysX's kinematic actor under the hood. This controls its scale factor. |
432 | This should be a number a bit smaller than 1.0. |
433 | |
434 | <b>Default:</b> 0.8 |
435 | */ |
436 | PxF32 scaleCoeff; |
437 | |
438 | /** |
439 | \brief Cached volume growth |
440 | |
441 | Amount of space around the controller we cache to improve performance. This is a scale factor |
442 | that should be higher than 1.0f but not too big, ideally lower than 2.0f. |
443 | |
444 | <b>Default:</b> 1.5 |
445 | */ |
446 | PxF32 volumeGrowth; |
447 | |
448 | /** |
449 | \brief Specifies a user report callback. |
450 | |
451 | This report callback is called when the character collides with shapes and other characters. |
452 | |
453 | Setting this to NULL disables the callback. |
454 | |
455 | <b>Default:</b> NULL |
456 | |
457 | @see PxUserControllerHitReport |
458 | */ |
459 | PxUserControllerHitReport* reportCallback; |
460 | |
461 | /** |
462 | \brief Specifies a user behavior callback. |
463 | |
464 | This behavior callback is called to customize the controller's behavior w.r.t. touched shapes. |
465 | |
466 | Setting this to NULL disables the callback. |
467 | |
468 | <b>Default:</b> NULL |
469 | |
470 | @see PxControllerBehaviorCallback |
471 | */ |
472 | PxControllerBehaviorCallback* behaviorCallback; |
473 | |
474 | /** |
475 | \brief The non-walkable mode controls if a character controller slides or not on a non-walkable part. |
476 | |
477 | This is only used when slopeLimit is non zero. |
478 | |
479 | <b>Default:</b> PxControllerNonWalkableMode::ePREVENT_CLIMBING |
480 | |
481 | @see PxControllerNonWalkableMode |
482 | */ |
483 | PxControllerNonWalkableMode::Enum nonWalkableMode; |
484 | |
485 | /** |
486 | \brief The material for the actor associated with the controller. |
487 | |
488 | The controller internally creates a rigid body actor. This parameter specifies the material of the actor. |
489 | |
490 | <b>Default:</b> NULL |
491 | |
492 | @see PxMaterial |
493 | */ |
494 | PxMaterial* material; |
495 | |
496 | /** |
497 | \brief Use a deletion listener to get informed about released objects and clear internal caches if needed. |
498 | |
499 | If a character controller registers a deletion listener, it will get informed about released objects. That allows the |
500 | controller to invalidate cached data that connects to a released object. If a deletion listener is not |
501 | registered, PxController::invalidateCache has to be called manually after objects have been released. |
502 | |
503 | @see PxController::invalidateCache |
504 | |
505 | <b>Default:</b> true |
506 | */ |
507 | bool registerDeletionListener; |
508 | |
509 | /** |
510 | \brief User specified data associated with the controller. |
511 | |
512 | <b>Default:</b> NULL |
513 | */ |
514 | void* userData; |
515 | |
516 | protected: |
517 | const PxControllerShapeType::Enum mType; //!< The type of the controller. This gets set by the derived class' ctor, the user should not have to change it. |
518 | |
519 | /** |
520 | \brief constructor sets to default. |
521 | */ |
522 | PX_INLINE PxControllerDesc(PxControllerShapeType::Enum); |
523 | PX_INLINE virtual ~PxControllerDesc(); |
524 | |
525 | /** |
526 | \brief copy constructor. |
527 | */ |
528 | PX_INLINE PxControllerDesc(const PxControllerDesc&); |
529 | |
530 | /** |
531 | \brief assignment operator. |
532 | */ |
533 | PX_INLINE PxControllerDesc& operator=(const PxControllerDesc&); |
534 | |
535 | PX_INLINE void copy(const PxControllerDesc&); |
536 | }; |
537 | |
538 | PX_INLINE PxControllerDesc::PxControllerDesc(PxControllerShapeType::Enum t) : mType(t) |
539 | { |
540 | upDirection = PxVec3(0.0f, 1.0f, 0.0f); |
541 | slopeLimit = 0.707f; |
542 | contactOffset = 0.1f; |
543 | stepOffset = 0.5f; |
544 | density = 10.0f; |
545 | scaleCoeff = 0.8f; |
546 | volumeGrowth = 1.5f; |
547 | reportCallback = NULL; |
548 | behaviorCallback = NULL; |
549 | userData = NULL; |
550 | nonWalkableMode = PxControllerNonWalkableMode::ePREVENT_CLIMBING; |
551 | position.x = PxExtended(0.0); |
552 | position.y = PxExtended(0.0); |
553 | position.z = PxExtended(0.0); |
554 | material = NULL; |
555 | invisibleWallHeight = 0.0f; |
556 | maxJumpHeight = 0.0f; |
557 | registerDeletionListener = true; |
558 | } |
559 | |
560 | PX_INLINE PxControllerDesc::PxControllerDesc(const PxControllerDesc& other) : mType(other.mType) |
561 | { |
562 | copy(other); |
563 | } |
564 | |
565 | PX_INLINE PxControllerDesc& PxControllerDesc::operator=(const PxControllerDesc& other) |
566 | { |
567 | copy(other); |
568 | return *this; |
569 | } |
570 | |
571 | PX_INLINE void PxControllerDesc::copy(const PxControllerDesc& other) |
572 | { |
573 | upDirection = other.upDirection; |
574 | slopeLimit = other.slopeLimit; |
575 | contactOffset = other.contactOffset; |
576 | stepOffset = other.stepOffset; |
577 | density = other.density; |
578 | scaleCoeff = other.scaleCoeff; |
579 | volumeGrowth = other.volumeGrowth; |
580 | reportCallback = other.reportCallback; |
581 | behaviorCallback = other.behaviorCallback; |
582 | userData = other.userData; |
583 | nonWalkableMode = other.nonWalkableMode; |
584 | position.x = other.position.x; |
585 | position.y = other.position.y; |
586 | position.z = other.position.z; |
587 | material = other.material; |
588 | invisibleWallHeight = other.invisibleWallHeight; |
589 | maxJumpHeight = other.maxJumpHeight; |
590 | registerDeletionListener = other.registerDeletionListener; |
591 | } |
592 | |
593 | PX_INLINE PxControllerDesc::~PxControllerDesc() |
594 | { |
595 | } |
596 | |
597 | PX_INLINE bool PxControllerDesc::isValid() const |
598 | { |
599 | if( mType!=PxControllerShapeType::eBOX |
600 | && mType!=PxControllerShapeType::eCAPSULE) |
601 | return false; |
602 | if(scaleCoeff<0.0f) |
603 | return false; |
604 | if(volumeGrowth<1.0f) |
605 | return false; |
606 | if(density<0.0f) |
607 | return false; |
608 | if(slopeLimit<0.0f) |
609 | return false; |
610 | if(stepOffset<0.0f) |
611 | return false; |
612 | if(contactOffset<=0.0f) |
613 | return false; |
614 | if(!material) |
615 | return false; |
616 | if(!toVec3(v: position).isFinite()) |
617 | return false; //the float version needs to be finite otherwise actor creation will fail. |
618 | |
619 | return true; |
620 | } |
621 | |
622 | |
623 | /** |
624 | \brief Base class for character controllers. |
625 | |
626 | @see PxCapsuleController PxBoxController |
627 | */ |
628 | class PxController |
629 | { |
630 | public: |
631 | //********************************************************************* |
632 | // DEPRECATED FUNCTIONS: |
633 | // |
634 | // PX_DEPRECATED virtual void setInteraction(PxCCTInteractionMode::Enum flag) = 0; |
635 | // PX_DEPRECATED virtual PxCCTInteractionMode::Enum getInteraction() const = 0; |
636 | // PX_DEPRECATED virtual void setGroupsBitmask(PxU32 bitmask) = 0; |
637 | // PX_DEPRECATED virtual PxU32 getGroupsBitmask() const = 0; |
638 | // |
639 | // => replaced with: |
640 | // |
641 | // PxControllerFilters::mCCTFilterCallback. Please define a PxControllerFilterCallback object and emulate the old interaction mode there. |
642 | // |
643 | //********************************************************************* |
644 | |
645 | /** |
646 | \brief Return the type of controller |
647 | |
648 | @see PxControllerType |
649 | */ |
650 | virtual PxControllerShapeType::Enum getType() const = 0; |
651 | |
652 | /** |
653 | \brief Releases the controller. |
654 | */ |
655 | virtual void release() = 0; |
656 | |
657 | /** |
658 | \brief Moves the character using a "collide-and-slide" algorithm. |
659 | |
660 | \param[in] disp Displacement vector |
661 | \param[in] minDist The minimum travelled distance to consider. If travelled distance is smaller, the character doesn't move. |
662 | This is used to stop the recursive motion algorithm when remaining distance to travel is small. |
663 | \param[in] elapsedTime Time elapsed since last call |
664 | \param[in] filters User-defined filters for this move |
665 | \param[in] obstacles Potential additional obstacles the CCT should collide with. |
666 | \return Collision flags, collection of ::PxControllerCollisionFlags |
667 | */ |
668 | virtual PxControllerCollisionFlags move(const PxVec3& disp, PxF32 minDist, PxF32 elapsedTime, const PxControllerFilters& filters, const PxObstacleContext* obstacles=NULL) = 0; |
669 | |
670 | /** |
671 | \brief Sets controller's position. |
672 | |
673 | The position controlled by this function is the center of the collision shape. |
674 | |
675 | \warning This is a 'teleport' function, it doesn't check for collisions. |
676 | \warning The character's position must be such that it does not overlap the static geometry. |
677 | |
678 | To move the character under normal conditions use the #move() function. |
679 | |
680 | \param[in] position The new (center) positon for the controller. |
681 | \return Currently always returns true. |
682 | |
683 | @see PxControllerDesc.position getPosition() getFootPosition() setFootPosition() move() |
684 | */ |
685 | virtual bool setPosition(const PxExtendedVec3& position) = 0; |
686 | |
687 | /** |
688 | \brief Retrieve the raw position of the controller. |
689 | |
690 | The position retrieved by this function is the center of the collision shape. To retrieve the bottom position of the shape, |
691 | a.k.a. the foot position, use the getFootPosition() function. |
692 | |
693 | The position is updated by calls to move(). Calling this method without calling |
694 | move() will return the last position or the initial position of the controller. |
695 | |
696 | \return The controller's center position |
697 | |
698 | @see PxControllerDesc.position setPosition() getFootPosition() setFootPosition() move() |
699 | */ |
700 | virtual const PxExtendedVec3& getPosition() const = 0; |
701 | |
702 | /** |
703 | \brief Set controller's foot position. |
704 | |
705 | The position controlled by this function is the bottom of the collision shape, a.k.a. the foot position. |
706 | |
707 | \note The foot position takes the contact offset into account |
708 | |
709 | \warning This is a 'teleport' function, it doesn't check for collisions. |
710 | |
711 | To move the character under normal conditions use the #move() function. |
712 | |
713 | \param[in] position The new (bottom) positon for the controller. |
714 | \return Currently always returns true. |
715 | |
716 | @see PxControllerDesc.position setPosition() getPosition() getFootPosition() move() |
717 | */ |
718 | virtual bool (const PxExtendedVec3& position) = 0; |
719 | |
720 | /** |
721 | \brief Retrieve the "foot" position of the controller, i.e. the position of the bottom of the CCT's shape. |
722 | |
723 | \note The foot position takes the contact offset into account |
724 | |
725 | \return The controller's foot position |
726 | |
727 | @see PxControllerDesc.position setPosition() getPosition() setFootPosition() move() |
728 | */ |
729 | virtual PxExtendedVec3 () const = 0; |
730 | |
731 | /** |
732 | \brief Get the rigid body actor associated with this controller (see PhysX documentation). |
733 | The behavior upon manually altering this actor is undefined, you should primarily |
734 | use it for reading const properties. |
735 | |
736 | \return the actor associated with the controller. |
737 | */ |
738 | virtual PxRigidDynamic* getActor() const = 0; |
739 | |
740 | /** |
741 | \brief The step height. |
742 | |
743 | \param[in] offset The new step offset for the controller. |
744 | |
745 | @see PxControllerDesc.stepOffset |
746 | */ |
747 | virtual void setStepOffset(const PxF32 offset) =0; |
748 | |
749 | /** |
750 | \brief Retrieve the step height. |
751 | |
752 | \return The step offset for the controller. |
753 | |
754 | @see setStepOffset() |
755 | */ |
756 | virtual PxF32 getStepOffset() const =0; |
757 | |
758 | /** |
759 | \brief Sets the non-walkable mode for the CCT. |
760 | |
761 | \param[in] flag The new value of the non-walkable mode. |
762 | |
763 | \see PxControllerNonWalkableMode |
764 | */ |
765 | virtual void setNonWalkableMode(PxControllerNonWalkableMode::Enum flag) = 0; |
766 | |
767 | /** |
768 | \brief Retrieves the non-walkable mode for the CCT. |
769 | |
770 | \return The current non-walkable mode. |
771 | |
772 | \see PxControllerNonWalkableMode |
773 | */ |
774 | virtual PxControllerNonWalkableMode::Enum getNonWalkableMode() const = 0; |
775 | |
776 | /** |
777 | \brief Retrieve the contact offset. |
778 | |
779 | \return The contact offset for the controller. |
780 | |
781 | @see PxControllerDesc.contactOffset |
782 | */ |
783 | virtual PxF32 getContactOffset() const =0; |
784 | |
785 | /** |
786 | \brief Sets the contact offset. |
787 | |
788 | \param[in] offset The contact offset for the controller. |
789 | |
790 | @see PxControllerDesc.contactOffset |
791 | */ |
792 | virtual void setContactOffset(PxF32 offset) =0; |
793 | |
794 | /** |
795 | \brief Retrieve the 'up' direction. |
796 | |
797 | \return The up direction for the controller. |
798 | |
799 | @see PxControllerDesc.upDirection |
800 | */ |
801 | virtual PxVec3 getUpDirection() const =0; |
802 | |
803 | /** |
804 | \brief Sets the 'up' direction. |
805 | |
806 | \param[in] up The up direction for the controller. |
807 | |
808 | @see PxControllerDesc.upDirection |
809 | */ |
810 | virtual void setUpDirection(const PxVec3& up) =0; |
811 | |
812 | /** |
813 | \brief Retrieve the slope limit. |
814 | |
815 | \return The slope limit for the controller. |
816 | |
817 | @see PxControllerDesc.slopeLimit |
818 | */ |
819 | virtual PxF32 getSlopeLimit() const =0; |
820 | |
821 | /** |
822 | \brief Sets the slope limit. |
823 | |
824 | \note This feature can not be enabled at runtime, i.e. if the slope limit is zero when creating the CCT |
825 | (which disables the feature) then changing the slope limit at runtime will not have any effect, and the call |
826 | will be ignored. |
827 | |
828 | \param[in] slopeLimit The slope limit for the controller. |
829 | |
830 | @see PxControllerDesc.slopeLimit |
831 | */ |
832 | virtual void setSlopeLimit(PxF32 slopeLimit) =0; |
833 | |
834 | /** |
835 | \brief Flushes internal geometry cache. |
836 | |
837 | The character controller uses caching in order to speed up collision testing. The cache is |
838 | automatically flushed when a change to static objects is detected in the scene. For example when a |
839 | static shape is added, updated, or removed from the scene, the cache is automatically invalidated. |
840 | |
841 | However there may be situations that cannot be automatically detected, and those require manual |
842 | invalidation of the cache. Currently the user must call this when the filtering behavior changes (the |
843 | PxControllerFilters parameter of the PxController::move call). While the controller in principle |
844 | could detect a change in these parameters, it cannot detect a change in the behavior of the filtering |
845 | function. |
846 | |
847 | @see PxController.move |
848 | */ |
849 | virtual void invalidateCache() = 0; |
850 | |
851 | /** |
852 | \brief Retrieve the scene associated with the controller. |
853 | |
854 | \return The physics scene |
855 | */ |
856 | virtual PxScene* getScene() = 0; |
857 | |
858 | /** |
859 | \brief Returns the user data associated with this controller. |
860 | |
861 | \return The user pointer associated with the controller. |
862 | |
863 | @see PxControllerDesc.userData |
864 | */ |
865 | virtual void* getUserData() const = 0; |
866 | |
867 | /** |
868 | \brief Sets the user data associated with this controller. |
869 | |
870 | \param[in] userData The user pointer associated with the controller. |
871 | |
872 | @see PxControllerDesc.userData |
873 | */ |
874 | virtual void setUserData(void* userData) = 0; |
875 | |
876 | /** |
877 | \brief Returns information about the controller's internal state. |
878 | |
879 | \param[out] state The controller's internal state |
880 | |
881 | @see PxControllerState |
882 | */ |
883 | virtual void getState(PxControllerState& state) const = 0; |
884 | |
885 | /** |
886 | \brief Returns the controller's internal statistics. |
887 | |
888 | \param[out] stats The controller's internal statistics |
889 | |
890 | @see PxControllerStats |
891 | */ |
892 | virtual void getStats(PxControllerStats& stats) const = 0; |
893 | |
894 | /** |
895 | \brief Resizes the controller. |
896 | |
897 | This function attempts to resize the controller to a given size, while making sure the bottom |
898 | position of the controller remains constant. In other words the function modifies both the |
899 | height and the (center) position of the controller. This is a helper function that can be used |
900 | to implement a 'crouch' functionality for example. |
901 | |
902 | \param[in] height Desired controller's height |
903 | */ |
904 | virtual void resize(PxReal height) = 0; |
905 | |
906 | protected: |
907 | PX_INLINE PxController() {} |
908 | virtual ~PxController() {} |
909 | }; |
910 | |
911 | #if !PX_DOXYGEN |
912 | } // namespace physx |
913 | #endif |
914 | |
915 | /** @} */ |
916 | #endif |
917 | |