webgl2 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,120 @@
+## GLSL++: Unified WASM Core for Debugging and Generation
+
+This plan is a comprehensive roadmap for the **GLSL++** project. The core is a single **WASM artifact** that provides two distinct, clean interfaces for both runtime emulation (Component 1) and build-time code generation (Component 2).
+
+The entire system is focused on **Correctness and Debugging Fidelity**, leveraging existing Rust graphics crates to minimize the implementation of the $\sim$300 WebGL2 APIs.
+
+-----
+
+## I. Unified WASM Architecture and Delivery
+
+The project compiles into a single `.wasm` file and a single `.js` glue file, ensuring maximum portability between Node.js and browsers.
+
+### A. Final Artifacts
+
+| Artifact | Content | Purpose |
+| :--- | :--- | :--- |
+| **`glsl_plus_plus.wasm`** | Compiled Rust code for both Component 1 (GL Emulation) and Component 2 (Transpiler). | The **Core Engine**. |
+| **`glsl_plus_plus.js`** | Universal ES Module wrapper for asynchronous loading and initialization. | The **Clean Interface** for consumers. |
+
+### B. Core Dependencies (Shared `Cargo.toml`)
+
+| Crate | Role | Component(s) |
+| :--- | :--- | :--- |
+| **`glow`** | **API Surface Definition (300+ methods).** | **C1** |
+| **`wasm-bindgen`** | **JS/WASM Interop and Struct Export.** | **C1 & C2** |
+| **`naga`** | **GLSL Parsing, Reflection, and IR Generation.** | **C1 & C2** |
+| **`glam`** | **Vector/Matrix Math for Rasterizer.** | **C1** |
+| **`hashbrown`** | **Fast Resource Registry (`u32` handles).** | **C1** |
+| **`serde` / `serde-wasm-bindgen`** | **Safe, clean transfer of configuration and metadata objects.** | **C2** |
+| **`wgpu-types`** | **Validated Resource Structs (optional, highly recommended).** | **C1** |
+
+-----
+
+## II. Component 1: WASM GL Emulation Core (Runtime) 🎨
+
+This component implements the $\sim$300 WebGL2 API methods via the `glow` trait, running a pure software rasterizer for unit testing.
+
+### A. External Interface: The Factory Function
+
+Component 1 is accessed through a factory function to manage state initialization, ensuring the clean API shape requested.
+
+```rust
+// In src/gl_emulation.rs
+#[wasm_bindgen(js_name = createGLContext)]
+pub fn create_gl_context(width: u32, height: u32) -> GLContextHandle {
+    // Initializes internal state (framebuffer, viewport, etc.)
+    // Returns a handle to the initialized context instance.
+    // ...
+}
+
+// All 300+ methods (e.g., buffer_data, draw_arrays) are implemented as methods on GLContextHandle
+// and are automatically exposed by wasm-bindgen.
+```
+
+### B. Internal Implementation: The `glow::Context` Trait
+
+| Implementation Area | Detail | Rationale |
+| :--- | :--- | :--- |
+| **API Surface** | Implement the **`glow::Context`** trait on the internal `WasmGLContext` struct. Methods not required for unit testing (e.g., `end_query`, `fence_sync`) are stubbed out to return success/no-op. | Minimizes implementation effort while guaranteeing API correctness. |
+| **Resource Management** | **`WasmGLContext`** contains a **`hashbrown::HashMap<u32, ResourceData>`** registry. All API calls (`createBuffer`, `bindTexture`) reference and mutate resources based on these internal `u32` handles. | Avoids complex host pointers and ensures a deterministic, debuggable state machine. |
+| **Buffer Data Transfer** | The body of `buffer_data()` performs a **transactional copy** of the incoming JavaScript `TypedArray` data directly into the target `Vec<u8>` within the WASM linear memory heap. | Ensures data is persistent and safely managed within the WASM sandbox. |
+
+### C. The Software Rasterizer Loop (Triggered by `draw_arrays`)
+
+The core of the emulation resides here:
+
+1.  **Shader Integration (Naga):** The `link_program` step uses **`naga`** to translate the GLSL into a Rust function pointer/closure (the **CPU Kernel**).
+2.  **Execution Stages:** The `draw_arrays()` body runs the full pipeline: Input Assembly $\rightarrow$ **Vertex Kernel Execution** (calling the Rust function for each vertex) $\rightarrow$ Rasterization (`glam` math) $\rightarrow$ **Fragment Kernel Execution** (calling the Rust function for each pixel).
+3.  **Output:** Writes the final color values to the **`WasmGLContext.framebuffer`** array.
+
+### D. Final Output
+
+The last step exposes the pixel data cleanly for display:
+
+```rust
+// In src/gl_emulation.rs
+#[wasm_bindgen(js_name = presentFrame)]
+pub fn present_frame(handle: &GLContextHandle) -> js_sys::Uint8Array {
+    // Safely creates a view/copy of the framebuffer Vec<u8> for JavaScript.
+    // ...
+}
+```
+
+-----
+
+## III. Component 2: Transpiler/Codegen Tool (Build-Time) 🛠️
+
+Component 2 runs once during the build process, taking GLSL source and returning a structured object containing the generated JS code and metadata. It operates as a stateless function.
+
+### A. External Interface: Structured Object Return
+
+The function accepts the GLSL source and a native JS options object, returning a structured JS object that prevents string-whackery.
+
+```rust
+// In src/codegen.rs
+#[wasm_bindgen(js_name = generateKernelJS)]
+pub fn generate_kernel_js(
+    glsl_source: &str, 
+    options_js: JsValue // Incoming JS object for configuration
+) -> Result<GeneratedOutput, JsValue> {
+    // ... logic ...
+}
+```
+
+### B. Internal Implementation: Reflection and Codec
+
+1.  **Options Deserialization:** Use **`serde-wasm-bindgen`** to safely convert the incoming `JsValue` (the options object) into a **`CodegenOptions`** Rust struct for internal type safety.
+2.  **Naga Reflection:** The core logic uses **`naga`** to parse the GLSL and analyze the Intermediate Representation (IR). This analysis extracts:
+      * All **Uniform** names, types, and locations.
+      * All **Attribute** names and types.
+      * All **Texture/Sampler** definitions.
+3.  **JavaScript Generation:** Use the reflection data to programmatically generate the user-facing JavaScript class string, including:
+      * Class definition (`class MyKernel { ... }`).
+      * **Typed Setter Methods** (e.g., `setUniformFloat(name, value)`).
+      * WASM calls to Component 1's low-level `buffer_data`, `uniform_1f`, etc., methods.
+4.  **Structured Output (Codec):** Build the final **`GeneratedOutput`** struct, which uses **`#[wasm_bindgen]`** to ensure clean object transfer:
+      * `kernel_code`: The generated JavaScript class string.
+      * `metadata`: Array of objects detailing the introspected resources.
+      * `diagnostics`: Array of objects containing warnings and errors from `naga` and custom checks.
+

package/docs/1-webgl-emulator.md

@@ -0,0 +1,51 @@
+# WebGL Emulator (Component 1) Deep Dive
+
+The **WebGL Emulator** is the **pure-Rust software graphics driver** that compiles to a single, single-threaded WASM module. Its primary goal is **correctness, fidelity, and debuggability** by mimicking the entire WebGL2 state machine and rendering pipeline on the CPU.
+
+## 1. ⚙️ Core Architecture and State Management
+
+The emulator's design centers on satisfying the **`glow::Context` trait** while managing all resources within the WASM linear memory.
+
+* **Factory Function:** The entire system is instantiated via the clean factory function: `createGLContext(width, height)`. This function initializes the full internal state and returns a handle.
+* **State Container:** The central struct, e.g., `WasmGLContext`, is the single source of truth for the entire GL state. It manages:
+    * **Resource Registry (`hashbrown::HashMap<u32, ResourceData>`):** Maps the user-facing $\mathbf{u32}$ integer handles (returned by `gl.createBuffer()`, etc.) to the actual Rust structs holding the data and parameters.
+    * **Framebuffer:** A large `Vec<u32>` or `Vec<u8>` in the WASM heap that stores the final pixel output.
+    * **Bound State:** Fields tracking the currently bound program, active VAO, active texture unit, viewport dimensions, etc.
+
+## 2. 🔌 Implementing the $\mathbf{300+}$ API Surface with `glow`
+
+This step minimizes bug surface by reusing the `glow` API definition.
+
+* **Trait Implementation:** The `WasmGLContext` struct implements every method defined in the `glow::Context` trait.
+* **Stubbing:** Approximately $\mathbf{80\%}$ of the methods implement simple state updates or stubs:
+    * **State Setting:** Methods like `enable(DEPTH_TEST)` simply flip a boolean in the `WasmGLContext` struct.
+    * **Resource Binding:** Methods like `bind_buffer(ARRAY_BUFFER, handle)` update the state machine's field to hold the input $\mathbf{u32}$ handle.
+    * **Unsupported Features:** Methods for complex GPU features like `begin_query` or `fence_sync` are implemented as **no-ops** (stubs), returning success without affecting internal state, as they are non-goals for a unit-testing platform.
+* **Data Transfer (`buffer_data`):** The body of this function handles the vital **transactional copy** of `TypedArray` data from JavaScript into the WASM heap buffer referenced by the `u32` handle, ensuring data integrity within the emulation.
+
+## 3. 🧠 The Complex Core: Shader Translation and Execution
+
+The most bespoke and critical logic is transforming the GLSL source into executable Rust code.
+
+### A. Shader Compilation Flow (`compile_shader` / `link_program`)
+
+1.  **Parse & Reflect:** The `shader_source()` and `compile_shader()` methods feed the GLSL code into **`naga`**.
+    * **Naga Output:** `naga` performs parsing, validation, and produces its **Intermediate Representation (IR)**.
+2.  **Code Generation (IR $\rightarrow$ Rust):** A custom routine is required to traverse the Naga IR and output a **Rust source code string** that accurately replicates the shader's logic.
+    * **Vertex Kernel:** Generates a Rust function signature like `fn vs_kernel(uniforms: &Uniforms, vertex_in: &VertexIn) -> VertexOut`, where `VertexIn` and `VertexOut` are structs derived from the shader's attributes and varyings.
+    * **Fragment Kernel:** Generates a Rust function signature like `fn fs_kernel(uniforms: &Uniforms, fragment_in: &FragmentIn) -> Color`, implementing all shading logic.
+3.  **Kernel Storage:** The Rust source code is compiled (or dynamically built/cached), and a **function pointer or closure** to this executable kernel is stored in the internal `ProgramData` resource.
+
+### B. Software Rasterizer Execution (`draw_arrays` and similar)
+
+The `draw_arrays()` call initiates the CPU-bound process:
+
+1.  **Vertex Execution:** The emulation loop iterates through the vertex data. For each vertex, it calls the **Vertex Kernel (Rust function)**, which performs the vertex transformation using **`glam`** math and outputs the clip-space coordinates.
+2.  **Rasterization:** The **`glam`**-powered core logic handles triangle setup, clipping, barycentric interpolation of varyings, and determining which pixels are covered.
+3.  **Fragment Execution:** For every covered pixel, the loop calls the **Fragment Kernel (Rust function)**, passing the interpolated varyings and uniform data. This executes the final shading calculation.
+4.  **Output Merger:** Applies depth, stencil, and blending logic based on the current state before writing the final color result to the **WASM Framebuffer**.
+
+## 4. 🔬 Debugging and Output
+
+* **Debugging Hooks:** The structure of the generated **Rust CPU Kernels** is explicitly designed to be inspected by WASM debugging tools (like browser DevTools). Because the GLSL is translated into traceable Rust code, the developer can pause execution inside the shader logic.
+* **Final Output:** The separate `presentFrame()` function acts as the single bridge to the host, copying the contents of the **WASM Framebuffer** to a JavaScript `Uint8Array` for display via `ctx.putImageData()`.

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "webgl2",
-  "version": "1.0.1",
-  "description": "",
+  "version": "1.0.3",
+  "description": "WebGL2 tools to derisk large GPU projects on the web beyond toys and demos.",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mavity/mavity"
+  },
   "keywords": [],
   "author": "",
-  "license": "ISC"
+  "license": "TBD",
+  "bugs": {
+    "url": "https://github.com/mavity/mavity/issues"
+  },
+  "homepage": "https://github.com/mavity/mavity#readme"
 }