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_PHYSICS_GEOMUTILS_NX_HEIGHTFIELD
32#define PX_PHYSICS_GEOMUTILS_NX_HEIGHTFIELD
33/** \addtogroup geomutils
34 @{
35*/
36
37#include "geometry/PxHeightFieldFlag.h"
38#include "geometry/PxHeightFieldSample.h"
39#include "common/PxBase.h"
40
41#if !PX_DOXYGEN
42namespace physx
43{
44#endif
45
46class PxHeightFieldDesc;
47
48/**
49\brief A height field class.
50
51Height fields work in a similar way as triangle meshes specified to act as
52height fields, with some important differences:
53
54Triangle meshes can be made of nonuniform geometry, while height fields are
55regular, rectangular grids. This means that with PxHeightField, you sacrifice
56flexibility in return for improved performance and decreased memory consumption.
57
58In local space rows extend in X direction, columns in Z direction and height in Y direction.
59
60Like Convexes and TriangleMeshes, HeightFields are referenced by shape instances
61(see #PxHeightFieldGeometry, #PxShape).
62
63To avoid duplicating data when you have several instances of a particular
64height field differently, you do not use this class to represent a
65height field object directly. Instead, you create an instance of this height field
66via the PxHeightFieldGeometry and PxShape classes.
67
68<h3>Creation</h3>
69
70To create an instance of this class call PxPhysics::createHeightField() or
71PxCooking::createHeightField(const PxHeightFieldDesc&, PxPhysicsInsertionCallback&).
72To delete it call release(). This is only possible
73once you have released all of its PxHeightFiedShape instances.
74
75<h3>Visualizations:</h3>
76\li #PxVisualizationParameter::eCOLLISION_AABBS
77\li #PxVisualizationParameter::eCOLLISION_SHAPES
78\li #PxVisualizationParameter::eCOLLISION_AXES
79\li #PxVisualizationParameter::eCOLLISION_FNORMALS
80\li #PxVisualizationParameter::eCOLLISION_EDGES
81
82@see PxHeightFieldDesc PxHeightFieldGeometry PxShape PxPhysics.createHeightField() PxCooking.createHeightField()
83*/
84
85class PxHeightField : public PxBase
86{
87 public:
88 /**
89 \brief Decrements the reference count of a height field and releases it if the new reference count is zero.
90
91 @see PxPhysics.createHeightField() PxHeightFieldDesc PxHeightFieldGeometry PxShape
92 */
93 PX_PHYSX_COMMON_API virtual void release() = 0;
94
95 /**
96 \brief Writes out the sample data array.
97
98 The user provides destBufferSize bytes storage at destBuffer.
99 The data is formatted and arranged as PxHeightFieldDesc.samples.
100
101 \param[out] destBuffer The destination buffer for the sample data.
102 \param[in] destBufferSize The size of the destination buffer.
103 \return The number of bytes written.
104
105 @see PxHeightFieldDesc.samples
106 */
107 PX_PHYSX_COMMON_API virtual PxU32 saveCells(void* destBuffer, PxU32 destBufferSize) const = 0;
108
109 /**
110 \brief Replaces a rectangular subfield in the sample data array.
111
112 The user provides the description of a rectangular subfield in subfieldDesc.
113 The data is formatted and arranged as PxHeightFieldDesc.samples.
114
115 \param[in] startCol First cell in the destination heightfield to be modified. Can be negative.
116 \param[in] startRow First row in the destination heightfield to be modified. Can be negative.
117 \param[in] subfieldDesc Description of the source subfield to read the samples from.
118 \param[in] shrinkBounds If left as false, the bounds will never shrink but only grow. If set to true the bounds will be recomputed from all HF samples at O(nbColums*nbRows) perf cost.
119 \return True on success, false on failure. Failure can occur due to format mismatch.
120
121 \note Modified samples are constrained to the same height quantization range as the original heightfield.
122 Source samples that are out of range of target heightfield will be clipped with no error.
123 PhysX does not keep a mapping from the heightfield to heightfield shapes that reference it.
124 Call PxShape::setGeometry on each shape which references the height field, to ensure that internal data structures are updated to reflect the new geometry.
125 Please note that PxShape::setGeometry does not guarantee correct/continuous behavior when objects are resting on top of old or new geometry.
126
127 @see PxHeightFieldDesc.samples PxShape.setGeometry
128 */
129 PX_PHYSX_COMMON_API virtual bool modifySamples(PxI32 startCol, PxI32 startRow, const PxHeightFieldDesc& subfieldDesc, bool shrinkBounds = false) = 0;
130
131 /**
132 \brief Retrieves the number of sample rows in the samples array.
133
134 \return The number of sample rows in the samples array.
135
136 @see PxHeightFieldDesc.nbRows
137 */
138 PX_PHYSX_COMMON_API virtual PxU32 getNbRows() const = 0;
139
140 /**
141 \brief Retrieves the number of sample columns in the samples array.
142
143 \return The number of sample columns in the samples array.
144
145 @see PxHeightFieldDesc.nbColumns
146 */
147 PX_PHYSX_COMMON_API virtual PxU32 getNbColumns() const = 0;
148
149 /**
150 \brief Retrieves the format of the sample data.
151
152 \return The format of the sample data.
153
154 @see PxHeightFieldDesc.format PxHeightFieldFormat
155 */
156 PX_PHYSX_COMMON_API virtual PxHeightFieldFormat::Enum getFormat() const = 0;
157
158 /**
159 \brief Retrieves the offset in bytes between consecutive samples in the array.
160
161 \return The offset in bytes between consecutive samples in the array.
162
163 @see PxHeightFieldDesc.sampleStride
164 */
165 PX_PHYSX_COMMON_API virtual PxU32 getSampleStride() const = 0;
166
167 /**
168 \brief Retrieves the convex edge threshold.
169
170 \return The convex edge threshold.
171
172 @see PxHeightFieldDesc.convexEdgeThreshold
173 */
174 PX_PHYSX_COMMON_API virtual PxReal getConvexEdgeThreshold() const = 0;
175
176 /**
177 \brief Retrieves the flags bits, combined from values of the enum ::PxHeightFieldFlag.
178
179 \return The flags bits, combined from values of the enum ::PxHeightFieldFlag.
180
181 @see PxHeightFieldDesc.flags PxHeightFieldFlag
182 */
183 PX_PHYSX_COMMON_API virtual PxHeightFieldFlags getFlags() const = 0;
184
185 /**
186 \brief Retrieves the height at the given coordinates in grid space.
187
188 \return The height at the given coordinates or 0 if the coordinates are out of range.
189 */
190 PX_PHYSX_COMMON_API virtual PxReal getHeight(PxReal x, PxReal z) const = 0;
191
192 /**
193 \brief Returns the reference count for shared heightfields.
194
195 At creation, the reference count of the heightfield is 1. Every shape referencing this heightfield increments the
196 count by 1. When the reference count reaches 0, and only then, the heightfield gets destroyed automatically.
197
198 \return the current reference count.
199 */
200 PX_PHYSX_COMMON_API virtual PxU32 getReferenceCount() const = 0;
201
202 /**
203 \brief Acquires a counted reference to a heightfield.
204
205 This method increases the reference count of the heightfield by 1. Decrement the reference count by calling release()
206 */
207 PX_PHYSX_COMMON_API virtual void acquireReference() = 0;
208
209 /**
210 \brief Returns material table index of given triangle
211
212 \note This function takes a post cooking triangle index.
213
214 \param[in] triangleIndex (internal) index of desired triangle
215 \return Material table index, or 0xffff if no per-triangle materials are used
216 */
217 PX_PHYSX_COMMON_API virtual PxMaterialTableIndex getTriangleMaterialIndex(PxTriangleID triangleIndex) const = 0;
218
219 /**
220 \brief Returns a triangle face normal for a given triangle index
221
222 \note This function takes a post cooking triangle index.
223
224 \param[in] triangleIndex (internal) index of desired triangle
225 \return Triangle normal for a given triangle index
226 */
227 PX_PHYSX_COMMON_API virtual PxVec3 getTriangleNormal(PxTriangleID triangleIndex) const = 0;
228
229 /**
230 \brief Returns heightfield sample of given row and column
231
232 \param[in] row Given heightfield row
233 \param[in] column Given heightfield column
234 \return Heightfield sample
235 */
236 PX_PHYSX_COMMON_API virtual const PxHeightFieldSample& getSample(PxU32 row, PxU32 column) const = 0;
237
238 /**
239 \brief Returns the number of times the heightfield data has been modified
240
241 This method returns the number of times modifySamples has been called on this heightfield, so that code that has
242 retained state that depends on the heightfield can efficiently determine whether it has been modified.
243
244 \return the number of times the heightfield sample data has been modified.
245 */
246 PX_PHYSX_COMMON_API virtual PxU32 getTimestamp() const = 0;
247
248 PX_PHYSX_COMMON_API virtual const char* getConcreteTypeName() const { return "PxHeightField"; }
249
250protected:
251 PX_INLINE PxHeightField(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags) {}
252 PX_INLINE PxHeightField(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
253 PX_PHYSX_COMMON_API virtual ~PxHeightField() {}
254 PX_PHYSX_COMMON_API virtual bool isKindOf(const char* name) const { return !::strcmp(s1: "PxHeightField", s2: name) || PxBase::isKindOf(superClass: name); }
255};
256
257#if !PX_DOXYGEN
258} // namespace physx
259#endif
260
261/** @} */
262#endif
263

source code of qtquick3dphysics/src/3rdparty/PhysX/include/geometry/PxHeightField.h