wgpu 1.2.0 → 1.2.2

data/lib/wgpu/core/instance.rb

@@ -4,6 +4,8 @@ module WGPU
   class Instance
     attr_reader :handle
 
+    # Creates a WebGPU instance.
+    # @raise [InitializationError] if native instance creation fails
     def initialize
       desc = Native::InstanceDescriptor.new
       desc[:next_in_chain] = nil
@@ -15,6 +17,8 @@ module WGPU
       raise InitializationError, "Failed to create WebGPU instance" if @handle.null?
     end
 
+    # Requests an adapter matching the supplied preferences.
+    # @return [Adapter]
     def request_adapter(power_preference: :high_performance, backend: nil, feature_level: :core,
                         force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
       Adapter.request(
@@ -28,6 +32,8 @@ module WGPU
       )
     end
 
+    # Requests an adapter on a background task.
+    # @return [AsyncTask] task yielding an {Adapter}
     def request_adapter_async(power_preference: :high_performance, backend: nil, feature_level: :core,
                               force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
       AsyncTask.new do
@@ -42,6 +48,9 @@ module WGPU
       end
     end
 
+    # Lists adapters exposed by the instance.
+    # @param backends [Integer, nil] backend bit mask
+    # @return [Array<Adapter>]
     def enumerate_adapters(backends: nil)
       options = nil
       if backends
@@ -61,20 +70,31 @@ module WGPU
       end
     end
 
+    # Enumerates adapters on a background task.
+    # @return [AsyncTask] task yielding adapter objects
     def enumerate_adapters_async(backends: nil)
       AsyncTask.new do
         enumerate_adapters(backends: backends)
       end
     end
 
+    # Creates a canvas context from platform presentation information.
+    # @param present_info [Hash] platform surface information
+    # @return [CanvasContext]
     def get_canvas_context(present_info)
       CanvasContext.new(self, present_info)
     end
 
+    # Processes pending instance callbacks and events.
+    # @return [void]
     def process_events
       Native.wgpuInstanceProcessEvents(@handle)
     end
 
+    # Releases the native instance handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuInstanceRelease(@handle)

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?
@@ -20,7 +27,7 @@ module WGPU
         raise CommandError, "Command buffer has already been submitted" if buffer.submitted?
       end
 
-      handles = buffers.map(&:handle)
+      handles = buffers.map { |buffer| NativeResource.checked_handle(buffer, expected_class: CommandBuffer) }
       ptr = FFI::MemoryPointer.new(:pointer, handles.size)
       ptr.write_array_of_pointer(handles)
 
@@ -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")
@@ -42,18 +54,24 @@ module WGPU
 
       Native.wgpuQueueWriteBuffer(
         @handle,
-        buffer.handle,
+        NativeResource.checked_handle(buffer, expected_class: Buffer),
         buffer_offset,
         data_ptr + data_offset,
         write_size
       )
     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:)
 
       dst = Native::ImageCopyTexture.new
-      dst[:texture] = destination[:texture].handle
+      dst[:texture] = NativeResource.checked_handle(destination[:texture], expected_class: Texture)
       dst[:mip_level] = destination[:mip_level] || 0
       dst[:origin][:x] = destination.dig(:origin, :x) || 0
       dst[:origin][:y] = destination.dig(:origin, :y) || 0
@@ -64,16 +82,7 @@ module WGPU
         name: "texture aspect"
       )
 
-      extent = Native::Extent3D.new
-      if size.is_a?(Array)
-        extent[:width] = size[0]
-        extent[:height] = size[1] || 1
-        extent[:depth_or_array_layers] = size[2] || 1
-      else
-        extent[:width] = size[:width]
-        extent[:height] = size[:height] || 1
-        extent[:depth_or_array_layers] = size[:depth_or_array_layers] || 1
-      end
+      extent = DescriptorHelpers.extent_3d(size)
 
       layout = Native::TextureDataLayout.new
       layout[:offset] = data_layout[:offset] || 0
@@ -83,6 +92,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 +103,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,20 +115,32 @@ 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
 
-      width, height, depth = texture_extent(size)
+      extent = DescriptorHelpers.extent_3d(size)
+      width, height, depth = extent.values
       bytes_per_row = data_layout[:bytes_per_row]
       raise ArgumentError, "data_layout[:bytes_per_row] is required" unless bytes_per_row
 
@@ -125,10 +151,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 +164,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 +179,42 @@ 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)
+      timeout = AsyncWaiter.normalize_timeout(timeout)
       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 +225,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)
@@ -209,12 +264,57 @@ module WGPU
 
     private
 
-    def texture_extent(size)
-      if size.is_a?(Array)
-        [size.fetch(0), size[1] || 1, size[2] || 1]
-      else
-        [size.fetch(:width), size[:height] || 1, size[:depth_or_array_layers] || 1]
+    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

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
@@ -15,12 +18,15 @@ module WGPU
       desc[:label][:data] = nil
       desc[:label][:length] = 0
 
-      handle = Native.wgpuInstanceCreateSurface(instance.handle, desc)
+      handle = Native.wgpuInstanceCreateSurface(NativeResource.checked_handle(instance, expected_class: Instance), desc)
       raise SurfaceError, "Failed to create surface from Metal layer" if handle.null?
 
       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
@@ -33,12 +39,15 @@ module WGPU
       desc[:label][:data] = nil
       desc[:label][:length] = 0
 
-      handle = Native.wgpuInstanceCreateSurface(instance.handle, desc)
+      handle = Native.wgpuInstanceCreateSurface(NativeResource.checked_handle(instance, expected_class: Instance), desc)
       raise SurfaceError, "Failed to create surface from Windows HWND" if handle.null?
 
       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
@@ -51,12 +60,15 @@ module WGPU
       desc[:label][:data] = nil
       desc[:label][:length] = 0
 
-      handle = Native.wgpuInstanceCreateSurface(instance.handle, desc)
+      handle = Native.wgpuInstanceCreateSurface(NativeResource.checked_handle(instance, expected_class: Instance), desc)
       raise SurfaceError, "Failed to create surface from Xlib window" if handle.null?
 
       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
@@ -69,12 +81,15 @@ module WGPU
       desc[:label][:data] = nil
       desc[:label][:length] = 0
 
-      handle = Native.wgpuInstanceCreateSurface(instance.handle, desc)
+      handle = Native.wgpuInstanceCreateSurface(NativeResource.checked_handle(instance, expected_class: Instance), desc)
       raise SurfaceError, "Failed to create surface from Wayland surface" if handle.null?
 
       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,10 +97,12 @@ 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
-      config[:device] = device.handle
+      config[:device] = NativeResource.checked_handle(device, expected_class: Device)
       config[:format] = Native::EnumHelper.coerce(Native::TextureFormat, format, name: "surface format")
       config[:usage] = normalize_usage(usage)
       config[:width] = width
@@ -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,29 +177,46 @@ 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)
+      Native.wgpuSurfaceGetCapabilities(@handle, NativeResource.checked_handle(adapter, expected_class: Adapter), caps)
 
       formats = []
       if caps[:format_count] > 0 && !caps[:formats].null?
@@ -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?