Add next version of 3d mesh intro

Author: eliemichel

next/basic-3d-rendering/3d-meshes/a-simple-example.md

@@ -1,4 +1,4 @@
-A simple example <span class="bullet">🟠</span>
+A simple example <span class="bullet">🟢</span>
 ================
 
 ```{lit-setup}
@@ -10,7 +10,6 @@ A simple example <span class="bullet">🟠</span>
 ```{lit-setup}
 :tangle-root: 050 - A simple example - Next
 :parent: 043 - More uniforms - Next
-:debug:
 ```
 
 ````{tab} With webgpu.hpp
@@ -92,7 +91,7 @@ bool ResourceManager::loadGeometry(
 }
 ```
 
-```{lit} C++, Public ResourceManager members (hidden, replace)
+```{lit} C++, Declaration of ResourceManager::loadGeometry (hidden, replace, also for tangle root "Vanilla")
 /**
  * Load a file from `path` using our ad-hoc format and populate the `pointData`
  * and `indexData` vectors.
@@ -103,35 +102,6 @@ static bool loadGeometry(
 	std::vector<uint16_t>& indexData,
 	int dimensions // <-- new argument
 );
-/**
- * Create a shader module for a given WebGPU `device` from a WGSL shader source
- * loaded from file `path`.
- */
-static wgpu::ShaderModule loadShaderModule(
-	const std::filesystem::path& path,
-	wgpu::Device device
-);
-```
-
-```{lit} C++, Public ResourceManager members (hidden, replace, for tangle root "Vanilla")
-/**
- * Load a file from `path` using our ad-hoc format and populate the `pointData`
- * and `indexData` vectors.
- */
-static bool loadGeometry(
-	const std::filesystem::path& path,
-	std::vector<float>& pointData,
-	std::vector<uint16_t>& indexData,
-	int dimensions // <-- new argument
-);
-/**
- * Create a shader module for a given WebGPU `device` from a WGSL shader source
- * loaded from file `path`.
- */
-static WGPUShaderModule loadShaderModule(
-	const std::filesystem::path& path,
-	WGPUDevice device
-);
 ```
 
 ```{lit} C++, Implementation of ResourceManager::loadGeometry (hidden, replace, also for tangle root "Vanilla")
@@ -313,11 +283,11 @@ Basic transform
 
 **WIP**
 
-*This is a gentle introduction to trigonometry. If you are familiar with the concept, you may jump ahead.*
+*This is a gentle introduction to **trigonometry**. If you are familiar with the concept, you may jump ahead.*
 
-Seen from above, this pyramid boringly looks like an square. Could we **rotate** this? A very basic way to change the view angle is to swap axes:
+Seen from above, this pyramid boringly looks like an square. Could we **rotate** this? A very basic way to change the view angle is to **swap axes**:
 
-```rust
+```{lit} rust, Set vertex out position (also for tangle root "Vanilla")
 var position = vec3f(
 	in.position.x,
 	in.position.z, // swap axis Y and Z
@@ -326,6 +296,22 @@ var position = vec3f(
 out.position = vec4f(position.x, position.y * ratio, 0.0, 1.0);
 ```
 
+````{admonition} Where to insert this?
+:class: foldable
+
+We place this in the **vertex shader**:
+
+```{lit} Vertex shader (replace, also for tangle root "Vanilla")
+fn vs_main(in: VertexInput) -> VertexOutput {
+	var out: VertexOutput;
+	let ratio = 640.0 / 480.0;
+	{{Set vertex out position}}
+	out.color = in.color;
+	return out;
+}
+```
+````
+
 ```{figure} /images/pyramid-side.png
 :align: center
 :class: with-shadow
@@ -334,7 +320,7 @@ The pyramid seen from the side (still no perspective).
 
 What about in-between rotations? The idea is to **mix axes**, adding a little bit of z in the y coordinates and a little bit of y in the z coordinates.
 
-```rust
+```{lit} rust, Set vertex out position (replace, also for tangle root "Vanilla")
 var position = vec3f(
 	in.position.x,
 	in.position.y + 0.5 * in.position.z, // add a bit of Z in Y...
@@ -349,7 +335,7 @@ out.position = vec4f(position.x, position.y * ratio, 0.0, 1.0);
 The pyramid from a tilted view angle.
 ```
 
-Of course at some point we have to remove some of `in.position.y` from Y so that after a quarter of turn we reach `Y = 0.0 * in.position.y + 1.0 * in.position.z`, as in the example above. So more generally our transform writes like this, where `alpha` and `beta` depend on the rotation angle:
+Of course at some point we have to remove some of `in.position.y` from Y so that after a quarter of turn we reach `Y = 0.0 * in.position.y + 1.0 * in.position.z`, as in the example above. So **more generally** our transform writes like this, where `alpha` and `beta` depend on the **rotation angle**:
 
 ```rust
 let angle = uMyUniforms.time; // you can multiply it go rotate faster
@@ -364,12 +350,12 @@ out.position = vec4f(position.x, position.y * ratio, 0.0, 1.0);
 ```
 
 ```{note}
-If you payed close attention to the snippet above, you should have noticed **a minus sign** `-` before the second `beta`. It is not visible on our pyramid because it is symmetrical but swapping axes also flips the object. To **counter-balance** this, we can change the sign of one of the dimensions. Hence the Z coordinate after a quarter of turn must be `-in.position.y` instead of `in.position.y`.
+If you pay close attention to the snippet above, you can notice **a minus sign** `-` before the second `beta`. It is not visible on our pyramid because it is symmetrical but swapping axes also flips the object. To **counter-balance** this, we can change the sign of one of the dimensions. Hence the Z coordinate after a quarter of turn must be `-in.position.y` instead of `in.position.y`.
 ```
 
-It turns out that these weights `alpha` and `beta` are not easy to express in terms of basic operations with respect to the angle. So mathematicians came up with a dedicated name for them: **cosine** and **sine**! And the good news is that these are **built-in operations** in WGSL:
+It turns out that these **weights** `alpha` and `beta` are not easy to express in terms of basic operations **with respect to the angle**. So mathematicians came up with a dedicated name for them: **cosine** and **sine**! And the good news is that these are **built-in operations** in WGSL:
 
-```rust
+```{lit} rust, Set vertex out position (replace, also for tangle root "Vanilla")
 let angle = uMyUniforms.time; // you can multiply it go rotate faster
 let alpha = cos(angle);
 let beta = sin(angle);
@@ -383,27 +369,23 @@ out.position = vec4f(position.x, position.y * ratio, 0.0, 1.0);
 
 <figure class="align-center">
 	<video autoplay loop muted inline nocontrols style="width:100%;height:auto;max-width:642px">
-		<source src="../../_static/pyramid-ryz.mp4" type="video/mp4">
+		<source src="../../../_static/pyramid-ryz.mp4" type="video/mp4">
 	</video>
 	<figcaption>
 		<p><span class="caption-text">Rotation in the YZ plane</span></p>
 	</figcaption>
 </figure>
 
-```{image} /images/trigo-light.svg
+```{themed-figure} /images/trigo-{theme}.svg
 :align: center
-:class: only-light
-```
 
-```{image} /images/trigo-dark.svg
-:align: center
-:class: only-dark
+A side-view of the pyramid. The (signed) length of the green vertical and horizontal lines give the value of `alpha` and `beta` respectively.
 ```
 
 Congratulations, you have learned most of what there is to know about **trigonometry** for computer graphics!
 
 ```{hint}
-**If you cannot remember** which one is the $cos$ and which one is the $sin$ among `alpha` and `beta` (don't worry! It happens to everyone), **just take an example** of very simple rotation: `angle = 0`. In such a case, we need `alpha = 1` and `beta = 0`. If you look at a plot of the $sin$ and $cos$ functions you'll quickly see that $cos(0) = 1$ and $sin(0) = 0$
+**If you cannot remember** which one is the $cos$ and which one is the $sin$ among `alpha` and `beta` (don't worry! It happens to everyone), **just take an example** with very simple rotation: `angle = 0`. In such a case, we need `alpha = 1` and `beta = 0`. If you look at a plot of the $sin$ and $cos$ functions you'll quickly see that $cos(0) = 1$ and $sin(0) = 0$
 ```
 
 ```{important}
@@ -413,7 +395,7 @@ $$
 \frac{r \text{ radians}}{d \text{ degrees}} = \frac{2\pi \text{ radians}}{360 \text{ degrees}}
 $$
 
-So to convert an angle $d$ in degrees into its equivalent $r$ in radians, we simply do:
+So to convert an angle $d$ in **degrees** into its equivalent $r$ in **radians**, we simply do:
 
 $$
 r = d \times \frac{\pi}{180}
@@ -425,9 +407,9 @@ Conclusion
 
 We have a beginning of something. With this rotation, it starts looking like 3D, but there remains some important points to be concerned about:
 
- - **Depth fighting** As highlighted in the image below, the triangles do not overlap in the correct order.
- - **Transform** We have the basics, but it is a bit manual, and there is still **no perspective**!
- - **Shading** The trick of setting the tip of the pyramid to a darker color was good for starting, but we can do much better.
+ - **Depth fighting:** As highlighted in the image below, the triangles do not overlap in the correct order.
+ - **Transform:** We have the basics, but it is a bit manual, and there is still **no perspective**!
+ - **Shading:** The trick of setting the tip of the pyramid to a darker color was good for a start, but we can do much better.
 
 These points are, in this order, the topic of the next 4 chapters (transforms are split in 2 chapters).
 

next/basic-3d-rendering/input-geometry/loading-from-file.md

@@ -354,7 +354,11 @@ We do not have any `private` member for now, but we will later on.
 
 We can declare in `public` members our `loadGeometry` function:
 
-```{lit} C++, Public ResourceManager members (also for tangle root "Vanilla")
+```{lit} C++, Public ResourceManager members (hidden, also for tangle root "Vanilla")
+{{Declaration of ResourceManager::loadGeometry}}
+```
+
+```{lit} C++, Declaration of ResourceManager::loadGeometry (also for tangle root "Vanilla")
 /**
  * Load a file from `path` using our ad-hoc format and populate the `pointData`
  * and `indexData` vectors.
@@ -516,8 +520,12 @@ Now that we have a basic resource management mechanism, I strongly suggest we al
 
 Let us first declare it in `ResourceManager.h`:
 
+```{lit} C++, Public ResourceManager members (append, also for tangle root "Vanilla")
+{{Declaration of ResourceManager::loadShaderModule}}
+```
+
 ````{tab} With webgpu.hpp
-```{lit} C++, Public ResourceManager members (append)
+```{lit} C++, Declaration of ResourceManager::loadShaderModule
 /**
  * Create a shader module for a given WebGPU `device` from a WGSL shader source
  * loaded from file `path`.
@@ -530,7 +538,7 @@ static wgpu::ShaderModule loadShaderModule(
 ````
 
 ````{tab} Vanilla webgpu.h
-```{lit} C++, Public ResourceManager members (append, for tangle root "Vanilla")
+```{lit} C++, Declaration of ResourceManager::loadShaderModule (for tangle root "Vanilla")
 /**
  * Create a shader module for a given WebGPU `device` from a WGSL shader source
  * loaded from file `path`.