eng doc

docs/user/meshes/meshes.md

@@ -0,0 +1,125 @@
+# Meshes: geometries, entities and transforms
+
+A displayed object in WSG goes through three levels:
+
+```
+Geometry (CPU, source of truth) ──► Mesh (GPU: vertex/index buffers) ──► Entity (placement in the scene)
+```
+
+- **`Geometry`**: raw CPU-side data — positions + optional normals/UVs/colors/indices.
+- **`Mesh`**: GPU container (buffers uploaded once). It **retains** its `Arc<Geometry>` on the
+  CPU side, along with its material.
+- **`Entity`**: a `mesh + Transform` association. This is the unit the engine draws. The same
+  `Mesh` can be shared by several entities (each with its own `Transform`).
+
+## 1. Procedural primitives (the shortest path)
+
+The `math::primitives` module provides ready-to-use `Geometry` generators
+(positions + normals + UVs + indices):
+
+| Function | Parameters | Result |
+|----------|-----------|--------|
+| `cube(size)` | side length | origin-centered cube, per-face normals |
+| `plane(width, depth, seg_x, seg_z)` | dimensions + subdivisions | horizontal plane (Y-up), UVs |
+| `uv_sphere(radius, sectors, stacks)` | radius + resolution | UV sphere (seam visible) |
+| `icosphere(radius, subdivisions)` | radius + subdivisions | smooth sphere (normalized, seam-free) |
+| `cylinder(radius, height, sectors)` | radius, height, resolution | centered cylinder |
+| `cone(radius, height, sectors)` | radius, height, resolution | cone (base at the bottom when translated in Y) |
+| `torus(major, minor, major_segments, minor_segments)` | radii + resolution | torus |
+
+```rust
+use wsg_lib::math::{cube, icosphere, torus};
+
+app.scene.create_mesh("cube_mesh", cube(0.8), Some("solid_mat")).unwrap();
+app.scene.create_mesh("sphere_mesh", icosphere(0.5, 2), Some("solid_mat")).unwrap();
+```
+
+## 2. Custom `Geometry` (your own mesh)
+
+`Geometry` is a builder: positions are mandatory, everything else is optional
+(sensible defaults are applied at upload — e.g. normal `[0,0,1]`, white color).
+
+```rust
+use wsg_lib::resources::Geometry;
+
+let geometry = Geometry::new(vec![
+    [-0.5, 0.5, 0.0],
+    [ 0.5, 0.5, 0.0],
+    [ 0.5, -0.5, 0.0],
+    [-0.5, -0.5, 0.0],
+])
+.with_normals(vec![[0.0, 0.0, 1.0]; 4])   // required for lighting (Phong)
+.with_colors(vec![
+    [1.0, 0.0, 0.0, 1.0],
+    [0.0, 1.0, 0.0, 1.0],
+    [0.0, 0.0, 1.0, 1.0],
+    [1.0, 1.0, 0.0, 1.0],
+])
+.with_indices(vec![0, 1, 2, 0, 2, 3]);     // triangulation (without indices: triangle list)
+```
+
+Other attributes: `.with_uvs(vec![[u, v], …])` (required for textures — see
+[Materials & textures](materials.md)). `geometry.validate()` checks the arrays for
+consistency (aligned lengths, indices in range) before upload.
+
+> **Indices**: `Vec<u16>` — a custom mesh must therefore stay under 65,536 vertices. The
+> engine's primitives respect this limit.
+
+## 3. Registering in the scene
+
+```rust
+// The mesh is built (GPU buffers) and bound to its material in one call.
+// `material = None`: the scene will use its default material (`standard`) at render time.
+app.scene.create_mesh("cube_mesh", geometry, Some("cube_material"))?;
+
+// The entity references the mesh by its id (String IDs).
+app.scene.add_entity("cube", "cube_mesh")?;
+// …or with an explicit placement:
+app.scene.add_entity_with_transform("cube", "cube_mesh", transform)?;
+```
+
+All these methods return `Result<_, String>` (unifying the typed errors is on the
+horizon — see [ROADMAP](../../ROADMAP.md)).
+
+## 4. Moving / animating: the `Transform`
+
+Placement lives on the **entity** (not on the mesh): `Transform { translation: Vec3,
+rotation: Quat, scale: Vec3 }`, converted to a world matrix by the engine every frame.
+
+The snippet below is the animation from the [`cube`](../../../lib/examples/meshes/cube.rs) example:
+
+```rust
+fn update(&mut self, app: &mut wsg_lib::App) {
+    self.angle += 0.02;
+    let mut tf = *app.scene.entity_transform("cube").expect("entity present");
+    tf.rotation = Quat::from_rotation_y(self.angle) * Quat::from_rotation_x(self.angle * 0.3);
+    app.scene.set_entity_transform("cube", tf);
+}
+```
+
+Other entity operations: `entity_transform(label)` (read), `remove_entity(label)` (hides
+without freeing resources), `entity_count()`.
+
+> **Rotation order**: `Quat` does not commute — `rot_y * rot_x` is not `rot_x * rot_y`.
+> The order above (Y then X) gives a readable "top spinning" motion.
+
+## 5. Mesh sharing
+
+Create **one** mesh per geometry and as many entities as occurrences:
+
+```rust
+app.scene.create_mesh("rock_mesh", icosphere(0.3, 1), Some("rock_mat")).unwrap();
+for i in 0..10 {
+    let label = format!("rock_{i}");
+    let mut tf = Transform::identity();
+    tf.translation = Vec3::new(i as f32 * 0.8, 0.15, 0.0);
+    app.scene.add_entity_with_transform(&label, "rock_mesh", tf).unwrap();
+}
+```
+
+The GPU buffers are uploaded only once; only the world matrices differ.
+
+## Links
+
+- [User README](../README.md) · [Quickstart](../quickstart.md) · [Materials & textures](materials.md) · [Lights](../lights/lights.md)
+- [Root README](../../../README.md) · [ARCHI_APP](../../tech/ARCHI_APP.md)