wgsl-renderer 0.0.2 → 0.0.4

package/README.md

@@ -1,25 +1,61 @@
 # WGSL Multi-Pass Renderer
 
-一个基于WebGPU和WGSL的多通道渲染器。
+English | [中文](./README.zh-CN.md)
 
-## ✨ 特性
+A multi-pass renderer based on WebGPU and WGSL.
 
-- 🔗 **灵活的Pass链** - Pass 2开始自动绑定上一个pass的输出
-- 🖼️ **多Pass渲染** - 支持纹理渲染、后处理效果等多通道
-- ⚡ **高性能渲染循环** - 支持单帧渲染和循环渲染模式
-- 🛠️ **TypeScript支持** - 完整的类型定义和清晰的API分离
-- 🎮 **Uniform系统** - 内置uniform buffer管理，支持动态参数
-- 🔄 **自动Resize** - 内置ResizeObserver自动处理canvas大小变化
+## ✨ 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.querySelector('canvas');
+const renderer = await createWGSLRenderer(canvas)
+
+renderer.addPass({
+    name: 'my-pass',
+    shaderCode: `
+struct VSOut {
+    @builtin(position) pos: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+};
+
+@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;
+}
+
+@fragment
+fn fs_main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
+    return vec4(1.0, 1.0, 0.0, 1.0);
+}`,
+})
+
+renderer.renderFrame()
+```
+
+
+
+### Basic Multi-Pass Usage
 
 ```typescript
 import { createWGSLRenderer } from 'wgls-renderer'
@@ -27,50 +63,54 @@ import { createWGSLRenderer } from 'wgls-renderer'
 const canvas = document.getElementById('canvas')
 const renderer = await createWGSLRenderer(canvas)
 
-// 创建采样器
+// Create sampler
 const sampler = renderer.createSampler()
 
-// 加载图片纹理
-const { texture } = await renderer.loadImageTexture('image.jpg')
+// Load image texture
+const { texture, width, height } = await renderer.loadImageTexture('image.jpg')
 
-// 添加Pass 1: 渲染纹理
+// Add Pass 1: Render texture
 renderer.addPass({
     name: 'texture_pass',
     shaderCode: textureShader,
-    blendMode: 'alpha',
     resources: [texture, sampler], // binding 0, 1
 })
 
-// 添加Pass 2: 后处理效果 (自动绑定Pass 1的输出到binding 0)
-const uniforms = renderer.createUniforms(16) // 支持复杂的uniform结构
+// Add Pass 2: Post-processing effect
+const uniforms = renderer.createUniforms(8) //  Create uniform variable binding
+
+// Get Pass 1 output texture and bind to Pass 2
+const texturePassOutput = renderer.getPassTexture('texture_pass')
 renderer.addPass({
     name: 'post_process',
     shaderCode: postProcessShader,
-    blendMode: 'alpha',
-    resources: [sampler, uniforms.getBuffer()], // 对应binding 1, 2 (binding 0自动绑定到Pass 1的输出)
+    resources: [
+        texturePassOutput, 		// @group(0) @binding(0)
+        sampler, 				// @group(0) @binding(1)
+        uniforms.getBuffer(), 	// @group(0) @binding(2)
+    ],
 })
 
-// 启动循环渲染，可以在回调函数中更新uniforms
-renderer.loopRender(() => {
-
-    // 更新uniforms (注意WebGPU的内存对齐规则)
-    uniforms.values[0] = canvas.width // resolution.x
-    uniforms.values[1] = canvas.height // resolution.y
-    uniforms.values[2] = performance.now() // time
-    uniforms.values[3] = 0 // padding (vec3对齐)
-    uniforms.values[4] = 1024 // textureResolution.x
-    uniforms.values[5] = 1024 // textureResolution.y
-    uniforms.apply()
+// 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
@@ -97,20 +137,18 @@ fn fs_main(@location(0) uv: vec2<f32>) -> @location(0) vec4<f32> {
 }
 ```
 
-### Pass 2: 动态后处理效果
+### Pass 2: Brightness & Contrast Adjustment
 
 ```wgsl
 // postProcessShader
 struct Uniforms {
-    resolution: vec2<f32>,     // offset 0-7
-    time: f32,                 // offset 8
+    brightness: f32,  // offset 0
+    contrast: f32,    // offset 4
+    saturation: f32,  // offset 8
     // 4 bytes padding for vec3 alignment
-    texResolution: vec2<f32>,  // offset 16-23
-    speed: f32,                // offset 24
-    // 8 bytes padding for next vec3
 }
 
-@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;
 
@@ -118,277 +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?)
 
-创建WGSL渲染器实例。
+Create WGSL renderer instance.
 
 ```typescript
+import { createWGSLRenderer } from 'wgsl-renderer'
 const renderer = await createWGSLRenderer(canvas)
 ```
 
-### createUniforms(length)
+options:
 
-创建uniform变量，length单位为float数量。
+```ts
+interface WGSLRendererOptions { 
+    config?: GPUCanvasConfiguration;
+}
+```
 
-```typescript
-const myUniforms = renderer.createUniforms(8) // 8个float
+### 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)
+}
 ```
 
-### getContext()
+### renderer.getPassTexture(passName)
 
-获取WebGPU画布上下文。
+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
-const context = renderer.getContext()
+// 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,
+    ],
+})
 ```
 
-### getDevice()
-
-获取WebGPU设备对象。
+**Corresponding WGSL binding:**
 
-```typescript
-const device = renderer.getDevice()
+```wgsl
+@group(0) @binding(0) var myTexture: texture_2d<f32>;      // resources[0]
+@group(0) @binding(1) var mySampler: sampler;              // resources[1]
 ```
 
-### 渲染控制
 
-#### renderFrame()
-单帧渲染，不循环。
 
-```typescript
-renderer.renderFrame()
-```
+### renderer.createUniforms(length)
 
-#### loopRender(callback?)
-循环渲染，支持每帧回调，可用于时时更新uniforms。
+Create uniform variables using Float32Array, length unit is the number of floats.
 
 ```typescript
-renderer.loopRender(() => {
+const myUniforms = renderer.createUniforms(8) // 8 floats
 
-    // 每帧更新uniforms
-    myUniforms.values[0] = performance.now() / 1000.0
-    myUniforms.apply()
+// 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
 ```
 
-#### stopLoop()
-停止循环渲染。
+### renderer.getContext()
+
+Get WebGPU canvas context.
 
 ```typescript
-renderer.stopLoop()
+const context = renderer.getContext()
 ```
 
-### addPass(descriptor)
+### renderer.getDevice()
 
-添加一个渲染通道。
+Get WebGPU device object.
 
 ```typescript
-renderer.addPass({
-    name: 'my_pass',
-    shaderCode: wgslShaderCode,
-    blendMode: 'alpha',
-    resources: [textureView, sampler], // 资源数组
-})
+const device = renderer.getDevice()
 ```
 
-**资源数组绑定规则:**
+### Render Control
 
-- **Pass 1**: 无自动绑定，完全自由
-  - **Binding 0**: `resources[0]`
-  - **Binding 1**: `resources[1]`
-  - 以此类推...
+#### renderer.renderFrame()
+Single frame rendering.
 
-- **Pass 2及以上**: 自动绑定上一个pass的输出
-  - **Binding 0**: 上一个pass的输出纹理（自动）
-  - **Binding 1**: `resources[0]`
-  - **Binding 2**: `resources[1]`
-  - 以此类推...
+#### renderer.loopRender(callback?)
+Built-in loop rendering with per-frame callback for real-time uniform updates.
 
-**对应的WGSL绑定:**
-
-```wgsl
-// Pass 1:
-@group(0) @binding(0) var myTexture: texture_2d<f32>;      // resources[0]
-@group(0) @binding(1) var mySampler: sampler;              // resources[1]
+```typescript
+renderer.loopRender(time => {
 
-// Pass 2+:
-@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]
+    // Update uniforms every frame
+    myUniforms.values[2] = time * 0.001
+    myUniforms.apply()
+})
 ```
 
-### Uniform
+#### renderer.stopLoop()
+Stop loop rendering.
 
-#### 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
-```
 
-**JavaScript Uniforms设置 (注意内存对齐):**
-
-```javascript
-const uniforms = renderer.createUniforms(16) // 64字节
-uniforms.values[0] = canvas.width // resolution.x
-uniforms.values[1] = canvas.height // resolution.y
-uniforms.values[2] = performance.now() // time
-uniforms.values[3] = 0 // padding (vec3对齐)
-uniforms.values[4] = 1024 // texResolution.x
-uniforms.values[5] = 1024 // texResolution.y
-uniforms.values[6] = 1.0 // speed
-uniforms.values[7] = 0 // padding
-uniforms.values[8] = 0 // padding
-uniforms.apply()
-```
+### renderer.createSampler(options?)
 
-## 🔧 内置方法
+Create sampler with default parameters:
 
-### 纹理相关
+```ts
+const options = {
+    magFilter: 'linear',
+    minFilter: 'linear',
+    addressModeU: 'clamp-to-edge',
+    addressModeV: 'clamp-to-edge',
+}
 
-```typescript
-// 从url加载图片纹理
-const { texture, width, height } = await renderer.loadImageTexture('image.png')
+const sampler = renderer.createSampler(options)
+```
 
-// 创建采样器
-const sampler = renderer.createSampler()
+## 🎯 Pass Flow
 
-// 绑定到Pass
-const textureView = texture.createView()
-renderer.addPass({
-    name: 'texture-pass',
-    shaderCode: shaderCode,
-    resources: [
-        textureView,
-        sampler, 
-    ],
-})
-```
+The renderer provides the following management features:
 
-```wgsl
-// 如果是Pass 1:
-@group(0) @binding(0) var myTexture: texture_2d<f32>;      
-@group(0) @binding(1) var mySampler: sampler;
+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)`
 
-// 如果是Pass 2及以后:
-@group(0) @binding(0) var prevTexture: texture_2d<f32>; // 自动绑定，上一个Pass的输出纹理
-@group(0) @binding(1) var myTexture: texture_2d<f32>;
-@group(0) @binding(2) var mySampler: sampler;
-```
+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
 
-### Uniform变量
+3. **Complete Flexibility**
+   - Users decide binding order and method
+   - Support arbitrarily complex pass connections
+   - Can create circular dependencies (if needed)
 
+**Example Usage:**
 ```typescript
-// 创建uniform buffer，length单位为float数量
-const uniforms = renderer.createUniforms(8) // 8个float (32字节)
-uniforms.values[0] = 1.0 // 设置第一个float值
-uniforms.values[1] = 0.5 // 设置第二个float值
-uniforms.values[2] = 0.25 // 设置第三个float值
-// 向量值需要内存对齐，这里的offset必须是4的倍数，因此跳过uniforms.values[3]
-uniforms.values[4] = 1.0 // texResolution.x
-uniforms.values[5] = 1024.0 // texResolution.y
-
-uniforms.apply() // 应用到GPU
-const uniformBuffer = uniforms.getBuffer() // 获取GPUBuffer
-
-// 绑定到Pass
+// Method 1: Simple chain reference
 renderer.addPass({
-    name: 'uniform-pass',
-    shaderCode: shaderCode,
-    resources: [
+    name: 'background',
+    resources: [bgTexture, sampler1],
+})
 
-        // 数组第0项，Pass 1着色器中对应@group(0) @binding(0)，Pass2及以后的着色器中是@group(0) @binding(1)
-        uniformBuffer, 
-    ],
+renderer.addPass({
+    name: 'main_effect',
+    resources: [renderer.getPassTexture('background'), sampler2], // Reference background output
 })
-```
 
-```wgsl
-struct Uniforms {
-    value1: f32, // 对应 uniforms.values[0]
-    value2: f32, // 对应 uniforms.values[1]
-    value3: f32, // 对应 uniforms.values[2]
-    textureResolution: vec2<f32>, // x, y分别对应 uniforms.values[4], uniforms.values[5]
-    // ...
-}
+renderer.addPass({
+    name: 'post_process',
+    resources: [renderer.getPassTexture('main_effect'), sampler3], // Reference main_effect output
+})
 
-// 如果是Pass 1:
-@group(0) @binding(0) var<uniform> uniforms: Uniforms;
+// 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] })
 
-// 如果是Pass 2及以后:
-@group(0) @binding(0) var prevTexture: texture_2d<f32>; // 自动绑定，上一个Pass的输出纹理
-@group(0) @binding(1) var<uniform> uniforms: Uniforms;
-```
+// Create blend pass, referencing multiple different passes simultaneously
+const layer1Output = renderer.getPassTexture('layer1')
+const layer2Output = renderer.getPassTexture('layer2')
+const layer3Output = renderer.getPassTexture('layer3')
 
-### 控制相关
+renderer.addPass({
+    name: 'composite',
+    resources: [layer1Output, layer2Output, layer3Output, finalSampler],
+})
 
-```typescript
-// 调整画布大小
-renderer.resize(800, 600)
+// Method 3: Dynamic update binding
+const mainPass = renderer.getPassByName('main_effect')
+if (mainPass) {
 
-// 停止渲染
-renderer.stopLoop()
+    // Dynamically change reference relationship at runtime
+    mainPass.updateBindGroup([renderer.getPassTexture('layer1'), newSampler])
+}
 ```
 
-## 🎯 Pass流程
-
-渲染器自动管理以下pass流程：
-
-1. **User Pass 1**
-   - 无自动绑定，完全自由
-   - Binding 0+: 用户资源
-   - 输出到 `pass_0_output`
-
-2. **User Pass 2**
-   - Binding 0: Pass 1输出纹理（自动）
-   - Binding 1+: 用户资源
-   - 输出到 `pass_1_output`
-
-3. **User Pass 3+**
-   - Binding 0: 上一个pass输出纹理（自动）
-   - Binding 1+: 用户资源
-   - 输出到 `pass_N-1_output`
+**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
+})
 
-4. **Final Pass**
-   - Binding 0: 上一个pass输出纹理（自动）
-   - Binding 1+: 用户资源
-   - 渲染到canvas
+// Error message: Cannot find pass named 'nonexistent_pass'. Available passes: [background, main_effect, ...]
+```
 
-## 🛠️ 开发
+## 🛠️ Development
 
 ```bash
-# 开发模式
+# Development mode
 pnpm dev
 
-# 构建
+# Build
 pnpm build
 ```
 
-## 📝 许可证
+## 📝 License
 
 MIT License
 
-## 🤝 贡献
+## 🤝 Contributing
 
-欢迎提交Issue和Pull Request！
+Issues and Pull Requests are welcome!