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 PX_COOKING_H
32#define PX_COOKING_H
33/** \addtogroup cooking
34@{
35*/
36#include "common/PxPhysXCommonConfig.h"
37#include "common/PxTolerancesScale.h"
38#include "cooking/Pxc.h"
39
40#include "cooking/PxConvexMeshDesc.h"
41#include "cooking/PxTriangleMeshDesc.h"
42#include "cooking/PxMidphaseDesc.h"
43#include "cooking/PxBVHStructureDesc.h"
44#include "geometry/PxTriangleMesh.h"
45#include "geometry/PxBVHStructure.h"
46
47#if !PX_DOXYGEN
48namespace physx
49{
50#endif
51
52class PxPhysicsInsertionCallback;
53class PxFoundation;
54
55/**
56\brief Result from convex cooking.
57*/
58struct PxConvexMeshCookingResult
59{
60 enum Enum
61 {
62 /**
63 \brief Convex mesh cooking succeeded.
64 */
65 eSUCCESS,
66
67 /**
68 \brief Convex mesh cooking failed, algorithm couldn't find 4 initial vertices without a small triangle.
69
70 @see PxCookingParams::areaTestEpsilon PxConvexFlag::eCHECK_ZERO_AREA_TRIANGLES
71 */
72 eZERO_AREA_TEST_FAILED,
73
74 /**
75 \brief Convex mesh cooking succeeded, but the algorithm has reached the 255 polygons limit.
76 The produced hull does not contain all input vertices. Try to simplify the input vertices
77 or try to use the eINFLATE_CONVEX or the eQUANTIZE_INPUT flags.
78
79 @see PxConvexFlag::eINFLATE_CONVEX PxConvexFlag::eQUANTIZE_INPUT
80 */
81 ePOLYGONS_LIMIT_REACHED,
82
83 /**
84 \brief Something unrecoverable happened. Check the error stream to find out what.
85 */
86 eFAILURE
87 };
88};
89
90/** \brief Enumeration for convex mesh cooking algorithms. */
91struct PxConvexMeshCookingType
92{
93 enum Enum
94 {
95 /**
96 \brief The Quickhull algorithm constructs the hull from the given input points. The resulting hull
97 will only contain a subset of the input points.
98
99 */
100 eQUICKHULL
101 };
102};
103
104/**
105\brief Result from triangle mesh cooking
106*/
107struct PxTriangleMeshCookingResult
108{
109 enum Enum
110 {
111 /**
112 \brief Everything is A-OK.
113 */
114 eSUCCESS = 0,
115
116 /**
117 \brief a triangle is too large for well-conditioned results. Tessellate the mesh for better behavior, see the user guide section on cooking for more details.
118 */
119 eLARGE_TRIANGLE,
120
121 /**
122 \brief Something unrecoverable happened. Check the error stream to find out what.
123 */
124 eFAILURE
125 };
126};
127
128/**
129
130\brief Enum for the set of mesh pre-processing parameters.
131
132*/
133
134struct PxMeshPreprocessingFlag
135{
136 enum Enum
137 {
138 /**
139 \brief When set, mesh welding is performed. See PxCookingParams::meshWeldTolerance. Clean mesh must be enabled.
140 */
141 eWELD_VERTICES = 1 << 0,
142
143 /**
144 \brief When set, mesh cleaning is disabled. This makes cooking faster.
145
146 When clean mesh is not performed, mesh welding is also not performed.
147
148 It is recommended to use only meshes that passed during validateTriangleMesh.
149
150 */
151 eDISABLE_CLEAN_MESH = 1 << 1,
152
153 /**
154 \brief When set, active edges are set for each triangle edge. This makes cooking faster but slow up contact generation.
155 */
156 eDISABLE_ACTIVE_EDGES_PRECOMPUTE = 1 << 2,
157
158 /**
159 \brief When set, 32-bit indices will always be created regardless of triangle count.
160
161 \note By default mesh will be created with 16-bit indices for triangle count <= 0xFFFF and 32-bit otherwise.
162 */
163 eFORCE_32BIT_INDICES = 1 << 3
164 };
165};
166
167typedef PxFlags<PxMeshPreprocessingFlag::Enum,PxU32> PxMeshPreprocessingFlags;
168
169/**
170
171\brief Structure describing parameters affecting mesh cooking.
172
173@see PxSetCookingParams() PxGetCookingParams()
174*/
175struct PxCookingParams
176{
177 /**
178 \brief Zero-size area epsilon used in convex hull computation.
179
180 If the area of a triangle of the hull is below this value, the triangle will be rejected. This test
181 is done only if PxConvexFlag::eCHECK_ZERO_AREA_TRIANGLES is used.
182
183 @see PxConvexFlag::eCHECK_ZERO_AREA_TRIANGLES
184
185 <b>Default value:</b> 0.06f*PxTolerancesScale.length*PxTolerancesScale.length
186
187 <b>Range:</b> (0.0f, PX_MAX_F32)
188 */
189 float areaTestEpsilon;
190
191 /**
192 \brief Plane tolerance used in convex hull computation.
193
194 The value is used during hull construction. When a new point is about to be added to the hull it
195 gets dropped when the point is closer to the hull than the planeTolerance. The planeTolerance
196 is increased according to the hull size.
197
198 If 0.0f is set all points are accepted when the convex hull is created. This may lead to edge cases
199 where the new points may be merged into an existing polygon and the polygons plane equation might
200 slightly change therefore. This might lead to failures during polygon merging phase in the hull computation.
201
202 It is recommended to use the default value, however if it is required that all points needs to be
203 accepted or huge thin convexes are created, it might be required to lower the default value.
204
205 \note The plane tolerance is used only within PxConvexMeshCookingType::eQUICKHULL algorithm.
206
207 <b>Default value:</b> 0.0007f
208
209 <b>Range:</b> <0.0f, PX_MAX_F32)
210 */
211 float planeTolerance;
212
213 /**
214 \brief Convex hull creation algorithm.
215
216 <b>Default value:</b> PxConvexMeshCookingType::eQUICKHULL
217
218 @see PxConvexMeshCookingType
219 */
220 PxConvexMeshCookingType::Enum convexMeshCookingType;
221
222 /**
223 \brief When true, the face remap table is not created. This saves a significant amount of memory, but the SDK will
224 not be able to provide the remap information for internal mesh triangles returned by collisions,
225 sweeps or raycasts hits.
226
227 <b>Default value:</b> false
228 */
229 bool suppressTriangleMeshRemapTable;
230
231 /**
232 \brief When true, the triangle adjacency information is created. You can get the adjacency triangles
233 for a given triangle from getTriangle.
234
235 <b>Default value:</b> false
236 */
237 bool buildTriangleAdjacencies;
238
239 /**
240 \brief When true, addigional information required for GPU-accelerated rigid body simulation is created. This can increase memory usage and cooking times for convex meshes and triangle meshes.
241
242 <b>Default value:</b> false
243 */
244 bool buildGPUData;
245
246 /**
247 \brief Tolerance scale is used to check if cooked triangles are not too huge. This check will help with simulation stability.
248
249 \note The PxTolerancesScale values have to match the values used when creating a PxPhysics or PxScene instance.
250
251 @see PxTolerancesScale
252 */
253 PxTolerancesScale scale;
254
255 /**
256 \brief Mesh pre-processing parameters. Used to control options like whether the mesh cooking performs vertex welding before cooking.
257
258 <b>Default value:</b> 0
259 */
260 PxMeshPreprocessingFlags meshPreprocessParams;
261
262 /**
263 \brief Mesh weld tolerance. If mesh welding is enabled, this controls the distance at which vertices are welded.
264 If mesh welding is not enabled, this value defines the acceptance distance for mesh validation. Provided no two vertices are within this distance, the mesh is considered to be
265 clean. If not, a warning will be emitted. Having a clean, welded mesh is required to achieve the best possible performance.
266
267 The default vertex welding uses a snap-to-grid approach. This approach effectively truncates each vertex to integer values using meshWeldTolerance.
268 Once these snapped vertices are produced, all vertices that snap to a given vertex on the grid are remapped to reference a single vertex. Following this,
269 all triangles' indices are remapped to reference this subset of clean vertices. It should be noted that the vertices that we do not alter the
270 position of the vertices; the snap-to-grid is only performed to identify nearby vertices.
271
272 The mesh validation approach also uses the same snap-to-grid approach to identify nearby vertices. If more than one vertex snaps to a given grid coordinate,
273 we ensure that the distance between the vertices is at least meshWeldTolerance. If this is not the case, a warning is emitted.
274
275 <b>Default value:</b> 0.0
276 */
277 PxReal meshWeldTolerance;
278
279 /**
280 \brief Controls the desired midphase desc structure for triangle meshes.
281
282 @see PxBVH33MidphaseDesc, PxBVH34MidphaseDesc, PxMidphaseDesc
283
284 <b>Default value:</b> PxMeshMidPhase::eBVH33
285 */
286 PxMidphaseDesc midphaseDesc;
287
288 /**
289 \brief Vertex limit beyond which additional acceleration structures are computed for each convex mesh. Increase that limit to reduce memory usage.
290 Computing the extra structures all the time does not guarantee optimal performance. There is a per-platform break-even point below which the
291 extra structures actually hurt performance.
292
293 <b>Default value:</b> 32
294 */
295 PxU32 gaussMapLimit;
296
297 PxCookingParams(const PxTolerancesScale& sc):
298 areaTestEpsilon (0.06f*sc.length*sc.length),
299 planeTolerance (0.0007f),
300 convexMeshCookingType (PxConvexMeshCookingType::eQUICKHULL),
301 suppressTriangleMeshRemapTable (false),
302 buildTriangleAdjacencies (false),
303 buildGPUData (false),
304 scale (sc),
305 meshPreprocessParams (0),
306 meshWeldTolerance (0.f),
307 gaussMapLimit (32)
308 {
309 }
310};
311
312class PxCooking
313{
314public:
315 /**
316 \brief Closes this instance of the interface.
317
318 This function should be called to cleanly shut down the Cooking library before application exit.
319
320 \note This function is required to be called to release foundation usage.
321
322 */
323 virtual void release() = 0;
324
325 /**
326 \brief Sets cooking parameters
327
328 \param[in] params Cooking parameters
329
330 @see getParams()
331 */
332 virtual void setParams(const PxCookingParams& params) = 0;
333
334 /**
335 \brief Gets cooking parameters
336
337 \return Current cooking parameters.
338
339 @see PxCookingParams setParams()
340 */
341 virtual const PxCookingParams& getParams() const = 0;
342
343 /**
344 \brief Checks endianness is the same between cooking & target platforms
345
346 \return True if there is and endian mismatch.
347 */
348 virtual bool platformMismatch() const = 0;
349
350 /**
351 \brief Cooks a triangle mesh. The results are written to the stream.
352
353 To create a triangle mesh object it is necessary to first 'cook' the mesh data into
354 a form which allows the SDK to perform efficient collision detection.
355
356 cookTriangleMesh() allows a mesh description to be cooked into a binary stream
357 suitable for loading and performing collision detection at runtime.
358
359 \param[in] desc The triangle mesh descriptor to read the mesh from.
360 \param[in] stream User stream to output the cooked data.
361 \param[out] condition Result from triangle mesh cooking.
362 \return true on success
363
364 @see cookConvexMesh() setParams() PxPhysics.createTriangleMesh() PxTriangleMeshCookingResult::Enum
365 */
366 virtual bool cookTriangleMesh(const PxTriangleMeshDesc& desc, PxOutputStream& stream, PxTriangleMeshCookingResult::Enum* condition = NULL) const = 0;
367
368
369 /**
370 \brief Cooks and creates a triangle mesh and inserts it into PxPhysics.
371
372 \note PxPhysicsInsertionCallback can be obtained through PxPhysics::getPhysicsInsertionCallback().
373
374 \param[in] desc The triangle mesh descriptor to read the mesh from.
375 \param[in] insertionCallback The insertion interface from PxPhysics.
376 \param[out] condition Result from triangle mesh cooking.
377 \return PxTriangleMesh pointer on success.
378
379 @see cookTriangleMesh() setParams() PxPhysics.createTriangleMesh() PxPhysicsInsertionCallback
380 */
381 virtual PxTriangleMesh* createTriangleMesh(const PxTriangleMeshDesc& desc, PxPhysicsInsertionCallback& insertionCallback, PxTriangleMeshCookingResult::Enum* condition = NULL) const = 0;
382
383 /**
384 \brief Verifies if the triangle mesh is valid. Prints an error message for each inconsistency found.
385
386 The following conditions are true for a valid triangle mesh:
387 1. There are no duplicate vertices (within specified vertexWeldTolerance. See PxCookingParams::meshWeldTolerance)
388 2. There are no large triangles (within specified PxTolerancesScale.)
389
390 \param[in] desc The triangle mesh descriptor to read the mesh from.
391
392 \return true if all the validity conditions hold, false otherwise.
393
394 @see cookTriangleMesh()
395 */
396 virtual bool validateTriangleMesh(const PxTriangleMeshDesc& desc) const = 0;
397
398
399 /**
400 \brief Cooks a convex mesh. The results are written to the stream.
401
402 To create a triangle mesh object it is necessary to first 'cook' the mesh data into
403 a form which allows the SDK to perform efficient collision detection.
404
405 cookConvexMesh() allows a mesh description to be cooked into a binary stream
406 suitable for loading and performing collision detection at runtime.
407
408 \note The number of vertices and the number of convex polygons in a cooked convex mesh is limited to 255.
409 \note If those limits are exceeded in either the user-provided data or the final cooked mesh, an error is reported.
410
411 \param[in] desc The convex mesh descriptor to read the mesh from.
412 \param[in] stream User stream to output the cooked data.
413 \param[out] condition Result from convex mesh cooking.
414 \return true on success.
415
416 @see cookTriangleMesh() setParams() PxConvexMeshCookingResult::Enum
417 */
418 virtual bool cookConvexMesh(const PxConvexMeshDesc& desc, PxOutputStream& stream, PxConvexMeshCookingResult::Enum* condition = NULL) const = 0;
419
420 /**
421 \brief Cooks and creates a convex mesh and inserts it into PxPhysics.
422
423 \note This method does the same as cookConvexMesh, but the produced convex mesh is not stored
424 into a stream but is directly inserted in PxPhysics. Use this method if you are unable to cook offline.
425
426 \note PxPhysicsInsertionCallback can be obtained through PxPhysics::getPhysicsInsertionCallback().
427
428 \param[in] desc The convex mesh descriptor to read the mesh from.
429 \param[in] insertionCallback The insertion interface from PxPhysics.
430 \param[out] condition Result from convex mesh cooking.
431 \return PxConvexMesh pointer on success
432
433 @see cookConvexMesh() setParams() PxPhysicsInsertionCallback
434 */
435 virtual PxConvexMesh* createConvexMesh(const PxConvexMeshDesc& desc, PxPhysicsInsertionCallback& insertionCallback, PxConvexMeshCookingResult::Enum* condition = NULL) const = 0;
436
437 /**
438 \brief Verifies if the convex mesh is valid. Prints an error message for each inconsistency found.
439
440 The convex mesh descriptor must contain an already created convex mesh - the vertices, indices and polygons must be provided.
441
442 \note This function should be used if PxConvexFlag::eDISABLE_MESH_VALIDATION is planned to be used in release builds.
443
444 \param[in] desc The convex mesh descriptor to read the mesh from.
445
446 \return true if all the validity conditions hold, false otherwise.
447
448 @see cookConvexMesh()
449 */
450 virtual bool validateConvexMesh(const PxConvexMeshDesc& desc) const = 0;
451
452
453 /**
454 \brief Computed hull polygons from given vertices and triangles. Polygons are needed for PxConvexMeshDesc rather than triangles.
455
456 Please note that the resulting polygons may have different number of vertices. Some vertices may be removed.
457 The output vertices, indices and polygons must be used to construct a hull.
458
459 The provided PxAllocatorCallback does allocate the out array's. It is the user responsibility to deallocated those
460 array's.
461
462 \param[in] mesh Simple triangle mesh containing vertices and triangles used to compute polygons.
463 \param[in] inCallback Memory allocator for out array allocations.
464 \param[out] nbVerts Number of vertices used by polygons.
465 \param[out] vertices Vertices array used by polygons.
466 \param[out] nbIndices Number of indices used by polygons.
467 \param[out] indices Indices array used by polygons.
468 \param[out] nbPolygons Number of created polygons.
469 \param[out] hullPolygons Polygons array.
470 \return true on success
471
472 @see cookConvexMesh() PxConvexFlags PxConvexMeshDesc PxSimpleTriangleMesh
473 */
474 virtual bool computeHullPolygons(const PxSimpleTriangleMesh& mesh, PxAllocatorCallback& inCallback, PxU32& nbVerts, PxVec3*& vertices,
475 PxU32& nbIndices, PxU32*& indices, PxU32& nbPolygons, PxHullPolygon*& hullPolygons) const = 0;
476
477 /**
478 \brief Cooks a heightfield. The results are written to the stream.
479
480 To create a heightfield object there is an option to precompute some of calculations done while loading the heightfield data.
481
482 cookHeightField() allows a heightfield description to be cooked into a binary stream
483 suitable for loading and performing collision detection at runtime.
484
485 \param[in] desc The heightfield descriptor to read the HF from.
486 \param[in] stream User stream to output the cooked data.
487 \return true on success
488
489 @see PxPhysics.createHeightField()
490 */
491 virtual bool cookHeightField(const PxHeightFieldDesc& desc, PxOutputStream& stream) const = 0;
492
493 /**
494 \brief Cooks and creates a heightfield mesh and inserts it into PxPhysics.
495
496 \param[in] desc The heightfield descriptor to read the HF from.
497 \param[in] insertionCallback The insertion interface from PxPhysics.
498 \return PxHeightField pointer on success
499
500 @see cookConvexMesh() setParams() PxPhysics.createTriangleMesh() PxPhysicsInsertionCallback
501 */
502 virtual PxHeightField* createHeightField(const PxHeightFieldDesc& desc, PxPhysicsInsertionCallback& insertionCallback) const = 0;
503
504 /**
505 \brief Cooks a bounding volume hierarchy structure. The results are written to the stream.
506
507 cookBVHStructure() allows a BVH structure description to be cooked into a binary stream
508 suitable for loading and performing BVH detection at runtime.
509
510 \param[in] desc The BVH structure descriptor.
511 \param[in] stream User stream to output the cooked data.
512 \return true on success.
513
514 @see PxBVHStructure PxRigidActorExt::getRigidActorShapeLocalBoundsList
515 */
516 virtual bool cookBVHStructure(const PxBVHStructureDesc& desc, PxOutputStream& stream) const = 0;
517
518 /**
519 \brief Cooks and creates a bounding volume hierarchy structure and inserts it into PxPhysics.
520
521 \note This method does the same as cookBVHStructure, but the produced BVH structure is not stored
522 into a stream but is directly inserted in PxPhysics. Use this method if you are unable to cook offline.
523
524 \note PxPhysicsInsertionCallback can be obtained through PxPhysics::getPhysicsInsertionCallback().
525
526 \param[in] desc The BVH structure descriptor.
527 \param[in] insertionCallback The insertion interface from PxPhysics.
528 \return PxBVHStructure pointer on success
529
530 @see cookBVHStructure() PxPhysicsInsertionCallback
531 */
532 virtual PxBVHStructure* createBVHStructure(const PxBVHStructureDesc& desc, PxPhysicsInsertionCallback& insertionCallback) const = 0;
533protected:
534 virtual ~PxCooking(){}
535};
536
537#if !PX_DOXYGEN
538} // namespace physx
539#endif
540
541/**
542\brief Create an instance of the cooking interface.
543
544Note that the foundation object is handled as an application-wide singleton in statically linked executables
545and a DLL-wide singleton in dynamically linked executables. Therefore, if you are using the runtime SDK in the
546same executable as cooking, you should pass the Physics's copy of foundation (acquired with
547PxPhysics::getFoundation()) to the cooker. This will also ensure correct handling of memory for objects
548passed from the cooker to the SDK.
549
550To use cooking in standalone mode, create an instance of the Foundation object with PxCreateFoundation.
551You should pass the same foundation object to all instances of the cooking interface.
552
553\param[in] version the SDK version number
554\param[in] foundation the foundation object associated with this instance of the cooking interface.
555\param[in] params the parameters for this instance of the cooking interface
556\return true on success.
557*/
558PX_C_EXPORT PX_PHYSX_COOKING_API physx::PxCooking* PX_CALL_CONV PxCreateCooking(physx::PxU32 version,
559 physx::PxFoundation& foundation,
560 const physx::PxCookingParams& params);
561
562/** @} */
563#endif
564

source code of qtquick3dphysics/src/3rdparty/PhysX/include/cooking/PxCooking.h