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

Loading...
Searching...
No Matches
Classes | Functions
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.