| TGX 1.1.2 A tiny 2D/3D graphics library optimized for 32 bits microcontrollers.

Loading...
Searching...
No Matches
Public Attributes | List of all members
tgx::Mesh3D< color_t > Struct Template Reference

3D mesh data structure. More...

`#include <Mesh3D.h>`

## Public Attributes
int32_t | id
| Set to 1 (may change in future version).
uint16_t | nb_vertices
| Number of vertices in the vertex array.
uint16_t | nb_texcoords
| Number of texture coordinates in the texcoord array.
uint16_t | nb_normals
| Number of normal vectors in the normal array.
uint16_t | nb_faces
| Number of triangular faces in the mesh.
uint16_t | len_face
| Number of elements (uint16_t) in the face array.
const fVec3 * | vertice
| Vertex array.
const fVec2 * | texcoord
| Texture coord array (nullptr if none).
const fVec3 * | normal
| Normal vector array (nullptr if none). all vectors must have unit norm.
const uint16_t * | face
| Array of triangles (format described above).
const Image< color_t > * | texture
| Texture image (or nullptr if none).
RGBf | color
| Default color to use when texturing is disabled.
float | ambiant_strength
| Object ambient coefficient (how much it reflects the ambient light component). Typical value: 0.2f.
float | diffuse_strength
| Object diffuse coefficient (how much it reflects the diffuse light component). Typical value: 0.7f.
float | specular_strength
| Object specular coefficient (how much it reflects the specular light component). Typical value: 0.5f.
int | specular_exponent
| Specular exponent. 0 to disable specular lighting. Typical value between 4 and 64.
const Mesh3D * | next
| Next object to draw when chaining is enabled. nullptr at end of chain.
fBox3 | bounding_box
| Object bounding box.
const char * | name
| Mesh name, or nullptr.

## Detailed Description

template<typename color_t>
struct tgx::Mesh3D< color_t >

3D mesh data structure.

A Mesh3D structure contains all the information about an object's geometry, color, material properties and textures. A mesh can be rendered onto an `Image` object using the `Renderer3D::drawMesh()` method.

The mesh data format is designed to be compact and favors linear access to elements in order to improve cache coherency so that meshes can be stored and rendered directly from "slow" memory such as FLASH on a MCU.

The Python tool `tools/tgx_mesh.py`, or its command-line counterpart `tools/cli_tools/tgx_mesh_cli.py`, can create legacy `Mesh3D` objects from `.obj` files when `Mesh3D` output is requested. New projects should normally prefer `Mesh3Dv2`; legacy `Mesh3D` remains available for compatibility with existing sketches.

MESH FORMAT

Parameters

  vertice | Array of all the vertices of the mesh in `(x,y,z)` `fVec3` format. A vertex is referred to by its index in this array. Maximum number of vertices per mesh: 32767.
  texcoord | Array of texture coordinates in `(u,v)` `fVec2` format. A texture coordinate is referred to by its index in this array. Set to nullptr (and nb_texcoords=0) if the mesh has no texture. Maximum number of texture coords: 65535
  normal | Array of normal vectors in `(x,y,z)` `fVec3` format. A normal vector is referred to by its index in this array. Set to nullptr if no normal vectors are defined. Normal vectors must have unit norm. Maximum number of normal vectors: 65535
  face | Array of triangular faces. The array is composed of `uint16_t` and is divided into chains of triangles. See below for details.
  texture | Image texture object associated with the mesh, or nullptr if none.
  next | Pointer to the next mesh, or nullptr if none. Chained meshes make it possible to draw complex models with multiple texture images and more than 32767 vertices.

Structure of the `face` array.

The array is composed of "chains of triangles". Each chain starts with a `uint16_t` that specifies its length and is followed by a sequence of elements where each element occupies 1, 2 or 3 `uint16_t`. The array takes the following general form:

[chain 1 length = n] [elem 1] [elem 2] [elem 3] ... [elem n+2]
[chain 2 length = m] [elem 1] [elem 2] [elem 3] ... [elem m+2]
...
[chain k length = p] [elem 1] [elem 2] [elem 3] ... [elem p+2] [endtag = 0]

- An endtag `(int16_t)0` is used as a sentinel to mark the end of the `face` array.
- Each chain starts with a single uint16_t [chain length] that specifies the number of triangles in the chain. It is followed by [chain length]+2 elements.

An "element" represents a vertex of a triangle and occupies 1, 2 or 3 `uint16_t` depending on whether the texcoord and normal arrays exist in the mesh. The first `uint16_t` of an element is the vertex index (with a direction bit), then is followed by the texture index if a texture array is present and then finally followed by the normal index if a normal array is present.

Schematically:

1bit 15bits (16bits, opt.) (16bits, opt.)
[DBIT| VERTEX INDEX] [TEXTURE INDEX] [NORMAL INDEX]

The first 3 elements of a chain represent the 3 vertices that compose the first triangle of the chain. Their DBIT is always 0. Each subsequent element is combined with the current triangle to deduce the next triangle in the following way: suppose the current triangle is `[V1, V2, V3]` and the next element is `DBIT|V4`:

- if `DBIT = 0`, then the next triangle is `[V1, V3, V4]`
- if `DBIT = 1`, then the next triangle is `[V3, V2, V4]`.

Example

We assume here `texcoord = nullptr` but `normal != nullptr` so that each element is coded on 2 `uint16_t`.

Let us consider the following face array composed of 19 `uint16_t`:

face = {3,0,1,2,2,4,6,32773,8,7,7,1,8,7,9,4,5,5,0}
tgx::Mesh3D::face
const uint16_t * face
Array of triangles (format described above).
Definition: Mesh3D.h:172

It should be read as

3 the first chain has 3 triangles
0/1 2/2 4/6 first triangle with vertex 0,2,4 and normals 1,2,6
5/8 32773 = 32768 + 5 so DBIT = 1, second triangle
7/7 third triangle DBIT = 0
1 the second chain has a single triangle
8/7 9/4 5/5 the triangle of the second chain
0 end tag

after decoding, this gives a list of 4 triangles (with normals associated with each vertex index).

0/1 2/2 4/6
4/6 2/2 5/8
4/6 5/8 7/7
8/7 9/4 5/5

The documentation for this struct was generated from the following file:

- src/Mesh3D.h