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_COOKING_H
15#define PX_COOKING_H
16/** \addtogroup cooking
17@{
18*/
19#include "common/PxPhysXCommonConfig.h"
20#include "common/PxTolerancesScale.h"
21#include "cooking/Pxc.h"
22
23#include "cooking/PxConvexMeshDesc.h"
24#include "cooking/PxTriangleMeshDesc.h"
25
26#ifndef PX_DOXYGEN
27namespace physx
28{
29#endif
30
31class PxOutputStream;
32class PxBinaryConverter;
33class PxPhysicsInsertionCallback;
34
35struct PxPlatform
36{
37 enum Enum
38 {
39 ePC,
40 eXENON,
41 ePLAYSTATION3,
42 eARM,
43 eWIIU
44 };
45};
46
47/**
48\brief Result from convex cooking.
49*/
50struct PxConvexMeshCookingResult
51{
52 enum Enum
53 {
54 /**
55 \brief Convex mesh cooking succeeded.
56 */
57 eSUCCESS,
58
59 /**
60 \brief Convex mesh cooking failed, algorithm couldn't find 4 initial vertices without a small triangle.
61
62 @see PxCookingParams::areaTestEpsilon PxConvexFlag::eCHECK_ZERO_AREA_TRIANGLES
63 */
64 eZERO_AREA_TEST_FAILED,
65
66 /**
67 \brief Something unrecoverable happened. Check the error stream to find out what.
68 */
69 eFAILURE
70 };
71};
72
73/**
74
75\brief Enum for the set of mesh pre-processing parameters.
76
77*/
78
79struct PxMeshPreprocessingFlag
80{
81 enum Enum
82 {
83 /**
84 \brief When set, mesh welding is performed. See PxCookingParams::meshWeldTolerance. Clean mesh must be enabled.
85 */
86 eWELD_VERTICES = 1 << 0,
87
88 /**
89 \brief When set, unreferenced vertices are removed during clean mesh. Clean mesh must be enabledt.
90 */
91 PX_DEPRECATED eREMOVE_UNREFERENCED_VERTICES = 1 << 1,
92
93 /**
94 \brief When set, duplicit vertices are removed during clean mesh. Clean mesh must be enabled.
95 */
96 PX_DEPRECATED eREMOVE_DUPLICATED_TRIANGLES = 1 << 2,
97
98 /**
99 \brief When set, mesh cleaning is disabled. This makes cooking faster.
100
101 When clean mesh is not performed, mesh welding is also not performed.
102
103 It is recommended to use only meshes that passed during validateTriangleMesh.
104
105 */
106 eDISABLE_CLEAN_MESH = 1 << 3,
107
108 /**
109 \brief When set, active edges are set for each triangle edge. This makes cooking faster but slow up contact generation.
110 */
111 eDISABLE_ACTIVE_EDGES_PRECOMPUTE = 1 << 4,
112
113 /**
114 \brief When set, 32-bit indices will always be created regardless of triangle count.
115
116 \note By default mesh will be created with 16-bit indices for triangle count <= 0xFFFF and 32-bit otherwise.
117 */
118 eFORCE_32BIT_INDICES = 1 << 5
119 };
120};
121
122typedef PxFlags<PxMeshPreprocessingFlag::Enum,PxU32> PxMeshPreprocessingFlags;
123
124/** \brief Enumeration for mesh cooking hints. */
125struct PxMeshCookingHint
126{
127 enum Enum
128 {
129 eSIM_PERFORMANCE = 0, //!< Default value. Favors higher quality hierarchy with higher runtime performance over cooking speed.
130 eCOOKING_PERFORMANCE = 1 //!< Enables fast cooking path at the expense of somewhat lower quality hierarchy construction.
131 };
132};
133
134/**
135
136\brief Structure describing parameters affecting mesh cooking.
137
138@see PxSetCookingParams() PxGetCookingParams()
139*/
140struct PxCookingParams
141{
142 /**
143 \brief Target platform
144
145 Should be set to the platform which you intend to load the cooked mesh data on. This allows
146 the SDK to optimize the mesh data in an appropriate way for the platform and make sure that
147 endianness issues are accounted for correctly.
148
149 <b>Default value:</b> Same as the platform on which the SDK is running.
150 */
151 PxPlatform::Enum targetPlatform;
152
153 /**
154 \brief Skin width for convexes.
155
156 Specifies the amount to inflate the convex mesh when the PxConvexFlag::eINFLATE_CONVEX is used.
157
158 The value is used for moving planes outward, and beveling sharp edges. This helps the hull generator
159 code produce more stable convexes for collision detection. Please note that the resulting hull will
160 increase its size, so contact generation may produce noticeable separation between shapes. The separation
161 distance can be reduced by decreasing the contactOffset and restOffset. See the user's manual on
162 'Shapes - Tuning Shape Collision Behavior' for details.
163
164 Change the value if the produced hulls are too thin or improper for your usage. Increasing the value
165 too much will result in incorrect hull size and a large separation between shapes.
166
167 <b>Default value:</b> 0.025f*PxTolerancesScale.length
168
169 <b>Range:</b> (0.0f, PX_MAX_F32)
170 */
171 float skinWidth;
172
173 /**
174 \brief Zero-size area epsilon used in convex hull computation.
175
176 If the area of a triangle of the hull is below this value, the triangle will be rejected. This test
177 is done only if PxConvexFlag::eCHECK_ZERO_AREA_TRIANGLES is used.
178
179 @see PxConvexFlag::eCHECK_ZERO_AREA_TRIANGLES
180
181 <b>Default value:</b> 0.06f*PxTolerancesScale.length*PxTolerancesScale.length
182
183 <b>Range:</b> (0.0f, PX_MAX_F32)
184 */
185 float areaTestEpsilon;
186
187 /**
188 \brief When true, the face remap table is not created. This saves a significant amount of memory, but the SDK will
189 not be able to provide the remap information for internal mesh triangles returned by collisions,
190 sweeps or raycasts hits.
191
192 <b>Default value:</b> false
193 */
194 bool suppressTriangleMeshRemapTable;
195
196 /**
197 \brief When true, the triangle adjacency information is created. You can get the adjacency triangles
198 for a given triangle from getTriangle.
199
200 <b>Default value:</b> false
201 */
202 bool buildTriangleAdjacencies;
203
204 /**
205 \brief Tolerance scale is used to check if cooked triangles are not too huge. This check will help with simulation stability.
206
207 \note The PxTolerancesScale values have to match the values used when creating a PxPhysics or PxScene instance.
208
209 @see PxTolerancesScale
210 */
211 PxTolerancesScale scale;
212
213 /**
214 \brief Mesh pre-processing parameters. Used to control options like whether the mesh cooking performs vertex welding before cooking.
215
216 <b>Default value:</b> 0
217 */
218 PxMeshPreprocessingFlags meshPreprocessParams;
219
220 /**
221 \brief Mesh cooking hint. Used to specify mesh hierarchy construction preference.
222
223 <b>Default value:</b> PxMeshCookingHint::eSIM_PERFORMANCE
224 */
225 PxMeshCookingHint::Enum meshCookingHint;
226
227 /**
228 \brief Mesh weld tolerance. If mesh welding is enabled, this controls the distance at which vertices are welded.
229 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
230 clean. If not, a warning will be emitted. Having a clean, welded mesh is required to achieve the best possible performance.
231
232 The default vertex welding uses a snap-to-grid approach. This approach effectively truncates each vertex to integer values using meshWeldTolerance.
233 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,
234 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
235 position of the vertices; the snap-to-grid is only performed to identify nearby vertices.
236
237 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,
238 we ensure that the distance between the vertices is at least meshWeldTolerance. If this is not the case, a warning is emitted.
239
240 <b>Default value:</b> 0.0
241 */
242 PxReal meshWeldTolerance;
243
244 /**
245 \brief Controls the trade-off between mesh size and runtime performance.
246
247 Using a value of 1.0 will produce a larger cooked mesh with generally higher runtime performance,
248 using 0.0 will produce a smaller cooked mesh, with generally lower runtime performance.
249
250 Values outside of [0,1] range will be clamped and cause a warning when any mesh gets cooked.
251
252 <b>Default value:</b> 0.55
253 <b>Range:</b> [0.0f, 1.0f]
254 */
255 PxF32 meshSizePerformanceTradeOff;
256
257 PxCookingParams(const PxTolerancesScale& sc):
258 skinWidth(0.025f*sc.length),
259 areaTestEpsilon(0.06f*sc.length*sc.length),
260 suppressTriangleMeshRemapTable(false),
261 buildTriangleAdjacencies(false),
262 scale(sc),
263 meshPreprocessParams(0),
264 meshCookingHint(PxMeshCookingHint::eSIM_PERFORMANCE),
265 meshWeldTolerance(0.f),
266 meshSizePerformanceTradeOff(0.55f)
267 {
268#if defined(PX_X86) || defined(PX_X64)
269 targetPlatform = PxPlatform::ePC;
270#elif defined(PX_X360)
271 targetPlatform = PxPlatform::eXENON;
272#elif defined(PX_PS3)
273 targetPlatform = PxPlatform::ePLAYSTATION3;
274#elif defined(PX_ARM) || defined(PX_A64)
275 targetPlatform = PxPlatform::eARM;
276#elif defined(PX_WIIU)
277 targetPlatform = PxPlatform::eWIIU;
278#else
279#error Unknown platform
280#endif
281 }
282};
283
284class PxCooking
285{
286public:
287 /**
288 \brief Closes this instance of the interface.
289
290 This function should be called to cleanly shut down the Cooking library before application exit.
291
292 \note This function is required to be called to release foundation usage.
293
294 */
295 virtual void release() = 0;
296
297 /**
298 \brief Sets cooking parameters
299
300 \param[in] params Cooking parameters
301
302 @see getParams()
303 */
304 virtual void setParams(const PxCookingParams& params) = 0;
305
306 /**
307 \brief Gets cooking parameters
308
309 \return Current cooking parameters.
310
311 @see PxCookingParams setParams()
312 */
313 virtual const PxCookingParams& getParams() = 0;
314
315 /**
316 \brief Checks endianness is the same between cooking & target platforms
317
318 \return True if there is and endian mismatch.
319 */
320 virtual bool platformMismatch() = 0;
321
322 /**
323 \brief Cooks a triangle mesh. The results are written to the stream.
324
325 To create a triangle mesh object it is necessary to first 'cook' the mesh data into
326 a form which allows the SDK to perform efficient collision detection.
327
328 cookTriangleMesh() allows a mesh description to be cooked into a binary stream
329 suitable for loading and performing collision detection at runtime.
330
331 Example
332
333 \include PxCookTriangleMesh_Example.cpp
334
335 \param[in] desc The triangle mesh descriptor to read the mesh from.
336 \param[in] stream User stream to output the cooked data.
337 \return true on success
338
339 @see cookConvexMesh() setParams() PxPhysics.createTriangleMesh()
340 */
341 virtual bool cookTriangleMesh(const PxTriangleMeshDesc& desc, PxOutputStream& stream) = 0;
342
343 /**
344 \brief Cooks and creates a triangle mesh and inserts it into PxPhysics.
345
346 \param[in] desc The triangle mesh descriptor to read the mesh from.
347 \param[in] insertionCallback The insertion interface from PxPhysics.
348 \return PxTriangleMesh pointer on success
349
350 @see cookConvexMesh() setParams() PxPhysics.createTriangleMesh() PxPhysicsInsertionCallback
351 */
352 virtual PxTriangleMesh* createTriangleMesh(const PxTriangleMeshDesc& desc, PxPhysicsInsertionCallback& insertionCallback) = 0;
353
354 /**
355 \brief Verifies if the triangle mesh is valid. Prints an error message for each inconsistency found.
356
357 The following conditions are true for a valid triangle mesh:
358 1. There are no duplicate vertices (within specified vertexWeldTolerance. See PxCookingParams::meshWeldTolerance)
359 2. There are no large triangles (within specified PxTolerancesScale.)
360
361 \param[in] desc The triangle mesh descriptor to read the mesh from.
362
363 \return true if all the validity conditions hold, false otherwise.
364
365 @see cookTriangleMesh()
366 */
367 virtual bool validateTriangleMesh(const PxTriangleMeshDesc& desc) = 0;
368
369 /**
370 \brief Cooks a convex mesh. The results are written to the stream.
371
372 To create a triangle mesh object it is necessary to first 'cook' the mesh data into
373 a form which allows the SDK to perform efficient collision detection.
374
375 cookConvexMesh() allows a mesh description to be cooked into a binary stream
376 suitable for loading and performing collision detection at runtime.
377
378 Example
379
380 \include PxCookConvexMesh_Example.cpp
381
382 \note The number of vertices and the number of convex polygons in a cooked convex mesh is limited to 256.
383 \note If those limits are exceeded in either the user-provided data or the final cooked mesh, an error is reported.
384 \note If the number of polygons exceed, using the #PxConvexFlag::eINFLATE_CONVEX can help you to obtain a valid convex.
385
386 \param[in] desc The convex mesh descriptor to read the mesh from.
387 \param[in] stream User stream to output the cooked data.
388 \param[out] condition Result from convex mesh cooking.
389 \return true on success
390
391 @see cookTriangleMesh() setParams() PxConvexMeshCookingResult::Enum
392 */
393 virtual bool cookConvexMesh(const PxConvexMeshDesc& desc, PxOutputStream& stream, PxConvexMeshCookingResult::Enum* condition = NULL) = 0;
394
395 /**
396 \brief Computed hull polygons from given vertices and triangles. Polygons are needed for PxConvexMeshDesc rather than triangles.
397
398 Please note that the resulting polygons may have different number of vertices. Some vertices may be removed.
399 The output vertices, indices and polygons must be used to construct a hull.
400
401 The provided PxAllocatorCallback does allocate the out array's. It is the user responsibility to deallocated those
402 array's.
403
404 \param[in] mesh Simple triangle mesh containing vertices and triangles used to compute polygons.
405 \param[in] inCallback Memory allocator for out array allocations.
406 \param[out] nbVerts Number of vertices used by polygons.
407 \param[out] vertices Vertices array used by polygons.
408 \param[out] nbIndices Number of indices used by polygons.
409 \param[out] indices Indices array used by polygons.
410 \param[out] nbPolygons Number of created polygons.
411 \param[out] hullPolygons Polygons array.
412 \return true on success
413
414 @see cookConvexMesh() PxConvexFlags PxConvexMeshDesc PxSimpleTriangleMesh
415 */
416 virtual bool computeHullPolygons(const PxSimpleTriangleMesh& mesh, PxAllocatorCallback& inCallback, PxU32& nbVerts, PxVec3*& vertices,
417 PxU32& nbIndices, PxU32*& indices, PxU32& nbPolygons, PxHullPolygon*& hullPolygons) = 0;
418
419 /**
420 \brief Cooks a heightfield. The results are written to the stream.
421
422 To create a heightfield object there is an option to precompute some of calculations done while loading the heightfield data.
423
424 cookHeightField() allows a heightfield description to be cooked into a binary stream
425 suitable for loading and performing collision detection at runtime.
426
427 \param[in] desc The heightfield descriptor to read the HF from.
428 \param[in] stream User stream to output the cooked data.
429 \return true on success
430
431 @see PxPhysics.createHeightField()
432 */
433 virtual bool cookHeightField(const PxHeightFieldDesc& desc, PxOutputStream& stream) = 0;
434
435 /**
436 \brief Cooks and creates a heightfield mesh and inserts it into PxPhysics.
437
438 \param[in] desc The heightfield descriptor to read the HF from.
439 \param[in] insertionCallback The insertion interface from PxPhysics.
440 \return PxHeightField pointer on success
441
442 @see cookConvexMesh() setParams() PxPhysics.createTriangleMesh() PxPhysicsInsertionCallback
443 */
444 virtual PxHeightField* createHeightField(const PxHeightFieldDesc& desc, PxPhysicsInsertionCallback& insertionCallback) = 0;
445
446
447protected:
448 virtual ~PxCooking(){}
449};
450
451#ifndef PX_DOXYGEN
452} // namespace physx
453#endif
454
455/**
456\brief Create an instance of the cooking interface.
457
458Note that the foundation object is handled as an application-wide singleton in statically linked executables
459and a DLL-wide singleton in dynamically linked executables. Therefore, if you are using the runtime SDK in the
460same executable as cooking, you should pass the Physics's copy of foundation (acquired with
461PxPhysics::getFoundation()) to the cooker. This will also ensure correct handling of memory for objects
462passed from the cooker to the SDK.
463
464To use cooking in standalone mode, create an instance of the Foundation object with PxCreateCookingFoundation.
465You should pass the same foundation object to all instances of the cooking interface.
466
467\param[in] version the SDK version number
468\param[in] foundation the foundation object associated with this instance of the cooking interface.
469\param[in] params the parameters for this instance of the cooking interface
470\return true on success.
471*/
472PX_C_EXPORT PX_PHYSX_COOKING_API physx::PxCooking* PX_CALL_CONV PxCreateCooking(physx::PxU32 version,
473 physx::PxFoundation& foundation,
474 const physx::PxCookingParams& params);
475
476/** @} */
477#endif
478