fragmentcolor 0.10.6 → 0.10.7

package/README.md

@@ -1,198 +1,125 @@
-# FragmentColor
+# FragmentColor for JavaScript (WASM)
 
-[FragmentColor](https://fragmentcolor.org) is a cross-platform GPU programming library implemented in Rust and [wgpu](https://wgpu.rs).
+[FragmentColor](https://fragmentcolor.org) is a cross‑platform GPU programming library implemented in Rust and wgpu, compiled to WebAssembly for JavaScript.
 
-It has bindings for **Javascript**, **Python**, **Swift**, and **Kotlin**
-and targets each platform's native graphics API: **Vulkan**, **Metal**, **DirectX**, **OpenGL**, **WebGL**, or **WebGPU**.\
-See [Platform Support](#platform-support) for details.
+This README is specific to the npm package. For Rust usage, see the repository README.md. For Python, see README_PY.md.
 
-The API encourages a simple shader composition workflow. You can use **WGSL** or **GLSL** shaders
-for visual consistency across platforms, while avoiding the verbosity of modern GPU APIs.
+- Documentation: https://fragmentcolor.org/welcome
+- API Reference: https://fragmentcolor.org/api
 
-**We strive to remove the complexity without sacrificing control**. Because of the composition primitives, you can
-build a highly customized render graph with multiple render passes.
-
-Check the [Documentation](/welcome) and the [API Reference](/api) for more information.
-
-> ⚠️ **This library is its early days of development**
->
-> The API is subject to frequent changes in minor versions. Documentation is not always in sync.
->
-> Check the [Roadmap](/ROADMAP.md) and [Changelog](/CHANGELOG.md) on [GitHub](https://github.com/vista-art/fragmentcolor) to stay tuned on the latest updates.
-
-## Example
-
-From a given shader source, our library will:
-
-- parse the shader
-- compile/reload it at runtime
-- create the Uniform bindings in your platform's native graphics API
-- expose them with the dot notation.
-
-### Example usage (Python)
+## Install
 
 ```bash
-pip install fragmentcolor glfw rendercanvas
-```
-
-```python
-from fragmentcolor import FragmentColor as fc, Renderer, Shader, Pass, Frame
-from rendercanvas.auto import RenderCanvas, loop
-
-# Initializes a renderer and a target compatible with the given canvas
-canvas = RenderCanvas(size=(800, 600))
-renderer = Renderer()
-target = renderer.create_target(canvas)
-
-# You can pass the shader as a source string, file path, or URL:
-circle = Shader("./path/to/circle.wgsl")
-triangle = Shader("https://fragmentcolor.org/shaders/triangle.wgsl")
-my_shader = Shader("""
-struct VertexOutput {
-    @builtin(position) coords: vec4<f32>,
-}
-
-struct MyStruct {
-    my_field: vec3<f32>,
-}
-
-@group(0) @binding(0)
-var<uniform> my_struct: MyStruct;
-
-@group(0) @binding(1)
-var<uniform> my_vec2: vec2<f32>;
-
-@vertex
-fn vs_main(@builtin(vertex_index) in_vertex_index: u32) -> VertexOutput {
-    const vertices = array(
-        vec2( -1., -1.),
-        vec2(  3., -1.),
-        vec2( -1.,  3.)
-    );
-    return VertexOutput(vec4<f32>(vertices[in_vertex_index], 0.0, 1.0));
-}
-
-@fragment
-fn fs_main() -> @location(0) vec4<f32> {
-    return vec4<f32>(my_struct.my_field, 1.0);
-}
-""")
-
-# The library binds and updates the uniforms automatically
-my_shader.set("my_struct.my_field", [0.1, 0.8, 0.9])
-my_shader.set("my_vec2", [1.0, 1.0])
-
-# One shader is all you need to render
-renderer.render(shader, target)
-
-# But you can also combine multiple shaders in a render Pass
-rpass = Pass("single pass")
-rpass.add_shader(circle)
-rpass.add_shader(triangle)
-rpass.add_shader(my_shader)
-renderer.render(rpass, target)
-
-# Finally, you can combine multiple passes in a Frame
-frame = Frame()
-frame.add_pass(rpass)
-frame.add_pass(Pass("GUI pass"))
-renderer.render(frame, target)
-
-# To animate, simply update the uniforms in a loop
-@canvas.request_draw
-def animate():
-    circle.set("position", [0.0, 0.0])
-    renderer.render(frame, target)
-
-loop.run()
+npm install fragmentcolor
+# or
+pnpm add fragmentcolor
+# or
+yarn add fragmentcolor
 ```
 
-### Example usage (Javascript)
-
-```javascript
-import { Shader, Renderer } from "fragmentcolor";
-
-const canvas = document.getElementById("my-canvas");
-const renderer = new Renderer();
-const target = renderer.init(canvas);
-
-const shader = new Shader("https://fragmentcolor.org/shaders/circle.wgsl");
-shader.set("resolution", [canvas.width, canvas.heigth]);
-shader.set("circle.radius", 0.05);
-shader.set("circle.color", [1.0, 0.0, 0.0, 0.8]);
-
-const renderer = new Renderer();
-
-function animate() {
-  shader.set("circle.position", [mouseX, mouseY]);
-  renderer.render(shader, target);
-
-  requestAnimationFrame(animate);
+## Quick start
+
+```js
+import init, { Renderer, Shader, Pass, Frame } from "fragmentcolor";
+
+async function start() {
+  // Initializes the WASM module
+  await init();
+
+  // Initializes a renderer and a target compatible with the given canvas
+  const canvas = document.getElementById("my-canvas");
+  const renderer = new Renderer();
+  const target = await renderer.createTarget(canvas);
+
+  // You can pass the shader as a source string, file path, or URL:
+  const circle = new Shader("./path/to/circle.wgsl");
+  const triangle = new Shader("https://fragmentcolor.org/shaders/triangle.wgsl");
+  const shader = new Shader(`
+    struct VertexOutput {
+        @builtin(position) coords: vec4<f32>,
+    }
+
+    struct MyStruct {
+        my_field: vec3<f32>,
+    }
+
+    @group(0) @binding(0)
+    var<uniform> my_struct: MyStruct;
+
+    @group(0) @binding(1)
+    var<uniform> my_vec2: vec2<f32>;
+
+    @vertex
+    fn vs_main(@builtin(vertex_index) in_vertex_index: u32) -> VertexOutput {
+        const vertices = array(
+            vec2( -1., -1.),
+            vec2(  3., -1.),
+            vec2( -1.,  3.)
+        );
+        return VertexOutput(vec4<f32>(vertices[in_vertex_index], 0.0, 1.0));
+    }
+
+    @fragment
+    fn fs_main() -> @location(0) vec4<f32> {
+        return vec4<f32>(my_struct.my_field, 1.0);
+    }
+  `);
+
+  // The library binds and updates the uniforms automatically
+  shader.set("my_struct.my_field", [0.1, 0.8, 0.9]);
+  shader.set("my_vec2", [1.0, 1.0]);
+
+  // One shader is all you need to render
+  renderer.render(circle, target);
+
+  // But you can also combine multiple shaders in a render Pass
+  const rpass = new Pass("single pass");
+  rpass.addShader(circle);
+  rpass.addShader(triangle);
+  rpass.addShader(shader);
+  renderer.render(rpass, target);
+
+  // Finally, you can combine multiple passes in a Frame
+  const frame = new Frame();
+  frame.addPass(rpass);
+  frame.addPass(new Pass("GUI pass"));
+  renderer.render(frame, target);
+
+  // To animate, simply update the uniforms in a loop
+  function animate() {
+    circle.set("position", [0.0, 0.0]);
+    renderer.render(frame, target);
+    requestAnimationFrame(animate);
+  }
+  animate();
 }
-animate();
-```
 
-## Limitations
-
-- The current version of this library **always use a fullscreen triangle for every shader**. Support for custom geometries and instanced rendering is planned.
-
-- In Python, we depend on [rendercanvas](https://github.com/pygfx/rendercanvas) adapter to support multiple window libraries. Direct support for other libraries is planned.
-
-- Textures and Samplers are currently not supported, but are also planned.
-
-- Javascript, Swift, and Kotlin are currently WIP.
-
-## Running this project
-
-### Target: Desktop (Rust library)
-
-For Rust, check the examples folder and run them with:
-
-```bash
-cargo run --example circle
-cargo run --example triangle
-cargo run --example multiobject
-cargo run --example multipass
-```
-
-### Target: Desktop (Python module)
-
-**NOTE:** Pip Package currently only available for MacOS (Apple Silicon)
-
-```bash
-pip install fragmentcolor glfw rendercanvas
+start();
 ```
 
-Alternativaly, You can build it locally with [maturin](https://www.maturin.rs/installation.html):
+## Web (WASM) development
 
 ```bash
-pipx install maturin
-maturin develop
-pip install glfw rendercanvas
-```
+# Build WASM package (wasm-pack target web) and sync into local JS examples
+./build_web        # add --debug for a debug build
 
-The built library is located in `platforms/python/fragmentcolor`
+# Run JS demos (Vite dev server) and open browser
+./run_web repl     # or: ./run_web multipass | ./run_web headless
 
-```bash
-cd platforms/python/fragmentcolor
-python3 main.py
+# Manual alternative
+pnpm --dir examples/javascript install
+pnpm --dir examples/javascript dev
 ```
 
-### Target: Web browser (WASM module)
-
-- TBD
-
-### Target: iOS (Swift library)
+## Documentation & website
 
-- TBD
-
-### Target: Android (Kotlin library)
-
-- TBD
+- Docs source of truth lives in docs/api and is referenced from code via `#[lsp_doc]`.
+- Examples on method pages are sliced from the healthcheck scripts; no filesystem reads in docs.
+- Doc examples follow async + pollster patterns on the Rust side and are converted to JavaScript automatically.
 
 ## Platform support
 
-Platform support is the same as upstream [wgpu](https://github.com/gfx-rs/wgpu):
+Platform support is aligned with upstream wgpu:
 
 | API    | Windows      | Linux/Android   | macOS/iOS | Web (wasm)  |
 | ------ | ------------ | --------------- | --------- | ----------- |
@@ -203,6 +130,14 @@ Platform support is the same as upstream [wgpu](https://github.com/gfx-rs/wgpu):
 | WebGPU |              |                 |           | ✅          |
 
 ✅ = First Class Support  
-🆗 = Downlevel/Best Effort Support
-📐 = Requires the [ANGLE](http://angleproject.org/) translation layer (GL ES 3.0 only)  
-🌋 = Requires the [MoltenVK](https://vulkan.lunarg.com/sdk/home#mac) translation layer
+🆗 = Downlevel/Best Effort Support  
+📐 = Requires the ANGLE translation layer (GL ES 3.0 only)  
+🌋 = Requires the MoltenVK translation layer
+
+## Limitations (planned features)
+
+- Swift & Kotlin bindings are not supported yet, but planned.
+
+---
+
+Note on generation: this README_JS.md is generated from this template (README_JS.tpl.md) and the repository README.md examples by the build script. Do not edit the generated README_JS.md directly.