From c021bc7bda3acc188b0b135ec21bce99c1273644 Mon Sep 17 00:00:00 2001 From: Andrey Kolkov Date: Sat, 7 Nov 2026 22:18:05 +0300 Subject: [PATCH 1/2] docs(readme): claims that match the code, and an acknowledgment of gfx-rs/wgpu Every claim was checked against the code, the tests and CI: - ErrMapCanceled is the error's name (was ErrMapCancelled). - Vulkan on macOS is not run in CI (no MoltenVK on the runner): Untested. Metal runs on the macOS runner's virtual GPU. - The software rasterizer lists what the draw path does. The tile-based parallel rasterizer is used only by tests and benchmarks, clip-space clipping is not done yet, and the known gaps are named. - The -tags rust build is not usable for real rendering with go-webgpu/webgpu v0.5.5 (0.34.6 known issue). - No 'first' claims, no 'full' or 'battle-tested' without evidence; StagingBelt no longer claims zero allocation (no benchmark backs it). - An Acknowledgments section thanks the authors of gfx-rs/wgpu, whose architecture wgpu follows. --- README.md | 46 ++++++++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 53715aa2..f5e105e0 100644 --- a/README.md +++ b/README.md @@ -32,10 +32,10 @@ |----------|--------------| | **Backends** | Vulkan, Metal, DirectX 12, OpenGL ES, Software, **Browser WebGPU**, **Rust FFI** | | **Platforms** | Windows, Linux, macOS, **Browser (WASM)**, **Android/arm64 (preview)**; iOS untested | -| **API** | WebGPU-compliant (W3C specification) | +| **API** | Follows the W3C WebGPU specification | | **Shaders** | WGSL via gogpu/naga compiler (SPIR-V, HLSL, MSL, GLSL, DXIL) | -| **Compute** | Full compute shader support, GPU→CPU readback | -| **Present** | Damage-aware presentation — compositor dirty rects (first WebGPU implementation) | +| **Compute** | Compute shaders and GPU→CPU readback on every native backend (software: see its known gaps below) | +| **Present** | Damage-aware presentation — compositor dirty rects | | **Ray Tracing** | Not usable yet: HAL code only, no public API, not run on a GPU. Public inline ray queries are planned, Vulkan first ([status](docs/RAY-TRACING.md), [#369](https://github.com/gogpu/wgpu/issues/369)) | | **Debug** | Leak detection, error scopes (native backends; not yet in the browser backend), validation layers, DRED diagnostics (DX12), structured logging (`log/slog`) | | **Build** | Zero CGO, simple `go build` | @@ -64,12 +64,13 @@ New surface integrations should use the explicit safe or unsafe target API described in [Surface targets](docs/SURFACE-TARGETS.md). The original two-`uintptr` method remains available as a compatibility adapter. -**Rust FFI backend** (optional, battle-tested wgpu-native drivers): +**Rust FFI backend** (optional, through wgpu-native): ```bash go build -tags rust ``` > Requires [wgpu-native](https://github.com/gfx-rs/wgpu-native/releases) v29 binary. Set `WGPU_NATIVE_PATH` or place in system PATH. See [go-webgpu/webgpu](https://github.com/go-webgpu/webgpu) for details. +> With go-webgpu/webgpu v0.5.5 this build is not usable for real rendering yet (vertex buffers and depth attachments fail; see the 0.34.6 known issues in [CHANGELOG.md](CHANGELOG.md)). **Browser (WASM):** ```bash @@ -80,7 +81,7 @@ GOOS=js GOARCH=wasm go build -o app.wasm . > | Build Tag | Implementation | Use Case | > |-----------|---------------|----------| > | (default) | Pure Go → core → HAL → Vulkan/Metal/DX12/GLES/Software | Zero deps, cross-compile | -> | `-tags rust` | go-webgpu/webgpu → wgpu-native v29 | Battle-tested GPU drivers | +> | `-tags rust` | go-webgpu/webgpu → wgpu-native v29 | wgpu-native's backends | > | `GOOS=js` | syscall/js → Browser WebGPU | Web applications | > > **API consistency:** The public API compiles on all build targets. HAL wrapper functions (`NewDeviceFromHAL`, `NewSurfaceFromHAL`, etc.) return errors or nil on Rust/Browser builds where no Go HAL layer exists. Use `RequestAdapter` → `RequestDevice` for the standard cross-backend path. @@ -201,7 +202,7 @@ if ready, _ := pending.Status(); ready { ``` Safety guarantees: UAF protection via generation counters on `MappedRange`, -`ErrBufferDestroyed` on destroy-during-pending, `ErrMapCancelled` on unmap-during-pending, +`ErrBufferDestroyed` on destroy-during-pending, `ErrMapCanceled` on unmap-during-pending, `ErrMapRangeOverlap` for overlapping `MappedRange` calls, `MAP_ALIGNMENT = 8` validation, thread-safe concurrent `Device.Poll`. @@ -272,8 +273,8 @@ import _ "github.com/gogpu/wgpu/hal/allbackends" | Backend | Windows | Linux | macOS | iOS | Android/arm64 | Notes | |---------|:-------:|:-----:|:-----:|:---:|:-------------:|-------| -| **Vulkan** | Yes | Yes | Yes | - | Preview | MoltenVK on macOS; [Android contract](docs/ANDROID.md) | -| **Metal** | - | - | Yes | Untested | - | Native Apple GPU; never run on iOS | +| **Vulkan** | Yes | Yes | Untested | - | Preview | macOS through MoltenVK, not run in CI; [Android contract](docs/ANDROID.md) | +| **Metal** | - | - | Yes | Untested | - | Native Apple GPU; CI runs it on the macOS runner's virtual GPU; never run on iOS | | **DX12** | Yes | - | - | - | - | Windows 10+ | | **GLES** | Yes | Yes | - | - | - | OpenGL 3.3+ / OpenGL ES 3.0+ | | **Software** | Yes | Yes | Yes | Untested | - | CPU fallback | @@ -315,15 +316,15 @@ Windows GPU access via: - Encoder pool with allocator recycling (Rust wgpu-core pattern) - In-memory shader cache (SHA-256 keyed, LRU eviction, works for both paths) - DRED diagnostics (auto-breadcrumbs + page fault tracking on TDR) -- **Dual shader compilation:** HLSL→FXC (default, SM 5.1) or **DXIL direct** via naga (`GOGPU_DX12_DXIL=1`, SM 6.0+, zero external dependencies — first Pure Go DXIL generator) -- StagingBelt ring-buffer allocator for zero-allocation GPU data transfer +- **Dual shader compilation:** HLSL→FXC (default, SM 5.1) or **DXIL direct** via naga (`GOGPU_DX12_DXIL=1`, experimental, SM 6.0+, no external compiler) +- StagingBelt ring-buffer allocator that reuses staging memory for uploads ### OpenGL ES Backend Cross-platform GPU access via OpenGL ES 3.0+: - Pure Go EGL/GL bindings (goffi) -- Full rendering pipeline: VAO, FBO, MSAA, blend, stencil, depth +- Rendering pipeline: VAO, FBO, MSAA, blend, stencil, depth - WGSL shader compilation (WGSL → GLSL via naga) - Combined texture-sampler binding via SamplerBindMap (Rust wgpu pattern) - Text rendering with proper texture completeness handling @@ -333,7 +334,7 @@ Cross-platform GPU access via OpenGL ES 3.0+: ### Software Backend -Full-featured CPU rasterizer for headless and windowed rendering. Always compiled — no build tags or GPU hardware required. +CPU rasterizer for headless and windowed rendering. Always compiled — no build tags or GPU hardware required. ```go // Software backend auto-registers via init(). @@ -344,21 +345,21 @@ import _ "github.com/gogpu/wgpu/hal/software" // Use cases: // - CI/CD testing without GPU // - Server-side image generation -// - Reference implementation // - Fallback when GPU unavailable // - Embedded systems without GPU ``` **Rasterization Features:** -- Edge function triangle rasterization (Pineda algorithm) -- Perspective-correct interpolation -- Depth buffer (8 compare functions) -- Stencil buffer (8 operations) -- Blending (13 factors, 5 operations) -- 6-plane frustum clipping (Sutherland-Hodgman) -- 8x8 tile-based parallel rendering +- Edge function triangle rasterization (Pineda algorithm) with the top-left fill rule +- Depth test (all 8 compare functions) +- Stencil test (all 8 operations) +- Blending (13 factors without dual-source, 5 operations) - **SPIR-V interpreter** — executes vertex/fragment/compute shaders on CPU. Designed for shader debugging, CI/CD testing, and GPU-less environments — **not for production rendering** (interpreted, much slower than JIT software renderers such as SwiftShader). +**Known gaps** (being fixed): primitives are not clipped in clip space yet; shader derivatives return 0, so +implicit-LOD sampling uses mip level 0; compute `var` memory is not shared between invocations; encoded +commands run when they are recorded, not at `Queue.Submit`; compressed texture formats cannot be sampled. + **Debug & Testing:** - Render pass instrumentation: `hal.Logger().Debug()` events + `RenderPassStats` for CI e2e assertions - Public `wgpu.HeadlessSurfaceTarget` + `Surface.ReadPixels()` lifecycle for deterministic headless render verification; snapshots are owned, tightly packed RGBA8 @@ -452,6 +453,11 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +## Acknowledgments + +The architecture follows [gfx-rs/wgpu](https://github.com/gfx-rs/wgpu), the Rust WebGPU implementation: +wgpu-core, wgpu-hal and wgpu-types. Thanks to its authors and contributors for the design we build on. + ## License MIT License — see [LICENSE](LICENSE) for details. From 7648bee9ce889b52410f0428db7f15428357374a Mon Sep 17 00:00:00 2001 From: Andrey Kolkov Date: Sat, 7 Nov 2026 22:20:23 +0300 Subject: [PATCH 2/2] docs(readme): software has shared workgroup memory; -tags rust status from webgpu v0.34.8 shipped shared workgroup memory and real barriers on software (P1-SW-025), so it is no longer a known gap. The -tags rust note now says what go-webgpu/webgpu v0.5.5 does on each platform, as its maintainers describe it: an abort at adapter request on Linux amd64 and Intel macOS, and vertex buffer, depth attachment and bind group layout failures on Windows. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f5e105e0..4aece0a6 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ go build -tags rust ``` > Requires [wgpu-native](https://github.com/gfx-rs/wgpu-native/releases) v29 binary. Set `WGPU_NATIVE_PATH` or place in system PATH. See [go-webgpu/webgpu](https://github.com/go-webgpu/webgpu) for details. -> With go-webgpu/webgpu v0.5.5 this build is not usable for real rendering yet (vertex buffers and depth attachments fail; see the 0.34.6 known issues in [CHANGELOG.md](CHANGELOG.md)). +> With go-webgpu/webgpu v0.5.5, `-tags rust` is not usable for real rendering: on Linux amd64 and Intel macOS it aborts at adapter request, and on Windows vertex buffers, depth attachments and explicit bind group layouts abort or crash (see the 0.34.6 known issues in [CHANGELOG.md](CHANGELOG.md)). These are fixed in go-webgpu/webgpu's next release. **Browser (WASM):** ```bash @@ -357,8 +357,8 @@ import _ "github.com/gogpu/wgpu/hal/software" - **SPIR-V interpreter** — executes vertex/fragment/compute shaders on CPU. Designed for shader debugging, CI/CD testing, and GPU-less environments — **not for production rendering** (interpreted, much slower than JIT software renderers such as SwiftShader). **Known gaps** (being fixed): primitives are not clipped in clip space yet; shader derivatives return 0, so -implicit-LOD sampling uses mip level 0; compute `var` memory is not shared between invocations; encoded -commands run when they are recorded, not at `Queue.Submit`; compressed texture formats cannot be sampled. +implicit-LOD sampling uses mip level 0; encoded commands run when they are recorded, not at `Queue.Submit`; +compressed texture formats cannot be sampled. **Debug & Testing:** - Render pass instrumentation: `hal.Logger().Debug()` events + `RenderPassStats` for CI e2e assertions