Module javafx.graphics
Package javafx.scene.shape

# Class TriangleMesh

java.lang.Object
javafx.scene.shape.Mesh
javafx.scene.shape.TriangleMesh

public class TriangleMesh extends Mesh
Defines a 3D triangle mesh that consists of its associated `VertexFormat` and a set of separate arrays of vertex components such as points, normals, texture coordinates, and an array of faces that define the individual triangles of the mesh.

Note that the term point, as used in the method names and method descriptions, actually refers to a 3D point (x, y, z) in space representing the position of a single vertex. The term points (plural) is used to indicate sets of 3D points for multiple vertices. Similarly, the term normal is used to indicate a 3D vector (nx, ny, nz) in space representing the direction of a single vertex. The term normals (plural) is used to indicate sets of 3D vectors for multiple vertices. The term texCoord is used to indicate a single pair of 2D texture coordinates (u, v) for a single vertex, while the term texCoords (plural) is used to indicate sets of texture coordinates for multiple vertices. Lastly, the term face is used to indicate 3 sets of interleaving points, normals (optional, depending on the associated VertexFormat) and texture coordinates that together represent the geometric topology of a single triangle, while the term faces (plural) is used to indicate sets of triangles (each represent by a face).

For example, the faces with `VertexFormat.POINT_TEXCOORD` that represent a single textured rectangle, using 2 triangles, have the following data order: [

p0, t0, p1, t1, p3, t3, // First triangle of a textured rectangle

p1, t1, p2, t2, p3, t3 // Second triangle of a textured rectangle

]

whereas the faces with `VertexFormat.POINT_NORMAL_TEXCOORD` that represent a single textured rectangle, using 2 triangles, have the following data order: [

p0, n0, t0, p1, n1, t1, p3, n3, t3, // First triangle of a textured rectangle

p1, n1, t1, p2, n2, t2, p3, n3, t3 // Second triangle of a textured rectangle

]

where p0, p1, p2 and p3 are indices into the points array, n0, n1, n2 and n3 are indices into the normals array, and t0, t1, t2 and t3 are indices into the texCoords array.

A triangle has a front and back face. The winding order of a triangle's vertices determines which side is the front face. JavaFX chooses the counter-clockwise (or right-hand rule) winding order as the front face. By default, only the front face of a triangle is rendered. See `CullFace` for more information.

The length of `points`, `normals`, and `texCoords` must be divisible by 3, 3, and 2 respectively. The length of `faces` must be divisible by 6 if it is of `VertexFormat.POINT_TEXCOORD` else it must be divisible by 9 if it is of `VertexFormat.POINT_NORMAL_TEXCOORD`. The values in the faces array must be within the range of the number of vertices in the points array (0 to points.length / 3 - 1) for the point indices, within the range of the number of vertices in the normals array (0 to normals.length / 3 - 1) for the normal indices, and within the range of the number of the vertices in the texCoords array (0 to texCoords.length / 2 - 1) for the texture coordinate indices.

A warning will be recorded to the logger and the mesh will not be rendered (and will have an empty bounds) if any of the array lengths are invalid or if any of the values in the faces array are out of range.

Since:
  JavaFX 8.0

- ## Property Summary

  Properties
  Type
  Property
  Description
  `final ObjectProperty<VertexFormat>`
  `vertexFormat`
  Specifies the vertex format of this `TriangleMesh`, one of `VertexFormat.POINT_TEXCOORD` or `VertexFormat.POINT_NORMAL_TEXCOORD`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TriangleMesh()`
  Creates a new instance of `TriangleMesh` class with the default `VertexFormat.POINT_TEXCOORD` format type.
  `TriangleMesh(VertexFormat vertexFormat)`
  Creates a new instance of `TriangleMesh` class with the specified `VertexFormat`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final int`
  `getFaceElementSize()`
  Returns the number of elements that represents a face.
  `final ObservableFaceArray`
  `getFaces()`
  Gets the `faces` array, indices into the `points`, `normals` (optional, if it is a `VertexFormat.POINT_NORMAL_TEXCOORD` mesh) and `texCoords` arrays, of this `TriangleMesh`.
  `final ObservableIntegerArray`
  `getFaceSmoothingGroups()`
  Gets the `faceSmoothingGroups` array of this `TriangleMesh`.
  `final int`
  `getNormalElementSize()`
  Returns the number of elements that represents a normal.
  `final ObservableFloatArray`
  `getNormals()`
  Gets the `normals` array of this `TriangleMesh`.
  `final int`
  `getPointElementSize()`
  Returns the number of elements that represents a point.
  `final ObservableFloatArray`
  `getPoints()`
  Gets the `points` array of this `TriangleMesh`.
  `final int`
  `getTexCoordElementSize()`
  Returns the number of elements that represents a texture coordinates.
  `final ObservableFloatArray`
  `getTexCoords()`
  Gets the `texCoords` array of this `TriangleMesh`.
  `final VertexFormat`
  `getVertexFormat()`
  Gets the value of the `vertexFormat` property.
  `final void`
  `setVertexFormat(VertexFormat value)`
  Sets the value of the `vertexFormat` property.
  `final ObjectProperty<VertexFormat>`
  `vertexFormatProperty()`
  Specifies the vertex format of this `TriangleMesh`, one of `VertexFormat.POINT_TEXCOORD` or `VertexFormat.POINT_NORMAL_TEXCOORD`.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Property Details

  - ### vertexFormat

    public final ObjectProperty<VertexFormat> vertexFormatProperty
    Specifies the vertex format of this `TriangleMesh`, one of `VertexFormat.POINT_TEXCOORD` or `VertexFormat.POINT_NORMAL_TEXCOORD`.
    Default value:
      VertexFormat.POINT_TEXCOORD
    Since:
      JavaFX 8u40
    See Also:
      - `getVertexFormat()`
      - `setVertexFormat(VertexFormat)`
      - `vertexFormatProperty()`

- ## Constructor Details

  - ### TriangleMesh

    public TriangleMesh()
    Creates a new instance of `TriangleMesh` class with the default `VertexFormat.POINT_TEXCOORD` format type.

  - ### TriangleMesh

    public TriangleMesh(VertexFormat vertexFormat)
    Creates a new instance of `TriangleMesh` class with the specified `VertexFormat`.
    Parameters:
      `vertexFormat` - specifies the vertex format type.
    Since:
      JavaFX 8u40

- ## Method Details

  - ### setVertexFormat

    public final void setVertexFormat(VertexFormat value)
    Sets the value of the `vertexFormat` property.
    Property description:
      Specifies the vertex format of this `TriangleMesh`, one of `VertexFormat.POINT_TEXCOORD` or `VertexFormat.POINT_NORMAL_TEXCOORD`.
    Default value:
      VertexFormat.POINT_TEXCOORD
    Parameters:
      `value` - the value for the `vertexFormat` property
    Since:
      JavaFX 8u40
    See Also:
      - `getVertexFormat()`
      - `vertexFormatProperty()`

  - ### getVertexFormat

    public final VertexFormat getVertexFormat()
    Gets the value of the `vertexFormat` property.
    Property description:
      Specifies the vertex format of this `TriangleMesh`, one of `VertexFormat.POINT_TEXCOORD` or `VertexFormat.POINT_NORMAL_TEXCOORD`.
    Default value:
      VertexFormat.POINT_TEXCOORD
    Returns:
      the value of the `vertexFormat` property
    Since:
      JavaFX 8u40
    See Also:
      - `setVertexFormat(VertexFormat)`
      - `vertexFormatProperty()`

  - ### vertexFormatProperty

    public final ObjectProperty<VertexFormat> vertexFormatProperty()
    Specifies the vertex format of this `TriangleMesh`, one of `VertexFormat.POINT_TEXCOORD` or `VertexFormat.POINT_NORMAL_TEXCOORD`.
    Default value:
      VertexFormat.POINT_TEXCOORD
    Returns:
      the `vertexFormat` property
    Since:
      JavaFX 8u40
    See Also:
      - `getVertexFormat()`
      - `setVertexFormat(VertexFormat)`

  - ### getPointElementSize

    public final int getPointElementSize()
    Returns the number of elements that represents a point.
    Returns:
      number of elements

  - ### getNormalElementSize

    public final int getNormalElementSize()
    Returns the number of elements that represents a normal.
    Returns:
      number of elements
    Since:
      JavaFX 8u40

  - ### getTexCoordElementSize

    public final int getTexCoordElementSize()
    Returns the number of elements that represents a texture coordinates.
    Returns:
      number of elements

  - ### getFaceElementSize

    public final int getFaceElementSize()
    Returns the number of elements that represents a face.
    Returns:
      number of elements

  - ### getPoints

    public final ObservableFloatArray getPoints()
    Gets the `points` array of this `TriangleMesh`.
    Returns:
      `points` array where each point is represented by 3 float values x, y and z, in that order.

  - ### getNormals

    public final ObservableFloatArray getNormals()
    Gets the `normals` array of this `TriangleMesh`.
    Returns:
      `normals` array where each normal is represented by 3 float values nx, ny and nz, in that order.
    Since:
      JavaFX 8u40

  - ### getTexCoords

    public final ObservableFloatArray getTexCoords()
    Gets the `texCoords` array of this `TriangleMesh`. The coordinates are proportional, so texture's top-left corner is at [0, 0] and bottom-right corner is at [1, 1].
    Returns:
      `texCoord` array where each texture coordinate is represented by 2 float values: u and v, in that order.

  - ### getFaces

    public final ObservableFaceArray getFaces()
    Gets the `faces` array, indices into the `points`, `normals` (optional, if it is a `VertexFormat.POINT_NORMAL_TEXCOORD` mesh) and `texCoords` arrays, of this `TriangleMesh`. All indices are in terms of elements in to the points, normals or texCoords arrays not individual floats.
    Returns:
      `faces` array where each face is of 3 * `VertexFormat.getVertexIndexSize()` integers.

  - ### getFaceSmoothingGroups

    public final ObservableIntegerArray getFaceSmoothingGroups()
    Gets the `faceSmoothingGroups` array of this `TriangleMesh`. Smoothing affects how a mesh is rendered but it does not effect its geometry. The face smoothing group value is used to control the smoothing between adjacent faces.

    The face smoothing group value is represented by an array of bits and up to 32 unique groups is possible; (1 << 0) to (1 << 31). The face smoothing group value can range from 0 (no smoothing group) to all 32 groups. A face can belong to zero or more smoothing groups. A face is a member of group N if bit N is set, for example, groups |= (1 << N). A value of 0 implies no smoothing group or hard edges. Smoothing is applied when adjacent pair of faces shared a smoothing group. Otherwise the faces are rendered with a hard edge between them.

    An empty faceSmoothingGroups implies all faces in this mesh have a smoothing group value of 1.

    If faceSmoothingGroups is not empty, its size must be equal to number of faces.

    This faceSmoothingGroups has no effect on its `TriangleMesh` if it is of `VertexFormat.POINT_NORMAL_TEXCOORD` format.

    Returns:
      the `faceSmoothingGroups` array of this `TriangleMesh`