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