PxHeightField

Defined in include/geometry/PxHeightField.h

Inheritance Relationships

Base Type

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:

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.

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.

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.

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.

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()

template<class T>
inline T *is()
template<class T>
inline const T *is() const
inline PxType getConcreteType() const

Returns concrete type of object.

See also

PxConcreteType

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.

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

Protected Attributes

PxType mConcreteType
PxBaseFlags mBaseFlags
PxU32 mBuiltInRefCount