wgpu 1.1.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd711bce02ed7be442c0f636460bf55f23df6e9b26cb7a6f07ed1b48b99ca78b
-  data.tar.gz: f6ffe9530b72876da7b91805ab22b9a20dd065857bfc7fe99c66a79823fb4c75
+  metadata.gz: c118a2950771b2f34f06fcf4642634e57e8b1de07c26681b81aa94d6a1faaf93
+  data.tar.gz: b4f4cc4e97846d21e74144194f97ede7cb2704725cb5887a885345ceedd1c8f1
 SHA512:
-  metadata.gz: 3430e9a25cdc932eb8441903b9f5f5aa83ebdafd34d56311ac8f794240a983b9adb6745fef484293dc968fb76b7e1f5da7813faa5a63b46b46126bb817e1b2eb
-  data.tar.gz: 75b6031fc4e7654541e6e8596434f8c1e3c4b24d89a16d5b946a29a40ba8da0b6082e395d8ac0a47928e7bc56b2e1e473a350051d78b9a9e6edc4945d293deed
+  metadata.gz: 5fad367a0475a31c846fa57151a01d6fda7aed9a5592f6167237117da8967df7269a7ac0233059a174be0803794dc844ee4660cd1383ce3fa858009620100036
+  data.tar.gz: 967d67b899a1ca01e5e805407677772aeaec152d72ede7b31746a8baef6d5fa04544863f7d8e70a4bb2804506ccf8fdd58036c5d5a99c49cfe338be73d667504

data/CHANGELOG.md

@@ -0,0 +1,88 @@
+# 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.1 - 2026-07-24
+
+### Added
+
+- Add reusable staging buffers to `Queue#read_buffer` and
+  `Queue#read_texture`, together with a padded texture-readback example and
+  guide.
+- Support WGSL override constants and omitted entry points across compute,
+  vertex, and fragment pipeline stages.
+- Add a pinned wgpu-native v27.0.4.0 header fixture, ABI update tooling, and
+  cross-platform native artifact verification.
+- Complete RBS and YARD coverage for the public API and expand acceptance
+  coverage for typed buffers, descriptors, errors, timeouts, resource
+  lifetimes, and GPU examples.
+
+### Changed
+
+- Centralize native capability metadata and validate enum, callback, struct,
+  and function ABI expectations against the pinned wgpu-native release.
+- Make compute and rendering examples verify their results, and enforce
+  documentation coverage, SDL3-free installation, release checks, and strict
+  lavapipe GPU coverage in CI.
+
+### Fixed
+
+- Retain callbacks, user data, devices, and instances through dependent
+  resource and pending-operation lifetimes, preventing use-after-free crashes
+  after release, garbage collection, or timeout.
+- Reject out-of-bounds mapped ranges and prevent late buffer, queue, shader,
+  and error-scope callbacks from corrupting completed operation state.
+- Preserve row padding and clean up temporary resources during buffer and
+  texture readback, including repeated reads with caller-owned staging buffers.
+- Recover rendering loops from timed-out, outdated, and lost surface frames,
+  report fatal acquisition states explicitly, and release every acquired
+  texture and view.
+- Track adopted native handles in leak diagnostics and keep release operations
+  idempotent across wrapper types.
+- Correct the isolated core-gem dependency path and make Windows native
+  artifact checks independent of shell quoting.
+
+## 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
 
@@ -51,6 +53,7 @@ export WGPU_LIB_PATH=/path/to/libwgpu_native.so
 
 ### Basic Setup
 
+<!-- wgpu-example: run; expect: Using: -->
 ```ruby
 require 'wgpu'
 
@@ -60,10 +63,15 @@ device = adapter.request_device
 queue = device.queue
 
 puts "Using: #{adapter.info[:device]} (#{adapter.info[:backend_type]})"
+
+device.release
+adapter.release
+instance.release
 ```
 
 ### Compute Shader Example
 
+<!-- wgpu-example: run; expect: [0.0, 2.0, 4.0 -->
 ```ruby
 require 'wgpu'
 
@@ -116,19 +124,29 @@ pass.set_pipeline(pipeline)
 pass.set_bind_group(0, bind_group)
 pass.dispatch_workgroups(input_data.size / 64)
 pass.end_pass
-queue.submit([encoder.finish])
+command_buffer = encoder.finish
+queue.submit(command_buffer)
 
 # Read results
-result = queue.read_buffer(buffer, device: device)
+result = queue.read_buffer(buffer)
 output_data = result.unpack("f*")
 
 puts output_data[0, 10].inspect
 # => [0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0]
+
+[
+  command_buffer, pass, encoder, pipeline, pipeline_layout,
+  bind_group, bind_group_layout, shader, buffer
+].each(&:release)
+device.release
+adapter.release
+instance.release
 ```
 
 ## 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 +156,14 @@ 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
+- `16_texture_readback.rb` - Aligned readback of a 65-pixel-wide texture with reusable staging
+
 Rendering examples (SDL3):
 - `07_triangle.rb` - Basic triangle rendering
 - `08_colored_quad.rb` - Indexed colored quad rendering
@@ -156,8 +182,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 +239,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)
+
+The published [API reference](https://www.rubydoc.info/gems/wgpu) is generated
+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,140 @@
+# WebGPU API coverage
+
+This page records the public Ruby API implemented by wgpu-ruby 1.2 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, limits, device-lost notification, and uncaptured-error subscriptions are exposed. |
+| `GPUDeviceLostInfo` | callback `reason` and `message` | ◐ | `Device#on_device_lost` exposes the native reason and message without a separate wrapper object. |
+| `GPUError` | `WGPU::GPUError` | ✅ | Typed value object with `type`, `message`, `to_h`, and exception conversion. |
+| `GPUExternalTexture` | — | ❌ | Browser video/external-texture import is not exposed. |
+| `GPUInternalError` | `WGPU::InternalError` | ◐ | Represented as a Ruby exception converted from `GPUError`. |
+| `GPUOutOfMemoryError` | `WGPU::OutOfMemoryError` | ◐ | Represented as a Ruby exception converted from `GPUError`. |
+| `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` | `Device#on_uncaptured_error` | ◐ | The callback receives `WGPU::GPUError`; there is no DOM event wrapper. |
+| `GPUValidationError` | `WGPU::ValidationError` | ◐ | Validation errors are translated during resource creation and typed error-scope handling. |
+| `WGSLLanguageFeatures` | — | ❌ | |
+| `GPUObjectBase` | `WGPU::NativeResource` | ✅ | All native wrappers share `handle`, `label`, `released?`, `use`, `inspect`, idempotent release, and use-after-release guards. |
+| `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. Every native wrapper also has the common
+`label`, `released?`, `use`, `inspect`, and idempotent `release` methods from
+`WGPU::NativeResource`.
+
+| Ruby class | Public class methods | Public instance methods |
+|---|---|---|
+| `WGPU` | — | module methods `log_level`, `log_level=`, `on_log` |
+| `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`, `pop_error_scope_typed`, `with_error_scope`, `on_uncaptured_error`, `on_device_lost`, `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`, typed `read_mapped_*` methods, `read_mapped_values`, `map_state`, `size`, `usage`, `destroy`, `release`, `handle` |
+| `WGPU::BufferMappedRange` | — | `read`, `write`, `read_bytes`, `write_bytes`, and typed `read_*` / `write_*` methods |
+| `WGPU::Texture` | `from_handle` | `create_view`, `width`, `height`, `depth_or_array_layers`, `size`, `mip_level_count`, `sample_count`, `dimension`, `format`, `usage`, `surface_status`, `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::GPUError` | `from_hash` | `type`, `message`, `exception_class`, `raise!`, `to_h` |
+| `WGPU::CompilationMessage` | — | `type`, `message`, `line_num`/`line`, `line_pos`/`column`, `offset`, `length`, `to_s` |
+| `WGPU::DataTypes` | `pack`, `unpack`, `byte_size`, `to_pointer`, `validate_alignment!` | — |
+| `WGPU::TextureFormat` | `block_size`, `block_dimensions`, `bytes_per_row`, `aligned_bytes_per_row`, `block_info` | — |
+| `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 | `ArgumentError`, 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 |
+| `16_texture_readback.rb` | Non-aligned-width texture readback | texture row alignment helpers, caller-owned reusable staging |
+
+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,41 @@
+# 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.
+
+The exported `wgpuDeviceCreateComputePipelineAsync` and
+`wgpuDeviceCreateRenderPipelineAsync` functions are also panic stubs in
+wgpu-native v27. Pipeline `*_async` methods therefore retain the safe Ruby
+Thread implementation until those native entry points are implemented.
+
+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`.
+
+`Device.request` can time out only when its adapter is associated with an
+`Instance`. When adopting a native adapter, pass `instance:` to
+`Adapter.from_handle`; without an instance there is no safe event-progress
+boundary for cleaning up a device that completes after timeout.
+
+`*_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,49 @@
+# 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.
+
+## Queries and debug markers
+
+Pass descriptors accept `timestamp_writes:` with a query set and beginning/end
+indices. Render passes additionally accept `occlusion_query_set:` and expose
+`begin_occlusion_query` / `end_occlusion_query`. Copy completed query values
+into a buffer with `CommandEncoder#resolve_query_set`; timestamp queries
+require the adapter's `:timestamp_query` feature and a device requested with
+that feature.
+
+[`examples/15_timestamp_query.rb`](../examples/15_timestamp_query.rb) shows the
+complete feature-gated timestamp flow, including query resolution and typed
+`u64` readback.
+
+Command encoders, compute/render passes, and render bundle encoders expose
+`push_debug_group`, `pop_debug_group`, and `insert_debug_marker`. Labels are
+forwarded directly to wgpu-native for capture/debugging tools:
+
+```ruby
+encoder.push_debug_group("upload and dispatch")
+encoder.insert_debug_marker("resources ready")
+encoder.pop_debug_group
+```
+
+Debug groups must be balanced before the encoder or pass is finished.

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,62 @@
+# Getting started: compute
+
+Compute workloads need Ruby 3.2+, the `wgpu` gem, and a supported GPU driver.
+They do not need SDL3.
+
+<!-- wgpu-example: run; expect: [2, 4, 6, 8] -->
+```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.