wgpu 1.2.0 → 1.2.1

data/lib/wgpu/core/adapter.rb

@@ -4,27 +4,62 @@ module WGPU
   class Adapter
     attr_reader :handle, :instance
 
+    # Wraps an existing native adapter handle.
+    # @param handle [FFI::Pointer] native adapter handle
+    # @param instance [Instance, nil] instance that owns the adapter
+    # @return [Adapter]
     def self.from_handle(handle, instance: nil)
-      adapter = allocate
-      adapter.instance_variable_set(:@handle, handle)
+      adapter = adopt_native_handle(handle)
       adapter.instance_variable_set(:@instance, instance)
       adapter
     end
 
+    # Requests an adapter and waits for the native callback.
+    #
+    # @param instance [Instance] instance used for discovery and callback progress
+    # @param power_preference [Symbol, Integer] preferred power profile
+    # @param backend [Symbol, Integer, nil] backend to restrict discovery to
+    # @param feature_level [Symbol, Integer] requested WebGPU feature level
+    # @param force_fallback_adapter [Boolean] whether to require a fallback adapter
+    # @param compatible_surface [Surface, nil] surface the adapter must support
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [Adapter] requested adapter
+    # @raise [AdapterError] if no adapter can be acquired
+    # @raise [TimeoutError] if the request exceeds +timeout+
     def self.request(instance, power_preference: :high_performance, backend: nil, feature_level: :core,
                      force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
       adapter_ptr = FFI::MemoryPointer.new(:pointer)
-      status_holder = { value: nil, message: nil }
+      status_holder = {
+        done: false,
+        value: nil,
+        message: nil,
+        abandoned: false,
+        cleanup_claimed: false,
+        mutex: Mutex.new
+      }
 
+      callback_token = nil
       callback = FFI::Function.new(
         :void, [:uint32, :pointer, Native::StringView.by_value, :pointer, :pointer]
       ) do |status, adapter, message, _userdata1, _userdata2|
-        status_holder[:value] = Native::RequestAdapterStatus[status]
-        if message[:data] && !message[:data].null? && message[:length] > 0
-          status_holder[:message] = message[:data].read_string(message[:length])
+        abandoned_adapter = nil
+        begin
+          status_holder[:mutex].synchronize do
+            status_holder[:value] = Native::RequestAdapterStatus[status]
+            if message[:data] && !message[:data].null? && message[:length] > 0
+              status_holder[:message] = message[:data].read_string(message[:length])
+            end
+            adapter_ptr.write_pointer(adapter)
+            status_holder[:done] = true
+            if status_holder[:abandoned] && !status_holder[:cleanup_claimed]
+              status_holder[:cleanup_claimed] = true
+              abandoned_adapter = adapter
+            end
+          end
+          Native.wgpuAdapterRelease(abandoned_adapter) if abandoned_adapter && !abandoned_adapter.null?
+        ensure
+          CallbackKeepalive.release(instance, callback_token)
         end
-        adapter_ptr.write_pointer(adapter)
-        status_holder[:done] = true
       end
 
       options = Native::RequestAdapterOptions.new
@@ -55,12 +90,26 @@ module WGPU
       callback_info[:userdata2] = nil
 
       callback_token = CallbackKeepalive.retain(instance, callback)
+      future =
+        begin
+          Native.wgpuInstanceRequestAdapter(instance.handle, options, callback_info)
+        rescue StandardError
+          CallbackKeepalive.release(instance, callback_token)
+          raise
+        end
+
       begin
-        status_holder[:done] = false
-        future = Native.wgpuInstanceRequestAdapter(instance.handle, options, callback_info)
         AsyncWaiter.wait(status_holder: status_holder, instance: instance, future: future, timeout: timeout)
-      ensure
-        CallbackKeepalive.release(instance, callback_token)
+      rescue TimeoutError
+        abandoned_adapter = status_holder[:mutex].synchronize do
+          status_holder[:abandoned] = true
+          next unless status_holder[:done] && !status_holder[:cleanup_claimed]
+
+          status_holder[:cleanup_claimed] = true
+          adapter_ptr.read_pointer
+        end
+        Native.wgpuAdapterRelease(abandoned_adapter) if abandoned_adapter && !abandoned_adapter.null?
+        raise
       end
 
       handle = adapter_ptr.read_pointer
@@ -72,11 +121,16 @@ module WGPU
       new(handle, instance: instance)
     end
 
+    # Wraps a native adapter handle.
+    # @param handle [FFI::Pointer] native adapter handle
+    # @param instance [Instance, nil] instance that owns the adapter
     def initialize(handle, instance: nil)
       @handle = handle
       @instance = instance
     end
 
+    # Requests a logical device from this adapter.
+    # @return [Device]
     def request_device(label: nil, required_features: [], required_limits: nil, timeout: nil)
       Device.request(
         self,
@@ -87,6 +141,8 @@ module WGPU
       )
     end
 
+    # Requests a logical device on a background task.
+    # @return [AsyncTask] task yielding a {Device}
     def request_device_async(label: nil, required_features: [], required_limits: nil, timeout: nil)
       AsyncTask.new do
         request_device(
@@ -98,6 +154,8 @@ module WGPU
       end
     end
 
+    # Returns identifying and backend information for the adapter.
+    # @return [Hash]
     def info
       info_struct = Native::AdapterInfo.new
       Native.wgpuAdapterGetInfo(@handle, info_struct)
@@ -117,22 +175,32 @@ module WGPU
       result
     end
 
+    # Returns the adapter's device name.
+    # @return [String]
     def name
       info[:device]
     end
 
+    # Returns the adapter vendor name.
+    # @return [String]
     def vendor
       info[:vendor]
     end
 
+    # Returns the backend used by the adapter.
+    # @return [Symbol, Integer]
     def backend_type
       info[:backend_type]
     end
 
+    # Returns the adapter's device classification.
+    # @return [Symbol, Integer]
     def adapter_type
       info[:adapter_type]
     end
 
+    # Lists optional features supported by the adapter.
+    # @return [Array<Symbol>]
     def features
       supported = Native::SupportedFeatures.new
       Native.wgpuAdapterGetFeatures(@handle, supported)
@@ -146,10 +214,15 @@ module WGPU
       result
     end
 
+    # Reports whether the adapter supports a feature.
+    # @param feature [Symbol] feature name
+    # @return [Boolean]
     def has_feature?(feature)
       features.include?(feature)
     end
 
+    # Returns the adapter resource limits.
+    # @return [Hash{Symbol => Integer}]
     def limits
       supported = Native::SupportedLimits.new
       supported[:next_in_chain] = nil
@@ -157,11 +230,17 @@ module WGPU
       limits_to_hash(supported[:limits])
     end
 
+    # Returns a concise human-readable adapter description.
+    # @return [String]
     def summary
       info_hash = info
       "#{info_hash[:device]} (#{info_hash[:adapter_type]}) via #{info_hash[:backend_type]}"
     end
 
+    # Releases the native adapter handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuAdapterRelease(@handle)

data/lib/wgpu/core/async_waiter.rb

@@ -10,10 +10,16 @@ module WGPU
 
     module_function
 
+    # Returns the delay between callback progress polls.
+    # @return [Float] seconds
     def poll_interval
       @poll_interval ||= POLL_INTERVAL_SECONDS
     end
 
+    # Sets the delay between callback progress polls.
+    # @param seconds [Numeric] positive delay in seconds
+    # @return [Float]
+    # @raise [ArgumentError] if the delay is not positive
     def poll_interval=(seconds)
       value = Float(seconds)
       raise ArgumentError, "poll interval must be positive" unless value.positive?
@@ -21,6 +27,10 @@ module WGPU
       @poll_interval = value
     end
 
+    # Selects the native callback delivery mode for an operation.
+    #
+    # @param instance [Instance, nil] instance capable of processing events
+    # @return [Integer] native {Native::CallbackMode} value
     def callback_mode(instance:)
       if instance
         callback_mode_value(:allow_process_events)
@@ -29,6 +39,11 @@ module WGPU
       end
     end
 
+    # Drives native event processing until a callback completes.
+    # @param status_holder [Hash] state whose +:done+ flag is set by the callback
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [void]
+    # @raise [TimeoutError] if completion exceeds the timeout
     def wait(status_holder:, instance: nil, device: nil, future: nil, timeout: nil)
       timeout = Float(timeout) if timeout
       raise ArgumentError, "timeout must be non-negative" if timeout&.negative?

data/lib/wgpu/core/canvas_context.rb

@@ -4,6 +4,9 @@ module WGPU
   class CanvasContext
     attr_reader :physical_size
 
+    # Creates a canvas context for platform presentation information.
+    # @param instance [Instance] owning WebGPU instance
+    # @param present_info [Hash] platform handles or an existing surface
     def initialize(instance, present_info = {})
       @instance = instance
       @present_info = present_info || {}
@@ -12,21 +15,38 @@ module WGPU
       @config = nil
     end
 
+    # Updates the drawable's physical pixel size.
+    # @param width [Integer] width in pixels
+    # @param height [Integer] height in pixels
+    # @return [Array<Integer>] stored width and height
+    # @raise [ArgumentError] if either dimension is negative
     def set_physical_size(width, height)
       raise ArgumentError, "width and height must be non-negative" if width.to_i.negative? || height.to_i.negative?
 
       @physical_size = [width.to_i, height.to_i]
     end
 
+    # Returns the surface format preferred by an adapter.
+    #
+    # @param adapter [Adapter] adapter used to query surface capabilities
+    # @return [Symbol] preferred texture format
     def get_preferred_format(adapter)
       ensure_surface
       @surface.get_preferred_format(adapter)
     end
 
+    # Returns the most recent canvas configuration.
+    #
+    # @return [Hash, nil] configuration options, or +nil+ when unconfigured
     def get_configuration
       @config
     end
 
+    # Configures the backing surface for presentation.
+    # @param device [Device] device used to render frames
+    # @param format [Symbol, nil] surface texture format
+    # @return [Hash] resolved canvas configuration
+    # @raise [SurfaceError] if no surface exists or dimensions are not positive
     def configure(device:, format: nil, usage: :render_attachment, view_formats: [], color_space: "srgb", tone_mapping: nil, alpha_mode: :opaque, width: nil, height: nil, present_mode: :fifo)
       ensure_surface
 
@@ -59,21 +79,33 @@ module WGPU
       }
     end
 
+    # Removes the current surface configuration.
+    # @return [void]
     def unconfigure
       @surface&.unconfigure
       @config = nil
     end
 
+    # Acquires the texture for the current presentation frame.
+    #
+    # @return [Texture] acquired surface texture
+    # @raise [SurfaceError] if the context has not been configured
+    # @raise [SurfaceAcquisitionError] if acquisition fails
     def get_current_texture
       raise SurfaceError, "Canvas context must be configured before get_current_texture" unless @config
 
       @surface.current_texture
     end
 
+    # Presents the current surface texture.
+    # @return [void]
     def present
       @surface&.present
     end
 
+    # Releases the backing surface and clears the configuration.
+    #
+    # @return [void]
     def release
       @surface&.release
       @surface = nil