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

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

Compact meshlet-based 3D mesh data structure. More...

`#include <Mesh3Dv2.h>`

## Public Attributes
int32_t | id
| Version/id. Expected to be 2162 for Mesh3Dv2.
uint16_t | nb_meshlets
| Number of meshlets in the mesh.
uint16_t | nb_materials
| Number of materials. Must be <= 256 because meshlet material indices are uint8_t.
const MeshMaterial3Dv2< color_t > * | materials
| Material array.
const Meshlet3Dv2 * | meshlets
| Meshlet header array.
const uint32_t * | payload
| 32-bit aligned meshlet payload blob.
fBox3 | bounding_box
| Global object bounding box.
const char * | name
| Mesh name, or nullptr.
const MeshMaterialExtra3Dv2< color_t > * | material_extras
| Optional material extension array, or nullptr.

## Detailed Description

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

Compact meshlet-based 3D mesh data structure.

Mesh3Dv2 is the compact static-mesh format used by the TGX meshlet renderer. It is designed for microcontrollers where the limiting factor is often flash/RAM bandwidth and cache locality rather than pure ALU throughput.

A Mesh3Dv2 object contains:

- a global bounding box for fast rejection of the whole mesh,
- an array of materials, each with an optional texture and lighting coefficients,
- an optional parallel material extension array for metadata such as emissive material data,
- a linear array of compact meshlet headers used for culling,
- a 32-bit aligned payload blob containing local arrays and face streams.

Unlike Mesh3D, Mesh3Dv2 does not use a linked list of sub-meshes. Multi-texture models are represented by one mesh object with several materials. Each meshlet stores a one-byte material index.

Meshlet payload layout

The payload for a meshlet starts at:

reinterpret_cast<const uint8_t*>(mesh.payload + meshlet.payload_offset32)

and is laid out as:

[int16_t vertices[meshlet.nb_vertices][3]]
[int16_t normals[meshlet.nb_normals][3]]
[int16_t texcoords[meshlet.nb_texcoords][2]]
[uint8_t face stream]
[padding bytes to reach the next 4-byte boundary]

The payload stores local meshlet arrays. Vertex positions are quantized relative to the decoded meshlet bounding sphere above, not relative to the global mesh bounding box. They are decoded as:

vertex = decoded_sphere_center + q * (decoded_sphere_radius / 32767)

Normals use signed-normalized coordinates:

normal = q * (1 / 32767)

Texture coordinates use a fixed signed range large enough for ordinary UVs and simple tiling:

texcoord = q * (4 / 32767) // range approximately [-4, 4]

The renderer computes these scale factors once per meshlet and then only performs multiply-adds when a vertex, normal or texture coordinate is actually needed by the active shader path.

Face stream

Each triangle chain starts with a uint8_t triangle count and is followed by count+2 vertex elements. A zero chain length marks the end of the meshlet face stream.

An element occupies 1, 2 or 3 bytes depending on whether local texture coordinates and normals are present:

[DBIT|LOCAL_VERTEX_INDEX] [LOCAL_TEXCOORD_INDEX, opt.] [LOCAL_NORMAL_INDEX, opt.]

The DBIT is the high bit of the vertex byte. The local vertex index is stored in the low 7 bits, so each meshlet supports up to 128 local vertices. The first three elements of a chain have DBIT=0 and define the first triangle. Each subsequent element defines the next triangle using the same convention as Mesh3D:

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

Alignment and endianness

Mesh3Dv2::payload is a uint32_t array. Meshlet payload offsets are expressed in 32-bit words, and each meshlet payload is padded to a multiple of 4 bytes. The generated payload is intended for little-endian targets, which covers the current TGX targets (x86/x64, Teensy 3/4, ESP32, RP2040 and RP2350).

Material extensions

Mesh3Dv2::material_extras is optional and may be nullptr. If present, it contains Mesh3Dv2::nb_materials entries and entry `i` extends Mesh3Dv2::materials[i]. The Mesh3Dv2 id remains 2162 because the geometry and payload format are unchanged.

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

- src/Mesh3Dv2.h