wgpu 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd711bce02ed7be442c0f636460bf55f23df6e9b26cb7a6f07ed1b48b99ca78b
-  data.tar.gz: f6ffe9530b72876da7b91805ab22b9a20dd065857bfc7fe99c66a79823fb4c75
+  metadata.gz: 65be5bedee12b2389a8bf8fd8ec2dcb883d739852178dda17cae6b682a26663e
+  data.tar.gz: 584a76214478803361befac5011bb22df20034f4b9e18731be6685b69877eabd
 SHA512:
-  metadata.gz: 3430e9a25cdc932eb8441903b9f5f5aa83ebdafd34d56311ac8f794240a983b9adb6745fef484293dc968fb76b7e1f5da7813faa5a63b46b46126bb817e1b2eb
-  data.tar.gz: 75b6031fc4e7654541e6e8596434f8c1e3c4b24d89a16d5b946a29a40ba8da0b6082e395d8ac0a47928e7bc56b2e1e473a350051d78b9a9e6edc4945d293deed
+  metadata.gz: cde23ae0101bf4e385adb161faca1221069ba15b275c066bcc1770aaab5f88e957bcaa7f8fcd06e1e711730fa75908fbee31e31140a06ba53c8acc55f4b634ed
+  data.tar.gz: d2d974230e674a282ca23a790eb16155730f2b5d9e97d0bc4df3c08822e862e0b17874c9c41b80155a5297bbda427c53ac35e77a7b455050ddb8c2da02031498

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 1.2.0 - 2026-07-23
+
+### Added
+
+- Add typed buffer data, texture layout, shader diagnostics, GPU errors, and
+  synchronous timeout APIs.
+- Add ensure-safe command pass blocks, auto pipeline layouts, resource guards,
+  leak diagnostics, and callback keepalive.
+- Add checksum-verified wgpu-native installation and ABI verification.
+- Add headless rendering pixel verification, 3D/array texture round-trips,
+  async/error/timestamp examples, and GPU CI coverage.
+- Add block-scoped resource cleanup, native diagnostic logging, RBS
+  signatures, YARD documentation, and Trusted Publishing release automation.
+
+### Changed
+
+- Make the SDL3 Ruby gem optional for compute-only users.
+- Validate descriptor shapes, enum values, buffer alignment, and texture
+  readback layout before native calls.
+- Treat command buffers as consumed after submission and expose typed surface
+  acquisition status.
+
+### Fixed
+
+- Correct `CompareFunction` values and add missing v27 surface status and
+  vertex format enum entries discovered by header verification.
+- Guard exported-but-unimplemented v27 functions before they can abort Ruby,
+  expose native extension feature names, and avoid v27 query-set double
+  removal after `destroy`.
+
+## 1.1.0 - 2026-02-16
+
+- Align bindings with wgpu v27 async ABI.
+- Add shared async waiting for adapter/device.
+- Migrate buffer/queue/shader async completion paths.
+
+## 1.0.0 - 2026-02-15
+
+- Initial release

data/README.md

@@ -4,7 +4,7 @@ Ruby bindings for [WebGPU](https://www.w3.org/TR/webgpu/) via [wgpu-native](http
 
 ## Features
 
-- Complete WebGPU API bindings using Ruby-FFI
+- WebGPU object bindings using Ruby-FFI, with an explicit [API coverage matrix](docs/api_coverage.md)
 - GPU compute shaders (GPGPU)
 - Cross-platform support (macOS, Linux, Windows)
 - Automatic wgpu-native library download on gem install
@@ -12,7 +12,7 @@ Ruby bindings for [WebGPU](https://www.w3.org/TR/webgpu/) via [wgpu-native](http
 ## Requirements
 
 - Ruby 3.2+
-- Supported platforms:
+- Supported platforms (64-bit only):
   - macOS (x86_64, arm64)
   - Linux (x86_64, aarch64)
   - Windows (x86_64)
@@ -38,6 +38,8 @@ gem install wgpu
 ```
 
 The wgpu-native library is automatically downloaded from GitHub Releases during installation.
+See [Installation and native artifacts](docs/installation.md) for supported
+artifacts, cache behavior, manual installation, and troubleshooting.
 
 ### Custom wgpu-native Build
 
@@ -128,7 +130,8 @@ puts output_data[0, 10].inspect
 
 ## Examples
 
-See the `examples/` directory for more complete examples:
+See the [`examples/` guide](examples/README.md) for prerequisites, expected
+results, and more complete examples:
 
 Compute examples:
 - `01_adapter_info.rb` - Query GPU adapter information
@@ -138,6 +141,13 @@ Compute examples:
 - `05_image_blur.rb` - Image processing with box filter
 - `06_parallel_reduction.rb` - Parallel sum reduction
 
+Headless validation examples:
+
+- `12_headless_render.rb` - Offscreen triangle and pixel verification
+- `13_error_handling.rb` - Typed, labeled validation errors
+- `14_async_map.rb` - Async mapping through a forced GC cycle
+- `15_timestamp_query.rb` - Feature-gated timestamp query resolution
+
 Rendering examples (SDL3):
 - `07_triangle.rb` - Basic triangle rendering
 - `08_colored_quad.rb` - Indexed colored quad rendering
@@ -156,8 +166,14 @@ Rendering examples require SDL3 on your system:
 ```bash
 # macOS
 brew install sdl3
+
+# Gemfile
+gem "sdl3", "~> 1.0"
 ```
 
+The core `wgpu` gem does not depend on SDL3. Only code that explicitly requires
+`wgpu/window` needs the optional Ruby gem and system library.
+
 ## API Overview
 
 ### Core Objects
@@ -207,6 +223,13 @@ bundle install
 bundle exec rake spec
 ```
 
+See [Resource lifetime](docs/resource_lifetime.md) before building long-running
+applications, and use the [API coverage matrix](docs/api_coverage.md) to check
+the current relationship to the WebGPU specification. The
+[documentation index](docs/README.md) links the compute/rendering guides,
+buffer/texture rules, async and error handling, troubleshooting, and release
+operations.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/wgpu-ruby.

data/docs/README.md

@@ -0,0 +1,22 @@
+# Documentation
+
+- [Getting started: compute](getting_started_compute.md)
+- [Getting started: rendering](getting_started_rendering.md)
+- [API coverage](api_coverage.md)
+- [Installation and native artifacts](installation.md)
+- [Resource lifetime](resource_lifetime.md)
+- [Async operations and polling](async.md)
+- [GPU errors](errors.md)
+- [Buffer data](buffer_data.md)
+- [Texture readback](texture_readback.md)
+- [Shaders and diagnostics](shaders.md)
+- [Bind groups and layouts](bind_groups.md)
+- [Pipeline descriptors](pipeline_descriptors.md)
+- [Command encoding](command_encoding.md)
+- [Troubleshooting](troubleshooting.md)
+- [Upgrading wgpu-native](upgrading_wgpu_native.md)
+- [Releasing](releasing.md)
+
+Generated API documentation is built with `bundle exec yard doc`. Static API
+signatures live in `sig/wgpu.rbs` and validate with
+`bundle exec rbs -I sig validate`.

data/docs/api_coverage.md

@@ -0,0 +1,132 @@
+# WebGPU API coverage
+
+This page records the public Ruby API implemented by wgpu-ruby 1.1 and its
+relationship to the WebGPU object model. It is a baseline, not a claim that
+every WebGPU feature is implemented.
+
+The WebGPU names below follow the
+[WebGPU Editor's Draft](https://gpuweb.github.io/gpuweb/). Browser-only APIs
+such as DOM canvas discovery and external image import are intentionally
+called out instead of being hidden by a general "complete" claim.
+
+Legend:
+
+- ✅: a public Ruby wrapper exists for the interface's core operations
+- ◐: some operations or the returned data shape are implemented
+- ❌: no public wrapper exists
+- N/A: browser integration that does not map directly to a native Ruby binding
+
+## Object and supporting-interface coverage
+
+| WebGPU interface | Ruby API | Status | Notes |
+|---|---|:---:|---|
+| `GPU` | `WGPU::Instance` | ◐ | Native entry point; adapter requests and event processing are exposed. Browser canvas-format and WGSL-language-feature queries are not. |
+| `GPUAdapter` | `WGPU::Adapter` | ✅ | Adapter info, features, limits, and device requests are exposed. |
+| `GPUAdapterInfo` | `Hash` from `Adapter#info` | ◐ | Returned as a Ruby hash rather than a value object. |
+| `GPUBindGroup` | `WGPU::BindGroup` | ✅ | |
+| `GPUBindGroupLayout` | `WGPU::BindGroupLayout` | ✅ | |
+| `GPUBuffer` | `WGPU::Buffer` | ✅ | Mapping, destruction, and Ruby data helpers are included. |
+| `GPUCanvasContext` | `WGPU::CanvasContext` | ◐ | Native-window presentation wrapper; no DOM `canvas` attribute. |
+| `GPUCommandBuffer` | `WGPU::CommandBuffer` | ✅ | |
+| `GPUCommandEncoder` | `WGPU::CommandEncoder` | ✅ | Buffer/texture copies, query resolution, timestamps, and debug markers are exposed. |
+| `GPUCompilationInfo` | `ShaderModule#get_compilation_info` + `CompilationMessage` | ◐ | Typed diagnostics are ready, but pinned wgpu-native v27 exports only a panic stub; calls fail safely in Ruby. |
+| `GPUCompilationMessage` | `WGPU::CompilationMessage` | ✅ | Message, type, line, column, offset, and length are typed fields. |
+| `GPUComputePassEncoder` | `WGPU::ComputePass` | ✅ | |
+| `GPUComputePipeline` | `WGPU::ComputePipeline` | ✅ | Auto layout and override constants are accepted. |
+| `GPUDevice` | `WGPU::Device` | ◐ | Resource creation, error scopes, polling, features, and limits are exposed; device-lost and uncaptured-error subscriptions are not. |
+| `GPUDeviceLostInfo` | — | ❌ | |
+| `GPUError` | error hashes and `WGPU::Error` subclasses | ◐ | There is no common `GPUError` value object yet. |
+| `GPUExternalTexture` | — | ❌ | Browser video/external-texture import is not exposed. |
+| `GPUInternalError` | — | ❌ | |
+| `GPUOutOfMemoryError` | — | ❌ | |
+| `GPUPipelineError` | `WGPU::PipelineError` | ◐ | Ruby exception exists; native pipeline error data is not a value object. |
+| `GPUPipelineLayout` | `WGPU::PipelineLayout` | ✅ | |
+| `GPUQuerySet` | `WGPU::QuerySet` | ✅ | |
+| `GPUQueue` | `WGPU::Queue` | ◐ | Submission, writes, work-done notification, and readback helpers are exposed; browser `copyExternalImageToTexture` is not. |
+| `GPURenderBundle` | `WGPU::RenderBundle` | ✅ | |
+| `GPURenderBundleEncoder` | `WGPU::RenderBundleEncoder` | ✅ | |
+| `GPURenderPassEncoder` | `WGPU::RenderPass` | ✅ | |
+| `GPURenderPipeline` | `WGPU::RenderPipeline` | ✅ | Auto layout and override constants are accepted. |
+| `GPUSampler` | `WGPU::Sampler` | ✅ | |
+| `GPUShaderModule` | `WGPU::ShaderModule` | ✅ | WGSL and wgpu-native SPIR-V/GLSL extensions are supported. |
+| `GPUSupportedFeatures` | `Array<Symbol>` | ◐ | Represented as a Ruby array. |
+| `GPUSupportedLimits` | `Hash` | ◐ | Represented as a Ruby hash. |
+| `GPUTexture` | `WGPU::Texture` | ✅ | |
+| `GPUTextureView` | `WGPU::TextureView` | ✅ | |
+| `GPUUncapturedErrorEvent` | — | ❌ | |
+| `GPUValidationError` | class-specific Ruby exceptions | ◐ | Validation errors are translated during resource creation. |
+| `WGSLLanguageFeatures` | — | ❌ | |
+| `GPUObjectBase` | `#handle`, labels on descriptors | ◐ | Common released-state behavior is not yet centralized. |
+| `GPUPipelineBase` | `#get_bind_group_layout` | ✅ | Implemented by compute and render pipelines. |
+| `GPUCommandsMixin` | `WGPU::CommandEncoder` | ✅ | |
+| `GPUDebugCommandsMixin` | encoder/pass debug methods | ✅ | |
+| `GPUBindingCommandsMixin` | pass/bundle binding methods | ✅ | |
+| `GPURenderCommandsMixin` | render pass/bundle draw methods | ✅ | |
+| `NavigatorGPU` | — | N/A | Browser-only discovery API. |
+
+Descriptor dictionaries are represented as Ruby keyword arguments and nested
+hashes, then converted to the matching `WGPU*Descriptor` FFI structs. The
+implemented object APIs cover buffer, texture/view, sampler, bind group/layout,
+pipeline layout, shader module, compute/render pipeline, command/pass/bundle,
+query set, surface, and device/adapter/instance descriptors. Browser-only
+descriptors (`GPUExternalTextureDescriptor`, external image copy descriptors,
+and DOM canvas ownership) are not implemented.
+
+## Public Ruby API
+
+Constructors are omitted where objects are normally returned by another
+wrapper. `handle` readers are listed once here as a common escape hatch for
+native interoperation.
+
+| Ruby class | Public class methods | Public instance methods |
+|---|---|---|
+| `WGPU::Instance` | — | `request_adapter`, `request_adapter_async`, `enumerate_adapters`, `enumerate_adapters_async`, `process_events`, `get_canvas_context`, `release`, `handle` |
+| `WGPU::Adapter` | `request`, `from_handle` | `request_device`, `request_device_async`, `info`, `name`, `vendor`, `adapter_type`, `backend_type`, `features`, `has_feature?`, `limits`, `summary`, `release`, `handle`, `instance` |
+| `WGPU::Device` | `request` | `queue`, `adapter`, `adapter_info`, `features`, `has_feature?`, `limits`, all `create_*` methods, `push_error_scope`, `pop_error_scope`, `pop_error_scope_async`, `with_error_scope`, `poll`, `destroy`, `release`, `handle` |
+| `WGPU::Queue` | — | `submit`, `write_buffer`, `write_texture`, `read_buffer`, `read_texture`, `on_submitted_work_done`, `on_submitted_work_done_async`, `release`, `handle` |
+| `WGPU::Surface` | `from_metal_layer`, `from_windows_hwnd`, `from_xlib_window`, `from_wayland_surface` | `configure`, `unconfigure`, `current_texture`, `get_current_texture`, `present`, `get_configuration`, `get_preferred_format`, `capabilities`, `release`, `handle` |
+| `WGPU::CanvasContext` | — | `configure`, `unconfigure`, `get_current_texture`, `present`, `get_configuration`, `get_preferred_format`, `set_physical_size`, `physical_size`, `release` |
+| `WGPU::Buffer` | — | `write`, `mapped_range`, `get_mapped_range`, `unmap`, `map_sync`, `map_async`, `read_mapped_data`, `read_mapped`, `write_mapped`, `read_mapped_floats`, `map_state`, `size`, `usage`, `destroy`, `release`, `handle` |
+| `WGPU::BufferMappedRange` | — | `read_bytes`, `write_bytes`, `read_floats`, `write_floats` |
+| `WGPU::Texture` | `from_handle` | `create_view`, `width`, `height`, `depth_or_array_layers`, `size`, `mip_level_count`, `sample_count`, `dimension`, `format`, `usage`, `destroy`, `release`, `handle` |
+| `WGPU::TextureView` | `from_handle` | `texture`, `size`, `release`, `handle` |
+| `WGPU::Sampler` | — | `release`, `handle` |
+| `WGPU::QuerySet` | — | `count`, `type`, `destroy`, `release`, `handle` |
+| `WGPU::ShaderModule` | — | `get_compilation_info`, `get_compilation_info_async`, `release`, `handle` |
+| `WGPU::BindGroupLayout` | `from_handle` | `release`, `handle` |
+| `WGPU::BindGroup` | — | `release`, `handle` |
+| `WGPU::PipelineLayout` | — | `release`, `handle` |
+| `WGPU::ComputePipeline` | — | `get_bind_group_layout`, `release`, `handle` |
+| `WGPU::RenderPipeline` | — | `get_bind_group_layout`, `release`, `handle` |
+| `WGPU::CommandEncoder` | — | `begin_compute_pass`, `begin_render_pass`, copy/clear/query/debug methods, `finish`, `release`, `handle` |
+| `WGPU::CommandBuffer` | — | `release`, `handle` |
+| `WGPU::ComputePass` | — | pipeline/bind-group setup, dispatch/debug methods, `end_pass`, `end`, `release`, `handle` |
+| `WGPU::RenderPass` | — | pipeline/bind-group/buffer setup, draw/state/query/debug methods, `end_pass`, `end`, `release`, `handle` |
+| `WGPU::RenderBundleEncoder` | — | pipeline/bind-group/buffer setup, draw/debug methods, `finish`, `release`, `handle` |
+| `WGPU::RenderBundle` | — | `release`, `handle` |
+| `WGPU::AsyncTask` | — | `wait`, `value`, `then`, `complete?`, `pending?`, `error` |
+| `WGPU::Window::SDLWindow` | — | `create_surface`, event/key helpers, `drawable_size`, `close` |
+
+## Examples as executable specifications
+
+| Example | Purpose | Principal wgpu-ruby APIs exercised |
+|---|---|---|
+| `01_adapter_info.rb` | Adapter discovery and reporting | `Instance#enumerate_adapters`, `#request_adapter`, adapter info/features/limits |
+| `02_compute_basic.rb` | Minimal storage-buffer compute | buffer mapping, bind groups/layouts, compute pipeline/pass, submit, readback |
+| `03_buffer_operations.rb` | Buffer write, copy, map, and read | `create_buffer_with_data`, `Queue#write_buffer`, buffer copy, `map_sync` |
+| `04_matrix_multiply.rb` | Multi-buffer compute | typed byte upload, storage/uniform bindings, workgroup dispatch, readback |
+| `05_image_blur.rb` | 2D compute workload | multiple storage buffers, 2D dispatch, readback |
+| `06_parallel_reduction.rb` | Iterative compute reduction | repeated dispatch/submission, `Queue#write_buffer`, readback |
+| `07_triangle.rb` | Basic surface rendering | SDL surface setup, render pipeline/pass, draw, present |
+| `08_colored_quad.rb` | Indexed vertex rendering | vertex/index buffers, render pipeline/pass, indexed draw |
+| `09_clear_color.rb` | Per-frame clear and presentation | current texture/view, render pass clear, submit, present |
+| `10_textured_quad.rb` | Texture sampling | texture upload/view, sampler, texture bind group, draw |
+| `11_rotating_cube.rb` | Depth-tested 3D rendering | vertex/index/uniform/depth resources, pipeline, per-frame uniform write, draw |
+| `12_headless_render.rb` | Offscreen triangle and readback | render-to-texture, block render pass, aligned texture readback, pixel assertions |
+| `13_error_handling.rb` | Typed and labeled validation error | `BufferError`, operation/label context |
+| `14_async_map.rb` | Async map and callback retention | `map_async`, `AsyncTask`, typed mapped reads, GC stress |
+| `15_timestamp_query.rb` | Feature-gated GPU timestamps | timestamp pass writes, query resolution, u64 readback |
+
+When a public API changes, the corresponding example is part of the acceptance
+test surface. Compute and headless examples are automated in GPU CI; SDL
+window examples remain manual integration checks.

data/docs/async.md

@@ -0,0 +1,31 @@
+# Async operations and polling
+
+wgpu-native v27 returns futures for adapter/device requests, buffer mapping,
+error scopes, compilation info, and queue completion. wgpu-ruby keeps callback
+objects alive until each operation finishes and selects the best available
+progress mechanism:
+
+1. zero-time `wgpuInstanceWaitAny` polling;
+2. `Instance#process_events`;
+3. `Device#poll`;
+4. a short Ruby sleep when native polling cannot block.
+
+wgpu-native v27 aborts when its unsupported timed-WaitAny instance feature is
+requested, so wgpu-ruby deliberately leaves that feature disabled. The Ruby
+poll interval defaults to 1 ms and can be adjusted with
+`WGPU::AsyncWaiter.poll_interval=`.
+
+That release also exports `wgpuBufferGetMapState` as an unimplemented panic
+stub. `Buffer#map_state` is maintained by wgpu-ruby as `:unmapped`,
+`:pending`, or `:mapped` while map operations run.
+
+Synchronous adapter/device requests, `Buffer#map_sync`,
+`Device#pop_error_scope`, and `Queue#on_submitted_work_done` accept
+`timeout:` in seconds. The default `nil` preserves the prior unbounded wait.
+Expiry raises `WGPU::TimeoutError`.
+
+`*_async` methods return `WGPU::AsyncTask`, a convenience wrapper backed by a
+Ruby Thread. Concurrent operations on the same WebGPU object are not
+guaranteed safe. Prefer synchronous operations or external serialization when
+ordering matters. Rendering event loops should call `instance.process_events`
+or `device.poll` regularly.

data/docs/bind_groups.md

@@ -0,0 +1,25 @@
+# Bind groups and pipeline layouts
+
+Each bind group layout entry requires `binding:`, `visibility:`, and exactly one
+resource variant:
+
+| Variant | Keys | Defaults |
+|---|---|---|
+| `buffer:` | `type`, `has_dynamic_offset`, `min_binding_size` | `:storage`, `false`, `0` |
+| `sampler:` | `type` | `:filtering` |
+| `texture:` | `sample_type`, `view_dimension`, `multisampled` | `:float`, `:d2`, `false` |
+| `storage_texture:` | `format` (required), `access`, `view_dimension` | `:write_only`, `:d2` |
+
+`visibility:` accepts one shader-stage Symbol, an integer bitmask, or an Array
+such as `%i[vertex fragment]`. Unknown keys warn; missing required keys and
+conflicting resource variants raise `ArgumentError` before FFI.
+
+A bind group entry requires `binding:` and exactly one of `buffer:`,
+`sampler:`, or `texture_view:`. Buffer entries may also include `offset:` and
+`size:`.
+
+Compute and render pipelines accept `layout: :auto` (also `"auto"` or `nil`).
+Call `pipeline.get_bind_group_layout(index)` to obtain an inferred layout.
+That returned wrapper owns a native reference; the caller must release it.
+`examples/02_compute_basic.rb` demonstrates this path. Explicit
+`PipelineLayout` objects remain fully supported.

data/docs/buffer_data.md

@@ -0,0 +1,37 @@
+# Buffer data
+
+Ruby Arrays passed to buffer APIs use 32-bit floats by default, preserving the
+original wgpu-ruby behavior. Pass `type:` to use another WebGPU scalar
+representation:
+
+| `type:` | Encoding | Bytes |
+|---|---|---:|
+| `:f32` | IEEE 754 float | 4 |
+| `:f64` | IEEE 754 double | 8 |
+| `:u32` | unsigned integer | 4 |
+| `:i32` | signed integer | 4 |
+| `:u16` | unsigned integer | 2 |
+| `:u8` | unsigned integer | 1 |
+
+The keyword is accepted by `Device#create_buffer_with_data`, `Buffer#write`,
+`Buffer#write_mapped`, `Queue#write_buffer`, and `Queue#write_texture`.
+Strings remain raw bytes and `FFI::Pointer` values remain unconverted.
+
+```ruby
+buffer = device.create_buffer_with_data(
+  data: [1, 2, 3, 4],
+  type: :u32,
+  usage: %i[storage copy_src]
+)
+
+queue.write_buffer(buffer, 0, [10, 20], type: :u32)
+```
+
+`BufferMappedRange#read` and `#write` expose the same `type:` keyword. The
+existing `read_floats` / `write_floats` methods remain aliases for the `:f32`
+path. Typed convenience pairs are also available for float64, uint32, int32,
+uint16, and uint8.
+
+WebGPU alignment errors are reported before entering FFI: queue write offsets
+and sizes must be multiples of 4 bytes; mapped offsets must be multiples of 8
+bytes and mapped sizes multiples of 4 bytes.

data/docs/command_encoding.md

@@ -0,0 +1,24 @@
+# Command encoding
+
+Compute and render passes support both the original explicit form and an
+ensure-safe block form:
+
+```ruby
+encoder.begin_compute_pass do |pass|
+  pass.set_pipeline(pipeline)
+  pass.dispatch_workgroups(4)
+end
+
+encoder.begin_render_pass(color_attachments: attachments) do |pass|
+  pass.set_pipeline(pipeline)
+  pass.draw(3)
+end
+```
+
+The block form always ends and releases the pass, including when the block
+raises, and returns the block's value. The explicit form remains compatible:
+call `end_pass` (or `end`) and `release` yourself.
+
+Only one pass may be active on a command encoder. `CommandEncoder#finish`
+raises `WGPU::CommandError` while a pass is still active instead of handing
+invalid state to wgpu-native. Calling `end_pass` more than once is harmless.

data/docs/errors.md

@@ -0,0 +1,40 @@
+# GPU errors
+
+`Device#pop_error_scope` keeps its v1.x Hash return value. New code may call
+`pop_error_scope_typed`, which returns a `WGPU::GPUError` or `nil` for
+`:no_error`.
+
+`GPUError` has `type` and `message` readers, `to_h`, and `raise!`. `raise!`
+maps WebGPU error types to `ValidationError`, `OutOfMemoryError`,
+`InternalError`, or `DeviceLostError`.
+
+Device-level callbacks can be installed after device creation:
+
+```ruby
+device.on_uncaptured_error do |error|
+  warn "#{error.type}: #{error.message}"
+end
+
+device.on_device_lost do |reason, message|
+  warn "#{reason}: #{message}"
+end
+```
+
+wgpu-ruby installs native dispatch callbacks when requesting the device and
+keeps them alive until release. User handlers can therefore be replaced without
+recreating the native device. Without a handler, uncaptured errors and
+unexpected device loss are written as warnings. Exceptions raised by a user
+handler are caught at the FFI boundary and reported as warnings rather than
+escaping through native callback code.
+
+wgpu-native's process-wide diagnostic log can be routed into an application:
+
+```ruby
+WGPU.on_log do |level, message|
+  MyLogger.public_send(level == :warn ? :warn : :debug, message)
+end
+WGPU.log_level = :info
+```
+
+The callback is retained for the process lifetime (or until replaced), so a
+Ruby GC cycle cannot invalidate the native callback pointer.

data/docs/getting_started_compute.md

@@ -0,0 +1,61 @@
+# Getting started: compute
+
+Compute workloads need Ruby 3.2+, the `wgpu` gem, and a supported GPU driver.
+They do not need SDL3.
+
+```ruby
+require "wgpu"
+
+instance = WGPU::Instance.new
+adapter = instance.request_adapter(timeout: 10)
+device = adapter.request_device(timeout: 10)
+
+shader = device.create_shader_module(
+  code: <<~WGSL,
+    @group(0) @binding(0) var<storage, read_write> values: array<u32>;
+
+    @compute @workgroup_size(4)
+    fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+      values[id.x] *= 2u;
+    }
+  WGSL
+)
+
+buffer = device.create_buffer_with_data(
+  data: [1, 2, 3, 4],
+  type: :u32,
+  usage: %i[storage copy_src copy_dst]
+)
+
+pipeline = device.create_compute_pipeline(
+  layout: :auto,
+  compute: { module: shader }
+)
+layout = pipeline.get_bind_group_layout(0)
+group = device.create_bind_group(
+  layout: layout,
+  entries: [{ binding: 0, buffer: buffer }]
+)
+
+encoder = device.create_command_encoder
+encoder.begin_compute_pass do |pass|
+  pass.set_pipeline(pipeline)
+  pass.set_bind_group(0, group)
+  pass.dispatch_workgroups(1)
+end
+command_buffer = encoder.finish
+device.queue.submit(command_buffer)
+
+bytes = device.queue.read_buffer(buffer)
+puts WGPU::DataTypes.unpack(bytes, type: :u32).inspect
+
+[command_buffer, encoder, group, layout, pipeline, buffer, shader].each(&:release)
+device.release
+adapter.release
+instance.release
+```
+
+The full executable version is
+[`examples/02_compute_basic.rb`](../examples/02_compute_basic.rb). For
+production code, put resource release in `ensure` blocks and register
+`Device#on_uncaptured_error` during startup.

data/docs/getting_started_rendering.md

@@ -0,0 +1,62 @@
+# Getting started: rendering
+
+Rendering adds a window-system integration. The bundled helper uses SDL3, but
+surfaces themselves are independent of SDL and may be created from native
+Metal, Win32, Xlib, or Wayland handles.
+
+Add the optional dependency:
+
+```ruby
+gem "wgpu"
+gem "sdl3", "~> 1.0"
+```
+
+Install the SDL3 system library, then load the helper explicitly:
+
+```ruby
+require "wgpu"
+require "wgpu/window"
+
+window = WGPU::Window::SDLWindow.new(
+  title: "WebGPU",
+  width: 800,
+  height: 600
+)
+instance = WGPU::Instance.new
+surface = window.create_surface(instance)
+adapter = instance.request_adapter(compatible_surface: surface)
+device = adapter.request_device
+
+format = surface.capabilities(adapter).fetch(:formats).first
+width, height = window.drawable_size
+surface.configure(
+  device: device,
+  format: format,
+  width: width,
+  height: height,
+  present_mode: :fifo
+)
+```
+
+For every frame, acquire `surface.current_texture`, create a view, encode and
+submit a render pass, call `surface.present`, and release frame-local objects.
+The returned texture exposes `surface_status` as `:success_optimal` or
+`:success_suboptimal`. Acquisition failures raise
+`WGPU::SurfaceAcquisitionError`; inspect its `status` reader for `:timeout`,
+`:outdated`, `:lost`, `:out_of_memory`, or `:device_lost`. Reconfigure on
+`:outdated`/`:lost` after re-reading the drawable size.
+When `drawable_size` changes, configure the surface again with positive pixel
+dimensions. Do not render while a minimized window reports zero dimensions.
+
+`Surface` is the low-level native-window API. `CanvasContext` owns and
+delegates to a surface while retaining the familiar configure/acquire/present
+shape. Integrations other than SDL3 can pass an `FFI::Pointer` obtained from
+their window toolkit to `Surface.from_metal_layer`,
+`Surface.from_windows_hwnd`, `Surface.from_xlib_window`, or
+`Surface.from_wayland_surface`. The application must keep the corresponding
+native window/display/layer alive longer than the surface; wgpu-ruby does not
+take ownership of those platform objects.
+
+[`examples/09_clear_color.rb`](../examples/09_clear_color.rb) is the smallest
+resizable render loop. The other rendering examples cover vertex/index
+buffers, textures, bind groups, depth testing, and uniform updates.