{"id":47066928,"url":"https://github.com/jeantimex/webgpu-water","last_synced_at":"2026-03-12T05:06:17.944Z","repository":{"id":333429685,"uuid":"1136711986","full_name":"jeantimex/webgpu-water","owner":"jeantimex","description":"A real-time water simulation using WebGPU","archived":false,"fork":false,"pushed_at":"2026-02-08T07:14:33.000Z","size":700,"stargazers_count":146,"open_issues_count":1,"forks_count":12,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-08T14:30:46.248Z","etag":null,"topics":["fluid-simulation","water-simulation","webgpu"],"latest_commit_sha":null,"homepage":"https://jeantimex.github.io/webgpu-water/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeantimex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T07:45:48.000Z","updated_at":"2026-02-08T07:14:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jeantimex/webgpu-water","commit_stats":null,"previous_names":["jeantimex/webgpu-water"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jeantimex/webgpu-water","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeantimex%2Fwebgpu-water","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeantimex%2Fwebgpu-water/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeantimex%2Fwebgpu-water/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeantimex%2Fwebgpu-water/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeantimex","download_url":"https://codeload.github.com/jeantimex/webgpu-water/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeantimex%2Fwebgpu-water/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30416310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T04:41:02.746Z","status":"ssl_error","status_checked_at":"2026-03-12T04:40:12.571Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fluid-simulation","water-simulation","webgpu"],"created_at":"2026-03-12T05:06:17.413Z","updated_at":"2026-03-12T05:06:17.937Z","avatar_url":"https://github.com/jeantimex.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebGPU Water Simulation\n\nA real-time water simulation using WebGPU, ported from [Evan Wallace's WebGL Water](https://madebyevan.com/webgl-water/).\n\nhttps://github.com/user-attachments/assets/10f27799-944a-47e1-81dd-cb84540dd842\n\n[Live demo](https://jeantimex.github.io/webgpu-water/)\n\n## Overview\n\nThis project is a WebGPU port of the classic WebGL water demonstration originally created by Evan Wallace. It showcases advanced real-time graphics techniques including raytraced reflections, refractions, caustics, and physically-based water simulation, all running in the browser using the modern WebGPU API.\n\n## Features\n\n- **Heightfield Water Simulation** - GPU-accelerated wave propagation using finite difference methods on a 256×256 grid\n- **Raytraced Reflections \u0026 Refractions** - Accurate light behavior at the water surface using Snell's law\n- **Real-time Caustics** - Dynamic light patterns projected onto the pool floor (1024×1024 resolution)\n- **Fresnel Effect** - Realistic blending between reflection and refraction based on viewing angle\n- **Analytic Ambient Occlusion** - Soft shadowing for the pool walls and sphere\n- **Interactive Sphere** - Physically simulated object with buoyancy and water displacement\n- **Cubemap Skybox** - Environmental reflections for realistic scene rendering\n\n## Controls\n\n| Action               | Control                     |\n| -------------------- | --------------------------- |\n| Draw ripples         | Click/drag on water surface |\n| Rotate camera        | Click/drag on empty space   |\n| Move sphere          | Click/drag on the sphere    |\n| Toggle gravity       | Press `G`                   |\n| Pause/Resume         | Press `Spacebar`            |\n| Link light to camera | Hold `L`                    |\n\n## Technical Implementation\n\n### Water Physics\n\nThe water simulation uses a heightfield approach where each pixel in a 256×256 texture stores:\n\n- **Red channel**: Water height\n- **Green channel**: Vertical velocity\n- **Blue/Alpha channels**: Surface normal (compressed)\n\nThe wave equation is discretized using finite differences:\n\n```\nvelocity += (neighbor_average - height) * 2.0\nvelocity *= 0.995  // damping\nheight += velocity\n```\n\nThe simulation runs two steps per frame for stability, using ping-pong textures to avoid read-after-write conflicts.\n\n### Rendering Pipeline\n\n1. **Simulation Pass** - Update water heights and velocities\n2. **Normal Pass** - Compute surface normals from the heightfield\n3. **Caustics Pass** - Project refracted light onto pool surfaces\n4. **Scene Pass** - Render pool, sphere, and water surface with full lighting\n\n### Caustics Generation\n\nCaustics are computed by:\n\n1. Refracting light rays through the water surface\n2. Projecting rays onto the pool floor\n3. Computing intensity based on area compression (using `dpdx`/`dpdy` derivatives)\n4. Accumulating results with additive blending\n\n## Challenges Porting from WebGL to WebGPU\n\nPorting from WebGL to WebGPU involved several significant challenges:\n\n### 1. Shader Language Translation (GLSL → WGSL)\n\nWebGPU uses WGSL (WebGPU Shading Language) instead of GLSL. This required:\n\n- Rewriting all shaders with different syntax (`vec3` → `vec3f`, `texture2D` → `textureSample`)\n- Adapting to WGSL's stricter type system and explicit type conversions\n- Handling different function signatures (e.g., `refract`, `reflect`, `normalize`)\n- Using `textureSampleLevel` in vertex shaders since automatic LOD selection isn't available\n\n### 2. Explicit Resource Binding\n\nUnlike WebGL's implicit uniform binding, WebGPU requires explicit bind group layouts:\n\n- All resources must be declared with `@group` and `@binding` attributes\n- Bind group layouts must be created and managed manually\n- Samplers and textures are separate bindings (not combined like GLSL's `sampler2D`)\n\n### 3. Coordinate System Differences\n\nWebGPU has different coordinate conventions:\n\n- **Clip space Y**: WebGPU is Y-up (1 at top), requiring flips in certain projections\n- **Texture coordinates**: Origin is top-left in WebGPU vs bottom-left in WebGL\n- **Depth range**: WebGPU uses [0, 1] instead of WebGL's [-1, 1]\n\n### 4. Render Target Management\n\nWebGPU requires explicit texture management:\n\n- Render attachments must specify `loadOp` and `storeOp`\n- No implicit default framebuffer—must get texture view from canvas context each frame\n- Depth textures must be explicitly created and managed on resize\n\n### 5. Pipeline State Objects\n\nWebGPU uses immutable pipeline state objects instead of WebGL's mutable state machine:\n\n- All render state (blending, culling, depth test) must be declared upfront\n- Separate pipelines needed for above-water and underwater rendering (different cull modes)\n- Pipeline creation is more verbose but enables better GPU optimization\n\n### 6. Float Texture Support\n\nWebGL's `OES_texture_float` extension maps differently to WebGPU:\n\n- Must check for `float32-filterable` feature at adapter request time\n- Falls back to `rgba16float` if full float filtering isn't available\n- Explicit feature request required in device creation\n\n### 7. Extension Equivalents\n\nWebGL extensions required for the original demo have different WebGPU equivalents:\n\n- `OES_texture_float` → `float32-filterable` feature\n- `OES_standard_derivatives` → Built-in `dpdx`/`dpdy` functions in WGSL\n- No explicit extension loading needed—features are part of the core spec or optional features\n\n### 8. Command Encoding Pattern\n\nWebGPU uses a command buffer pattern instead of immediate mode:\n\n- Commands are recorded into encoders, then submitted as batches\n- Better maps to modern GPU architectures but requires different code structure\n- Enables better CPU/GPU parallelism\n\n### 9. No Global State\n\nWebGPU has no concept of a \"current\" bound texture or buffer:\n\n- All resources must be explicitly specified in bind groups\n- Bind groups are set per-draw call\n- More explicit but eliminates subtle state-related bugs\n\n## Dependencies\n\n- [wgpu-matrix](https://github.com/greggman/wgpu-matrix) - Matrix math library for WebGPU\n- [Vite](https://vitejs.dev/) - Build tool and development server\n\n## Credits\n\n- **Original WebGL Implementation**: [Evan Wallace](https://madebyevan.com/)\n- **WebGPU Port**: [jeantimex](https://github.com/jeantimex)\n\n## References\n\n- [Original WebGL Water Demo](https://madebyevan.com/webgl-water/)\n- [Rendering Water Caustics](https://medium.com/@evanwallace/rendering-water-caustics-a3a7aae5b247) - Evan Wallace's article on caustics\n- [WebGPU Specification](https://www.w3.org/TR/webgpu/)\n- [WGSL Specification](https://www.w3.org/TR/WGSL/)\n\n## License\n\nThis project is open source. The original WebGL water simulation was created by Evan Wallace.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeantimex%2Fwebgpu-water","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeantimex%2Fwebgpu-water","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeantimex%2Fwebgpu-water/lists"}