wgpu 1.2.0 → 1.2.1

data/lib/wgpu/native/functions.rb

@@ -2,6 +2,9 @@
 
 module WGPU
   module Native
+    attach_function :wgpuGetVersion,
+                    [], :uint32
+
     attach_function :wgpuCreateInstance,
                     [InstanceDescriptor.by_ref], :pointer
 
@@ -68,9 +71,17 @@ module WGPU
     attach_function :wgpuDeviceCreateRenderPipeline,
                     [:pointer, :pointer], :pointer
 
+    attach_function :wgpuDeviceCreateRenderPipelineAsync,
+                    [:pointer, RenderPipelineDescriptor.by_ref, CreateRenderPipelineAsyncCallbackInfo.by_value],
+                    Future.by_value
+
     attach_function :wgpuDeviceCreateComputePipeline,
                     [:pointer, ComputePipelineDescriptor.by_ref], :pointer
 
+    attach_function :wgpuDeviceCreateComputePipelineAsync,
+                    [:pointer, ComputePipelineDescriptor.by_ref, CreateComputePipelineAsyncCallbackInfo.by_value],
+                    Future.by_value
+
     attach_function :wgpuDeviceCreateCommandEncoder,
                     [:pointer, CommandEncoderDescriptor.by_ref], :pointer
 

data/lib/wgpu/native/installer.rb

@@ -11,22 +11,50 @@ module WGPU
   module Native
     class InstallError < StandardError; end
 
+    # Downloads, verifies, and installs the pinned wgpu-native artifact.
     class Installer
       attr_reader :platform
 
+      # Creates an installer for a target Ruby platform.
+      #
+      # The final four dependencies are injectable to keep network, process,
+      # archive, and distribution branches testable without external effects.
+      #
+      # @param platform [String] target Ruby platform
+      # @param env [Hash] environment variables
+      # @param home [String] home directory used for cache resolution
+      # @param host_os [String] host operating-system identifier
+      # @param output [IO] progress output
+      # @param command_runner [#call, nil] process runner
+      # @param http_factory [#call, nil] factory receiving a URI
+      # @param zip_file_loader [#call, nil] factory returning Zip::File
+      # @param distribution [Module] artifact metadata provider
       def initialize(platform: RUBY_PLATFORM, env: ENV, home: Dir.home,
-                     host_os: RbConfig::CONFIG["host_os"], output: $stdout)
+                     host_os: RbConfig::CONFIG["host_os"], output: $stdout,
+                     command_runner: nil, http_factory: nil, zip_file_loader: nil,
+                     distribution: Distribution)
         @platform = platform
         @env = env
         @home = home
         @host_os = host_os
         @output = output
-      end
-
+        @command_runner = command_runner || method(:system)
+        @http_factory = http_factory || ->(uri) { Net::HTTP.new(uri.host, uri.port) }
+        @zip_file_loader = zip_file_loader || lambda {
+          require "zip"
+          Zip::File
+        }
+        @distribution = distribution
+      end
+
+      # Installs or reuses the native library for {#platform}.
+      #
+      # @return [String] absolute path to the native library
+      # @raise [InstallError] if the artifact cannot be obtained or verified
       def install
         return custom_library_path if custom_library_path
 
-        artifact = Distribution.artifact_for(platform)
+        artifact = @distribution.artifact_for(platform)
         cached_path = existing_library_path(artifact)
         if cached_path
           @output.puts "wgpu-native already cached at #{cached_path}"
@@ -38,8 +66,11 @@ module WGPU
         raise InstallError, "#{error.message}\n\n#{recovery_instructions}"
       end
 
+      # Returns the primary versioned cache directory.
+      #
+      # @return [String]
       def clean_path
-        Distribution.primary_cache_dir(env: @env, home: @home, host_os: @host_os)
+        @distribution.primary_cache_dir(env: @env, home: @home, host_os: @host_os)
       end
 
       private
@@ -53,7 +84,7 @@ module WGPU
       end
 
       def existing_library_path(artifact)
-        Distribution.cache_directories(env: @env, home: @home, host_os: @host_os).each do |directory|
+        @distribution.cache_directories(env: @env, home: @home, host_os: @host_os).each do |directory|
           path = File.join(directory, "lib", artifact.fetch(:library))
           return path if File.file?(path)
         end
@@ -66,9 +97,9 @@ module WGPU
         library_path = File.join(cache_dir, "lib", artifact.fetch(:library))
         FileUtils.mkdir_p(cache_dir)
 
-        @output.puts "Downloading wgpu-native #{Distribution::VERSION} from GitHub..."
-        @output.puts "  URL: #{Distribution.release_url(artifact)}"
-        download_file(Distribution.release_url(artifact), archive_path)
+        @output.puts "Downloading wgpu-native #{@distribution.const_get(:VERSION)} from GitHub..."
+        @output.puts "  URL: #{@distribution.release_url(artifact)}"
+        download_file(@distribution.release_url(artifact), archive_path)
         verify_checksum!(archive_path, artifact.fetch(:sha256))
 
         @output.puts "Extracting to #{cache_dir}..."
@@ -97,18 +128,18 @@ module WGPU
       end
 
       def curl_available?
-        system("curl", "--version", out: File::NULL, err: File::NULL)
+        @command_runner.call("curl", "--version", out: File::NULL, err: File::NULL)
       end
 
       def download_with_curl(url, destination)
-        system("curl", "-fsSL", "-o", destination, url)
+        @command_runner.call("curl", "-fsSL", "-o", destination, url)
       end
 
       def download_with_ruby(url, destination, redirects = 5)
         raise InstallError, "Too many redirects while downloading #{url}" if redirects.zero?
 
         uri = URI.parse(url)
-        http = Net::HTTP.new(uri.host, uri.port)
+        http = @http_factory.call(uri)
         http.use_ssl = uri.scheme == "https"
         http.open_timeout = 10
         http.read_timeout = 120
@@ -144,10 +175,10 @@ module WGPU
       end
 
       def extract_with_rubyzip(archive_path, destination)
-        require "zip"
+        zip_file_class = @zip_file_loader.call
         destination_root = "#{File.expand_path(destination)}#{File::SEPARATOR}"
 
-        Zip::File.open(archive_path) do |zip_file|
+        zip_file_class.open(archive_path) do |zip_file|
           zip_file.each do |entry|
             target = File.expand_path(entry.name, destination)
             unless target.start_with?(destination_root)
@@ -164,7 +195,7 @@ module WGPU
       end
 
       def extract_with_powershell(archive_path, destination)
-        system(
+        @command_runner.call(
           "powershell",
           "-NoProfile",
           "-Command",
@@ -173,7 +204,7 @@ module WGPU
       end
 
       def extract_with_unzip(archive_path, destination)
-        system("unzip", "-o", "-q", archive_path, "-d", destination)
+        @command_runner.call("unzip", "-o", "-q", archive_path, "-d", destination)
       end
 
       def windows?
@@ -182,7 +213,7 @@ module WGPU
 
       def recovery_instructions
         <<~INSTRUCTIONS.chomp
-          Download the matching #{Distribution::VERSION} artifact manually and set:
+          Download the matching #{@distribution.const_get(:VERSION)} artifact manually and set:
             WGPU_LIB_PATH=/absolute/path/to/the/wgpu-native/shared-library
           See docs/installation.md for platform details.
         INSTRUCTIONS

data/lib/wgpu/native/loader.rb

@@ -6,6 +6,12 @@ require_relative "distribution"
 module WGPU
   module Native
     module OptionalFunctions
+      # Attaches a native function without failing library initialization.
+      #
+      # @param name [Symbol] exported function name
+      # @param arguments [Array] FFI argument types
+      # @param result [Symbol, FFI::Type] FFI return type
+      # @return [void]
       def attach_optional_function(name, arguments, result)
         attach_function(name, arguments, result)
         optional_functions[name] = true
@@ -18,10 +24,16 @@ module WGPU
         end
       end
 
+      # Reports whether an optional native function was attached.
+      # @param name [Symbol] exported function name
+      # @return [Boolean]
       def optional_function_available?(name)
         optional_functions.fetch(name, false)
       end
 
+      # Returns availability information for optional native functions.
+      #
+      # @return [Hash{Symbol => Boolean}] immutable capability snapshot
       def optional_capabilities
         optional_functions.dup.freeze
       end
@@ -37,6 +49,9 @@ module WGPU
     extend OptionalFunctions
 
     class << self
+      # Resolves the native library from an override or the versioned cache.
+      # @return [String] absolute shared-library path
+      # @raise [LoadError] when no library can be found
       def library_path
         if ENV["WGPU_LIB_PATH"] && !ENV["WGPU_LIB_PATH"].empty?
           path = File.expand_path(ENV["WGPU_LIB_PATH"])
@@ -60,10 +75,17 @@ module WGPU
         MSG
       end
 
+      # Returns the preferred native-library cache directory.
+      #
+      # @return [String] absolute cache directory
       def cache_dir
         Distribution.primary_cache_dir
       end
 
+      # Returns the shared-library filename for this platform.
+      #
+      # @return [String] platform-specific filename
+      # @raise [LoadError] if the platform is unsupported
       def library_name
         Distribution.artifact_for.fetch(:library)
       end

data/lib/wgpu/native/structs.rb

@@ -378,6 +378,22 @@ module WGPU
              :userdata2, :pointer
     end
 
+    class CreateComputePipelineAsyncCallbackInfo < FFI::Struct
+      layout :next_in_chain, :pointer,
+             :mode, :uint32,
+             :callback, :pointer,
+             :userdata1, :pointer,
+             :userdata2, :pointer
+    end
+
+    class CreateRenderPipelineAsyncCallbackInfo < FFI::Struct
+      layout :next_in_chain, :pointer,
+             :mode, :uint32,
+             :callback, :pointer,
+             :userdata1, :pointer,
+             :userdata2, :pointer
+    end
+
     class BufferMapCallbackInfo < FFI::Struct
       layout :next_in_chain, :pointer,
              :mode, :uint32,
@@ -395,7 +411,8 @@ module WGPU
              :mip_level_count, :uint32,
              :base_array_layer, :uint32,
              :array_layer_count, :uint32,
-             :aspect, TextureAspect
+             :aspect, TextureAspect,
+             :usage, :uint64
     end
 
     class SamplerDescriptor < FFI::Struct

data/lib/wgpu/native_resource.rb

@@ -13,6 +13,10 @@ module WGPU
 
     module_function
 
+    # Registers a live native resource when leak debugging is enabled.
+    #
+    # @param resource [NativeResource] resource to track
+    # @return [void]
     def register(resource)
       return unless WGPU.debug_leaks
 
@@ -22,10 +26,17 @@ module WGPU
       ObjectSpace.define_finalizer(resource, finalizer(object_id))
     end
 
+    # Removes a resource from leak tracking.
+    #
+    # @param resource [NativeResource] resource that was released
+    # @return [void]
     def unregister(resource)
       @mutex.synchronize { @resources.delete(resource.object_id) }
     end
 
+    # Warns about and clears every tracked resource.
+    #
+    # @return [void]
     def warn_remaining
       resources = @mutex.synchronize do
         remaining = @resources.values
@@ -53,25 +64,100 @@ module WGPU
 
   at_exit { LeakTracker.warn_remaining if WGPU.debug_leaks }
 
+  class DeviceCallbackLifetime
+    # Creates a shared lifetime that runs cleanup after its final owner releases.
+    # @yield cleanup invoked exactly once
+    def initialize(&cleanup)
+      @cleanup = cleanup
+      @references = 0
+      @completed = false
+      @mutex = Mutex.new
+    end
+
+    # Adds an owning native wrapper.
+    # @return [void]
+    def retain
+      @mutex.synchronize do
+        raise ResourceError, "device callback lifetime is already complete" if @completed
+
+        @references += 1
+      end
+    end
+
+    # Removes an owning native wrapper and cleans up after the final owner.
+    # @return [void]
+    def release
+      cleanup = @mutex.synchronize do
+        return if @completed
+
+        @references -= 1
+        raise ResourceError, "device callback lifetime reference underflow" if @references.negative?
+        next unless @references.zero?
+
+        @completed = true
+        @cleanup
+      end
+      cleanup&.call
+    end
+  end
+  private_constant :DeviceCallbackLifetime
+
   module CallbackKeepalive
     INITIALIZATION_MUTEX = Mutex.new
+    RETAINED_MUTEX = Mutex.new
+    RETAINED_CALLBACKS = {}
 
     module_function
 
+    # Retains an FFI callback for as long as an operation needs it.
+    #
+    # @param owner [Object] object that owns the callback registry
+    # @param callback [FFI::Function] callback to retain
+    # @return [Object] opaque token used by {.release}
     def retain(owner, callback)
       mutex, callbacks = storage_for(owner)
       token = Object.new
       mutex.synchronize { callbacks[token] = callback }
+      RETAINED_MUTEX.synchronize { RETAINED_CALLBACKS[token] = callback }
       token
     end
 
+    # Releases a retained callback token.
+    #
+    # @param owner [Object] object that owns the callback registry
+    # @param token [Object, nil] token returned by {.retain}
+    # @return [void]
     def release(owner, token)
       return unless token
 
       mutex, callbacks = storage_for(owner)
       mutex.synchronize { callbacks.delete(token) }
+      RETAINED_MUTEX.synchronize { RETAINED_CALLBACKS.delete(token) }
+    end
+
+    # Moves a retained callback token to another owner without unrooting it.
+    #
+    # @param from [Object] current registry owner
+    # @param to [Object] new registry owner
+    # @param token [Object] token returned by {.retain}
+    # @return [Boolean] whether the live token was transferred
+    def transfer(from, to, token)
+      return false unless token
+
+      callback = RETAINED_MUTEX.synchronize { RETAINED_CALLBACKS[token] }
+      return false unless callback
+
+      from_mutex, from_callbacks = storage_for(from)
+      to_mutex, to_callbacks = storage_for(to)
+      from_mutex.synchronize { from_callbacks.delete(token) }
+      to_mutex.synchronize { to_callbacks[token] = callback }
+      true
     end
 
+    # Returns the number of callbacks retained for an owner.
+    #
+    # @param owner [Object] object that owns the callback registry
+    # @return [Integer] retained callback count
     def count(owner)
       mutex, callbacks = storage_for(owner)
       mutex.synchronize { callbacks.length }
@@ -96,22 +182,53 @@ module WGPU
   module NativeResource
     GUARDED_METHOD_EXEMPTIONS = [:initialize, :release, :released?, :handle, :label, :inspect].freeze
 
+    module ClassMethods
+      private
+
+      def adopt_native_handle(handle, label: nil)
+        resource = allocate
+        resource.send(:initialize_native_resource, handle: handle, label: label)
+      end
+    end
+
     module Lifecycle
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
+      # Initializes a wrapper and registers its native-resource lifecycle.
+      #
+      # @param args [Array] positional arguments forwarded to the resource
+      # @param kwargs [Hash] keyword arguments forwarded to the resource
+      # @yield block forwarded to the resource initializer
+      # @return [NativeResource] initialized resource
       def initialize(*args, **kwargs, &block)
         super
-        @released = false
-        @label = kwargs[:label] if kwargs.key?(:label)
-        LeakTracker.register(self)
+        initialize_native_resource(label: kwargs.fetch(:label, UNSET))
+        attach_device_callback_lifetime_from_parent
       end
 
+      # Releases a resource once and unregisters it from leak tracking.
+      #
+      # @return [void]
       def release(...)
         return if released?
 
         result = super
+        release_device_callback_lifetime
         @released = true
         LeakTracker.unregister(self)
         result
       end
+
+      private
+
+      def initialize_native_resource(handle: UNSET, label: UNSET)
+        @handle = handle unless handle.equal?(UNSET)
+        @label = label unless label.equal?(UNSET)
+        @released = false
+        LeakTracker.register(self)
+        self
+      end
     end
 
     def self.included(base)
@@ -124,12 +241,15 @@ module WGPU
           super(*args, **kwargs, &block)
         end
       end
+      base.extend(ClassMethods)
       base.prepend(guard)
       base.prepend(Lifecycle)
     end
 
     attr_reader :label
 
+    # Reports whether the native handle has been released or is null.
+    # @return [Boolean]
     def released?
       return true if @released
       return false unless instance_variable_defined?(:@handle)
@@ -154,6 +274,9 @@ module WGPU
       release if block_given? && !released?
     end
 
+    # Returns a concise lifecycle-oriented representation.
+    #
+    # @return [String] class, optional label, and release state
     def inspect
       label_text = @label ? " label=#{@label.inspect}" : ""
       "#<#{self.class}#{label_text} released=#{released?}>"
@@ -161,6 +284,54 @@ module WGPU
 
     private
 
+    def attach_device_callback_lifetime(owner)
+      lifetime = owner&.instance_variable_get(:@device_callback_lifetime)
+      return self unless lifetime
+
+      lifetime.retain
+      @device_callback_lifetime = lifetime
+      @device_callback_lifetime_retained = true
+      self
+    end
+
+    def attach_device_callback_lifetime_from_parent
+      return if @device_callback_lifetime_retained
+
+      if @device_callback_lifetime
+        @device_callback_lifetime.retain
+        @device_callback_lifetime_retained = true
+        return
+      end
+
+      owner = @device || @encoder || @texture
+      attach_device_callback_lifetime(owner)
+    end
+
+    def release_device_callback_lifetime
+      return unless @device_callback_lifetime_retained
+
+      @device_callback_lifetime_retained = false
+      @device_callback_lifetime.release
+    end
+
+    def device_callback_lifetime_lease
+      lifetime = @device_callback_lifetime
+      return proc {} unless lifetime
+
+      lifetime.retain
+      released = false
+      mutex = Mutex.new
+      proc do
+        should_release = mutex.synchronize do
+          next false if released
+
+          released = true
+          true
+        end
+        lifetime.release if should_release
+      end
+    end
+
     def ensure_not_released!
       return unless released?
 

data/lib/wgpu/pipeline/bind_group.rb

@@ -4,6 +4,11 @@ module WGPU
   class BindGroup
     attr_reader :handle
 
+    # Creates bindings between shader slots and GPU resources.
+    # @param device [Device] owning device
+    # @param layout [BindGroupLayout] layout the entries must match
+    # @param entries [Array<Hash>] resource binding descriptors
+    # @raise [PipelineError] if native validation or creation fails
     def initialize(device, label: nil, layout:, entries:)
       @device = device
 
@@ -38,6 +43,10 @@ module WGPU
       end
     end
 
+    # Releases the native bind group handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuBindGroupRelease(@handle)

data/lib/wgpu/pipeline/bind_group_layout.rb

@@ -4,13 +4,22 @@ module WGPU
   class BindGroupLayout
     attr_reader :handle
 
-    def self.from_handle(handle)
-      layout = allocate
-      layout.instance_variable_set(:@handle, handle)
-      layout.instance_variable_set(:@device, nil)
+    # Wraps a native bind group layout handle owned by the caller.
+    #
+    # @param handle [FFI::Pointer] native bind group layout handle
+    # @param device [Device, nil] device whose callbacks the layout may use
+    # @return [BindGroupLayout] adopted wrapper
+    def self.from_handle(handle, device: nil)
+      layout = adopt_native_handle(handle)
+      layout.instance_variable_set(:@device, device)
+      layout.send(:attach_device_callback_lifetime, device)
       layout
     end
 
+    # Creates a layout describing shader-visible resource bindings.
+    # @param device [Device] owning device
+    # @param entries [Array<Hash>] binding layout descriptors
+    # @raise [PipelineError] if native validation or creation fails
     def initialize(device, label: nil, entries:)
       @device = device
       desc, @descriptor_keepalive = build_descriptor(label:, entries:)
@@ -26,6 +35,10 @@ module WGPU
       end
     end
 
+    # Releases the native bind group layout handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuBindGroupLayoutRelease(@handle)

data/lib/wgpu/pipeline/compute_pipeline.rb

@@ -4,6 +4,11 @@ module WGPU
   class ComputePipeline
     attr_reader :handle
 
+    # Creates a compute pipeline.
+    # @param device [Device] owning device
+    # @param layout [PipelineLayout, :auto, nil] pipeline layout
+    # @param compute [Hash] programmable compute stage descriptor
+    # @raise [PipelineError] if native validation or creation fails
     def initialize(device, label: nil, layout:, compute:)
       @device = device
       desc, @pointers = build_descriptor(label:, layout:, compute:)
@@ -18,12 +23,20 @@ module WGPU
       end
     end
 
+    # Returns the bind group layout inferred or assigned at an index.
+    # @param index [Integer] bind group index
+    # @return [BindGroupLayout]
+    # @raise [PipelineError] if no native layout is returned
     def get_bind_group_layout(index)
       handle = Native.wgpuComputePipelineGetBindGroupLayout(@handle, index)
       raise PipelineError, "Failed to get bind group layout at index #{index}" if handle.null?
-      BindGroupLayout.from_handle(handle)
+      BindGroupLayout.from_handle(handle, device: @device)
     end
 
+    # Releases the native compute pipeline handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuComputePipelineRelease(@handle)
@@ -40,9 +53,6 @@ module WGPU
         context: "compute pipeline stage"
       )
       @pointers = []
-      entry_point = compute[:entry_point] || "main"
-      entry_point_ptr = FFI::MemoryPointer.from_string(entry_point)
-      @pointers << entry_point_ptr
 
       desc = Native::ComputePipelineDescriptor.new
       desc[:next_in_chain] = nil
@@ -50,11 +60,12 @@ module WGPU
       desc[:layout] = normalize_layout(layout)
       desc[:compute][:next_in_chain] = nil
       desc[:compute][:module] = compute.fetch(:module).handle
-      desc[:compute][:entry_point][:data] = entry_point_ptr
-      desc[:compute][:entry_point][:length] = entry_point.bytesize
-      desc[:compute][:constant_count] = 0
-      desc[:compute][:constants] = nil
-      setup_constants(desc[:compute], compute[:constants])
+      DescriptorHelpers.set_nullable_string_view(
+        desc[:compute][:entry_point],
+        compute[:entry_point],
+        keepalive: @pointers
+      )
+      DescriptorHelpers.set_constants(desc[:compute], compute[:constants], keepalive: @pointers)
 
       [desc, @pointers]
     end
@@ -63,28 +74,5 @@ module WGPU
       return nil if layout.nil? || layout == :auto || layout == "auto"
       layout.handle
     end
-
-    def setup_constants(stage_desc, constants)
-      return if constants.nil? || constants.empty?
-
-      constants_ptr = FFI::MemoryPointer.new(Native::ConstantEntry, constants.size)
-      @pointers << constants_ptr
-
-      constants.each_with_index do |(key, value), i|
-        entry_ptr = constants_ptr + (i * Native::ConstantEntry.size)
-        entry = Native::ConstantEntry.new(entry_ptr)
-        entry[:next_in_chain] = nil
-
-        key_str = key.to_s
-        key_ptr = FFI::MemoryPointer.from_string(key_str)
-        @pointers << key_ptr
-        entry[:key][:data] = key_ptr
-        entry[:key][:length] = key_str.bytesize
-        entry[:value] = value.to_f
-      end
-
-      stage_desc[:constant_count] = constants.size
-      stage_desc[:constants] = constants_ptr
-    end
   end
 end