js: add clusterizer API - documentation

Documents the new JS clusterizer API in the JS readme.

Author: JolifantoBambla

js/README.md

@@ -155,6 +155,74 @@ The simplification algorithm uses relative errors for input and output; to conve
 getScale: (vertex_positions: Float32Array, vertex_positions_stride: number) => number;
 ```
 
+## Clusterizer
+
+`MeshoptClusterizer` (`meshopt_clusterizer.js`) implements meshlet generation and optimization.
+
+To split a triangle mesh into clusters, call `buildMeshlets`, which tries to balance topological efficiency (by maximizing vertex reuse inside meshlets) with culling efficiency.
+
+```ts
+buildMeshlets(indices: Uint32Array, vertex_positions: Float32Array, vertex_positions_stride: number, max_vertices: number, max_triangles: number, cone_weight?: number) => MeshletBuffers;
+```
+
+The algorithm uses position data stored in a strided array; `vertex_positions_stride` represents the distance between subsequent positions in `Float32` units.
+
+The maximum number of triangles and number of vertices per meshlet can be controlled via `max_triangles` and `max_vertices` parameters. However, `max_vertices` must not be greater than 255 and `max_triangles` must not be greater than 512.
+
+Additionally, if cluster cone culling is to be used, `buildMeshlets` allows specifying a `cone_weight` as a value between 0 and 1 to balance culling efficiency with other forms of culling. By default, `cone_weight` is set to 0.
+
+All meshlets are implicitly optimized for better triangle and vertex locality by `buildMeshlets`.
+
+The algorithm returns the meshlet data as packed buffers:
+
+```ts
+const buffers = MeshoptClusterizer.buildMeshlets(indices, positions, stride, /* args */);
+
+console.log(buffers.meshlets);      // prints the raw packed Uint32Array containing the meshlet data, i.e., the indices into the vertices and triangles array
+console.log(buffers.vertices);      // prints the raw packed Uint32Array containing the indices into the original meshes vertices
+console.log(buffers.triangles);     // prints the raw packed Uint8Array containing the indices into the verices array.
+console.log(buffers.meshletCount);  // prints the number of meshlets - this is not the same as buffers.meshlets.length because each meshlet consists of 4 unsigned 32-bit integers
+```
+
+Individual meshlets can be extracted from the packed buffers using `extractMeshlet`. The memory of the returned `Meshlet` object's `vertices` and `triangles` arrays is backed by the `MeshletBuffers` object.
+
+```ts
+const buffers = MeshoptClusterizer.buildMeshlets(indices, positions, stride, /* args */);
+
+const meshlet = MeshoptClusterizer.extractMeshlet(buffers, 0);
+console.log(meshlet.vertices);  // prints the packed Uint32Array of the first meshlet's vertex indices, i.e., indices into the original meshes vertex buffer
+console.log(meshlet.triangles); // prints the packed Uint8Array of the first meshlet's indices into its own vertices array
+
+console.log(MeshoptClusterizer.extractMeshlet(buffers, 0).triangles[0] === meshlet.triangles[0]) // prints true
+
+meshlet.triangles.set([123], 0);
+console.log(MeshoptClusterizer.extractMeshlet(buffers, 0).triangles[0] === meshlet.triangles[0]) // still prints true
+```
+
+After generating the meshlet data, it's also possible to generate extra culling data for one or more meshlets:
+
+```ts
+computeMeshletBounds(buffers: MeshletBuffers, vertex_positions: Float32Array, vertex_positions_stride: number) => Bounds | Bounds[];
+```
+
+If `buffers` contains more than one meshlet, `computeMeshletBounds` returns an array of `Bounds`. Otherwise, a single `Bounds` object is returned.
+
+```ts
+const buffers = MeshoptClusterizer.buildMeshlets(indices, positions, stride, /* args */);
+const bounds = MeshoptClusterizer.computeMeshletBounds(buffers, positions, stride);
+console.log(bounds[0].centerX, bounds[0].centerY, bounds[0].centerZ);       // prints the center of the first meshlet's bounding sphere
+console.log(bounds[0].radius);                                              // prints the radius of the first meshlet's bounding sphere
+console.log(bounds[0].coneApexX, bounds[0].coneApexY, bounds[0].coneApexZ); // prints the apex of the first meshlet's normal cone
+console.log(bounds[0].coneAxisX, bounds[0].coneAxisY, bounds[0].coneAxisZ); // prints the axis of the first meshlet's normal cone
+console.log(bounds[0].coneCutoff);                                          // prins the cutoff angle of the first meshlet's normal cone
+```
+
+It is also possible to compute bounds of a vertex cluster that is not generated by `MeshoptClusterizer` using `computeClusterBounds`. Like `buildMeshlets`, this algorithm takes vertex indices and a strided vertex positions array with a vertex stride in `Float32` units as input.
+
+```ts
+computeClusterBounds(indices: Uint32Array, vertex_positions: Float32Array, vertex_positions_stride: number) => Bounds;
+```
+
 ## License
 
 This library is available to anybody free of charge, under the terms of MIT License (see LICENSE.md).