wgpu 1.1.0 → 1.2.1

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,29 +17,40 @@ module WGPU
       raise InitializationError, "Failed to create WebGPU instance" if @handle.null?
     end
 
-    def request_adapter(power_preference: :high_performance, backend: nil, feature_level: :core, force_fallback_adapter: false, compatible_surface: nil)
+    # 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(
         self,
         power_preference: power_preference,
         backend: backend,
         feature_level: feature_level,
         force_fallback_adapter: force_fallback_adapter,
-        compatible_surface: compatible_surface
+        compatible_surface: compatible_surface,
+        timeout: timeout
       )
     end
 
-    def request_adapter_async(power_preference: :high_performance, backend: nil, feature_level: :core, force_fallback_adapter: false, compatible_surface: nil)
+    # 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
         request_adapter(
           power_preference: power_preference,
           backend: backend,
           feature_level: feature_level,
           force_fallback_adapter: force_fallback_adapter,
-          compatible_surface: compatible_surface
+          compatible_surface: compatible_surface,
+          timeout: timeout
         )
       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
@@ -57,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,24 +4,45 @@ 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?
 
+      if buffers.map(&:object_id).uniq.length != buffers.length
+        raise CommandError, "The same command buffer cannot appear twice in one submission"
+      end
+      buffers.each do |buffer|
+        raise CommandError, "Command buffer has already been submitted" if buffer.submitted?
+      end
+
       handles = buffers.map(&:handle)
       ptr = FFI::MemoryPointer.new(:pointer, handles.size)
       ptr.write_array_of_pointer(handles)
 
       Native.wgpuQueueSubmit(@handle, handles.size, ptr)
+      buffers.each(&:mark_submitted!)
     end
 
-    def write_buffer(buffer, buffer_offset, data, data_offset: 0, size: nil)
-      data_ptr, byte_size = data_to_pointer(data)
+    # 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")
       data_offset = Integer(data_offset)
       raise ArgumentError, "data_offset must be non-negative" if data_offset.negative?
       raise ArgumentError, "data_offset out of range" if data_offset > byte_size
@@ -29,6 +50,7 @@ module WGPU
       write_size = size.nil? ? (byte_size - data_offset) : Integer(size)
       raise ArgumentError, "size must be non-negative" if write_size.negative?
       raise ArgumentError, "data_offset + size out of range" if data_offset + write_size > byte_size
+      DataTypes.validate_alignment!(write_size, 4, name: "size")
 
       Native.wgpuQueueWriteBuffer(
         @handle,
@@ -39,8 +61,14 @@ module WGPU
       )
     end
 
-    def write_texture(destination:, data:, data_layout:, size:)
-      data_ptr, byte_size = data_to_pointer(data)
+    # 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
@@ -48,7 +76,11 @@ module WGPU
       dst[:origin][:x] = destination.dig(:origin, :x) || 0
       dst[:origin][:y] = destination.dig(:origin, :y) || 0
       dst[:origin][:z] = destination.dig(:origin, :z) || 0
-      dst[:aspect] = destination[:aspect] || :all
+      dst[:aspect] = Native::EnumHelper.coerce(
+        Native::TextureAspect,
+        destination[:aspect] || :all,
+        name: "texture aspect"
+      )
 
       extent = Native::Extent3D.new
       if size.is_a?(Array)
@@ -69,14 +101,18 @@ module WGPU
       Native.wgpuQueueWriteTexture(@handle, dst, data_ptr, byte_size, layout, extent)
     end
 
-    def read_buffer(buffer, offset: 0, size: nil, device:)
-      size ||= buffer.size - offset
-
-      staging = Buffer.new(device,
-        size: size,
-        usage: [:map_read, :copy_dst]
-      )
+    # 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
 
+      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,
@@ -88,27 +124,55 @@ module WGPU
       command_buffer = encoder.finish
       submit([command_buffer])
 
+      map_requested = true
       staging.map_sync(:read)
-      data = staging.read_mapped_data
-      staging.unmap
-      staging.release
-
-      data
+      staging.read_mapped_data(size:)
+    ensure
+      cleanup_readback_resources(
+        staging:,
+        unmap_staging: map_requested,
+        owns_staging:,
+        command_buffer:,
+        encoder:,
+        active_error: $!
+      )
     end
 
-    def read_texture(source:, data_layout:, size:, device:)
-      width = size[:width] || size[0]
-      height = size[:height] || size[1] || 1
-      depth = size[:depth_or_array_layers] || size[2] || 1
+    # 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)
       bytes_per_row = data_layout[:bytes_per_row]
-      rows_per_image = data_layout[:rows_per_image] || height
-      buffer_size = bytes_per_row * rows_per_image * depth
+      raise ArgumentError, "data_layout[:bytes_per_row] is required" unless bytes_per_row
 
-      staging = Buffer.new(device,
-        size: buffer_size,
-        usage: [:map_read, :copy_dst]
+      DataTypes.validate_alignment!(
+        bytes_per_row,
+        TextureFormat::COPY_ALIGNMENT,
+        name: "bytes_per_row"
       )
+      format = source[:format] || source[:texture].format
+      aspect = source[:aspect] || :all
+      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} " \
+          "(tight row is #{tight_bytes_per_row} bytes)"
+      end
 
+      rows_per_image = data_layout[:rows_per_image] || height
+      buffer_size = bytes_per_row * rows_per_image * depth
+
+      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,
@@ -123,24 +187,41 @@ module WGPU
       command_buffer = encoder.finish
       submit([command_buffer])
 
+      map_requested = true
       staging.map_sync(:read)
-      data = staging.read_mapped_data
-      staging.unmap
-      staging.release
-
-      data
+      staging.read_mapped_data(size: buffer_size)
+    ensure
+      cleanup_readback_resources(
+        staging:,
+        unmap_staging: map_requested,
+        owns_staging:,
+        command_buffer:,
+        encoder:,
+        active_error: $!
+      )
     end
 
-    def on_submitted_work_done(device: nil)
+    # 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
@@ -150,18 +231,38 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      future = Native.wgpuQueueOnSubmittedWorkDone(@handle, callback_info)
-      AsyncWaiter.wait(status_holder: status_holder, instance: instance, device: device, future: future)
+      callback_token = CallbackKeepalive.retain(self, callback)
+      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
 
-    def on_submitted_work_done_async(device: nil)
+    # 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)
+        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)
@@ -170,21 +271,66 @@ module WGPU
 
     private
 
-    def data_to_pointer(data)
-      case data
-      when String
-        ptr = FFI::MemoryPointer.new(:char, data.bytesize)
-        ptr.put_bytes(0, data)
-        [ptr, data.bytesize]
-      when Array
-        ptr = FFI::MemoryPointer.new(:float, data.size)
-        ptr.write_array_of_float(data)
-        [ptr, data.size * 4]
-      when FFI::Pointer
-        [data, data.size]
+    def texture_extent(size)
+      if size.is_a?(Array)
+        [size.fetch(0), size[1] || 1, size[2] || 1]
       else
-        raise ArgumentError, "Unsupported data type: #{data.class}"
+        [size.fetch(:width), size[:height] || 1, size[:depth_or_array_layers] || 1]
       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,11 +97,13 @@ 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[:format] = format
+      config[:format] = Native::EnumHelper.coerce(Native::TextureFormat, format, name: "surface format")
       config[:usage] = normalize_usage(usage)
       config[:width] = width
       config[:height] = height
@@ -95,19 +112,29 @@ module WGPU
         @view_formats_ptr = nil
         config[:view_formats] = nil
       else
-        format_values = view_formats.map do |vf|
-          vf.is_a?(Integer) ? vf : Native::TextureFormat[vf]
+        format_values = view_formats.map do |view_format|
+          Native::EnumHelper.coerce(Native::TextureFormat, view_format, name: "view format")
         end
         @view_formats_ptr = FFI::MemoryPointer.new(:uint32, format_values.size)
         @view_formats_ptr.write_array_of_uint32(format_values)
         config[:view_formats] = @view_formats_ptr
       end
-      config[:alpha_mode] = Native::CompositeAlphaMode[alpha_mode]
-      config[:present_mode] = Native::PresentMode[present_mode]
+      config[:alpha_mode] = Native::EnumHelper.coerce(
+        Native::CompositeAlphaMode,
+        alpha_mode,
+        name: "alpha mode"
+      )
+      config[:present_mode] = Native::EnumHelper.coerce(
+        Native::PresentMode,
+        present_mode,
+        name: "present mode"
+      )
 
       Native.wgpuSurfaceConfigure(@handle, config)
+      release_device_callback_lifetime
       @configured = true
       @device = device
+      attach_device_callback_lifetime(device)
       @config = {
         device: device,
         format: format,
@@ -120,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
 
@@ -134,7 +169,7 @@ module WGPU
 
       status = Native::SurfaceGetCurrentTextureStatus[surface_texture[:status]]
       unless status == :success_optimal || status == :success_suboptimal
-        raise SurfaceError, "Failed to get current texture: #{status}"
+        raise SurfaceAcquisitionError.new(status)
       end
 
       texture_ptr = surface_texture[:texture]
@@ -142,26 +177,43 @@ module WGPU
         raise SurfaceError, "Surface returned null texture"
       end
 
-      Texture.from_handle(texture_ptr)
+      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)
@@ -197,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)
@@ -206,16 +262,7 @@ module WGPU
     private
 
     def normalize_usage(usage)
-      case usage
-      when Integer
-        usage
-      when Symbol
-        Native::TextureUsage[usage]
-      when Array
-        usage.reduce(0) { |acc, u| acc | Native::TextureUsage[u] }
-      else
-        raise ArgumentError, "Invalid usage: #{usage}"
-      end
+      Native::EnumHelper.coerce_flags(Native::TextureUsage, usage, name: "surface usage")
     end
   end
 end