wgsl-renderer 0.0.1 → 0.0.3

package/LICENSE.md

@@ -1,9 +1,9 @@
-The MIT License (MIT)
-
-Copyright (c) 2025 taiyuuki
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sub license, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
+The MIT License (MIT)
+
+Copyright (c) 2025 taiyuuki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sub license, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,163 +1,119 @@
 # WGSL Multi-Pass Renderer
 
-一个基于WebGPU和WGSL的多通道渲染器。
+English | [中文](./README.zh-CN.md)
 
-## ✨ 特性
+A multi-pass renderer based on WebGPU and WGSL.
 
-- 🔗 **自动Pass链** - Binding 0自动绑定到上一个pass的输出
-- 🖼️ **多Pass渲染** - 支持背景、纹理渲染、后处理效果等多通道
-- ⚡ **高性能渲染循环** - 支持单帧渲染和循环渲染模式
-- 🛠️ **TypeScript支持** - 完整的类型定义和清晰的API分离
-- 🎮 **Uniform系统** - 内置uniform buffer管理，支持动态参数
+## ✨ Features
 
-## 🚀 快速开始
+- 🖼️ **Multi-Pass Rendering** - Support for texture rendering, post-processing effects, and other multi-pass rendering
+- ⚡ **High-Performance Rendering Loop** - Support for single-frame rendering and loop rendering modes
+- 🛠️ **TypeScript Support** - Complete type definitions and clear API separation
+- 🎮 **Uniform System** - Built-in uniform buffer management with dynamic parameter support
 
-### 安装
+## 🚀 Quick Start
+
+### Installation
 
 ```bash
 npm i wgls-renderer
 ```
 
-### 基础使用
+### Add Pass
 
 ```typescript
-import { createWGSLRenderer } from 'wgls-renderer';
-
-const canvas = document.getElementById('canvas');
-const renderer = await createWGSLRenderer(canvas, {
-    backgroundColor: 0x66CCFF  // 支持多种格式：0xRRGGBB, "#RRGGBB", {r, g, b}
-});
-
-// 创建采样器
-const sampler = renderer.createSampler();
+import { createWGSLRenderer } from 'wgls-renderer'
 
-// 加载纹理
-const { texture } = await renderer.loadTexture('image.jpg');
+const canvas = document.querySelector('canvas');
+const renderer = await createWGSLRenderer(canvas)
 
-// 添加Pass 1: 渲染纹理
 renderer.addPass({
-    name: 'texture_pass',
-    shaderCode: textureShader,
-    blendMode: 'alpha',
-    resources: [texture.createView(), sampler]  // binding 1, 2
-});
-
-// 添加Pass 2: 后处理效果
-const uniforms = renderer.createUniforms(4);  // time, resolution.x, resolution.y, padding
-renderer.addPass({
-    name: 'post_process',
-    shaderCode: postProcessShader,
-    blendMode: 'alpha',
-    resources: [sampler, uniforms.getBuffer()]  // binding 1, 2
-});
-
-// 启动循环渲染，支持uniforms更新
-renderer.loopRender(() => {
-    // 更新uniforms
-    uniforms.values[0] = performance.now() / 1000.0;  // 时间
-    uniforms.values[1] = canvas.width;               // 分辨率
-    uniforms.values[2] = canvas.height;
-    uniforms.apply();
-});
-
-// 或者单帧渲染
-renderer.renderFrame();
-```
-
-## 📋 API
+    name: 'my-pass',
+    shaderCode: `
+struct VSOut {
+    @builtin(position) pos: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+};
 
-### createWGSLRenderer(canvas, options?)
+@vertex
+fn vs_main(@location(0) p: vec3<f32>) -> VSOut {
+    var o: VSOut;
+    o.pos = vec4<f32>(p, 1.0);
+    o.uv = p.xy * 0.5 + vec2<f32>(0.5, 0.5);
+    o.uv.y = 1.0 - o.uv.y;
+    return o;
+}
 
-创建WGSL渲染器实例。
+@fragment
+fn fs_main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
+    return vec4(1.0, 1.0, 0.0, 1.0);
+}`,
+})
 
-```typescript
-const renderer = await createWGSLRenderer(canvas, {
-    backgroundColor: 0x66CCFF  // 支持多种格式
-});
+renderer.renderFrame()
 ```
 
 
-- `number`: 十六进制颜色 `0xRRGGBB`
-- `string`: 十六进制字符串 `"#RRGGBB"`
-- `object`: RGB对象 `{r: 0-1, g: 0-1, b: 0-1}`
-
-### 渲染控制
-
-#### renderFrame()
-单帧渲染，不循环。
-
-```typescript
-renderer.renderFrame();
-```
 
-#### loopRender(callback?)
-循环渲染，支持每帧回调，可用于时时更新uniforms。
+### Basic Multi-Pass Usage
 
 ```typescript
-renderer.loopRender(() => {
-    // 每帧更新uniforms
-    myUniforms.values[0] = performance.now() / 1000.0;
-    myUniforms.apply();
-});
-```
+import { createWGSLRenderer } from 'wgls-renderer'
 
-#### stopLoop()
-停止循环渲染。
+const canvas = document.getElementById('canvas')
+const renderer = await createWGSLRenderer(canvas)
 
-```typescript
-renderer.stopLoop();
-```
+// Create sampler
+const sampler = renderer.createSampler()
 
-### addPass(descriptor)
+// Load image texture
+const { texture, width, height } = await renderer.loadImageTexture('image.jpg')
 
-添加一个渲染通道。
-
-```typescript
+// Add Pass 1: Render texture
 renderer.addPass({
-    name: 'my_pass',
-    shaderCode: wgslShaderCode,
-    blendMode: 'alpha',
-    resources: [textureView, sampler]  // 资源数组
-});
-```
-
-**资源数组绑定规则:**
-- **Binding 0**: 自动绑定到上一个pass的输出（无需在数组中指定）
-- **Binding 1**: `resources[0]`
-- **Binding 2**: `resources[1]`
-- 以此类推...
-
-**对应的WGSL绑定:**
-```wgsl
-@group(0) @binding(0) var prevTexture: texture_2d<f32>;     // 自动
-@group(0) @binding(1) var myTexture: texture_2d<f32>;      // resources[0]
-@group(0) @binding(2) var mySampler: sampler;              // resources[1]
-```
-
-### Uniform
-
-#### createUniforms(length)
-创建uniform buffer管理对象。
-
-```typescript
-const uniforms = renderer.createUniforms(4);  // 4个float
-uniforms.values[0] = 1.0;                    // 设置值
-uniforms.apply();                            // 应用到GPU
-const buffer = uniforms.getBuffer();         // 获取GPUBuffer
-```
+    name: 'texture_pass',
+    shaderCode: textureShader,
+    resources: [texture, sampler], // binding 0, 1
+})
 
-#### getUniformsByID(id)
-通过symbol ID获取uniform对象。
+// Add Pass 2: Post-processing effect
+const uniforms = renderer.createUniforms(8) //  Create uniform variable binding
 
-```typescript
-const uniform = renderer.getUniformsByID(myUniformSymbol);
+// Get Pass 1 output texture and bind to Pass 2
+const texturePassOutput = renderer.getPassTexture('texture_pass')
+renderer.addPass({
+    name: 'post_process',
+    shaderCode: postProcessShader,
+    resources: [
+        texturePassOutput, 		// @group(0) @binding(0)
+        sampler, 				// @group(0) @binding(1)
+        uniforms.getBuffer(), 	// @group(0) @binding(2)
+    ],
+})
+
+// Start loop rendering, can update uniforms in callback
+renderer.loopRender((t) => {
+
+    // Update uniforms (Note WebGPU memory alignment rules)
+    uniforms.values[0] = canvas.width 		// resolution.x
+    uniforms.values[1] = canvas.height 		// resolution.y
+    uniforms.values[2] = t / 1000			// time
+    uniforms.values[3] = 0 					// padding (leave empty)
+    uniforms.values[4] = width 				// textureResolution.x
+    uniforms.values[5] = height 			// textureResolution.y
+    uniforms.apply() 						// Apply to GPU
+})
+
+// Or manually execute single frame render
+renderer.renderFrame()
 ```
 
-## 🎨 着色器示例
+## 🎨 Shader Examples
 
-### Pass 1: 纹理渲染
+### Pass 1: Texture Rendering
 
 ```wgsl
+// textureShader
 struct VSOut {
     @builtin(position) pos: vec4<f32>,
     @location(0) uv: vec2<f32>,
@@ -172,34 +128,27 @@ fn vs_main(@location(0) p: vec3<f32>) -> VSOut {
     return o;
 }
 
-@group(0) @binding(0) var prevTexture: texture_2d<f32>; // 内置的纯色背景纹理
-@group(0) @binding(1) var myTexture: texture_2d<f32>;
-@group(0) @binding(2) var mySampler: sampler;
+@group(0) @binding(0) var myTexture: texture_2d<f32>;
+@group(0) @binding(1) var mySampler: sampler;
 
 @fragment
 fn fs_main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
-    let bgColor = textureSample(prevTexture, mySampler, uv);
-    let texColor = textureSample(myTexture, mySampler, uv);
-
-    // 背景与纹理混合
-    return vec4<f32>(
-        bgColor.r * (1.0 - texColor.a) + texColor.r * texColor.a,
-        bgColor.g * (1.0 - texColor.a) + texColor.g * texColor.a,
-        bgColor.b * (1.0 - texColor.a) + texColor.b * texColor.a,
-        1.0
-    );
+    return textureSample(myTexture, mySampler, uv);
 }
 ```
 
-### Pass 2: 动态后处理效果
+### Pass 2: Brightness & Contrast Adjustment
 
 ```wgsl
+// postProcessShader
 struct Uniforms {
-    time: f32,
-    resolution: vec2<f32>,
+    brightness: f32,  // offset 0
+    contrast: f32,    // offset 4
+    saturation: f32,  // offset 8
+    // 4 bytes padding for vec3 alignment
 }
 
-@group(0) @binding(0) var prevTexture: texture_2d<f32>; // Pass 1的输出纹理
+@group(0) @binding(0) var prevTexture: texture_2d<f32>; // Pass 1 output texture
 @group(0) @binding(1) var mySampler: sampler;
 @group(0) @binding(2) var<uniform> uniforms: Uniforms;
 
@@ -207,102 +156,247 @@ struct Uniforms {
 fn fs_main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
     var color = textureSample(prevTexture, mySampler, uv);
 
-    // 动态扫描线效果
-    let scanline = 0.8 + 0.2 * sin(uv.y * 600.0 + uniforms.time * 5.0);
-    color = vec4<f32>(color.r * scanline, color.g * scanline, color.b * scanline, color.a);
+    // Apply brightness
+    color.rgb += uniforms.brightness;
 
-    // 动态波纹效果
-    let waveAmplitude = 0.05 + 0.02 * sin(uniforms.time * 2.0);
-    let waveX = sin(uv.x * 10.0 + uniforms.time * 3.0) * cos(uv.y * 8.0 + uniforms.time * 2.0) * waveAmplitude;
+    // Apply contrast
+    color.rgb = (color.rgb - 0.5) * uniforms.contrast + 0.5;
 
-    let finalR = clamp(color.r + waveX, 0.0, 1.0);
-    let finalG = clamp(color.g - waveX * 0.5, 0.0, 1.0);
-    let finalB = clamp(color.b + waveX * 0.3, 0.0, 1.0);
+    // Apply saturation
+    let gray = dot(color.rgb, vec3<f32>(0.299, 0.587, 0.114));
+    color.rgb = mix(vec3<f32>(gray), color.rgb, uniforms.saturation);
 
-    return vec4<f32>(finalR, finalG, finalB, color.a);
+    return clamp(color, vec4<f32>(0.0), vec4<f32>(1.0));
 }
 ```
 
-## 🔧 内置方法
 
-### 纹理相关
+## 📋 API
+
+### createWGSLRenderer(canvas, options?)
+
+Create WGSL renderer instance.
 
 ```typescript
-// 加载纹理
-const { texture, width, height } = await renderer.loadTexture('image.png');
+import { createWGSLRenderer } from 'wgsl-renderer'
+const renderer = await createWGSLRenderer(canvas)
+```
+
+options:
+
+```ts
+interface WGSLRendererOptions { 
+    config?: GPUCanvasConfiguration;
+}
+```
 
-// 创建采样器
-const sampler = renderer.createSampler({
+### renderer.addPass(passOptions)
+
+Add a render pass.
+
+```ts
+interface RenderPassOptions {
+    name: string;
+    shaderCode: string;
+    entryPoints?: { 
+        vertex?: string;	// Default is 'vs_main' function
+        fragment?: string;	// Default is 'fs_main' function
+    };
+    clearColor?: { r: number; g: number; b: number; a: number };
+    blendMode?: 'additive' | 'alpha' | 'multiply' | 'none';
+    resources?: GPUBindingResource[];
+    view?: GPUTextureView; 		// Optional custom view for this pass
+    format?: GPUTextureFormat; 	// Optional format for the view (required when using custom view with different format)
+}
+```
+
+### renderer.getPassTexture(passName)
+
+Get the output texture of the specified pass. The return value is not a real texture but a placeholder that automatically binds the output texture to the shader during actual rendering.
+
+```typescript
+// Get output texture of my_pass
+const passOutputTexture = renderer.getPassTexture('my_pass')
+const sampler = renderer.createSampler()
+renderer.addPass({
+    name: 'my_pass2',
+    shaderCode: wgslShaderCode,
+    resources: [
+        passOutputTexture,
+        sampler,
+    ],
+})
+```
+
+**Corresponding WGSL binding:**
+
+```wgsl
+@group(0) @binding(0) var myTexture: texture_2d<f32>;      // resources[0]
+@group(0) @binding(1) var mySampler: sampler;              // resources[1]
+```
+
+
+
+### renderer.createUniforms(length)
+
+Create uniform variables using Float32Array, length unit is the number of floats.
+
+```typescript
+const myUniforms = renderer.createUniforms(8) // 8 floats
+
+// Bind to shader
+renderer.addPass({
+    name: 'my_pass',
+    shaderCode: wgslShaderCode,
+    resources: [
+        myUniforms.getBuffer(), // group(0) binding(0) var<uniform>
+    ],
+})
+
+myUniforms.values[0] = 1.0 	// Set value
+myUniforms.apply() 			// Apply to GPU
+```
+
+### renderer.getContext()
+
+Get WebGPU canvas context.
+
+```typescript
+const context = renderer.getContext()
+```
+
+### renderer.getDevice()
+
+Get WebGPU device object.
+
+```typescript
+const device = renderer.getDevice()
+```
+
+### Render Control
+
+#### renderer.renderFrame()
+Single frame rendering.
+
+#### renderer.loopRender(callback?)
+Built-in loop rendering with per-frame callback for real-time uniform updates.
+
+```typescript
+renderer.loopRender(time => {
+
+    // Update uniforms every frame
+    myUniforms.values[2] = time * 0.001
+    myUniforms.apply()
+})
+```
+
+#### renderer.stopLoop()
+Stop loop rendering.
+
+
+
+### renderer.createSampler(options?)
+
+Create sampler with default parameters:
+
+```ts
+const options = {
     magFilter: 'linear',
     minFilter: 'linear',
     addressModeU: 'clamp-to-edge',
     addressModeV: 'clamp-to-edge',
-});
+}
 
-// 创建纹理绑定
-const textureView = renderer.createTextureBinding(texture);
+const sampler = renderer.createSampler(options)
 ```
 
-### 控制相关
+## 🎯 Pass Flow
 
-```typescript
-// 调整画布大小
-renderer.resize(800, 600);
+The renderer provides the following management features:
 
-// 停止渲染
-renderer.stopLoop();
-```
+1. **User-defined all Passes**
+   - Users have complete control over all resource binding
+   - Can get output texture of any pass through `getPassTexture(passName)`
+   - Can get pass object through `getPassByName(passName)`
+
+2. **Texture Management**
+   - Each pass automatically creates output texture (format: `{passName}_output`)
+   - Users can manually bind these textures to other passes
+   - The last pass automatically renders to canvas
+
+3. **Complete Flexibility**
+   - Users decide binding order and method
+   - Support arbitrarily complex pass connections
+   - Can create circular dependencies (if needed)
 
-## 🎯 Pass流程
+**Example Usage:**
+```typescript
+// Method 1: Simple chain reference
+renderer.addPass({
+    name: 'background',
+    resources: [bgTexture, sampler1],
+})
 
-渲染器自动管理以下pass流程：
+renderer.addPass({
+    name: 'main_effect',
+    resources: [renderer.getPassTexture('background'), sampler2], // Reference background output
+})
 
-1. **Background Pass** (内置)
-   - 渲染纯色背景
-   - 输出到 `pass_0_output`
+renderer.addPass({
+    name: 'post_process',
+    resources: [renderer.getPassTexture('main_effect'), sampler3], // Reference main_effect output
+})
 
-2. **User Pass 1**
-   - Binding 0: 背景输出
-   - Binding 1+: 用户资源
-   - 输出到 `pass_1_output`
+// Method 2: Complex multi-pass blending
+renderer.addPass({ name: 'layer1', resources: [textureA, sampler] })
+renderer.addPass({ name: 'layer2', resources: [textureB, sampler] })
+renderer.addPass({ name: 'layer3', resources: [textureC, sampler] })
 
-3. **User Pass 2**
-   - Binding 0: Pass 1输出
-   - Binding 1+: 用户资源
-   - 输出到 `pass_2_output`
+// Create blend pass, referencing multiple different passes simultaneously
+const layer1Output = renderer.getPassTexture('layer1')
+const layer2Output = renderer.getPassTexture('layer2')
+const layer3Output = renderer.getPassTexture('layer3')
 
-4. **Final Pass**
-   - Binding 0: 上一个pass输出
-   - 渲染到canvas
+renderer.addPass({
+    name: 'composite',
+    resources: [layer1Output, layer2Output, layer3Output, finalSampler],
+})
 
-## 📁 项目结构
+// Method 3: Dynamic update binding
+const mainPass = renderer.getPassByName('main_effect')
+if (mainPass) {
 
+    // Dynamically change reference relationship at runtime
+    mainPass.updateBindGroup([renderer.getPassTexture('layer1'), newSampler])
+}
 ```
-src/
-├── index.ts              # 主渲染器类，包含完整的API
-├── RenderPass.ts          # Pass渲染逻辑和类型定义
-├── TextureManager.ts      # 纹理管理
-examples/
-└── multi-pass-demo.html  # 完整示例，包含纹理、动态uniforms效果
+
+**Error Handling Example:**
+```typescript
+// If referencing non-existent pass, will throw detailed error during rendering
+const invalidTexture = renderer.getPassTexture('nonexistent_pass') // This pass doesn't exist
+renderer.addPass({
+    name: 'test',
+    resources: [invalidTexture, sampler], // Will throw error during rendering
+})
+
+// Error message: Cannot find pass named 'nonexistent_pass'. Available passes: [background, main_effect, ...]
 ```
 
-## 🛠️ 开发
+## 🛠️ Development
 
 ```bash
-# 开发模式
-npm run dev
-
-# 构建
-npm run build
+# Development mode
+pnpm dev
 
-# 类型检查
-npm run type-check
+# Build
+pnpm build
 ```
 
-## 📝 许可证
+## 📝 License
 
 MIT License
 
-## 🤝 贡献
+## 🤝 Contributing
 
-欢迎提交Issue和Pull Request！
+Issues and Pull Requests are welcome!