Mesh3Dv2.h File Reference

Compact meshlet-based 3D model mesh format with 16-bit quantization. More...

#include "Misc.h"
#include "Vec2.h"
#include "Vec3.h"
#include "Vec4.h"
#include "Box3.h"
#include "Color.h"
#include "Image.h"
#include <stdint.h>
#include "Mesh3Dv2.inl"

Go to the source code of this file.

Classes
struct	tgx::MeshMaterial3Dv2< color_t >
	Material definition for a Mesh3Dv2 object. More...
struct	tgx::MeshMaterialExtra3Dv2< color_t >
	Optional material extension for a Mesh3Dv2 object. More...
struct	tgx::Meshlet3Dv2
	Header for a single meshlet inside a Mesh3Dv2 object. More...
struct	tgx::Mesh3Dv2< color_t >
	Compact meshlet-based 3D mesh data structure. More...

Functions
template<typename color_t >
const Mesh3Dv2< color_t > *	tgx::cacheMesh (const Mesh3Dv2< color_t > *mesh, void *ram1_buffer, size_t ram1_size, void *ram2_buffer, size_t ram2_size, const char *copy_order="PLMI", size_t *ram1_used=nullptr, size_t *ram2_used=nullptr)
	Creates a cached version of a Mesh3Dv2 object by copying selected data arrays into one or two user-supplied RAM buffers. More...
template<typename color_t >
const Mesh3Dv2< color_t > *	tgx::cacheMesh (const Mesh3Dv2< color_t > *mesh, void *ram_buffer, size_t ram_size, const char *copy_order="PLMI", size_t *ram_used=nullptr)
	Convenience overload of cacheMesh() with a single RAM buffer.
template<typename color_t >
Mesh3Dv2< color_t > *	tgx::copyMeshEXTMEM (const Mesh3Dv2< color_t > *mesh, bool copy_payload=false, bool copy_meshlets=false, bool copy_materials=false, bool copy_textures=true, size_t *extmem_used=nullptr)
	Create a copy of a Mesh3Dv2 object where selected PROGMEM arrays are copied to EXTMEM. More...
template<typename color_t >
void	tgx::freeMeshEXTMEM (Mesh3Dv2< color_t > *mesh)
	Delete a Mesh3Dv2 object allocated with copyMeshEXTMEM(). More...

Detailed Description

Compact meshlet-based 3D model mesh format with 16-bit quantization.

Function Documentation

cacheMesh()

template<typename color_t >

const Mesh3Dv2< color_t > * tgx::cacheMesh	(	const Mesh3Dv2< color_t > *	mesh,
		void *	ram1_buffer,
		size_t	ram1_size,
		void *	ram2_buffer,
		size_t	ram2_size,
		const char *	copy_order = "PLMI",
		size_t *	ram1_used = nullptr,
		size_t *	ram2_used = nullptr
	)

Creates a cached version of a Mesh3Dv2 object by copying selected data arrays into one or two user-supplied RAM buffers.

This is useful on MCUs where meshes are stored in slow flash/PROGMEM but some RAM is available for faster rendering. The method first copies the small Mesh3Dv2 structure itself, then tries to copy the requested arrays in the order specified by copy_order. Each allocation first tries the first buffer; if it does not fit there, it tries the second buffer when supplied. If an array does not fit in either buffer, its original pointer is kept.

Copy-order letters:

• "P" = meshlet payload blob.
• "L" = meshlet header array.
• "M" = material array and optional material extension array.
• "I" = texture images referenced by the material and material extension arrays.

Diffuse texture caching requires a writable material array because texture pointers inside materials must be remapped. Emissive texture caching similarly requires a writable material extension array when material_extras is present. Therefore, requesting "I" implicitly tries to cache the arrays it needs if they have not already been cached. If one array cannot be cached, only the texture pointers in that array are left untouched.

Remarks

1. The memory buffers supplied do not need to be aligned; the method aligns allocations internally.
2. Mesh3Dv2 has no linked sub-meshes. Multi-material models are represented by the material array and per-meshlet material indices.
3. The payload size is computed once when cacheMesh() is called, by scanning the final meshlet payload. This has no per-frame rendering cost.
4. The returned mesh points either to cached arrays or to the original arrays for data that did not fit in the supplied buffers.

Parameters

mesh	Pointer to the Mesh3Dv2 object to cache.
ram1_buffer	Pointer to the first memory buffer, usually the fastest RAM.
ram1_size	Size in bytes of the first RAM buffer.
ram2_buffer	Optional pointer to a second memory buffer, may be nullptr.
ram2_size	Optional size in bytes of the second RAM buffer, or 0 if not supplied.
copy_order	Optional C string describing which data should be copied and in which order. Default is "PLMI".
ram1_used	If non-null, receives the number of bytes consumed in ram1_buffer.
ram2_used	If non-null, receives the number of bytes consumed in ram2_buffer.

Returns

The cached mesh object, or the original mesh if even the Mesh3Dv2 structure itself could not be copied.

copyMeshEXTMEM()

template<typename color_t >

Mesh3Dv2< color_t > * tgx::copyMeshEXTMEM	(	const Mesh3Dv2< color_t > *	mesh,
		bool	copy_payload = false,
		bool	copy_meshlets = false,
		bool	copy_materials = false,
		bool	copy_textures = true,
		size_t *	extmem_used = nullptr
	)

Create a copy of a Mesh3Dv2 object where selected PROGMEM arrays are copied to EXTMEM.

Attention

This method is defined only for Teensy 4.1.

Requested payload, meshlet and texture-pixel arrays are copied only when their source pointer is in PROGMEM; otherwise the original pointer is kept. The material arrays are the exception: the base material array and the optional material extension array are copied when copy_materials or copy_textures is true, because they may need writable texture pointers.

If any source pointer belonging to the mesh is already in EXTMEM, the method fails to avoid ambiguous ownership.

Requesting texture copies also creates writable EXTMEM copies of the material arrays that contain texture pointers, even when copy_materials is false, so that texture pointers can be remapped to their EXTMEM copies.

Parameters

mesh	Pointer to the source Mesh3Dv2 object.
copy_payload	Copy the meshlet payload blob to EXTMEM when it is in PROGMEM.
copy_meshlets	Copy the meshlet header array to EXTMEM when it is in PROGMEM.
copy_materials	Copy the material array to EXTMEM.
copy_textures	Copy texture images referenced by the material array to EXTMEM.
extmem_used	If non-null, receives the number of bytes allocated in EXTMEM for the returned mesh.

Returns

A pointer to the new mesh in EXTMEM, or nullptr on error. On error, all allocations performed by the method are freed.

freeMeshEXTMEM()

template<typename color_t >

void tgx::freeMeshEXTMEM

(

Mesh3Dv2< color_t > *

mesh

)

Delete a Mesh3Dv2 object allocated with copyMeshEXTMEM().

Attention

This method is defined only for Teensy 4.1.