tgx::Mesh3D< color_t > Struct Template Reference

3D mesh data stucture. 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 ambiant coefficient (how much it reflects the ambiant 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 ambiant coefficient (how much it reflects the specular light component). Typical value: 0.5f.
int	specular_exponent
	Specular exponent. 0 to disable specular lightning. 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 stucture.

A Mesh3D structure contain all the informations about an object geometry, color, material property 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 scripts obj_to_h located in the \tools directory of the library can be used to create a Mesh3D object directly from an .obj file. The associated image textures (if any) can be converted using the Python script texture_2_h.

MESH FORMAT

Parameters

vertice	Array of all the vertices of the mesh in (x,y,z) fVec3 format. A vertex is refered by its index in this array. Maximum number of vertices per mesh: 32767.
texcoord	Array of texture coordinate in (u,v) fVec2 format. A texture coord is refered 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 refered 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 is none).
next	pointer to the next mesh (or nullptr if none). Chaining mesh enalbe to draw complex models with multiple textures 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 specify the number of triangles in the chain. It is followed by [chain length]+2 elements.

A "element" represent a vertex of a triangle and occupies 1, 2 or 3 uint16_t depending on whether the textcoord 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.

Schematiccally:

 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}

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