wgpu 1.2.0 → 1.2.1

data/lib/wgpu/core/queue.rb

@@ -4,11 +4,18 @@ module WGPU
   class Queue
     attr_reader :handle
 
+    # Wraps a device's native submission queue.
+    # @param handle [FFI::Pointer] native queue handle
+    # @param device [Device, nil] owning device
     def initialize(handle, device: nil)
       @handle = handle
       @device = device
     end
 
+    # Submits command buffers exactly once in the supplied order.
+    # @param command_buffers [CommandBuffer, Array<CommandBuffer>] buffers to submit
+    # @return [void]
+    # @raise [CommandError] for duplicate or previously submitted buffers
     def submit(command_buffers)
       buffers = Array(command_buffers)
       return if buffers.empty?
@@ -28,6 +35,11 @@ module WGPU
       buffers.each(&:mark_submitted!)
     end
 
+    # Writes typed data into a GPU buffer.
+    # @param buffer [Buffer] destination buffer
+    # @param buffer_offset [Integer] destination byte offset
+    # @param data [Array, String, FFI::Pointer] source data
+    # @return [void]
     def write_buffer(buffer, buffer_offset, data, data_offset: 0, size: nil, type: :f32)
       data_ptr, byte_size = DataTypes.to_pointer(data, type:)
       DataTypes.validate_alignment!(buffer_offset, 4, name: "buffer_offset")
@@ -49,6 +61,12 @@ module WGPU
       )
     end
 
+    # Writes typed data into a texture region.
+    # @param destination [Hash] destination texture and origin
+    # @param data [Array, String, FFI::Pointer] source data
+    # @param data_layout [Hash] source byte layout
+    # @param size [Hash, Array] extent to write
+    # @return [void]
     def write_texture(destination:, data:, data_layout:, size:, type: :f32)
       data_ptr, byte_size = DataTypes.to_pointer(data, type:)
 
@@ -83,6 +101,10 @@ module WGPU
       Native.wgpuQueueWriteTexture(@handle, dst, data_ptr, byte_size, layout, extent)
     end
 
+    # Copies a GPU buffer to mapped staging memory and returns its bytes.
+    # @param buffer [Buffer] source buffer
+    # @param staging [Buffer, nil] reusable map-read staging buffer
+    # @return [String] copied bytes
     def read_buffer(buffer, offset: 0, size: nil, device: nil, staging: nil)
       device ||= @device
       raise ArgumentError, "device is required when the queue has no owning device" unless device
@@ -90,6 +112,7 @@ module WGPU
       size ||= buffer.size - offset
       owns_staging = staging.nil?
       staging ||= Buffer.new(device, size: size, usage: [:map_read, :copy_dst])
+      validate_readback_staging!(staging, size)
       encoder = CommandEncoder.new(device)
       encoder.copy_buffer_to_buffer(
         source: buffer,
@@ -101,15 +124,26 @@ module WGPU
       command_buffer = encoder.finish
       submit([command_buffer])
 
+      map_requested = true
       staging.map_sync(:read)
       staging.read_mapped_data(size:)
     ensure
-      staging&.unmap if staging && staging.map_state == :mapped
-      command_buffer&.release
-      encoder&.release
-      staging&.release if owns_staging
+      cleanup_readback_resources(
+        staging:,
+        unmap_staging: map_requested,
+        owns_staging:,
+        command_buffer:,
+        encoder:,
+        active_error: $!
+      )
     end
 
+    # Copies a texture region to mapped staging memory and returns its padded bytes.
+    # @param source [Hash] source texture, origin, aspect, and optional format
+    # @param data_layout [Hash] destination byte layout
+    # @param size [Hash, Array] extent to read
+    # @param staging [Buffer, nil] reusable map-read staging buffer
+    # @return [String] copied bytes
     def read_texture(source:, data_layout:, size:, device: nil, staging: nil)
       device ||= @device
       raise ArgumentError, "device is required when the queue has no owning device" unless device
@@ -125,10 +159,12 @@ module WGPU
       )
       format = source[:format] || source[:texture].format
       aspect = source[:aspect] || :all
-      minimum_bytes_per_row = TextureFormat.bytes_per_row(width, format, aspect:)
+      tight_bytes_per_row = TextureFormat.bytes_per_row(width, format, aspect:)
+      minimum_bytes_per_row = TextureFormat.aligned_bytes_per_row(width, format, aspect:)
       if bytes_per_row < minimum_bytes_per_row
         raise ArgumentError,
-          "bytes_per_row must be at least #{minimum_bytes_per_row} for width #{width} and #{format.inspect}"
+          "bytes_per_row must be at least #{minimum_bytes_per_row} for width #{width} and #{format.inspect} " \
+          "(tight row is #{tight_bytes_per_row} bytes)"
       end
 
       rows_per_image = data_layout[:rows_per_image] || height
@@ -136,6 +172,7 @@ module WGPU
 
       owns_staging = staging.nil?
       staging ||= Buffer.new(device, size: buffer_size, usage: [:map_read, :copy_dst])
+      validate_readback_staging!(staging, buffer_size)
       encoder = CommandEncoder.new(device)
       encoder.copy_texture_to_buffer(
         source: source,
@@ -150,25 +187,41 @@ module WGPU
       command_buffer = encoder.finish
       submit([command_buffer])
 
+      map_requested = true
       staging.map_sync(:read)
       staging.read_mapped_data(size: buffer_size)
     ensure
-      staging&.unmap if staging && staging.map_state == :mapped
-      command_buffer&.release
-      encoder&.release
-      staging&.release if owns_staging
+      cleanup_readback_resources(
+        staging:,
+        unmap_staging: map_requested,
+        owns_staging:,
+        command_buffer:,
+        encoder:,
+        active_error: $!
+      )
     end
 
+    # Waits until all previously submitted queue work completes.
+    # @param device [Device, nil] device used to drive callback progress
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [Symbol] native completion status
     def on_submitted_work_done(device: nil, timeout: nil)
       device ||= @device
       instance = device&.adapter&.instance
       status_holder = { done: false, status: nil }
 
+      callback_lifetime_release = device_callback_lifetime_lease
+      callback_token = nil
       callback = FFI::Function.new(
         :void, [:uint32, :pointer, :pointer]
       ) do |status, _userdata1, _userdata2|
-        status_holder[:done] = true
-        status_holder[:status] = Native::QueueWorkDoneStatus[status]
+        begin
+          status_holder[:status] = Native::QueueWorkDoneStatus[status]
+          status_holder[:done] = true
+        ensure
+          CallbackKeepalive.release(self, callback_token)
+          callback_lifetime_release.call
+        end
       end
 
       callback_info = Native::QueueWorkDoneCallbackInfo.new
@@ -179,28 +232,37 @@ module WGPU
       callback_info[:userdata2] = nil
 
       callback_token = CallbackKeepalive.retain(self, callback)
-      begin
-        future = Native.wgpuQueueOnSubmittedWorkDone(@handle, callback_info)
-        AsyncWaiter.wait(
-          status_holder: status_holder,
-          instance: instance,
-          device: device,
-          future: future,
-          timeout: timeout
-        )
-      ensure
-        CallbackKeepalive.release(self, callback_token)
-      end
+      future =
+        begin
+          Native.wgpuQueueOnSubmittedWorkDone(@handle, callback_info)
+        rescue StandardError
+          CallbackKeepalive.release(self, callback_token)
+          callback_lifetime_release.call
+          raise
+        end
+      AsyncWaiter.wait(
+        status_holder: status_holder,
+        instance: instance,
+        device: device,
+        future: future,
+        timeout: timeout
+      )
 
       status_holder[:status]
     end
 
+    # Waits for prior queue work on a background task.
+    # @return [AsyncTask] task yielding the native completion status
     def on_submitted_work_done_async(device: nil, timeout: nil)
       AsyncTask.new do
         on_submitted_work_done(device: device, timeout: timeout)
       end
     end
 
+    # Releases the native queue handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuQueueRelease(@handle)
@@ -217,5 +279,58 @@ module WGPU
       end
     end
 
+    def validate_readback_staging!(staging, required_size)
+      if staging.size < required_size
+        raise ArgumentError,
+          "staging buffer size must be at least #{required_size} bytes (got #{staging.size})"
+      end
+
+      required_usage = Native::BufferUsage.fetch(:map_read) | Native::BufferUsage.fetch(:copy_dst)
+      unless (staging.usage & required_usage) == required_usage
+        raise ArgumentError, "staging buffer usage must include :map_read and :copy_dst"
+      end
+
+      return if staging.map_state == :unmapped
+
+      raise ArgumentError, "staging buffer must be unmapped before readback"
+    end
+
+    def cleanup_readback_resources(
+      staging:,
+      unmap_staging:,
+      owns_staging:,
+      command_buffer:,
+      encoder:,
+      active_error:
+    )
+      cleanup_error = nil
+
+      begin
+        staging&.unmap if unmap_staging && staging && staging.map_state == :mapped
+      rescue StandardError => e
+        cleanup_error ||= e
+      ensure
+        begin
+          command_buffer&.release
+        rescue StandardError => e
+          cleanup_error ||= e
+        ensure
+          begin
+            encoder&.release
+          rescue StandardError => e
+            cleanup_error ||= e
+          ensure
+            begin
+              staging&.release if owns_staging
+            rescue StandardError => e
+              cleanup_error ||= e
+            end
+          end
+        end
+      end
+
+      raise cleanup_error if cleanup_error && active_error.nil?
+    end
+
   end
 end

data/lib/wgpu/core/surface.rb

@@ -4,6 +4,9 @@ module WGPU
   class Surface
     attr_reader :handle
 
+    # Creates a surface backed by a Core Animation Metal layer.
+    # @return [Surface]
+    # @raise [SurfaceError] if native surface creation fails
     def self.from_metal_layer(instance, layer)
       source = Native::SurfaceSourceMetalLayer.new
       source[:chain][:next] = nil
@@ -21,6 +24,9 @@ module WGPU
       new(handle, instance)
     end
 
+    # Creates a surface backed by a Windows window handle.
+    # @return [Surface]
+    # @raise [SurfaceError] if native surface creation fails
     def self.from_windows_hwnd(instance, hinstance, hwnd)
       source = Native::SurfaceSourceWindowsHWND.new
       source[:chain][:next] = nil
@@ -39,6 +45,9 @@ module WGPU
       new(handle, instance)
     end
 
+    # Creates a surface backed by an Xlib window.
+    # @return [Surface]
+    # @raise [SurfaceError] if native surface creation fails
     def self.from_xlib_window(instance, display, window)
       source = Native::SurfaceSourceXlibWindow.new
       source[:chain][:next] = nil
@@ -57,6 +66,9 @@ module WGPU
       new(handle, instance)
     end
 
+    # Creates a surface backed by a Wayland surface.
+    # @return [Surface]
+    # @raise [SurfaceError] if native surface creation fails
     def self.from_wayland_surface(instance, display, surface)
       source = Native::SurfaceSourceWaylandSurface.new
       source[:chain][:next] = nil
@@ -75,6 +87,9 @@ module WGPU
       new(handle, instance)
     end
 
+    # Wraps a native presentation surface.
+    # @param handle [FFI::Pointer] native surface handle
+    # @param instance [Instance] owning instance
     def initialize(handle, instance)
       @handle = handle
       @instance = instance
@@ -82,6 +97,8 @@ module WGPU
       @config = nil
     end
 
+    # Configures this surface for presentation by a device.
+    # @return [Hash] stored configuration
     def configure(device:, format:, usage: :render_attachment, width:, height:, present_mode: :fifo, alpha_mode: :auto, view_formats: [])
       config = Native::SurfaceConfiguration.new
       config[:next_in_chain] = nil
@@ -114,8 +131,10 @@ module WGPU
       )
 
       Native.wgpuSurfaceConfigure(@handle, config)
+      release_device_callback_lifetime
       @configured = true
       @device = device
+      attach_device_callback_lifetime(device)
       @config = {
         device: device,
         format: format,
@@ -128,12 +147,20 @@ module WGPU
       }
     end
 
+    # Removes the current surface configuration.
+    # @return [void]
     def unconfigure
       Native.wgpuSurfaceUnconfigure(@handle)
+      release_device_callback_lifetime
       @configured = false
+      @device = nil
       @config = nil
     end
 
+    # Acquires the current surface texture.
+    # @return [Texture]
+    # @raise [SurfaceError] if unconfigured or no texture is returned
+    # @raise [SurfaceAcquisitionError] if the surface status is unsuccessful
     def current_texture
       raise SurfaceError, "Surface is not configured" unless @configured
 
@@ -150,26 +177,43 @@ module WGPU
         raise SurfaceError, "Surface returned null texture"
       end
 
-      Texture.from_handle(texture_ptr, surface_status: status)
+      Texture.from_handle(texture_ptr, surface_status: status, device: @device)
     end
 
+    # Acquires the texture for the current presentation frame.
+    #
+    # @return [Texture] acquired surface texture
+    # @raise [SurfaceError] if the surface is not configured
+    # @raise [SurfaceAcquisitionError] if acquisition fails
     def get_current_texture
       current_texture
     end
 
+    # Presents the current surface texture.
+    # @return [void]
     def present
       Native.wgpuSurfacePresent(@handle)
     end
 
+    # Returns the most recent surface configuration.
+    #
+    # @return [Hash, nil] configuration options, or +nil+ when unconfigured
     def get_configuration
       @config
     end
 
+    # Returns the first surface format supported by an adapter.
+    #
+    # @param adapter [Adapter] adapter used to query surface capabilities
+    # @return [Symbol] preferred texture format
     def get_preferred_format(adapter)
       caps = capabilities(adapter)
       caps[:formats].first || :bgra8_unorm
     end
 
+    # Returns the formats, presentation modes, alpha modes, and usages supported by an adapter.
+    # @param adapter [Adapter] adapter to query
+    # @return [Hash]
     def capabilities(adapter)
       caps = Native::SurfaceCapabilities.new
       Native.wgpuSurfaceGetCapabilities(@handle, adapter.handle, caps)
@@ -205,6 +249,10 @@ module WGPU
       Native.wgpuSurfaceCapabilitiesFreeMembers(caps) if caps
     end
 
+    # Releases the native surface handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuSurfaceRelease(@handle)

data/lib/wgpu/data_types.rb

@@ -13,6 +13,10 @@ module WGPU
 
     module_function
 
+    # Encodes Ruby values in little-endian native transfer format.
+    # @param values [Array] values to encode
+    # @param type [Symbol] element type
+    # @return [String] encoded bytes
     def pack(values, type: :f32)
       format, = format_for(type)
       Array(values).pack(format)
@@ -20,6 +24,10 @@ module WGPU
       raise ArgumentError, "value is out of range for #{type}: #{e.message}"
     end
 
+    # Decodes little-endian transfer bytes into Ruby values.
+    # @param bytes [String] encoded bytes
+    # @param type [Symbol] element type
+    # @return [Array]
     def unpack(bytes, type: :f32)
       format, byte_size = format_for(type)
       unless (bytes.bytesize % byte_size).zero?
@@ -29,10 +37,15 @@ module WGPU
       bytes.unpack(format)
     end
 
+    # Returns the byte width of one typed value.
+    # @param type [Symbol] element type
+    # @return [Integer]
     def byte_size(type)
       format_for(type).last
     end
 
+    # Converts data to an FFI pointer and reports its byte length.
+    # @return [Array(FFI::Pointer, Integer)] pointer and byte length
     def to_pointer(data, type: :f32)
       return [data, pointer_size(data)] if data.is_a?(FFI::Pointer)
 
@@ -42,6 +55,9 @@ module WGPU
       [pointer, bytes.bytesize]
     end
 
+    # Validates a non-negative aligned byte value.
+    # @return [Integer] normalized value
+    # @raise [ArgumentError] if negative or misaligned
     def validate_alignment!(value, alignment, name:)
       integer = Integer(value)
       raise ArgumentError, "#{name} must be non-negative" if integer.negative?

data/lib/wgpu/descriptor_helpers.rb

@@ -2,8 +2,16 @@
 
 module WGPU
   module DescriptorHelpers
+    SIZE_MAX = (1 << (FFI.type_size(:size_t) * 8)) - 1
+
     module_function
 
+    # Writes an optional Ruby label into a native descriptor.
+    #
+    # @param descriptor [FFI::Struct] descriptor with a +label+ member
+    # @param label [String, nil] label text
+    # @param keepalive [Array] receives allocated pointers that must remain alive
+    # @return [void]
     def set_label(descriptor, label, keepalive:)
       if label
         pointer = FFI::MemoryPointer.from_string(label)
@@ -16,6 +24,11 @@ module WGPU
       end
     end
 
+    # Allocates and fills a native uint32 array.
+    #
+    # @param values [Array<Integer>] values to copy
+    # @param keepalive [Array] receives the allocated pointer
+    # @return [FFI::MemoryPointer, nil] pointer, or +nil+ for an empty array
     def uint32_array(values, keepalive:)
       return nil if values.empty?
 
@@ -25,6 +38,58 @@ module WGPU
       pointer
     end
 
+    # Writes a nullable string into a native string view.
+    #
+    # @param string_view [Native::StringView] destination view
+    # @param value [String, nil] string value; +nil+ uses the native null sentinel
+    # @param keepalive [Array] receives allocated pointers that must remain alive
+    # @return [void]
+    def set_nullable_string_view(string_view, value, keepalive:)
+      if value.nil?
+        string_view[:data] = nil
+        string_view[:length] = SIZE_MAX
+        return
+      end
+
+      string = value
+      pointer = FFI::MemoryPointer.from_string(string)
+      keepalive << pointer
+      string_view[:data] = pointer
+      string_view[:length] = string.bytesize
+    end
+
+    # Writes pipeline-overridable constants into a stage descriptor.
+    #
+    # @param stage_descriptor [FFI::Struct] programmable stage descriptor
+    # @param constants [Hash{#to_s => Numeric}, nil] constant names and values
+    # @param keepalive [Array] receives allocated pointers that must remain alive
+    # @return [void]
+    def set_constants(stage_descriptor, constants, keepalive:)
+      stage_descriptor[:constant_count] = 0
+      stage_descriptor[:constants] = nil
+      return if constants.nil? || constants.empty?
+
+      constants_pointer = FFI::MemoryPointer.new(Native::ConstantEntry, constants.size)
+      keepalive << constants_pointer
+
+      constants.each_with_index do |(key, value), index|
+        entry_pointer = constants_pointer + (index * Native::ConstantEntry.size)
+        entry = Native::ConstantEntry.new(entry_pointer)
+        entry[:next_in_chain] = nil
+        set_nullable_string_view(entry[:key], key.to_s, keepalive:)
+        entry[:value] = value.to_f
+      end
+
+      stage_descriptor[:constant_count] = constants.size
+      stage_descriptor[:constants] = constants_pointer
+    end
+
+    # Checks required keys and warns about unsupported descriptor keys.
+    # @param options [Hash] descriptor options
+    # @param allowed [Array<Symbol>] supported keys
+    # @param required [Array<Symbol>] mandatory keys
+    # @return [Hash] original options
+    # @raise [ArgumentError] when required keys are missing
     def validate_keys!(options, allowed:, required: [], context: "descriptor")
       return options unless options.is_a?(Hash)
 

data/lib/wgpu/error.rb

@@ -20,6 +20,9 @@ module WGPU
   class SurfaceAcquisitionError < SurfaceError
     attr_reader :status
 
+    # Creates an acquisition error for a native surface status.
+    # @param status [Symbol] native acquisition status
+    # @param message [String, nil] optional override message
     def initialize(status, message = nil)
       @status = status
       super(message || "Failed to get current surface texture: #{status}")
@@ -28,12 +31,17 @@ module WGPU
   class RenderBundleError < Error; end
 
   GPUError = Data.define(:type, :message) do
+    # Converts a native error-scope result into a typed error.
+    # @param error [Hash, nil] native error result
+    # @return [GPUError, nil]
     def self.from_hash(error)
       return if error.nil? || error[:type].nil? || error[:type] == :no_error
 
       new(type: error[:type], message: error[:message].to_s)
     end
 
+    # Returns the Ruby exception class matching this GPU error type.
+    # @return [Class<Error>]
     def exception_class
       {
         validation: ValidationError,
@@ -43,10 +51,15 @@ module WGPU
       }.fetch(type, Error)
     end
 
+    # Raises this error as its matching Ruby exception.
+    # @return [void]
+    # @raise [Error]
     def raise!
       raise exception_class, "GPU error (#{type}): #{message}"
     end
 
+    # Returns a serializable representation of the error.
+    # @return [Hash]
     def to_h
       { type:, message: }
     end
@@ -63,6 +76,8 @@ module WGPU
     alias line line_num
     alias column line_pos
 
+    # Formats the diagnostic with source location, severity, and message.
+    # @return [String]
     def to_s
       location = line_num&.positive? ? "#{line_num}:#{line_pos}" : "unknown location"
       "#{location}: #{type}: #{message}"

data/lib/wgpu/native/abi_verifier.rb

@@ -22,18 +22,29 @@ module WGPU
         ]
       }.freeze
 
+      # Creates a verifier for a header and native binding.
+      # @param header_path [String, nil] header fixture to compare
+      # @param native [Module] native binding module
       def initialize(header_path: nil, native: Native)
         @header_path = header_path || self.class.default_header_path
         @native = native
       end
 
+      # Verifies the runtime version and Ruby enum ABI against the header.
+      # @return [true]
+      # @raise [WGPU::Error] when differences are detected
       def verify!
         differences = enum_differences
+        version_difference = native_version_difference
+        differences.unshift(version_difference) if version_difference
         return true if differences.empty?
 
-        raise WGPU::Error, "wgpu-native ABI enum differences:\n#{differences.join("\n")}"
+        raise WGPU::Error, "wgpu-native ABI differences:\n#{differences.join("\n")}"
       end
 
+      # Compares Ruby enum values with the pinned native header.
+      #
+      # @return [Array<String>] human-readable differences
       def enum_differences
         header_enums = parse_header
         ruby_enums.filter_map do |name, mapping|
@@ -44,10 +55,16 @@ module WGPU
         end
       end
 
+      # Locates the pinned header used for ABI verification.
+      # @return [String] absolute header path
+      # @raise [WGPU::Error] if no header is available
       def self.default_header_path
         override = ENV["WGPU_HEADER_PATH"]
         return File.expand_path(override) if override && !override.empty?
 
+        fixture = fixture_header_path
+        return fixture if File.file?(fixture)
+
         candidates = Distribution.cache_directories.map do |cache_dir|
           File.join(cache_dir, "include", "webgpu", "webgpu.h")
         end
@@ -56,13 +73,30 @@ module WGPU
 
         raise WGPU::Error, <<~MSG.chomp
           Pinned #{Distribution::VERSION} webgpu.h was not found.
-          Run `bundle exec rake wgpu:install`, or set WGPU_HEADER_PATH.
-          Searched: #{candidates.join(", ")}
+          Restore the repository ABI fixture, run `bundle exec rake wgpu:install`,
+          or set WGPU_HEADER_PATH.
+          Searched: #{([fixture] + candidates).join(", ")}
         MSG
       end
 
+      # Returns the repository's pinned enum fixture path.
+      #
+      # @return [String] absolute header fixture path
+      def self.fixture_header_path
+        File.expand_path("fixtures/webgpu-#{Distribution::VERSION}-enums.h", __dir__)
+      end
+
       private
 
+      def native_version_difference
+        actual = @native.wgpuGetVersion
+        expected = Distribution::ENCODED_VERSION
+        return if actual == expected
+
+        "version: runtime #{Distribution.version_string(actual)} (0x#{format("%08x", actual)}) " \
+          "does not match pinned #{Distribution::VERSION} (0x#{format("%08x", expected)})"
+      end
+
       def parse_header
         source = File.read(@header_path)
         source.scan(

data/lib/wgpu/native/callbacks.rb

@@ -8,6 +8,12 @@ module WGPU
     callback :request_device_callback,
              [RequestDeviceStatus, :pointer, StringView.by_value, :pointer, :pointer], :void
 
+    callback :create_compute_pipeline_async_callback,
+             [CreatePipelineAsyncStatus, :pointer, StringView.by_value, :pointer, :pointer], :void
+
+    callback :create_render_pipeline_async_callback,
+             [CreatePipelineAsyncStatus, :pointer, StringView.by_value, :pointer, :pointer], :void
+
     callback :buffer_map_callback,
              [MapAsyncStatus, StringView.by_value, :pointer, :pointer], :void