Module de.fabmax.physxjni
Package physx.geometry

Class PxHeightField

java.lang.Object
physx.NativeObject
physx.common.PxBase
physx.common.PxRefCounted
physx.geometry.PxHeightField
public class PxHeightField extends 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:

\li #PxVisualizationParameter::eCOLLISION_AABBS \li #PxVisualizationParameter::eCOLLISION_SHAPES \li #PxVisualizationParameter::eCOLLISION_AXES \li #PxVisualizationParameter::eCOLLISION_FNORMALS \li #PxVisualizationParameter::eCOLLISION_EDGES
See Also:

  • Field Details

    • SIZEOF

      public static final int SIZEOF

    • ALIGNOF

      public static final int ALIGNOF
      See Also:

  • Constructor Details

    • PxHeightField

      protected PxHeightField()

    • PxHeightField

      protected PxHeightField(long address)

  • Method Details

    • wrapPointer

      public static PxHeightField wrapPointer(long address)

    • arrayGet

      public static PxHeightField arrayGet(long baseAddress, int index)

    • saveCells

      public int saveCells(NativeObject destBuffer, int destBufferSize)
      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 - The destination buffer for the sample data.
      destBufferSize - The size of the destination buffer.
      Returns:
      The number of bytes written.

    • modifySamples

      public boolean modifySamples(int startCol, int startRow, PxHeightFieldDesc subfieldDesc)
      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.

      Parameters:
      startCol - First cell in the destination heightfield to be modified. Can be negative.
      startRow - First row in the destination heightfield to be modified. Can be negative.
      subfieldDesc - Description of the source subfield to read the samples from.
      Returns:
      True on success, false on failure. Failure can occur due to format mismatch.

      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.

      See Also:

    • modifySamples

      public boolean modifySamples(int startCol, int startRow, PxHeightFieldDesc subfieldDesc, boolean shrinkBounds)
      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.

      Parameters:
      startCol - First cell in the destination heightfield to be modified. Can be negative.
      startRow - First row in the destination heightfield to be modified. Can be negative.
      subfieldDesc - Description of the source subfield to read the samples from.
      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.
      Returns:
      True on success, false on failure. Failure can occur due to format mismatch.

      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.

      See Also:

    • getNbRows

      public int getNbRows()
      Retrieves the number of sample rows in the samples array.
      Returns:
      The number of sample rows in the samples array.

    • getNbColumns

      public int getNbColumns()
      Retrieves the number of sample columns in the samples array.
      Returns:
      The number of sample columns in the samples array.

    • getFormat

      public PxHeightFieldFormatEnum getFormat()
      Retrieves the format of the sample data.
      Returns:
      The format of the sample data.

    • getSampleStride

      public int getSampleStride()
      Retrieves the offset in bytes between consecutive samples in the array.
      Returns:
      The offset in bytes between consecutive samples in the array.

    • getConvexEdgeThreshold

      public float getConvexEdgeThreshold()
      Retrieves the convex edge threshold.
      Returns:
      The convex edge threshold.

    • getFlags

      public PxHeightFieldFlags getFlags()
      Retrieves the flags bits, combined from values of the enum ::PxHeightFieldFlag.
      Returns:
      The flags bits, combined from values of the enum ::PxHeightFieldFlag.

    • getHeight

      public float getHeight(float x, float z)
      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.

    • getTriangleMaterialIndex

      public short getTriangleMaterialIndex(int triangleIndex)
      Returns material table index of given triangle

      Note: This function takes a post cooking triangle index.

      Parameters:
      triangleIndex - (internal) index of desired triangle
      Returns:
      Material table index, or 0xffff if no per-triangle materials are used

    • getTriangleNormal

      public PxVec3 getTriangleNormal(int triangleIndex)
      Returns a triangle face normal for a given triangle index

      Note: This function takes a post cooking triangle index.

      Parameters:
      triangleIndex - (internal) index of desired triangle
      Returns:
      Triangle normal for a given triangle index

    • getSample

      public PxHeightFieldSample getSample(int row, int column)
      Returns heightfield sample of given row and column
      Parameters:
      row - Given heightfield row
      column - Given heightfield column
      Returns:
      Heightfield sample

    • getTimestamp

      public int getTimestamp()
      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.