{"id":34634488,"url":"https://github.com/gogpu/wgpu","last_synced_at":"2026-05-26T23:13:29.207Z","repository":{"id":328069245,"uuid":"1110695653","full_name":"gogpu/wgpu","owner":"gogpu","description":"Pure Go WebGPU Implementation","archived":false,"fork":false,"pushed_at":"2026-04-21T06:08:09.000Z","size":2188,"stargazers_count":80,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-21T08:03:07.978Z","etag":null,"topics":["directx12","go","golang","gpu","graphics","metal","pure-go","vulkan","webgpu"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/gogpu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-05T15:25:10.000Z","updated_at":"2026-04-21T06:01:38.000Z","dependencies_parsed_at":"2026-02-21T13:08:42.292Z","dependency_job_id":null,"html_url":"https://github.com/gogpu/wgpu","commit_stats":null,"previous_names":["gogpu/wgpu"],"tags_count":95,"template":false,"template_full_name":null,"purl":"pkg:github/gogpu/wgpu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fwgpu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fwgpu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fwgpu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fwgpu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gogpu","download_url":"https://codeload.github.com/gogpu/wgpu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gogpu%2Fwgpu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32200159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T20:19:26.138Z","status":"ssl_error","status_checked_at":"2026-04-23T20:19:23.520Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["directx12","go","golang","gpu","graphics","metal","pure-go","vulkan","webgpu"],"created_at":"2025-12-24T16:59:39.289Z","updated_at":"2026-05-26T23:13:29.197Z","avatar_url":"https://github.com/gogpu.png","language":"Go","funding_links":[],"categories":["Game Development"],"sub_categories":["Search and Analytic Databases"],"readme":"\u003ch1 align=\"center\"\u003ewgpu\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePure Go WebGPU Implementation\u003c/strong\u003e\u003cbr\u003e\n  No Rust. No CGO. Just Go.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/gogpu/wgpu/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/gogpu/wgpu/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/gogpu/wgpu\"\u003e\u003cimg src=\"https://codecov.io/gh/gogpu/wgpu/branch/main/graph/badge.svg\" alt=\"codecov\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/gogpu/wgpu\"\u003e\u003cimg src=\"https://pkg.go.dev/badge/github.com/gogpu/wgpu.svg\" alt=\"Go Reference\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/gogpu/wgpu\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/gogpu/wgpu\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/gogpu/wgpu/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/gogpu/wgpu\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/gogpu/wgpu\"\u003e\u003cimg src=\"https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go\" alt=\"Go Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/gogpu/wgpu\"\u003e\u003cimg src=\"https://img.shields.io/badge/CGO-none-success\" alt=\"Zero CGO\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003ePart of the \u003ca href=\"https://github.com/gogpu\"\u003eGoGPU\u003c/a\u003e ecosystem\u003c/sub\u003e\n\u003c/p\u003e\n\n---\n\n## Overview\n\n**wgpu** is a complete WebGPU implementation written entirely in Go. It provides direct GPU access through multiple hardware abstraction layer (HAL) backends without requiring Rust, CGO, or any external dependencies.\n\n### Key Features\n\n| Category | Capabilities |\n|----------|--------------|\n| **Backends** | Vulkan, Metal, DirectX 12, OpenGL ES, Software, **Browser WebGPU** |\n| **Platforms** | Windows, Linux, macOS, iOS, **Browser (WASM)** |\n| **API** | WebGPU-compliant (W3C specification) |\n| **Shaders** | WGSL via gogpu/naga compiler (SPIR-V, HLSL, MSL, GLSL, DXIL) |\n| **Compute** | Full compute shader support, GPU→CPU readback |\n| **Present** | Damage-aware presentation — compositor dirty rects (first WebGPU implementation) |\n| **Debug** | Leak detection, error scopes, validation layers, DRED diagnostics (DX12), structured logging (`log/slog`) |\n| **Build** | Zero CGO, simple `go build` |\n\n---\n\n## Installation\n\n```bash\ngo get github.com/gogpu/wgpu\n```\n\n**Requirements:** Go 1.25+\n\n**Build:**\n```bash\nCGO_ENABLED=0 go build\n```\n\n\u003e **Note:** wgpu uses Pure Go FFI via [goffi](https://github.com/go-webgpu/goffi). Both `CGO_ENABLED=0` (default, zero C compiler dependency) and `CGO_ENABLED=1` (for race detector or coexistence with CGO libraries) are supported.\n\n**Browser (WASM):**\n```bash\nGOOS=js GOARCH=wasm go build -o app.wasm .\n```\n\n\u003e Browser backend uses `syscall/js` → `navigator.gpu` directly, bypassing core/hal. Same public API, same user code — just a different build target. Zero external dependencies.\n\n---\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n\n    \"github.com/gogpu/wgpu\"\n    _ \"github.com/gogpu/wgpu/hal/allbackends\" // Auto-register platform backends\n)\n\nfunc main() {\n    // Create instance\n    instance, _ := wgpu.CreateInstance(nil)\n    defer instance.Release()\n\n    // Request high-performance GPU\n    adapter, _ := instance.RequestAdapter(\u0026wgpu.RequestAdapterOptions{\n        PowerPreference: wgpu.PowerPreferenceHighPerformance,\n    })\n    defer adapter.Release()\n\n    // Get adapter info\n    info := adapter.Info()\n    fmt.Printf(\"GPU: %s (%s)\\n\", info.Name, info.Backend)\n\n    // Create device\n    device, _ := adapter.RequestDevice(nil)\n    defer device.Release()\n\n    // Create a GPU buffer\n    buffer, _ := device.CreateBuffer(\u0026wgpu.BufferDescriptor{\n        Label: \"My Buffer\",\n        Size:  1024,\n        Usage: wgpu.BufferUsageStorage | wgpu.BufferUsageCopyDst,\n    })\n    defer buffer.Release()\n\n    // Write data to buffer\n    if err := device.Queue().WriteBuffer(buffer, 0, []byte{1, 2, 3, 4}); err != nil {\n        panic(err)\n    }\n}\n```\n\n### Compute Shaders\n\n```go\n// Create shader module from WGSL\nshader, _ := device.CreateShaderModule(\u0026wgpu.ShaderModuleDescriptor{\n    Label: \"Compute Shader\",\n    WGSL:  wgslSource,\n})\ndefer shader.Release()\n\n// Create compute pipeline\npipeline, _ := device.CreateComputePipeline(\u0026wgpu.ComputePipelineDescriptor{\n    Label:      \"Compute Pipeline\",\n    Layout:     pipelineLayout,\n    Module:     shader,\n    EntryPoint: \"main\",\n})\ndefer pipeline.Release()\n\n// Record and submit commands\nencoder, _ := device.CreateCommandEncoder(nil)\npass, _ := encoder.BeginComputePass(nil)\npass.SetPipeline(pipeline)\npass.SetBindGroup(0, bindGroup, nil)\npass.Dispatch(64, 1, 1)\npass.End()\n\ncmdBuffer, _ := encoder.Finish()\n_, _ = device.Queue().Submit(cmdBuffer)  // returns (submissionIndex, error)\n```\n\n### Buffer Mapping (GPU → CPU readback)\n\nWebGPU-spec-compliant dual-layer API. Primary path is blocking + `context.Context`\n(idiomatic Go, zero allocation); escape hatch `MapAsync` + `Device.Poll` is for\ngame loops that cannot afford to block.\n\n```go\n// Primary: blocking, idiomatic, zero-alloc.\n// Map blocks until the GPU finishes writing the buffer (or ctx cancels).\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\ndefer cancel()\n\nif err := stagingBuf.Map(ctx, wgpu.MapModeRead, 0, size); err != nil {\n    log.Fatal(err)\n}\ndefer stagingBuf.Unmap()\n\nrng, _ := stagingBuf.MappedRange(0, size)\ndata := rng.Bytes()  // []byte view, zero copy, valid until Unmap\nprocess(data)\n```\n\n```go\n// Escape hatch: async, non-blocking, for render loops.\npending, _ := stagingBuf.MapAsync(wgpu.MapModeRead, 0, size)\n\n// Continue rendering; auto-polled on next Queue.Submit.\nrenderFrame()\n\nif ready, _ := pending.Status(); ready {\n    rng, _ := stagingBuf.MappedRange(0, size)\n    process(rng.Bytes())\n    stagingBuf.Unmap()\n}\n```\n\nSafety guarantees: UAF protection via generation counters on `MappedRange`,\n`ErrBufferDestroyed` on destroy-during-pending, `ErrMapCancelled` on unmap-during-pending,\n`ErrMapRangeOverlap` for overlapping `MappedRange` calls, `MAP_ALIGNMENT = 8`\nvalidation, thread-safe concurrent `Device.Poll`.\n\nSee [ADR-BUFFER-MAPPING-API](docs/dev/research/ADR-BUFFER-MAPPING-API.md) for the\nfull design rationale and comparison with Rust wgpu.\n\n**Guides:** [Getting Started](docs/COMPUTE-SHADERS.md) | [Backend Differences](docs/COMPUTE-BACKENDS.md)\n\nFeatures: WGSL compute shaders, storage/uniform buffers, indirect dispatch, GPU timestamp queries (Vulkan, DX12), WebGPU-compliant `Buffer.Map` / `MapAsync` GPU→CPU readback with `context.Context` integration.\n\n---\n\n## Architecture\n\n```\nwgpu/\n├── *.go                # Public API (import \"github.com/gogpu/wgpu\")\n├── core/               # Validation, state tracking, deferred resource destruction\n├── hal/                # Hardware Abstraction Layer\n│   ├── allbackends/    # Platform-specific backend auto-registration\n│   ├── noop/           # No-op backend (testing)\n│   ├── software/       # CPU software rasterizer (~14K LOC)\n│   ├── gles/           # OpenGL ES 3.0+ (~12K LOC)\n│   ├── vulkan/         # Vulkan 1.3 (~42K LOC)\n│   ├── metal/          # Metal (~7K LOC)\n│   └── dx12/           # DirectX 12 (~17K LOC)\n├── examples/\n│   ├── compute-copy/   # GPU buffer copy with compute shader\n│   └── compute-sum/    # Parallel reduction on GPU\n└── cmd/\n    ├── vk-gen/         # Vulkan bindings generator\n    └── ...             # Backend integration tests\n```\n\n### Public API\n\nThe root package (`import \"github.com/gogpu/wgpu\"`) provides a safe, ergonomic API aligned with the W3C WebGPU specification. It wraps `core/` and `hal/` into user-friendly types:\n\n```\nUser Application\n  ↓ import \"github.com/gogpu/wgpu\"\nRoot Package (public API)\n  ↓ wraps\ncore/ (validation) + hal/ (backend interfaces)\n  ↓\nvulkan/ | metal/ | dx12/ | gles/ | software/\n```\n\n### HAL Backend Integration\n\nBackends auto-register via blank imports:\n\n```go\nimport _ \"github.com/gogpu/wgpu/hal/allbackends\"\n\n// Platform-specific backends auto-registered:\n// - Windows: Vulkan, DX12, GLES, Software\n// - Linux:   Vulkan, GLES, Software\n// - macOS:   Metal, Software\n```\n\n---\n\n## Backend Details\n\n### Platform Support\n\n| Backend | Windows | Linux | macOS | iOS | Notes |\n|---------|:-------:|:-----:|:-----:|:---:|-------|\n| **Vulkan** | Yes | Yes | Yes | - | MoltenVK on macOS |\n| **Metal** | - | - | Yes | Yes | Native Apple GPU |\n| **DX12** | Yes | - | - | - | Windows 10+ |\n| **GLES** | Yes | Yes | - | - | OpenGL ES 3.0+ |\n| **Software** | Yes | Yes | Yes | Yes | CPU fallback |\n\n**Architectures:** amd64, arm64 (including Windows ARM64 / Snapdragon X)\n\n### Vulkan Backend\n\nFull Vulkan 1.3 implementation with:\n\n- Auto-generated bindings from official `vk.xml`\n- Buddy allocator for GPU memory (O(log n), minimal fragmentation)\n- Dynamic rendering (VK_KHR_dynamic_rendering)\n- Classic render pass fallback for Intel compatibility\n- wgpu-style swapchain synchronization\n- MSAA render pass with automatic resolve\n- Complete resource management (Buffer, Texture, Pipeline, BindGroup)\n- Surface creation: Win32, X11, Wayland, Metal (MoltenVK)\n- Debug messenger for validation layer error capture (`VK_EXT_debug_utils`)\n- Structured diagnostic logging via `log/slog`\n\n### Metal Backend\n\nNative Apple GPU access via:\n\n- Pure Go Objective-C bridge (goffi)\n- Metal API via runtime message dispatch\n- CAMetalLayer integration for surface presentation\n- MSL shader compilation via naga\n\n### DirectX 12 Backend\n\nWindows GPU access via:\n\n- Pure Go COM bindings (syscall, no CGO)\n- DXGI integration for swapchain and adapters\n- Flip model with VRR support\n- Descriptor heap management with fence-based deferred destruction\n- Encoder pool with allocator recycling (Rust wgpu-core pattern)\n- In-memory shader cache (SHA-256 keyed, LRU eviction, works for both paths)\n- DRED diagnostics (auto-breadcrumbs + page fault tracking on TDR)\n- **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)\n- StagingBelt ring-buffer allocator for zero-allocation GPU data transfer\n\n### OpenGL ES Backend\n\nCross-platform GPU access via OpenGL ES 3.0+:\n\n- Pure Go EGL/GL bindings (goffi)\n- Full rendering pipeline: VAO, FBO, MSAA, blend, stencil, depth\n- WGSL shader compilation (WGSL → GLSL via naga)\n- Combined texture-sampler binding via SamplerBindMap (Rust wgpu pattern)\n- Text rendering with proper texture completeness handling\n- CopyTextureToBuffer readback for GPU → CPU data transfer\n- Platform detection: X11, Wayland, Surfaceless (headless CI)\n- Works with Mesa llvmpipe for software-only environments\n\n### Software Backend\n\nFull-featured CPU rasterizer for headless and windowed rendering. Always compiled — no build tags or GPU hardware required.\n\n```go\n// Software backend auto-registers via init().\n// No explicit import needed when using hal/allbackends.\n// For standalone usage:\nimport _ \"github.com/gogpu/wgpu/hal/software\"\n\n// Use cases:\n// - CI/CD testing without GPU\n// - Server-side image generation\n// - Reference implementation\n// - Fallback when GPU unavailable\n// - Embedded systems without GPU\n```\n\n**Rasterization Features:**\n- Edge function triangle rasterization (Pineda algorithm)\n- Perspective-correct interpolation\n- Depth buffer (8 compare functions)\n- Stencil buffer (8 operations)\n- Blending (13 factors, 5 operations)\n- 6-plane frustum clipping (Sutherland-Hodgman)\n- 8x8 tile-based parallel rendering\n- **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, ~100× slower than JIT software renderers like SwiftShader). See [ADR](docs/dev/research/ADR-SPIRV-JIT-VS-INTERPRETER.md).\n\n**Debug \u0026 Testing:**\n- Render pass instrumentation: `hal.Logger().Debug()` events + `RenderPassStats` for CI e2e assertions\n- `GetFramebuffer()` pixel readback for headless test verification\n- Damage-aware partial blit with pixel-level test coverage\n\n**Windowed Presentation:**\n- **Windows:** DWM-safe `CreateDIBSection` + `BitBlt` (SDL3/Qt6 pattern), zero-copy into GDI bitmap\n- **Linux X11:** `XPutImage` via goffi (Skia pattern), BGRA = X11 ZPixmap native format\n- **macOS:** CGImage + `setContents:` (CALayer) or Metal `nextDrawable` + `replaceRegion` (CAMetalLayer). Contributor: @k-chimi\n\n---\n\n## Environment Variables\n\n| Variable | Values | Description |\n|----------|--------|-------------|\n| `GOGPU_DX12_DXIL` | `1` | Enable DXIL direct compilation on DX12 (experimental). Bypasses HLSL→FXC, generates DXIL bytecode directly from naga IR. SM 6.0+, zero external dependencies. Default: off (uses HLSL→FXC). |\n| `GOGPU_DX12_DXIL_OVERRIDE_VS` | file path | Replace vertex shader DXIL with contents of the given file. For debugging only. |\n| `GOGPU_DX12_DXIL_OVERRIDE_PS` | file path | Replace pixel shader DXIL with contents of the given file. For debugging only. |\n\n\u003e **Note:** Backend selection (`GOGPU_GRAPHICS_API`) is handled by `gogpu` (the app framework), not by `wgpu` directly. See [gogpu documentation](https://github.com/gogpu/gogpu) for `GOGPU_GRAPHICS_API=vulkan|dx12|metal|gles|software`.\n\n---\n\n## Ecosystem\n\n**wgpu** is the foundation of the [GoGPU](https://github.com/gogpu) ecosystem.\n\n| Project | Description |\n|---------|-------------|\n| [gogpu/gogpu](https://github.com/gogpu/gogpu) | GPU framework with windowing and input |\n| **gogpu/wgpu** | **Pure Go WebGPU (this repo)** |\n| [gogpu/naga](https://github.com/gogpu/naga) | Shader compiler (WGSL to SPIR-V, HLSL, MSL, GLSL, DXIL) |\n| [gogpu/gg](https://github.com/gogpu/gg) | 2D graphics library with GPU SDF acceleration |\n| [gogpu/ui](https://github.com/gogpu/ui) | GUI toolkit: 22+ widgets, 4 themes |\n| [gogpu/gputypes](https://github.com/gogpu/gputypes) | Shared WebGPU type definitions |\n| [go-webgpu/goffi](https://github.com/go-webgpu/goffi) | Pure Go FFI library |\n\n---\n\n## Documentation\n\n- **[Compute Shaders Guide](docs/COMPUTE-SHADERS.md)** — Getting started with compute\n- **[Compute Backend Differences](docs/COMPUTE-BACKENDS.md)** — Per-backend capabilities\n- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** — System architecture\n- **[ROADMAP.md](ROADMAP.md)** — Development milestones\n- **[CHANGELOG.md](CHANGELOG.md)** — Release notes\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** — Contribution guidelines\n- **[pkg.go.dev](https://pkg.go.dev/github.com/gogpu/wgpu)** — API reference\n\n---\n\n## References\n\n- [WebGPU Specification](https://www.w3.org/TR/webgpu/) — W3C standard\n- [wgpu (Rust)](https://github.com/gfx-rs/wgpu) — Reference implementation\n- [Dawn (C++)](https://dawn.googlesource.com/dawn) — Google's implementation\n- [Architecture Deep-Dive (Chinese)](https://chenxutan.com/d/1987.html) — Performance benchmarks, Snatchable pattern analysis, zero-alloc hot paths\n\n---\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n**Priority areas:**\n- Cross-platform testing\n- Performance benchmarks\n- Documentation improvements\n- Bug reports and fixes\n\n---\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ewgpu\u003c/strong\u003e — WebGPU in Pure Go\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgogpu%2Fwgpu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgogpu%2Fwgpu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgogpu%2Fwgpu/lists"}