PxHeightField
Defined in include/geometry/PxHeightField.h
-
class PxHeightField : public PxRefCounted
A height field class.
Height fields work in a similar way as triangle meshes specified to act as height fields, with some important differences:
Triangle meshes can be made of nonuniform geometry, while height fields are regular, rectangular grids. This means that with PxHeightField, you sacrifice flexibility in return for improved performance and decreased memory consumption.
In local space rows extend in X direction, columns in Z direction and height in Y direction.
Like Convexes and TriangleMeshes, HeightFields are referenced by shape instances (see PxHeightFieldGeometry, PxShape).
To avoid duplicating data when you have several instances of a particular height field differently, you do not use this class to represent a height field object directly. Instead, you create an instance of this height field via the PxHeightFieldGeometry and PxShape classes.
Creation
To create an instance of this class call PxPhysics::createHeightField() or PxCooking::createHeightField(const PxHeightFieldDesc&, PxInsertionCallback&). To delete it call release(). This is only possible once you have released all of its PxHeightFiedShape instances.
Visualizations:
See also
PxHeightFieldDesc PxHeightFieldGeometry PxShape PxPhysics.createHeightField() PxCooking.createHeightField()
Public Functions
-
virtual void release() = 0
Decrements the reference count of a height field and releases it if the new reference count is zero.
-
virtual PxU32 saveCells(void *destBuffer, PxU32 destBufferSize) const = 0
Writes out the sample data array.
The user provides destBufferSize bytes storage at destBuffer. The data is formatted and arranged as PxHeightFieldDesc.samples.
See also
- Parameters
destBuffer – [out] The destination buffer for the sample data.
destBufferSize – [in] The size of the destination buffer.
- Returns
The number of bytes written.
-
virtual bool modifySamples(PxI32 startCol, PxI32 startRow, const PxHeightFieldDesc &subfieldDesc, bool shrinkBounds = false) = 0
Replaces a rectangular subfield in the sample data array.
The user provides the description of a rectangular subfield in subfieldDesc. The data is formatted and arranged as PxHeightFieldDesc.samples.
Note
Modified samples are constrained to the same height quantization range as the original heightfield. Source samples that are out of range of target heightfield will be clipped with no error. PhysX does not keep a mapping from the heightfield to heightfield shapes that reference it. Call PxShape::setGeometry on each shape which references the height field, to ensure that internal data structures are updated to reflect the new geometry. Please note that PxShape::setGeometry does not guarantee correct/continuous behavior when objects are resting on top of old or new geometry.
- Parameters
startCol – [in] First cell in the destination heightfield to be modified. Can be negative.
startRow – [in] First row in the destination heightfield to be modified. Can be negative.
subfieldDesc – [in] Description of the source subfield to read the samples from.
shrinkBounds – [in] 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.
- Returns
True on success, false on failure. Failure can occur due to format mismatch.
-
virtual PxU32 getNbRows() const = 0
Retrieves the number of sample rows in the samples array.
See also
- Returns
The number of sample rows in the samples array.
-
virtual PxU32 getNbColumns() const = 0
Retrieves the number of sample columns in the samples array.
See also
- Returns
The number of sample columns in the samples array.
-
virtual PxHeightFieldFormat::Enum getFormat() const = 0
Retrieves the format of the sample data.
- Returns
The format of the sample data.
-
virtual PxU32 getSampleStride() const = 0
Retrieves the offset in bytes between consecutive samples in the array.
See also
PxHeightFieldDesc.sampleStride
- Returns
The offset in bytes between consecutive samples in the array.
-
virtual PxReal getConvexEdgeThreshold() const = 0
Retrieves the convex edge threshold.
- Returns
The convex edge threshold.
-
virtual PxHeightFieldFlags getFlags() const = 0
Retrieves the flags bits, combined from values of the enum PxHeightFieldFlag.
See also
- Returns
The flags bits, combined from values of the enum PxHeightFieldFlag.
-
virtual PxReal getHeight(PxReal x, PxReal z) const = 0
Retrieves the height at the given coordinates in grid space.
- Returns
The height at the given coordinates or 0 if the coordinates are out of range.
-
virtual PxMaterialTableIndex getTriangleMaterialIndex(PxTriangleID triangleIndex) const = 0
Returns material table index of given triangle.
Note
This function takes a post cooking triangle index.
- Parameters
triangleIndex – [in] (internal) index of desired triangle
- Returns
Material table index, or 0xffff if no per-triangle materials are used
-
virtual PxVec3 getTriangleNormal(PxTriangleID triangleIndex) const = 0
Returns a triangle face normal for a given triangle index.
Note
This function takes a post cooking triangle index.
- Parameters
triangleIndex – [in] (internal) index of desired triangle
- Returns
Triangle normal for a given triangle index
-
virtual const PxHeightFieldSample &getSample(PxU32 row, PxU32 column) const = 0
Returns heightfield sample of given row and column
- Parameters
row – [in] Given heightfield row
column – [in] Given heightfield column
- Returns
Heightfield sample
-
virtual PxU32 getTimestamp() const = 0
Returns the number of times the heightfield data has been modified.
This method returns the number of times modifySamples has been called on this heightfield, so that code that has retained state that depends on the heightfield can efficiently determine whether it has been modified.
- Returns
the number of times the heightfield sample data has been modified.
-
inline virtual const char *getConcreteTypeName() const
Returns string name of dynamic type.
- Returns
Class name of most derived type of this object.
-
virtual PxU32 getReferenceCount() const = 0
Returns the reference count of the object.
At creation, the reference count of the object is 1. Every other object referencing this object increments the count by 1. When the reference count reaches 0, and only then, the object gets destroyed automatically.
- Returns
the current reference count.
-
virtual void acquireReference() = 0
Acquires a counted reference to this object.
This method increases the reference count of the object by 1. Decrement the reference count by calling release()
-
inline PxType getConcreteType() const
Returns concrete type of object.
See also
- Returns
PxConcreteType::Enum of serialized object
-
inline void setBaseFlag(PxBaseFlag::Enum flag, bool value)
Set PxBaseFlag
- Parameters
flag – [in] The flag to be set
value – [in] The flags new value
-
inline void setBaseFlags(PxBaseFlags inFlags)
Set PxBaseFlags
See also
PxBaseFlags
- Parameters
inFlags – [in] The flags to be set
-
inline PxBaseFlags getBaseFlags() const
Returns PxBaseFlags.
See also
PxBaseFlags
- Returns
PxBaseFlags
-
inline virtual bool isReleasable() const
Whether the object is subordinate.
A class is subordinate, if it can only be instantiated in the context of another class.
See also
- Returns
Whether the class is subordinate
Protected Functions
-
inline PxHeightField(PxType concreteType, PxBaseFlags baseFlags)
-
inline PxHeightField(PxBaseFlags baseFlags)
-
inline virtual ~PxHeightField()
-
inline virtual bool isKindOf(const char *name) const
Returns whether a given type name matches with the type of this instance.
-
inline virtual void onRefCountZero()
-
template<class T>
inline bool typeMatch() const