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_NX_PHYSICS
15#define PX_PHYSICS_NX_PHYSICS
16
17
18/** \addtogroup physics
19@{
20*/
21
22#include "PxPhysXConfig.h"
23#include "PxDeletionListener.h"
24#include "foundation/PxTransform.h"
25#include "PxShape.h"
26#include "physxvisualdebuggersdk/PvdConnectionManager.h"
27
28#if PX_USE_CLOTH_API
29#include "cloth/PxClothTypes.h"
30#include "cloth/PxClothFabric.h"
31#endif
32
33#ifndef PX_DOXYGEN
34namespace physx
35{
36#endif
37
38class PxInputStream;
39class PxOutputStream;
40class PxPhysicsInsertionCallback;
41
42class PxRigidActor;
43class PxConstraintConnector;
44struct PxConstraintShaderTable;
45
46class PxProfileZone;
47class PxProfileZoneManager;
48
49class PxGeometry;
50
51class PxSerializationRegistry;
52
53struct PxCookingValue
54{
55 enum Enum
56 {
57 /**
58 Version numbers follow this format:
59
60 Version = 16bit|16bit
61
62 The high part is increased each time the format changes so much that
63 pre-cooked files become incompatible with the system (and hence must
64 be re-cooked)
65
66 The low part is increased each time the format changes but the code
67 can still read old files. You don't need to re-cook the data in that
68 case, unless you want to make sure cooked files are optimal.
69 */
70 eCONVEX_VERSION_PC,
71 eMESH_VERSION_PC,
72 eCONVEX_VERSION_XENON,
73 eMESH_VERSION_XENON,
74 eCONVEX_VERSION_PLAYSTATION3,
75 eMESH_VERSION_PLAYSTATION3
76 };
77};
78
79/**
80\brief Abstract singleton factory class used for instancing objects in the Physics SDK.
81
82In addition you can use PxPhysics to set global parameters which will effect all scenes and create
83objects that can be shared across multiple scenes.
84
85You can get an instance of this class by calling PxCreateBasePhysics() or PxCreatePhysics() with pre-registered modules.
86
87@see PxCreatePhysics() PxCreateBasePhysics() PxScene PxVisualizationParameter
88*/
89class PxPhysics
90{
91public:
92
93 /** @name Basics
94 */
95 //@{
96
97
98
99 virtual ~PxPhysics() {}
100
101
102 /**
103 \brief Destroys the instance it is called on.
104
105 Use this release method to destroy an instance of this class. Be sure
106 to not keep a reference to this object after calling release.
107 Avoid release calls while a scene is simulating (in between simulate() and fetchResults() calls).
108
109 Note that this must be called once for each prior call to PxCreatePhysics, as
110 there is a reference counter. Also note that you mustn't destroy the allocator or the error callback (if available) until after the
111 reference count reaches 0 and the SDK is actually removed.
112
113 Releasing an SDK will also release any scenes, triangle meshes, convex meshes, heightfields and shapes
114 created through it, provided the user hasn't already done so.
115
116 \note This function is required to be called to release foundation usage.
117
118 @see PxCreatePhysics()
119 */
120 virtual void release() = 0;
121
122 /**
123 \brief Retrieves the Foundation instance.
124 \return A reference to the Foundation object.
125 */
126 virtual PxFoundation& getFoundation() = 0;
127
128 /**
129 \brief Retrieves the PhysX Visual Debugger.
130 \return A pointer to the PxVisualDebugger. Can be NULL if PVD is not supported on this platform.
131 */
132 virtual PxVisualDebugger* getVisualDebugger() = 0;
133
134 /**
135 The factory manager allows notifications when a new
136 connection to pvd is made. It also allows the users to specify
137 a scheme to handle the read-side of a network connection. By default,
138 the SDK specifies that a thread gets launched which blocks reading
139 on the network socket.
140
141 \return A valid manager *if* the SDK was compiled with PVD support. Null otherwise.
142 */
143 virtual PxVisualDebuggerConnectionManager* getPvdConnectionManager() = 0;
144
145 /*
146 \brief Retrieves the profile sdk manager.
147 * The profile sdk manager manages collections of SDKs and objects that are interested in
148 * receiving events from them. This is the hook if you want to write the profiling events
149 * from multiple SDK's out to a file.
150 \return The SDK's profiling system manager.
151 */
152 virtual PxProfileZoneManager* getProfileZoneManager() = 0;
153
154 /**
155 \brief Creates an aggregate with the specified maximum size and selfCollision property.
156
157 \param[in] maxSize the maximum number of actors that may be placed in the aggregate. This value must not exceed 128, otherwise NULL will be returned.
158 \param[in] enableSelfCollision whether the aggregate supports self-collision
159 \return The new aggregate.
160
161 @see PxAggregate
162 */
163 virtual PxAggregate* createAggregate(PxU32 maxSize, bool enableSelfCollision) = 0;
164
165 /**
166 \brief Returns the simulation tolerance parameters.
167 \return The current simulation tolerance parameters.
168 */
169 virtual const PxTolerancesScale& getTolerancesScale() const = 0;
170
171
172 //@}
173 /** @name Meshes
174 */
175 //@{
176
177 /**
178 \brief Creates a triangle mesh object.
179
180 This can then be instanced into #PxShape objects.
181
182 \param[in] stream The triangle mesh stream.
183 \return The new triangle mesh.
184
185 @see PxTriangleMesh PxMeshPreprocessingFlag PxTriangleMesh.release() PxInputStream PxTriangleMeshFlag
186 */
187 virtual PxTriangleMesh* createTriangleMesh(PxInputStream& stream) = 0;
188
189
190
191 /**
192 \brief Return the number of triangle meshes that currently exist.
193
194 \return Number of triangle meshes.
195
196 @see getTriangleMeshes()
197 */
198 virtual PxU32 getNbTriangleMeshes() const = 0;
199
200 /**
201 \brief Writes the array of triangle mesh pointers to a user buffer.
202
203 Returns the number of pointers written.
204
205 The ordering of the triangle meshes in the array is not specified.
206
207 \param[out] userBuffer The buffer to receive triangle mesh pointers.
208 \param[in] bufferSize The number of triangle mesh pointers which can be stored in the buffer.
209 \param[in] startIndex Index of first mesh pointer to be retrieved
210 \return The number of triangle mesh pointers written to userBuffer, this should be less or equal to bufferSize.
211
212 @see getNbTriangleMeshes() PxTriangleMesh
213 */
214 virtual PxU32 getTriangleMeshes(PxTriangleMesh** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
215
216 /**
217 \brief Creates a PxHeightField object.
218
219 Deprecated please use PxCooking::createHeightField
220
221 This can then be instanced into #PxShape objects.
222
223 \param[in] heightFieldDesc The descriptor to load the object from.
224 \return The new height field object.
225
226 @see PxHeightField PxHeightField.release() PxHeightFieldDesc PxHeightFieldGeometry PxShape PxRegisterHeightFields PxRegisterUnifiedHeightFields
227 */
228 PX_DEPRECATED virtual PxHeightField* createHeightField(const PxHeightFieldDesc& heightFieldDesc) = 0;
229
230 /**
231 \brief Creates a heightfield object from previously cooked stream.
232
233 This can then be instanced into #PxShape objects.
234
235 \param[in] stream The heightfield mesh stream.
236 \return The new heightfield.
237
238 @see PxHeightField PxHeightField.release() PxInputStream PxRegisterHeightFields PxRegisterUnifiedHeightFields
239 */
240 virtual PxHeightField* createHeightField(PxInputStream& stream) = 0;
241
242 /**
243 \brief Return the number of heightfields that currently exist.
244
245 \return Number of heightfields.
246
247 @see getHeightFields()
248 */
249 virtual PxU32 getNbHeightFields() const = 0;
250
251 /**
252 \brief Writes the array of heightfield pointers to a user buffer.
253
254 Returns the number of pointers written.
255
256 The ordering of the heightfields in the array is not specified.
257
258 \param[out] userBuffer The buffer to receive heightfield pointers.
259 \param[in] bufferSize The number of heightfield pointers which can be stored in the buffer.
260 \param[in] startIndex Index of first heightfield pointer to be retrieved
261 \return The number of heightfield pointers written to userBuffer, this should be less or equal to bufferSize.
262
263 @see getNbHeightFields() PxHeightField
264 */
265 virtual PxU32 getHeightFields(PxHeightField** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
266
267 /**
268 \brief Creates a convex mesh object.
269
270 This can then be instanced into #PxShape objects.
271
272 \param[in] stream The stream to load the convex mesh from.
273 \return The new convex mesh.
274
275 @see PxConvexMesh PxConvexMesh.release() PxInputStream createTriangleMesh() PxConvexMeshGeometry PxShape
276 */
277 virtual PxConvexMesh* createConvexMesh(PxInputStream &stream) = 0;
278
279 /**
280 \brief Return the number of convex meshes that currently exist.
281
282 \return Number of convex meshes.
283
284 @see getConvexMeshes()
285 */
286 virtual PxU32 getNbConvexMeshes() const = 0;
287
288 /**
289 \brief Writes the array of convex mesh pointers to a user buffer.
290
291 Returns the number of pointers written.
292
293 The ordering of the convex meshes in the array is not specified.
294
295 \param[out] userBuffer The buffer to receive convex mesh pointers.
296 \param[in] bufferSize The number of convex mesh pointers which can be stored in the buffer.
297 \param[in] startIndex Index of first convex mesh pointer to be retrieved
298 \return The number of convex mesh pointers written to userBuffer, this should be less or equal to bufferSize.
299
300 @see getNbConvexMeshes() PxConvexMesh
301 */
302 virtual PxU32 getConvexMeshes(PxConvexMesh** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
303
304
305#if PX_USE_CLOTH_API
306 /**
307 \brief Creates a cloth fabric object.
308
309 This can then be instanced into #PxCloth objects.
310
311 \param[in] stream The stream to load the cloth fabric from.
312 \return The new cloth fabric.
313
314 @see PxClothFabric PxClothFabric.release() PxInputStream PxCloth PxRegisterCloth
315 */
316 virtual PxClothFabric* createClothFabric(PxInputStream& stream) = 0;
317
318 /**
319 \brief Creates a cloth fabric object from particle connectivity and restlength information.
320
321 \note The particle connectivity can be created using #PxClothFabricCooker in extensions.
322
323 This can then be instanced into #PxCloth objects.
324
325 \param[in] desc Fabric descriptor, see #PxClothFabricDesc.
326 \return The new cloth fabric.
327
328 @see PxClothFabric PxClothFabric.release() PxCloth
329 */
330 virtual PxClothFabric* createClothFabric(const PxClothFabricDesc& desc) = 0;
331
332 /**
333 \brief Return the number of cloth fabrics that currently exist.
334
335 \return Number of cloth fabrics.
336
337 @see getClothFabrics()
338 */
339 virtual PxU32 getNbClothFabrics() const = 0;
340
341 /**
342 \brief Writes the array of cloth fabrics to a user buffer.
343
344 Returns the number of pointers written.
345
346 The ordering of the cloth fabrics in the array is not specified.
347
348 \param[out] userBuffer The buffer to receive cloth fabric pointers.
349 \param[in] bufferSize The number of cloth fabric pointers which can be stored in the buffer.
350 \return The number of cloth fabric pointers written to userBuffer, this should be less or equal to bufferSize.
351
352 @see getNbClothFabrics() PxClothFabric
353 */
354 virtual PxU32 getClothFabrics(PxClothFabric** userBuffer, PxU32 bufferSize) const = 0;
355#endif
356
357 //@}
358 /** @name Scenes
359 */
360 //@{
361
362 /**
363 \brief Creates a scene.
364
365 \param[in] sceneDesc Scene descriptor. See #PxSceneDesc
366 \return The new scene object.
367
368 @see PxScene PxScene.release() PxSceneDesc
369 */
370 virtual PxScene* createScene(const PxSceneDesc& sceneDesc) = 0;
371
372 /**
373 \brief Gets number of created scenes.
374
375 \return The number of scenes created.
376
377 @see getScene()
378 */
379 virtual PxU32 getNbScenes() const = 0;
380
381 /**
382 \brief Writes the array of scene pointers to a user buffer.
383
384 Returns the number of pointers written.
385
386 The ordering of the scene pointers in the array is not specified.
387
388 \param[out] userBuffer The buffer to receive scene pointers.
389 \param[in] bufferSize The number of scene pointers which can be stored in the buffer.
390 \param[in] startIndex Index of first scene pointer to be retrieved
391 \return The number of scene pointers written to userBuffer, this should be less or equal to bufferSize.
392
393 @see getNbScenes() PxScene
394 */
395 virtual PxU32 getScenes(PxScene** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
396
397 //@}
398 /** @name Actors
399 */
400 //@{
401
402 /**
403 \brief Creates a static rigid actor with the specified pose and all other fields initialized
404 to their default values.
405
406 \param[in] pose the initial pose of the actor. Must be a valid transform
407
408 @see PxRigidStatic
409 */
410
411 virtual PxRigidStatic* createRigidStatic(const PxTransform& pose) = 0;
412
413
414
415 /**
416 \brief Creates a dynamic rigid actor with the specified pose and all other fields initialized
417 to their default values.
418
419 \param[in] pose the initial pose of the actor. Must be a valid transform
420
421 @see PxRigidDynamic
422 */
423
424 virtual PxRigidDynamic* createRigidDynamic(const PxTransform& pose) = 0;
425
426
427#if PX_USE_PARTICLE_SYSTEM_API
428 /**
429 \brief Creates a particle system.
430
431 \param maxParticles the maximum number of particles that may be placed in the particle system
432 \param perParticleRestOffset whether the ParticleSystem supports perParticleRestOffset
433 \return The new particle system.
434
435 @see PxParticleSystem PxRegisterParticles
436 */
437 virtual PxParticleSystem* createParticleSystem(PxU32 maxParticles, bool perParticleRestOffset = false) = 0;
438
439 /**
440 \brief Creates a particle fluid.
441
442 \param maxParticles the maximum number of particles that may be placed in the particle fluid
443 \param perParticleRestOffset whether the ParticleFluid supports perParticleRestOffset
444 \return The new particle fluid.
445
446 @see PxParticleFluid PxRegisterParticles
447 */
448 virtual PxParticleFluid* createParticleFluid(PxU32 maxParticles, bool perParticleRestOffset = false) = 0;
449#endif
450
451
452#if PX_USE_CLOTH_API
453 /**
454 \brief Creates a cloth.
455
456 \param globalPose The world space transform of the cloth.
457 \param fabric The fabric the cloth should use.
458 \param particles Particle definition buffer. The size of the buffer has to match fabric.getNbParticles().
459 \param flags Cloth flags.
460 \return The new cloth.
461
462 @see PxCloth PxClothFabric PxClothFlags PxRegisterCloth
463 */
464 virtual PxCloth* createCloth(const PxTransform& globalPose, PxClothFabric& fabric, const PxClothParticle* particles, PxClothFlags flags) = 0;
465#endif
466
467 //@}
468 /** @name Shapes
469 */
470 //@{
471
472
473 /**
474 \brief Creates a shape which may be attached to multiple actors
475
476 The shape will be created with a reference count of 1.
477
478 \param[in] geometry the geometry for the shape
479 \param[in] material the material for the shape
480 \param[in] isExclusive whether this shape is exclusive to a single actor or maybe be shared
481 \param[in] shapeFlags the PxShapeFlags to be set
482
483 Shared shapes are not mutable when they are attached to an actor
484
485 @see PxShape
486 */
487
488 PX_FORCE_INLINE PxShape* createShape( const PxGeometry& geometry,
489 const PxMaterial& material,
490 bool isExclusive = false,
491 PxShapeFlags shapeFlags = PxShapeFlag::eVISUALIZATION | PxShapeFlag::eSCENE_QUERY_SHAPE | PxShapeFlag::eSIMULATION_SHAPE)
492 {
493 PxMaterial* materialPtr = const_cast<PxMaterial*>(&material);
494 return createShape(geometry, &materialPtr, 1, isExclusive, shapeFlags);
495 }
496
497
498 /**
499 \brief Creates a shape which may be attached to multiple actors
500
501 The shape will be created with a reference count of 1.
502
503 \param[in] geometry the geometry for the shape
504 \param[in] materials the materials for the shape
505 \param[in] materialCount the number of materials
506 \param[in] isExclusive whether this shape is exclusive to a single actor or may be shared
507 \param[in] shapeFlags the PxShapeFlags to be set
508
509 Shared shapes are not mutable when they are attached to an actor
510
511 @see PxShape
512 */
513
514 virtual PxShape* createShape(const PxGeometry& geometry,
515 PxMaterial*const * materials,
516 PxU16 materialCount,
517 bool isExclusive = false,
518 PxShapeFlags shapeFlags = PxShapeFlag::eVISUALIZATION | PxShapeFlag::eSCENE_QUERY_SHAPE | PxShapeFlag::eSIMULATION_SHAPE) = 0;
519
520
521 /**
522 \brief Return the number of shapes that currently exist.
523
524 \return Number of shapes.
525
526 @see getShapes()
527 */
528 virtual PxU32 getNbShapes() const = 0;
529
530 /**
531 \brief Writes the array of shape pointers to a user buffer.
532
533 Returns the number of pointers written.
534
535 The ordering of the shapes in the array is not specified.
536
537 \param[out] userBuffer The buffer to receive shape pointers.
538 \param[in] bufferSize The number of shape pointers which can be stored in the buffer.
539 \param[in] startIndex Index of first shape pointer to be retrieved
540 \return The number of shape pointers written to userBuffer, this should be less or equal to bufferSize.
541
542 @see getNbShapes() PxShape
543 */
544 virtual PxU32 getShapes(PxShape** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
545
546 //@}
547 /** @name Constraints and Articulations
548 */
549 //@{
550
551
552 /**
553 \brief Creates a constraint shader.
554
555 \note A constraint shader will get added automatically to the scene the two linked actors belong to. Either, but not both, of actor0 and actor1 may
556 be NULL to denote attachment to the world.
557
558 \param[in] actor0 the first actor
559 \param[in] actor1 the second actor
560 \param[in] connector the connector object, which the SDK uses to communicate with the infrastructure for the constraint
561 \param[in] shaders the shader functions for the constraint
562 \param[in] dataSize the size of the data block for the shader
563
564 \return The new shader.
565
566 @see PxConstraint
567 */
568 virtual PxConstraint* createConstraint(PxRigidActor* actor0, PxRigidActor* actor1, PxConstraintConnector& connector, const PxConstraintShaderTable& shaders, PxU32 dataSize) = 0;
569
570
571 /**
572 \brief Creates an articulation with all fields initialized to their default values.
573
574 \return the new articulation
575
576 @see PxArticulation, PxRegisterArticulations
577 */
578 virtual PxArticulation* createArticulation() = 0;
579
580 //@}
581 /** @name Materials
582 */
583 //@{
584
585
586 /**
587 \brief Creates a new material with default properties.
588
589 \return The new material.
590
591 \param staticFriction the coefficient of static friction
592 \param dynamicFriction the coefficient of dynamic friction
593 \param restitution the coefficient of restitution
594
595 @see PxMaterial
596 */
597 virtual PxMaterial* createMaterial(PxReal staticFriction, PxReal dynamicFriction, PxReal restitution) = 0;
598
599
600 /**
601 \brief Return the number of materials that currently exist.
602
603 \return Number of materials.
604
605 @see getMaterials()
606 */
607 virtual PxU32 getNbMaterials() const = 0;
608
609 /**
610 \brief Writes the array of material pointers to a user buffer.
611
612 Returns the number of pointers written.
613
614 The ordering of the materials in the array is not specified.
615
616 \param[out] userBuffer The buffer to receive material pointers.
617 \param[in] bufferSize The number of material pointers which can be stored in the buffer.
618 \param[in] startIndex Index of first material pointer to be retrieved
619 \return The number of material pointers written to userBuffer, this should be less or equal to bufferSize.
620
621 @see getNbMaterials() PxMaterial
622 */
623 virtual PxU32 getMaterials(PxMaterial** userBuffer, PxU32 bufferSize, PxU32 startIndex=0) const = 0;
624
625 //@}
626 /** @name Deletion Listeners
627 */
628 //@{
629
630 /**
631 \brief Register a deletion listener. Listeners will be called whenever an object is deleted.
632
633 It is illegal to register or unregister a deletion listener while deletions are being processed.
634
635 \note By default a registered listener will receive events from all objects. Set the restrictedObjectSet parameter to true on registration and use #registerDeletionListenerObjects to restrict the received events to specific objects.
636
637 \note The deletion events are only supported on core PhysX objects. In general, objects in extension modules do not provide this functionality, however, in the case of PxJoint objects, the underlying PxConstraint will send the events.
638
639 \param[in] observer Observer object to send notifications to.
640 \param[in] deletionEvents The deletion event types to get notified of.
641 \param[in] restrictedObjectSet If false, the deletion listener will get events from all objects, else the objects to receive events from have to be specified explicitly through #registerDeletionListenerObjects.
642
643 @see PxDeletionListener unregisterDeletionListener
644 */
645 virtual void registerDeletionListener(PxDeletionListener& observer, const PxDeletionEventFlags& deletionEvents, bool restrictedObjectSet = false) = 0;
646
647 /**
648 \brief Unregister a deletion listener.
649
650 It is illegal to register or unregister a deletion listener while deletions are being processed.
651
652 \param[in] observer Observer object to send notifications to
653
654 @see PxDeletionListener registerDeletionListener
655 */
656 virtual void unregisterDeletionListener(PxDeletionListener& observer) = 0;
657
658 /**
659 \brief Register specific objects for deletion events.
660
661 This method allows for a deletion listener to limit deletion events to specific objects only.
662
663 \note It is illegal to register or unregister objects while deletions are being processed.
664
665 \note The deletion listener has to be registered through #registerDeletionListener() and configured to support restricted objects sets prior to this method being used.
666
667 \param[in] observer Observer object to send notifications to.
668 \param[in] observables List of objects for which to receive deletion events. Only PhysX core objects are supported. In the case of PxJoint objects, the underlying PxConstraint can be used to get the events.
669 \param[in] observableCount Size of the observables list.
670
671 @see PxDeletionListener unregisterDeletionListenerObjects
672 */
673 virtual void registerDeletionListenerObjects(PxDeletionListener& observer, const PxBase* const* observables, PxU32 observableCount) = 0;
674
675 /**
676 \brief Unregister specific objects for deletion events.
677
678 This method allows to clear previously registered objects for a deletion listener (see #registerDeletionListenerObjects()).
679
680 \note It is illegal to register or unregister objects while deletions are being processed.
681
682 \note The deletion listener has to be registered through #registerDeletionListener() and configured to support restricted objects sets prior to this method being used.
683
684 \param[in] observer Observer object to stop sending notifications to.
685 \param[in] observables List of objects for which to not receive deletion events anymore.
686 \param[in] observableCount Size of the observables list.
687
688 @see PxDeletionListener registerDeletionListenerObjects
689 */
690 virtual void unregisterDeletionListenerObjects(PxDeletionListener& observer, const PxBase* const* observables, PxU32 observableCount) = 0;
691
692 /**
693 \brief Gets PxPhysics object insertion interface.
694
695 The insertion interface is needed ie. for PxCooking::createTriangleMesh, this allows runtime mesh creation. This is not adviced to do, please
696 use offline cooking if possible.
697
698 @see PxCooking::createTriangleMesh PxCooking::createHeightfield
699 */
700 virtual PxPhysicsInsertionCallback& getPhysicsInsertionCallback() = 0;
701
702 //@}
703};
704
705#ifndef PX_DOXYGEN
706} // namespace physx
707#endif
708
709/**
710\brief Reads an internal value (cooking format version).
711
712\param[in] cookValue See #PxCookingValue
713*/
714PX_C_EXPORT PX_PHYSX_CORE_API physx::PxU32 PX_CALL_CONV PxGetValue(physx::PxCookingValue::Enum cookValue);
715
716
717/**
718\brief Enables the usage of the articulations feature. This function is called automatically inside PxCreatePhysics().
719On resource constrained platforms, it is possible to call PxCreateBasePhysics() and then NOT call this function
720to save on code memory if your application does not use articulations. In this case the linker should strip out
721the relevant implementation code from the library. If you need to use articulations but not some other optional
722component, you shoud call PxCreateBasePhysics() followed by this call.
723*/
724PX_C_EXPORT PX_PHYSX_CORE_API void PX_CALL_CONV PxRegisterArticulations(physx::PxPhysics& physics);
725
726/**
727\brief Enables the usage of the default heightfield feature. This function is called automatically inside PxCreatePhysics().
728On resource constrained platforms, it is possible to call PxCreateBasePhysics() and then NOT call this function
729to save on code memory if your application does not use heightfields. In this case the linker should strip out
730the relevant implementation code from the library. If you need to use heightfield but not some other optional
731component, you shoud call PxCreateBasePhysics() followed by this call.
732
733This call will link the default 'legacy' implementation of heightfields which uses a special purpose collison code
734path distinct from triangle meshes.
735
736You must call this function at a time where no ::PxScene instance exists, typically before calling PxPhysics::createScene().
737This is to prevent a change to the heightfield implementation code at runtime which would have undefined results.
738
739Calling PxCreateBasePhysics() and then attempting to create a heightfield shape without first calling
740::PxRegisterHeightFields() or ::PxRegisterUnifiedHeightFields() will result in an error.
741*/
742PX_C_EXPORT PX_PHYSX_CORE_API void PX_CALL_CONV PxRegisterHeightFields(physx::PxPhysics& physics);
743
744/**
745\brief Enables the usage of the unified heightfield feature.
746
747This call will enable the new implementation of heightfields which is identical to the narrow phase of triangle meshes.
748
749You can call this after either PxCreatePhysics() or after PxCreateBasePhysics(), but you must call it at a time where
750no ::PxScene instance exists, typically before calling PxPhysics::createScene(). This is to prevent a change to the
751heightfield implementation code at runtime which would have undefined results.
752
753Calling PxCreateBasePhysics() and then attempting to create a heightfield shape without first calling
754::PxRegisterHeightFields() or ::PxRegisterUnifiedHeightFields() will result in an error.
755*/
756
757PX_C_EXPORT PX_PHYSX_CORE_API void PX_CALL_CONV PxRegisterUnifiedHeightFields(physx::PxPhysics& physics);
758
759/**
760\brief Enables the usage of the cloth feature. This function is called automatically inside PxCreatePhysics().
761On resource constrained platforms, it is possible to call PxCreateBasePhysics() and then NOT call this function
762to save on code memory if your application does not use cloth. In this case the linker should strip out
763the relevant implementation code from the library. If you need to use cloth but not some other optional
764component, you shoud call PxCreateBasePhysics() followed by this call.
765*/
766PX_C_EXPORT PX_PHYSX_CORE_API void PX_CALL_CONV PxRegisterCloth(physx::PxPhysics& physics);
767
768/**
769\brief Enables the usage of the particles feature. This function is called automatically inside PxCreatePhysics().
770On resource constrained platforms, it is possible to call PxCreateBasePhysics() and then NOT call this function
771to save on code memory if your application does not use particles. In this case the linker should strip out
772the relevant implementation code from the library. If you need to use particles but not some other optional
773component, you shoud call PxCreateBasePhysics() followed by this call.
774*/
775PX_C_EXPORT PX_PHYSX_CORE_API void PX_CALL_CONV PxRegisterParticles(physx::PxPhysics& physics);
776
777/**
778\brief Creates an instance of the physics SDK with minimal additional components registered
779
780Creates an instance of this class. May not be a class member to avoid name mangling.
781Pass the constant PX_PHYSICS_VERSION as the argument.
782There may be only one instance of this class per process. Calling this method after an instance
783has been created already will result in an error message and NULL will be returned.
784
785\param version Version number we are expecting(should be PX_PHYSICS_VERSION)
786\param foundation Foundation instance (see #PxFoundation)
787\param scale values used to determine default tolerances for objects at creation time
788\param trackOutstandingAllocations true if you want to track memory allocations
789 so a debugger connection partway through your physics simulation will get
790 an accurate map of everything that has been allocated so far. This could have a memory
791 and performance impact on your simulation hence it defaults to off.
792\param profileZoneManager If profiling information is required, a profile zone manager has to be provided.
793\return PxPhysics instance on success, NULL if operation failed
794
795@see PxPhysics, PxFoundation, PxTolerancesScale, PxProfileZoneManager
796*/
797PX_C_EXPORT PX_PHYSX_CORE_API physx::PxPhysics* PX_CALL_CONV PxCreateBasePhysics(physx::PxU32 version,
798 physx::PxFoundation& foundation,
799 const physx::PxTolerancesScale& scale,
800 bool trackOutstandingAllocations = false,
801 physx::PxProfileZoneManager* profileZoneManager = NULL);
802
803/**
804\brief Creates an instance of the physics SDK.
805
806Creates an instance of this class. May not be a class member to avoid name mangling.
807Pass the constant PX_PHYSICS_VERSION as the argument.
808There may be only one instance of this class per process. Calling this method after an instance
809has been created already will result in an error message and NULL will be returned.
810
811Calling this will register all optional code modules (Articulations, HeightFields, Cloth
812and Particles), preparing them for use. If you do not need some of these modules, consider
813calling PxCreateBasePhysics() instead and registering needed modules manually. If you would
814like to use the unified heightfield collision code instead, it is permitted to follow this call
815with a call to ::PxRegisterUnifiedHeightFields().
816
817\param version Version number we are expecting(should be PX_PHYSICS_VERSION)
818\param foundation Foundation instance (see #PxFoundation)
819\param scale values used to determine default tolerances for objects at creation time
820\param trackOutstandingAllocations true if you want to track memory allocations
821 so a debugger connection partway through your physics simulation will get
822 an accurate map of everything that has been allocated so far. This could have a memory
823 and performance impact on your simulation hence it defaults to off.
824\param profileZoneManager If profiling information is required, a profile zone manager has to be provided.
825 Additionally, for profiling with the Physx Visual Debugger the PVD connection flag
826 PxVisualDebuggerConnectionFlag::ePROFILE needs to be set.
827\return PxPhysics instance on success, NULL if operation failed
828
829@see PxPhysics, PxCreateBasePhysics, PxRegisterArticulations, PxRegisterHeightFields, PxRegisterCloth, PxRegisterParticles
830*/
831PX_INLINE physx::PxPhysics* PxCreatePhysics(physx::PxU32 version,
832 physx::PxFoundation& foundation,
833 const physx::PxTolerancesScale& scale,
834 bool trackOutstandingAllocations = false,
835 physx::PxProfileZoneManager* profileZoneManager = NULL)
836{
837 physx::PxPhysics* physics = PxCreateBasePhysics(version, foundation, scale, trackOutstandingAllocations, profileZoneManager);
838 if(!physics)
839 return NULL;
840
841 PxRegisterArticulations(*physics);
842 PxRegisterHeightFields(*physics);
843 PxRegisterCloth(*physics);
844 PxRegisterParticles(*physics);
845
846 return physics;
847}
848
849/**
850\brief Retrieves the Physics SDK after it has been created.
851
852Before using this function the user must call #PxCreatePhysics().
853
854\note The behavior of this method is undefined if the Physics SDK instance has not been created already.
855*/
856PX_C_EXPORT PX_PHYSX_CORE_API physx::PxPhysics& PX_CALL_CONV PxGetPhysics();
857
858#ifndef PX_DOXYGEN
859/**
860\brief Retrieves the PhysX SDK metadata.
861This function is used to implement PxSerialization.dumpBinaryMetaData() and is not intended to be needed otherwise.
862@see PxSerialization.dumpBinaryMetaData()
863*/
864PX_C_EXPORT PX_PHYSX_CORE_API void PX_CALL_CONV PxGetPhysicsBinaryMetaData(physx::PxOutputStream& stream);
865
866/**
867\brief Registers physics classes for serialization.
868This function is used to implement PxSerialization.createSerializationRegistry() and is not intended to be needed otherwise.
869@see PxSerializationRegistry
870*/
871PX_C_EXPORT PX_PHYSX_CORE_API void PX_CALL_CONV PxRegisterPhysicsSerializers(physx::PxSerializationRegistry& sr);
872
873/**
874\brief Unregisters physics classes for serialization.
875This function is used in the release implementation of PxSerializationRegistry and in not intended to be used otherwise.
876@see PxSerializationRegistry
877*/
878PX_C_EXPORT PX_PHYSX_CORE_API void PX_CALL_CONV PxUnregisterPhysicsSerializers(physx::PxSerializationRegistry& sr);
879
880
881/**
882\brief Adds collected objects to PxPhysics.
883
884This function adds all objects contained in the input collection to the PxPhysics instance. This is used after deserializing
885the collection, to populate the physics with inplace deserialized objects.
886\param[in] collection Objects to add to the PxPhysics instance.
887
888@see PxCollection
889*/
890PX_C_EXPORT PX_PHYSX_CORE_API void PX_CALL_CONV PxAddCollectionToPhysics(const physx::PxCollection& collection);
891
892#endif
893
894/** @} */
895#endif
896