A mesh grid demo

README.md

@@ -8,26 +8,53 @@ URL params:
 
 - `tab` content to draw, options(defaults to last one):
 
-  - `quat-curve`
-  - `hyper-cube`
-  - `hyper-cube-grid`
-  - `fly-city`
-  - `lamp-tree`
-  - `quat-tree`
-  - `quat-product`
-  - `prime-walk`
+  - `quat-curve` a curve
+  - `hyper-cube` hyper cube
+  - `hyper-cube-grid` a grid of hyper cubes
+  - `fly-city` quternion fractal
+  - `lamp-tree` quternion fractal
+  - `quat-tree` quaternion tree
+  - `quat-product` quaternion product curve
+  - `prime-walk` some walk path
+  - `sphere-tess` sphere tessellation folded to 2 dimensions
+  - `cubic-array` array and grid in cubic space
 
 - `read` to read from storage, options(defaults to `true`):
 
   - `true`
   - `false`
 
 - `axis` to draw axis, options(defaults to `true`):
+
   - `true`
   - `false`
 
+- `times` for expand times, only works on some demos, 0~10
+
+### Gamepad Controls
+
+Control between XYZ:
+
+![Gamepad Default](./assets/caterfoil-default.png)
+
+Hold `△` to enable control between XYW:
+
+![Gamepad W](./assets/caterfoil-W.png)
+
 ### Development
 
+Watch build MoonBit:
+
+```bash
+moon build --target js --debug --watch
+```
+
+Watch serve page:
+
+```bash
+yarn vite
+```
+
 ### Licence
 
 Apache 2.0

moon.mod.json

@@ -1,14 +1,14 @@
 {
   "name": "tiye/caterfoil",
-  "version": "0.1.0",
+  "version": "0.0.2",
   "deps": {
     "tiye/quaternion": "0.0.4",
-    "tiye/dom-ffi": "0.0.6"
+    "tiye/dom-ffi": "0.0.8"
   },
   "readme": "README.md",
   "repository": "",
   "license": "Apache-2.0",
   "keywords": [],
   "description": "",
   "source": "src"
-}
+}

src/caterfoil.mjs

@@ -7,8 +7,8 @@ console.log("Caterfoil loaded", Caterfoil);
 // load js code which Vite does not detect
 import("../target/js/debug/build/main/main.js")
   .then((module) => {
-    console.log("Main loaded", module);
+    console.log("mbt app loaded", module);
   })
   .catch((error) => {
-    console.error("Main error", error);
+    console.error("mbt app loading error", error);
   });

src/lib/caterfoil.mbt

@@ -3,6 +3,8 @@ pub extern "js" fn initialize_context() -> Promise =
   #| () => Caterfoil.initializeContext()
 
 ///|
+/// Triggers a redraw of the current Caterfoil render tree. Updates the WebGPU
+/// canvas with the latest state of all render objects in the scene graph.
 pub extern "js" fn paint_caterfoil_tree() -> Unit =
   #| () => Caterfoil.paintCaterfoilTree()
 
@@ -14,10 +16,19 @@ pub extern "js" fn render_caterfoil_tree(
   #| (el, dispatch) => Caterfoil.renderCaterfoilTree(el, dispatch)
 
 ///|
+/// Adjusts the canvas size to match its display size, ensuring proper rendering
+/// and preventing scaling artifacts.
+///
+/// Parameters:
+///
+/// * `canvas` : The HTML canvas element to be resized. Must be a valid DOM
+/// Element object obtained through methods like `Document::query_selector`.
 pub extern "js" fn reset_canvas_size(canvas : Element) -> Unit =
   #| (canvas) => Caterfoil.resetCanvasSize(canvas)
 
 ///|
+/// Initializes textures required for WebGPU rendering on the canvas. Sets up
+/// necessary texture configurations and bindings for the rendering pipeline.
 pub extern "js" fn initialize_canvas_textures() -> Unit =
   #| () => Caterfoil.initializeCanvasTextures()
 
@@ -26,6 +37,10 @@ pub extern "js" fn setup_mouse_events() -> Unit =
   #| () => Caterfoil.setupMouseEvents()
 
 ///|
+/// Sets up gamepad input handling for WebGPU rendering. Initializes event
+/// listeners and state management for gamepad connections, button presses, and
+/// axis movements. Enables real-time input detection from connected gamepads to
+/// control the WebGPU rendering viewport and scene.
 pub extern "js" fn load_gamepad_control() -> Unit =
   #| () => Caterfoil.loadGamepadControl()
 
@@ -34,10 +49,38 @@ pub extern "js" fn lines_wgsl() -> String =
   #| () => Caterfoil.triangleWgsl
 
 ///|
+/// Returns the WebGPU Shader Language (WGSL) code used for rendering polylines
+/// in Caterfoil. The shader includes vertex and fragment stages necessary for
+/// drawing thick lines with proper width and direction handling.
+///
+/// Returns a string containing the WGSL shader code for polyline rendering.
 pub extern "js" fn polyline_wgsl() -> String =
   #| () => Caterfoil.polylineWgsl
 
-///| get viewer states saved in localStorage so that it can be restored
+///|
+/// Connects a retained atom to browser's localStorage for persistent state
+/// management. The connection can be configured to enable/disable reading from
+/// or writing to localStorage.
+///
+/// Parameters:
+///
+/// * `name` : A unique identifier string for the retained atom. This name is
+/// used as the key in localStorage.
+/// * `read` : Optional boolean flag to control loading from localStorage.
+/// Defaults to `true`. When set to `false`, disables loading stored values.
+/// * `write` : Optional boolean flag to control saving to localStorage. Defaults
+/// to `true`. When set to `false`, disables saving values.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "connect_retained_atom_to_srorage" {
+///   // Connect an atom named "viewer-state" with both read and write enabled
+///   connect_retained_atom_to_srorage("viewer-state")
+///   // Connect an atom that only reads from storage
+///   connect_retained_atom_to_srorage("read-only-state", write=false)
+/// }
+/// ```
 pub fn connect_retained_atom_to_srorage(
   name : String,
   /// false to disable loading from localStorage
@@ -61,6 +104,39 @@ extern "js" fn caterfoil_connect_retained_atom_to_srorage(
   #| (name, read, write) => Caterfoil.connectRetainedAtomToStorage(name, {read, write})
 
 ///|
+/// Represents the vertex data used in Caterfoil rendering objects. Provides two
+/// variants for different rendering approaches:
+/// basic vertices for simple shapes and polyline vertices for thick lines with
+/// proper width handling.
+///
+/// Parameters:
+///
+/// For `WithPoints`:
+///
+/// * `vertices` : An array of basic vertices, each containing position and color
+/// information.
+///
+/// For `WithTriangles`:
+///
+/// * `vertices` : An array of polyline vertices, each containing position,
+/// color, direction, and side information for thick line rendering.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "ObjectData" {
+///   let points = ObjectData::WithPoints([
+///     Vertex::{
+///       position: @quaternion.new(0.0, 0.0, 0.0, 1.0),
+///       color: Color::red(),
+///     },
+///   ])
+///   match points {
+///     WithPoints(vertices) => inspect!(vertices.length(), content="1")
+///     WithTriangles(_) => inspect!(false, content="true")
+///   }
+/// }
+/// ```
 pub(all) enum ObjectData {
   WithPoints(Array[Vertex])
   WithTriangles(Array[PolylineVertex])
@@ -89,6 +165,41 @@ fn ObjectData::to_data(
 }
 
 ///|
+/// Represents configuration options for creating a WebGPU render object in
+/// Caterfoil. Contains essential information about the rendering pipeline,
+/// including shader configuration, vertex data, and rendering topology.
+///
+/// Fields:
+///
+/// * `label` : A string identifier for the render object, useful for debugging
+/// purposes.
+/// * `shader` : The WebGPU shader code as a string, defining how vertices should
+/// be processed and rendered.
+/// * `topology` : The primitive topology type that determines how vertices are
+/// interpreted (e.g., point list, line list, triangle list).
+/// * `data` : The vertex data to be rendered, can be either basic vertices or
+/// polyline vertices with additional attributes.
+/// * `indices` : Optional array of unsigned integers specifying the vertex
+/// indices for indexed rendering.
+/// * `get_params` : Optional callback function that returns an array of
+/// floating-point values used as shader parameters.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "CaterfoilObjectOptions" {
+///   let options = CaterfoilObjectOptions::{
+///     label: "triangle",
+///     shader: @caterfoil.lines_wgsl(),
+///     topology: ShaderPrimitiveTopology::TriangleList,
+///     data: ObjectData::WithPoints([]),
+///     indices: None,
+///     get_params: None,
+///   }
+///   inspect!(options.label, content="\"triangle\"")
+///   inspect!(options.topology, content="TriangleList")
+/// }
+/// ```
 pub(all) struct CaterfoilObjectOptions {
   label : String
   shader : String
@@ -164,13 +275,50 @@ fn CaterfoilAttribute::as_value(self : CaterfoilAttribute) -> JsValue {
 ///|
 type CaterfoilRenderObject
 
-///|
+///| Creates a new Caterfoil render object with the specified configuration
 extern "js" fn CaterfoilRenderObject::as_value(
   self : CaterfoilRenderObject
 ) -> JsValue =
   #| (self) => self
 
 ///|
+/// Creates a new WebGPU render object in the Caterfoil rendering system with
+/// specified vertex data and rendering configuration.
+///
+/// Parameters:
+///
+/// * `data` : The vertex data to be rendered. Can be either basic vertices
+/// (`WithPoints`) or polyline vertices (`WithTriangles`) with additional
+/// attributes for thick line rendering.
+/// * `shader` : Optional WebGPU shader code as a string. If not provided,
+/// automatically selects an appropriate shader based on the vertex data type
+/// (`lines_wgsl` for `WithPoints`, `polyline_wgsl` for `WithTriangles`).
+/// * `label` : Optional string identifier for the render object, useful for
+/// debugging. Defaults to "object".
+/// * `topology` : Optional primitive topology type that determines how vertices
+/// are interpreted (e.g., point list, line list). Defaults to `TriangleList`.
+/// * `get_params` : Optional callback function that returns an array of
+/// floating-point values used as shader parameters.
+/// * `indices` : Optional array of unsigned integers specifying the vertex
+/// indices for indexed rendering.
+///
+/// Returns a new `CaterfoilRenderObject` that can be used in the Caterfoil
+/// rendering system.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "object/basic" {
+///   let vertices = [
+///     Vertex::{
+///       position: @quaternion.new(0.0, 0.0, 0.0, 1.0),
+///       color: Color::red(),
+///     },
+///   ]
+///   let triangle = object(data=ObjectData::WithPoints(vertices))
+///   inspect!(triangle, content="[object Object]")
+/// }
+/// ```
 pub fn object(
   data~ : ObjectData,
   /// by default, pick the shader based on the data type
@@ -201,6 +349,28 @@ pub fn object(
 }
 
 ///|
+/// Creates a group of render objects in the Caterfoil rendering system, allowing
+/// multiple render objects to be combined and managed as a single unit.
+///
+/// Parameters:
+///
+/// * `children` : An array of `CaterfoilRenderObject`s that will be grouped
+/// together. These objects can be created using functions like `object()` or
+/// other `group()` calls.
+///
+/// Returns a new `CaterfoilRenderObject` that represents the group of render
+/// objects.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "group" {
+///   let triangle = @caterfoil.object(data=ObjectData::WithPoints([]))
+///   let circle = @caterfoil.object(data=ObjectData::WithPoints([]))
+///   let scene = @caterfoil.group([triangle, circle])
+///   inspect!(scene, content="[object Object]")
+/// }
+/// ```
 pub fn group(children : Array[CaterfoilRenderObject]) -> CaterfoilRenderObject {
   let arr = JsArray::new()
   for child in children {

src/lib/ffi.mbt

@@ -1,4 +1,4 @@
-///|
+///| a very naive ffi implementation for JS Promise
 type Promise
 
 ///|

src/lib/gpu.mbt

@@ -24,6 +24,46 @@ fn ShaderPrimitiveTopology::to_string(self : ShaderPrimitiveTopology) -> String
 }
 
 ///|
+/// Represents the format of vertex attributes in WebGPU shaders. Each variant
+/// describes the data type, size, and normalization of vertex data.
+///
+/// The format strings follow the WebGPU specification naming convention:
+///
+/// * First part indicates the data type (`uint`, `sint`, `float`) and bit width
+/// (8, 16, 32)
+/// * Second part (if present) indicates the number of components (x2, x3, x4)
+/// * Prefix `unorm` or `snorm` indicates normalized integer formats
+/// * Special case `unorm10_10_10_2` for packed 32-bit format with normalized
+/// components
+///
+/// Parameters:
+///
+/// * `Uint8x2`, `Uint8x4`: Two or four unsigned 8-bit integers
+/// * `Sint8x2`, `Sint8x4`: Two or four signed 8-bit integers
+/// * `Unorm8x2`, `Unorm8x4`: Two or four normalized unsigned 8-bit integers
+/// * `Snorm8x2`, `Snorm8x4`: Two or four normalized signed 8-bit integers
+/// * `Uint16x2`, `Uint16x4`: Two or four unsigned 16-bit integers
+/// * `Sint16x2`, `Sint16x4`: Two or four signed 16-bit integers
+/// * `Unorm16x2`, `Unorm16x4`: Two or four normalized unsigned 16-bit integers
+/// * `Snorm16x2`, `Snorm16x4`: Two or four normalized signed 16-bit integers
+/// * `Float16x2`, `Float16x4`: Two or four 16-bit floating point numbers
+/// * `Float32`, `Float32x2`, `Float32x3`, `Float32x4`: One to four 32-bit
+/// floating point numbers
+/// * `Uint32`, `Uint32x2`, `Uint32x3`, `Uint32x4`: One to four unsigned 32-bit
+/// integers
+/// * `Sint32`, `Sint32x2`, `Sint32x3`, `Sint32x4`: One to four signed 32-bit
+/// integers
+/// * `Unorm10_10_10_2`: Packed format with three 10-bit normalized unsigned
+/// integers and one 2-bit normalized unsigned integer
+///
+/// Example:
+///
+/// ```moonbit
+/// test "GPUVertexFormat" {
+///   let format = GPUVertexFormat::Float32x4
+///   inspect!(format.to_string(), content="\"float32x4\"")
+/// }
+/// ```
 pub(all) enum GPUVertexFormat {
   Uint8x2
   Uint8x4