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