wgpu 1.1.0 → 1.2.0

data/docs/installation.md

@@ -0,0 +1,94 @@
+# Installation and native artifacts
+
+wgpu-ruby is a Ruby-FFI binding. Gem installation downloads a prebuilt
+wgpu-native library; it does not compile a C extension.
+
+## Supported runtime
+
+- Ruby 3.2 or newer
+- 64-bit macOS x86_64/arm64
+- 64-bit Linux glibc x86_64/aarch64
+- 64-bit Windows x86_64 with the MSVC wgpu-native artifact
+
+Linux musl/Alpine and 32-bit runtimes do not have prebuilt artifacts. They may
+still work with a compatible custom library supplied through `WGPU_LIB_PATH`.
+
+## Pinned release and artifacts
+
+The binding targets wgpu-native `v27.0.4.0` from:
+
+`https://github.com/gfx-rs/wgpu-native/releases/download/v27.0.4.0/`
+
+| Ruby platform | Archive | Library |
+|---|---|---|
+| `x86_64-linux` | `wgpu-linux-x86_64-release.zip` | `libwgpu_native.so` |
+| `aarch64-linux` | `wgpu-linux-aarch64-release.zip` | `libwgpu_native.so` |
+| `x86_64-darwin` | `wgpu-macos-x86_64-release.zip` | `libwgpu_native.dylib` |
+| `arm64-darwin` | `wgpu-macos-aarch64-release.zip` | `libwgpu_native.dylib` |
+| Windows `mingw`/`mswin` | `wgpu-windows-x86_64-msvc-release.zip` | `wgpu_native.dll` |
+
+## Resolution order
+
+1. If `WGPU_LIB_PATH` is set, installation skips the download and runtime
+   loading uses that exact file.
+2. Otherwise the runtime uses the first configured cache location:
+   `WGPU_CACHE_DIR`, `XDG_CACHE_HOME`, then the operating-system default.
+3. The legacy `~/.cache/wgpu-ruby/v27.0.4.0/lib/` location is also searched so
+   an existing installation does not require another download.
+4. If the cached library is absent, reinstall the gem or run
+   `bundle exec ruby ext/wgpu/extconf.rb` from a source checkout.
+
+Download uses `curl` when available, then Ruby `Net::HTTP`. Extraction uses
+`rubyzip`, then PowerShell `Expand-Archive` on Windows, then `unzip`.
+
+## Manual installation
+
+1. Download the archive for the target above.
+2. Extract it and locate the library in the archive's `lib` directory.
+3. Set `WGPU_LIB_PATH` to the absolute library path before starting Ruby:
+
+```bash
+export WGPU_LIB_PATH=/opt/wgpu-native/lib/libwgpu_native.so
+bundle exec ruby -Ilib -e 'require "wgpu"; puts WGPU::Native.library_path'
+```
+
+PowerShell:
+
+```powershell
+$env:WGPU_LIB_PATH = "C:\wgpu-native\lib\wgpu_native.dll"
+bundle exec ruby -Ilib -e 'require "wgpu"; puts WGPU::Native.library_path'
+```
+
+The library must match the process architecture and the v27 ABI expected by
+this gem.
+
+## Environment variables
+
+| Variable | Meaning |
+|---|---|
+| `WGPU_LIB_PATH` | Absolute path to a custom wgpu-native shared library; highest priority. |
+| `WGPU_CACHE_DIR` | wgpu-ruby cache root override. The version directory is created directly beneath it. |
+| `XDG_CACHE_HOME` | Cache base on Unix when `WGPU_CACHE_DIR` is unset. |
+| `WGPU_SKIP_GPU_TESTS=1` | Skip tests that require an adapter. This is a test setting, not a runtime backend selector. |
+
+Default cache paths are:
+
+| Platform | Versioned cache directory |
+|---|---|
+| macOS | `~/Library/Caches/wgpu-ruby/v27.0.4.0/` |
+| Linux/other Unix | `~/.cache/wgpu-ruby/v27.0.4.0/` |
+| Windows | `%LOCALAPPDATA%\wgpu-ruby\v27.0.4.0\` |
+
+Every downloaded archive is checked against the SHA-256 digest recorded in
+`lib/wgpu/native/distribution.rb` before extraction. A mismatch deletes the
+archive and stops installation.
+
+## Troubleshooting
+
+- **Library not found:** rerun the install hook or set `WGPU_LIB_PATH`.
+- **Unsupported platform:** build wgpu-native for the host and use
+  `WGPU_LIB_PATH`.
+- **Linux cannot create an adapter:** install a Vulkan driver. Mesa lavapipe
+  (`mesa-vulkan-drivers`) is sufficient for software-based tests.
+- **Rendering examples fail to load SDL3:** install the SDL3 system library and
+  the `sdl3` Ruby gem. Compute APIs do not load `wgpu/window`.

data/docs/pipeline_descriptors.md

@@ -0,0 +1,38 @@
+# Pipeline descriptors
+
+`WGPU::ComputePipeline` and `WGPU::RenderPipeline` accept Ruby Hashes that mirror
+WebGPU pipeline descriptors. Passing `layout: :auto`, `"auto"`, or `nil` requests
+automatic layout inference. A layout object continues to select an explicit
+pipeline layout.
+
+## Default render state
+
+The wrapper applies the following WebGPU defaults when a field is omitted:
+
+| State | Field | Default |
+|---|---|---|
+| Vertex | `entry_point` | `"main"` |
+| Vertex buffer | `step_mode` | `:vertex` |
+| Primitive | `topology` | `:triangle_list` |
+| Primitive | `strip_index_format` | `:undefined` |
+| Primitive | `front_face` | `:ccw` |
+| Primitive | `cull_mode` | `:none` |
+| Primitive | `unclipped_depth` | `false` |
+| Multisample | `count` | `1` |
+| Multisample | `mask` | `0xFFFFFFFF` |
+| Multisample | `alpha_to_coverage_enabled` | `false` |
+| Depth/stencil | `depth_compare` | `:always` |
+| Stencil face | operations | `:keep` |
+| Color target | `write_mask` | `:all` |
+| Blend component | `operation` | `:add` |
+| Blend component | `src_factor` | `:one` |
+| Blend component | `dst_factor` | `:zero` |
+
+`vertex[:module]`, each vertex attribute's `format`, `offset`, and
+`shader_location`, and each color target's `format` are required. A
+depth/stencil state requires `format`. Unknown descriptor keys produce a warning
+so misspellings are visible while preserving v1.x compatibility.
+
+Both vertex/fragment and compute stages accept `constants:`, a Hash mapping WGSL
+override names to numeric values. The descriptor keeps all FFI strings and
+arrays alive until native pipeline creation completes.

data/docs/releasing.md

@@ -0,0 +1,22 @@
+# Releasing
+
+The release workflow uses RubyGems Trusted Publishing and runs for `v*` tags.
+Before the first automated release, configure a trusted publisher for the
+`ydah/wgpu-ruby` repository, workflow `release.yml`, and GitHub environment
+`release` on RubyGems.org.
+
+Release checklist:
+
+1. Complete the [wgpu-native upgrade checklist](upgrading_wgpu_native.md) when
+   the native version changes.
+2. Update `WGPU::VERSION` and move Unreleased changelog entries under the new
+   version/date heading.
+3. Run the complete local verification documented in the project README.
+4. Build and inspect the gem: `gem build wgpu.gemspec`.
+5. Merge the release commit, create an annotated `vX.Y.Z` tag, and push it.
+6. Confirm CI and the protected `release` environment. The workflow rejects a
+   tag that does not equal `v#{WGPU::VERSION}`.
+7. Verify the published gem and generated documentation on RubyGems.org.
+
+The workflow requests only `contents: write` and `id-token: write`; it stores no
+long-lived RubyGems API key.

data/docs/resource_lifetime.md

@@ -0,0 +1,94 @@
+# Resource lifetime
+
+wgpu-ruby follows wgpu-native's explicit reference-counted handle model.
+Callers own every wrapper returned to them and must call `release` when it is no
+longer needed. The library does not automatically release native handles from
+Ruby finalizers.
+
+## `release` and `destroy`
+
+- `release` gives up the wrapper's native reference. It sets the stored handle
+  to `FFI::Pointer::NULL`; calling `release` again is harmless.
+- `destroy` immediately invalidates the underlying GPU resource contents but
+  does not give up the wrapper's reference. Call `release` after `destroy`.
+- Calling another public native operation after `release` raises
+  `WGPU::ResourceError` before FFI is entered. `handle`, `released?`, `label`,
+  `inspect`, and repeated `release` remain available.
+- Every native wrapper supports `use { |resource| ... }`. It returns the block
+  result and releases the wrapper in `ensure`, including when the block raises.
+  This is Ruby convenience API rather than a WebGPU operation.
+
+For short-lived resources:
+
+```ruby
+bytes = device.create_buffer(
+  size: 256,
+  usage: %i[map_read copy_dst]
+).use do |buffer|
+  # Work with buffer; it is released on every exit path.
+end
+```
+
+## Wrapper matrix
+
+The table covers all 23 native wrapper classes. `BufferMappedRange`,
+`AsyncTask`, and `Window::SDLWindow` are not independent wgpu-native
+reference-counted handles.
+
+| Wrapper | `release` | `destroy` | Ownership note |
+|---|:---:|:---:|---|
+| `Instance` | ✅ | — | Release after all adapters/surfaces derived from it. |
+| `Adapter` | ✅ | — | Returned by instance discovery/request. |
+| `Device` | ✅ | ✅ | `release` also releases the cached queue wrapper first. |
+| `Queue` | ✅ | — | Normally owned through `Device#queue`; device release cascades to it. |
+| `Surface` | ✅ | — | Release after unconfiguring and after current texture work completes. |
+| `CanvasContext` | ✅ | — | Releases its internally created surface. |
+| `Buffer` | ✅ | ✅ | Destroy contents when early reclamation is desired, then release. |
+| `Texture` | ✅ | ✅ | Texture views should be released before their texture. |
+| `TextureView` | ✅ | — | `Texture#from_handle`/view wrappers are caller-owned. |
+| `Sampler` | ✅ | — | |
+| `QuerySet` | ✅ | ✅ | Destroy query storage, then release. The wrapper suppresses v27's aborting native double-removal path. |
+| `ShaderModule` | ✅ | — | |
+| `BindGroupLayout` | ✅ | — | Layouts returned by `get_bind_group_layout` are caller-owned. |
+| `BindGroup` | ✅ | — | |
+| `PipelineLayout` | ✅ | — | |
+| `ComputePipeline` | ✅ | — | |
+| `RenderPipeline` | ✅ | — | |
+| `CommandEncoder` | ✅ | — | Finish before release. |
+| `CommandBuffer` | ✅ | — | Release after submission is no longer needed. |
+| `ComputePass` | ✅ | — | End the pass before finishing its encoder. |
+| `RenderPass` | ✅ | — | End the pass before finishing its encoder. |
+| `RenderBundleEncoder` | ✅ | — | Finish before release. |
+| `RenderBundle` | ✅ | — | |
+
+## Recommended release order
+
+Release in the reverse order of creation:
+
+1. End active compute/render passes.
+2. Finish encoders and submit command buffers.
+3. Release pass encoders, command buffers, and command encoders.
+4. Release bind groups, pipelines/layouts, shader modules, samplers, texture
+   views, buffers, textures, and query sets.
+5. Unconfigure and release surfaces/canvas contexts.
+6. Release the device (which releases its queue), then adapter and instance.
+
+Explicitly synchronize work when the application needs resources to remain
+alive until completion. A `CommandBuffer` is consumed by its first successful
+`Queue#submit`; submitting it again raises `WGPU::CommandError`. Submission
+does not itself release the command buffer or its referenced Ruby wrappers.
+
+## Internal staging resources
+
+`Queue#read_buffer` and `Queue#read_texture` create a temporary staging buffer,
+submit a copy, map and read it, then unmap and release it. In the baseline
+implementation cleanup runs from `ensure`, including exceptional paths.
+Applications should not attempt to retain or release this internal buffer.
+
+## Leak diagnostics
+
+Set `WGPU_DEBUG_LEAKS=1` before requiring the gem, or set
+`WGPU.debug_leaks = true` before creating resources, to enable warnings.
+Unreleased resources are reported with their wrapper class and label during GC
+or process exit. The detector never releases a native handle; it is diagnostic
+only and is disabled by default.

data/docs/shaders.md

@@ -0,0 +1,32 @@
+# Shader modules and diagnostics
+
+WGSL remains the default input:
+
+```ruby
+shader = device.create_shader_module(code: wgsl, label: "simulation")
+```
+
+Pass `validate: true` to request compilation information immediately when the
+loaded wgpu-native version implements that API. Error messages are raised as
+`WGPU::ShaderError` with the shader label and line/column diagnostics. Without
+this option, creation follows the original lazy validation behavior.
+
+`ShaderModule#get_compilation_info` returns a Hash with `status:` and
+`messages:`. Each message is a `WGPU::CompilationMessage` with `type`,
+`message`, `line_num`/`line`, `line_pos`/`column`, `offset`, and `length`.
+
+wgpu-native v27.0.4.0 exports the compilation-info function as an
+unimplemented panic stub. wgpu-ruby detects that version and raises
+`WGPU::ShaderError` before crossing the native boundary. This guard avoids a
+process abort; diagnostics can be enabled when a future pinned wgpu-native
+release implements the function.
+
+wgpu-native's SPIR-V extension is available explicitly:
+
+```ruby
+shader = device.create_shader_module(spirv: binary_bytes, label: "compute")
+```
+
+SPIR-V input must contain a whole number of 32-bit words. It is a
+wgpu-native extension rather than portable WebGPU API and should be avoided
+when browser portability matters.

data/docs/texture_readback.md

@@ -0,0 +1,19 @@
+# Texture readback
+
+`WGPU::TextureFormat` exposes WebGPU texel-block calculations:
+
+```ruby
+tight = WGPU::TextureFormat.bytes_per_row(width, :rgba8_unorm)
+stride = WGPU::TextureFormat.aligned_bytes_per_row(width, :rgba8_unorm)
+```
+
+`block_size` returns the bytes in one texel block, while `block_dimensions`
+returns its width and height. Compressed BC, ETC2/EAC, and ASTC formats use
+their real block dimensions. Formats whose depth representation is
+implementation-defined do not claim a portable copy footprint. Combined
+depth/stencil copies require an explicit `aspect:`.
+
+`Queue#read_texture` validates that `bytes_per_row` is a multiple of WebGPU's
+256-byte copy alignment and large enough for the requested width and format.
+Use `aligned_bytes_per_row` when the tight row is not already aligned. Automatic
+padding and mipmap generation are intentionally outside this low-level binding.

data/docs/troubleshooting.md

@@ -0,0 +1,48 @@
+# Troubleshooting
+
+## Native library is not found
+
+Run `bundle exec rake wgpu:install`. The error lists every searched cache path.
+For a custom build, set `WGPU_LIB_PATH` to the shared library file, not its
+directory. See [installation](installation.md).
+
+## Download or checksum fails
+
+The installer deletes an archive whose SHA-256 differs from the pinned release
+metadata. Retry on a trusted network. Do not bypass the checksum; download the
+matching artifact manually and set `WGPU_LIB_PATH` if GitHub Releases is
+unavailable.
+
+## No adapter is available
+
+Update the platform GPU driver. On headless Linux, install Vulkan loader and
+Mesa lavapipe, set `VK_ICD_FILENAMES` to the lavapipe ICD JSON, and inspect
+`vulkaninfo --summary`. `WGPU_BACKEND=vulkan` can make backend selection
+explicit.
+
+## A synchronous operation hangs
+
+Pass `timeout:` to adapter/device requests, `Buffer#map_sync`,
+`Device#pop_error_scope`, or `Queue#on_submitted_work_done`. A timeout raises
+`WGPU::TimeoutError`. In an event loop, regularly call
+`Instance#process_events` or `Device#poll`.
+
+## Texture readback rejects bytes_per_row
+
+Buffer/texture copy rows must be 256-byte aligned. Calculate the value with
+`WGPU::TextureFormat.aligned_bytes_per_row(width, format)` and account for
+padding when decoding each row.
+
+## SDL3 cannot be loaded
+
+Compute code should only `require "wgpu"`. Rendering code must separately add
+the `sdl3` Ruby gem, install the SDL3 system library, and then require
+`wgpu/window`.
+
+## Diagnosing validation and shader errors
+
+Use `device.on_uncaptured_error`, scoped errors, and labels. Compilation-info
+validation is guarded on pinned wgpu-native v27 because its exported function
+is a panic stub; see [Shaders and diagnostics](shaders.md). Set
+`WGPU_DEBUG_LEAKS=1` in development to warn about wrappers that reach GC or
+process exit without `release`.

data/docs/upgrading_wgpu_native.md

@@ -0,0 +1,26 @@
+# Upgrading wgpu-native
+
+Use this checklist for each pinned wgpu-native update.
+
+1. Update only `WGPU::Native::Distribution::VERSION`.
+2. Obtain the five release artifact names and SHA-256 digests from the official
+   wgpu-native GitHub release. Update `ARTIFACTS`.
+3. Run `rg` for the old version and confirm no second version definition
+   remains.
+4. Run `bundle exec rake wgpu:clean wgpu:install` on a disposable cache, then
+   test an existing legacy cache separately.
+5. Run `bundle exec rake wgpu:verify_abi`. Review every enum addition, removal,
+   and value change against the checksum-pinned `webgpu.h`.
+6. Compare structs, field offsets, callback signatures, and exported functions.
+   Add ABI specs for changed layouts. Mark functions optional only when the Ruby
+   API has a valid capability fallback.
+7. Run `bundle exec rspec --tag '~gpu'`, RuboCop, RBS validation, and YARD.
+8. Run every `:gpu` spec and `rake examples:ci` with lavapipe. Run rendering
+   examples on at least one real surface backend.
+9. Build the gem and install it into a clean environment without SDL3.
+10. Record ABI/API changes, platform artifacts, and migration notes in
+    `CHANGELOG.md`.
+
+For a dry run, use a temporary `WGPU_CACHE_DIR` and restore the version/artifact
+edits afterward. Never replace the shared user cache as part of verification.
+

data/ext/wgpu/extconf.rb

@@ -1,151 +1,19 @@
 # frozen_string_literal: true
 
-require "fileutils"
-require "net/http"
-require "uri"
+lib_dir = File.expand_path("../../lib", __dir__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
 
-WGPU_VERSION = "v27.0.4.0"
-GITHUB_RELEASE_URL = "https://github.com/gfx-rs/wgpu-native/releases/download/#{WGPU_VERSION}"
+require "wgpu/native/installer"
 
-PLATFORM_MAP = {
-  /x86_64-linux/ => { file: "wgpu-linux-x86_64-release.zip", lib: "libwgpu_native.so" },
-  /aarch64-linux/ => { file: "wgpu-linux-aarch64-release.zip", lib: "libwgpu_native.so" },
-  /x86_64-darwin/ => { file: "wgpu-macos-x86_64-release.zip", lib: "libwgpu_native.dylib" },
-  /arm64-darwin/ => { file: "wgpu-macos-aarch64-release.zip", lib: "libwgpu_native.dylib" },
-  /mingw|mswin/ => { file: "wgpu-windows-x86_64-msvc-release.zip", lib: "wgpu_native.dll" }
-}.freeze
-
-def detect_platform
-  PLATFORM_MAP.each do |pattern, info|
-    return info if RUBY_PLATFORM =~ pattern
-  end
-  abort "Unsupported platform: #{RUBY_PLATFORM}\nSupported: #{PLATFORM_MAP.keys.map(&:inspect).join(", ")}"
-end
-
-def cache_dir
-  File.join(Dir.home, ".cache", "wgpu-ruby", WGPU_VERSION)
-end
-
-def windows?
-  RUBY_PLATFORM =~ /mingw|mswin/
-end
-
-def curl_available?
-  if windows?
-    system("where curl >nul 2>&1")
+begin
+  installer = WGPU::Native::Installer.new
+  if ENV["WGPU_LIB_PATH"]
+    puts "Using custom wgpu-native from WGPU_LIB_PATH: #{installer.install}"
   else
-    system("which curl >/dev/null 2>&1")
-  end
-end
-
-def download_with_curl(url, dest)
-  system("curl", "-fsSL", "-o", dest, url)
-end
-
-def download_with_ruby(url, dest, redirects = 5)
-  raise "Too many redirects" if redirects == 0
-
-  uri = URI.parse(url)
-  http = Net::HTTP.new(uri.host, uri.port)
-  http.use_ssl = (uri.scheme == "https")
-  http.open_timeout = 10
-  http.read_timeout = 120
-
-  request = Net::HTTP::Get.new(uri.request_uri)
-
-  http.request(request) do |response|
-    case response
-    when Net::HTTPRedirection
-      download_with_ruby(response["location"], dest, redirects - 1)
-    when Net::HTTPSuccess
-      File.open(dest, "wb") do |file|
-        response.read_body { |chunk| file.write(chunk) }
-      end
-    else
-      return false
-    end
-  end
-  true
-end
-
-def download_file(url, dest)
-  return if curl_available? && download_with_curl(url, dest)
-  return if download_with_ruby(url, dest)
-
-  abort "Download failed: #{url}"
-end
-
-def extract_with_rubyzip(zip_path, dest_dir)
-  require "zip"
-  Zip::File.open(zip_path) do |zip_file|
-    zip_file.each do |entry|
-      dest_path = File.join(dest_dir, entry.name)
-      FileUtils.mkdir_p(File.dirname(dest_path))
-      entry.extract(dest_path) { true }
-    end
-  end
-  true
-rescue LoadError
-  false
-end
-
-def extract_with_powershell(zip_path, dest_dir)
-  return false unless windows?
-
-  system("powershell", "-Command", "Expand-Archive -Force -Path '#{zip_path}' -DestinationPath '#{dest_dir}'")
-end
-
-def extract_with_unzip(zip_path, dest_dir)
-  system("unzip", "-o", "-q", zip_path, "-d", dest_dir)
-end
-
-def extract_zip(zip_path, dest_dir)
-  return if extract_with_rubyzip(zip_path, dest_dir)
-  return if windows? && extract_with_powershell(zip_path, dest_dir)
-  return if extract_with_unzip(zip_path, dest_dir)
-
-  abort "Failed to extract zip. Please install 'rubyzip' gem."
-end
-
-def lib_dir
-  File.join(cache_dir, "lib")
-end
-
-def download_wgpu_native
-  platform = detect_platform
-  lib_path = File.join(lib_dir, platform[:lib])
-
-  if File.exist?(lib_path)
-    puts "wgpu-native already cached at #{lib_path}"
-    return lib_path
+    installer.install
   end
-
-  FileUtils.mkdir_p(cache_dir)
-
-  url = "#{GITHUB_RELEASE_URL}/#{platform[:file]}"
-  zip_path = File.join(cache_dir, platform[:file])
-
-  puts "Downloading wgpu-native #{WGPU_VERSION} from GitHub..."
-  puts "  URL: #{url}"
-  download_file(url, zip_path)
-
-  puts "Extracting to #{cache_dir}..."
-  extract_zip(zip_path, cache_dir)
-
-  FileUtils.rm_f(zip_path)
-
-  unless File.exist?(lib_path)
-    abort "Failed to find #{platform[:lib]} after extraction"
-  end
-
-  puts "wgpu-native installed successfully!"
-  lib_path
-end
-
-if ENV["WGPU_LIB_PATH"]
-  puts "Using custom wgpu-native from WGPU_LIB_PATH: #{ENV["WGPU_LIB_PATH"]}"
-else
-  download_wgpu_native
+rescue WGPU::Native::InstallError => error
+  abort error.message
 end
 
 File.write("Makefile", <<~MAKEFILE)

data/lib/wgpu/commands/command_buffer.rb

@@ -6,6 +6,17 @@ module WGPU
 
     def initialize(handle)
       @handle = handle
+      @submitted = false
+    end
+
+    def submitted?
+      @submitted
+    end
+
+    def mark_submitted!
+      raise CommandError, "Command buffer has already been submitted" if @submitted
+
+      @submitted = true
     end
 
     def release