To holos module | To mesh module | Back to API reference | To module list


Vertex list declaration

There are several ways to specify vertex list for rendering:

Each way have same range of abilities. The choice of way should be dictated by efficiency (memory usage and speed) depending on your program's architecture.

Vertex declaration

There many vertex parameters to be specified. Usually it is only reasonable to declare valuable vertex parameters. So it is possible to define which parameters are specified per vertex. All other parameters remain at default state.

Here's vertex parameter specification:

vertex_declaration = vertex_coordinates..edge_flag..normal..texture_coordinates..color..attribute_list
, where
vertex_coordinates = "xy" | "xyz" | "xyzw" | "XY" | "XYZ" | "XYZW"
edge_flag = "" | "e"
normal = "" | "n" | "N"
texture_coordinates = "" | "s" | "st" | "stp" | "stpq" | "S" | "ST" | "STP" | "STPQ"
color = "" | "rgb" | "RGB" | "rgba" | "RGBA" | "c" | "C"
attribute_list = [attrib0 [, attrib1 [... , attrib15 ]]]
attribN = <1|2|3|4><i|u|f|d>

Lua specification Binary specification Lua value representation Binary value representation
"xy" 0 2 numbers double[2]
"xyz" 1 3 numbers double[3]
"xyzw" 2 4 numbers double[4]
"XY" 3 2 numbers float[2]
"XYZ" 4 3 numbers float[3]
"XYZW" 5 4 numbers float[4]
"e" 1 flag (any value is treated as boolean) uint8_t (separately after vertex list)
"n" 1 3 numbers double[3]
"N" 2 3 numbers float[3]
"s" 1 1 number double
"st" 2 2 numbers double[2]
"stp" 3 3 numbers double[3]
"stpq" 4 4 numbers double[4]
"S" 5 1 number float
"ST" 6 2 numbers float[2]
"STP" 7 3 numbers float[3]
"STPQ" 8 4 numbers float[4]
"rgba" 1 4 number double[4]
"rgb" 2 3 number double[3]
"RGBA" 3 4 number float[4]
"RGB" 4 3 number float[3]
"c" 5 1 number (may lead to precission loss) uint64_t (0xRRRRGGGGBBBBAAAA)
"C" 6 1 number uint32_t (0xRRGGBBAA)
"i" 0 number int32_t
"u" 1 number uint32_t
"f" 2 number float
"d" 3 number double

Index declaration

Index is vertex number starting from 0. Index mode is enabled only if 1 or more indeces are specified.

In Lua index is specified as number. Binary representation depends on vertex count: if vertex count is <= 255, index type is uint8_t; else if vertex count is <= 65535, index type is uint16_t; else index type is uint32_t.

Primitive mode types

Lua specification Binary specification Description
"points" 0 2 numbers
"lines" 1 3 numbers
"line_strip" 2 4 numbers
"line_loop" 3 2 numbers
"triangles" 4 3 numbers
"triangle_strip" 5 4 numbers
"triangle_fan" 6 flag (any value treated as boolean)
"quads" 7 3 numbers
"quad_strip" 8 3 numbers
"polygon" 9 1 number

holos primitive calls representation

These functions are named as in Primitive mode types table: holos.points (), holos.lines (), etc. Each function takes 2 arguments: string representing vertex specification format and table containing vertex list. Both are described at Vertex declaration section.

Here's the example:

holos.triangles ("xyC", {
		       {-0.5, -0.5, 0xff0000ff},
		       {0.5, -0.5, 0x00ff00ff},
		       {0, 0.5, 0x0000ffff},
		    })

mesh with vertex data loaded from Lua table

If mesh data is specified as table then a table have to be an array of up to 64 submeshes. Each submesh itself is a table with "primitive", "vertex_declaration" and "vertex_list" mandatory fields and optional field "index_list". "primitive" field have to contain a value from Primitive mode types table. "vertex_declaration" field have to contain a string described in section Vertex declaration. "vertex_list" field have to contain an array of verteces also described in Vertex declaration. "index_list" field have to contain an array of vertex indices as numbers starting from 0 (see Index declaration).

See an example:

local w, h = 200, 30
local color = 0x00ff00ff
local m = mesh ({
		   {
		      primitive = "line_loop",
		      vertex_declaration = "xyC",
		      vertex_list = {
			 {0.5, 0.5, color},
			 {0.5, h - 0.5, color},
			 {w - 0.5, h - 0.5, color},
			 {w - 0.5, 0.5, color},
		      },
		   },
		   {
		      primitive = "lines",
		      vertex_declaration = "xyC",
		      vertex_list = {
			 {2.5, 2.5, color},
			 {2.5, h - 2.5, color},
			 {w - 2.5, h - 2.5, color},
			 {w - 2.5, 2.5, color},
		      },
		   },
		})
holos.mesh (m)

mesh with vertex data loaded from binary file

File may contain a number of chunks. To read a chunk file pointer have to be set at a beginning of chunk and then file handler have to be passed to mesh loader (<mesh>.load () or mesh.new ()). After successfull chunk reading pointer is set excactly after read chunk.

Coding this is very simple:

local fh = assert (repository.open ("meshes/stone.mesh"))
local stone = assert (mesh (fh))
holos.mesh (stone)

See the following format description

Mesh binary chunk format (everything is stored in big-endian byte order)

Size Acceptible data Description
4 bytes 0x8bdee0a6 Mandatory head bytes
4 bytes 0..64 Submesh count
24*(submesh count) bytes See submesh description format Submesh descriptions
Depends on submesh descriptions See submesh declaration format Submesh declarations
8 bytes 0xd63f8954960baf1a Mandatory tail bytes

Submesh description format

Size Acceptible data Description
4 bytes 0..9 Primitive type
4 bytes See below Vertex declaration specification
8 bytes 16x(4 bits per attribute); see below Attribute declaration specification
4 bytes 0..524288 Vertex count
4 bytes 0..524288 Index count

Vertex declaration specification is a 32-bit mask containing following information:

Size Acceptible values Meaning
3 bits 0..5 Vertex coordinates
1 bit 0..1 Edge flag
2 bits 0..2 Normal
4 bits 0..8 Texture coordinates
3 bits 0..6 Color
14 bits Anything Ignored
5 bits 0..16 Attribute count

Attribute declaration specification contains 16 sets of 4-bit attribute specifications. Each 4-bit set contains following data:

Note that only number of attributes specified in Vertex declaration specification field is taken in account.

Submesh declaration format

Each submesh contains 3 sections (each one may be empty): vertex list, edge flag list (), index list

Vertex list

Vertex list is tightly packed list of packed vertex declarations. Vertex count is defined in submesh description. Each vertex declaration is binary set of tightly packed numbers defined at according vertex declaration specification in the same order as in Vertex declaration excluding edge flag. In the end there is padding to multiple of 8 bytes (which may be empty).

For example, "xyzSTC" vertex declaration specification would lead to following representation of each vertex inside file:

+--------+--------+--------+-------+-------+----------+
| Pos X  | Pos Y  | Pos Z  | Tex S | Tex T | Color    |
+--------+--------+--------+-------+-------+----------+
| double | double | double | float | float | uint32_t |
+--------+--------+--------+-------+-------+----------+

Edge flag list

Edge flag count is the same as vertex count. Edge flags are specified separately only because of byte-alignment. Each flag is byte in which 0x00 is for false and any other value is for true. In the end there is padding to multiple of 8 bytes (which may be empty).

Index flag list

Index list is tightly packed list of unsigned integers. Representation depends on vertex count: if vertex count is <= 255, index type is uint8_t; else if vertex count is <= 65535, index type is uint16_t; else index type is uint32_t. Note that any index out of boundary is treated as format error. In the end there is padding to multiple of 8 bytes (which may be empty).


To holos module | To mesh module | Back to API reference | To module list