wgpu 1.1.0 → 1.2.1

data/lib/wgpu/native_resource.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+module WGPU
+  class << self
+    attr_accessor :debug_leaks
+  end
+
+  self.debug_leaks = ENV["WGPU_DEBUG_LEAKS"] == "1"
+
+  module LeakTracker
+    @resources = {}
+    @mutex = Mutex.new
+
+    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
+
+      object_id = resource.object_id
+      description = describe(resource)
+      @mutex.synchronize { @resources[object_id] = description }
+      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
+        @resources.clear
+        remaining
+      end
+      resources.each { |description| warn "WGPU resource leaked: #{description}" }
+    end
+
+    def describe(resource)
+      label = resource.label
+      label_text = label ? " label=#{label.inspect}" : ""
+      "#{resource.class}#{label_text}"
+    end
+    private_class_method :describe
+
+    def finalizer(object_id)
+      proc do
+        description = @mutex.synchronize { @resources.delete(object_id) }
+        warn "WGPU resource leaked: #{description}" if description
+      end
+    end
+    private_class_method :finalizer
+  end
+
+  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 }
+    end
+
+    def storage_for(owner)
+      INITIALIZATION_MUTEX.synchronize do
+        mutex = owner.instance_variable_get(:@wgpu_callback_keepalive_mutex)
+        callbacks = owner.instance_variable_get(:@wgpu_callback_keepalive)
+        unless mutex && callbacks
+          mutex = Mutex.new
+          callbacks = {}
+          owner.instance_variable_set(:@wgpu_callback_keepalive_mutex, mutex)
+          owner.instance_variable_set(:@wgpu_callback_keepalive, callbacks)
+        end
+        [mutex, callbacks]
+      end
+    end
+    private_class_method :storage_for
+  end
+
+  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
+        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)
+      guard = Module.new
+      base.public_instance_methods(false).each do |method_name|
+        next if GUARDED_METHOD_EXEMPTIONS.include?(method_name)
+
+        guard.define_method(method_name) do |*args, **kwargs, &block|
+          ensure_not_released!
+          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)
+      return true if @handle.nil?
+
+      @handle.respond_to?(:null?) && @handle.null?
+    end
+
+    # Yields this wrapper and always releases it when the block exits.
+    #
+    # This is Ruby convenience API; WebGPU itself has no block-scoped resource
+    # primitive.
+    #
+    # @yieldparam resource [NativeResource] this resource
+    # @return the block result
+    def use
+      raise ArgumentError, "block is required" unless block_given?
+
+      ensure_not_released!
+      yield self
+    ensure
+      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?}>"
+    end
+
+    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?
+
+      label_text = @label ? " (#{@label})" : ""
+      raise ResourceError, "#{self.class}#{label_text} has been released"
+    end
+  end
+end

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)
@@ -47,6 +56,18 @@ module WGPU
     private
 
     def create_entry(entry_hash)
+      DescriptorHelpers.validate_keys!(
+        entry_hash,
+        allowed: %i[binding buffer offset size sampler texture_view],
+        required: [:binding],
+        context: "bind group entry"
+      )
+      resources = %i[buffer sampler texture_view].select { |key| entry_hash[key] }
+      unless resources.one?
+        raise ArgumentError,
+          "bind group entry must define exactly one resource (:buffer, :sampler, or :texture_view)"
+      end
+
       entry = Native::BindGroupEntry.new
       entry[:next_in_chain] = nil
       entry[:binding] = entry_hash[:binding]

data/lib/wgpu/pipeline/bind_group_layout.rb

@@ -4,39 +4,30 @@ 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
-
-      entries_array = entries.map { |e| create_entry(e) }
-      entries_ptr = FFI::MemoryPointer.new(Native::BindGroupLayoutEntry, entries_array.size)
-      entries_array.each_with_index do |entry, i|
-        offset = i * Native::BindGroupLayoutEntry.size
-        (entries_ptr + offset).put_bytes(0, entry.pointer.read_bytes(Native::BindGroupLayoutEntry.size))
-      end
-
-      desc = Native::BindGroupLayoutDescriptor.new
-      desc[:next_in_chain] = nil
-      if label
-        label_ptr = FFI::MemoryPointer.from_string(label)
-        desc[:label][:data] = label_ptr
-        desc[:label][:length] = label.bytesize
-      else
-        desc[:label][:data] = nil
-        desc[:label][:length] = 0
-      end
-      desc[:entry_count] = entries_array.size
-      desc[:entries] = entries_ptr
+      desc, @descriptor_keepalive = build_descriptor(label:, entries:)
 
       device.push_error_scope(:validation)
       @handle = Native.wgpuDeviceCreateBindGroupLayout(device.handle, desc)
       error = device.pop_error_scope
+      @descriptor_keepalive = nil
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
         msg = error[:message] || "Failed to create bind group layout"
@@ -44,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)
@@ -52,7 +47,39 @@ module WGPU
 
     private
 
+    def build_descriptor(label:, entries:)
+      keepalive = []
+      entries_array = entries.map { |entry| create_entry(entry) }
+      entries_ptr = FFI::MemoryPointer.new(Native::BindGroupLayoutEntry, entries_array.size)
+      entries_array.each_with_index do |entry, index|
+        offset = index * Native::BindGroupLayoutEntry.size
+        (entries_ptr + offset).put_bytes(0, entry.pointer.read_bytes(Native::BindGroupLayoutEntry.size))
+      end
+      keepalive.concat(entries_array)
+      keepalive << entries_ptr
+
+      desc = Native::BindGroupLayoutDescriptor.new
+      desc[:next_in_chain] = nil
+      DescriptorHelpers.set_label(desc, label, keepalive:)
+      desc[:entry_count] = entries_array.size
+      desc[:entries] = entries_ptr
+      [desc, keepalive]
+    end
+
     def create_entry(entry_hash)
+      DescriptorHelpers.validate_keys!(
+        entry_hash,
+        allowed: %i[binding visibility buffer sampler texture storage_texture],
+        required: %i[binding visibility],
+        context: "bind group layout entry"
+      )
+      variants = %i[buffer sampler texture storage_texture].select { |key| entry_hash[key] }
+      unless variants.one?
+        raise ArgumentError,
+          "bind group layout entry must define exactly one resource variant " \
+          "(:buffer, :sampler, :texture, or :storage_texture)"
+      end
+
       entry = Native::BindGroupLayoutEntry.new
       entry[:next_in_chain] = nil
       entry[:binding] = entry_hash[:binding]
@@ -78,44 +105,84 @@ module WGPU
 
       if entry_hash[:buffer]
         buffer_info = entry_hash[:buffer]
-        entry[:buffer][:type] = buffer_info[:type] || :storage
+        DescriptorHelpers.validate_keys!(
+          buffer_info,
+          allowed: %i[type has_dynamic_offset min_binding_size],
+          context: "buffer binding layout"
+        )
+        entry[:buffer][:type] = Native::EnumHelper.coerce(
+          Native::BufferBindingType,
+          buffer_info[:type] || :storage,
+          name: "buffer binding type"
+        )
         entry[:buffer][:has_dynamic_offset] = buffer_info[:has_dynamic_offset] ? 1 : 0
         entry[:buffer][:min_binding_size] = buffer_info[:min_binding_size] || 0
       end
 
       if entry_hash[:sampler]
         sampler_info = entry_hash[:sampler]
-        entry[:sampler][:type] = sampler_info[:type] || :filtering
+        DescriptorHelpers.validate_keys!(
+          sampler_info,
+          allowed: [:type],
+          context: "sampler binding layout"
+        )
+        entry[:sampler][:type] = Native::EnumHelper.coerce(
+          Native::SamplerBindingType,
+          sampler_info[:type] || :filtering,
+          name: "sampler binding type"
+        )
       end
 
       if entry_hash[:texture]
         texture_info = entry_hash[:texture]
-        entry[:texture][:sample_type] = texture_info[:sample_type] || :float
-        entry[:texture][:view_dimension] = texture_info[:view_dimension] || :d2
+        DescriptorHelpers.validate_keys!(
+          texture_info,
+          allowed: %i[sample_type view_dimension multisampled],
+          context: "texture binding layout"
+        )
+        entry[:texture][:sample_type] = Native::EnumHelper.coerce(
+          Native::TextureSampleType,
+          texture_info[:sample_type] || :float,
+          name: "texture sample type"
+        )
+        entry[:texture][:view_dimension] = Native::EnumHelper.coerce(
+          Native::TextureViewDimension,
+          texture_info[:view_dimension] || :d2,
+          name: "texture view dimension"
+        )
         entry[:texture][:multisampled] = texture_info[:multisampled] ? 1 : 0
       end
 
       if entry_hash[:storage_texture]
         st_info = entry_hash[:storage_texture]
-        entry[:storage_texture][:access] = st_info[:access] || :write_only
-        entry[:storage_texture][:format] = st_info[:format]
-        entry[:storage_texture][:view_dimension] = st_info[:view_dimension] || :d2
+        DescriptorHelpers.validate_keys!(
+          st_info,
+          allowed: %i[access format view_dimension],
+          required: [:format],
+          context: "storage texture binding layout"
+        )
+        entry[:storage_texture][:access] = Native::EnumHelper.coerce(
+          Native::StorageTextureAccess,
+          st_info[:access] || :write_only,
+          name: "storage texture access"
+        )
+        entry[:storage_texture][:format] = Native::EnumHelper.coerce(
+          Native::TextureFormat,
+          st_info.fetch(:format),
+          name: "storage texture format"
+        )
+        entry[:storage_texture][:view_dimension] = Native::EnumHelper.coerce(
+          Native::TextureViewDimension,
+          st_info[:view_dimension] || :d2,
+          name: "texture view dimension"
+        )
       end
 
       entry
     end
 
     def normalize_visibility(visibility)
-      case visibility
-      when Integer
-        visibility
-      when Symbol
-        Native::ShaderStage[visibility]
-      when Array
-        visibility.reduce(0) { |acc, v| acc | Native::ShaderStage[v] }
-      else
-        raise ArgumentError, "Invalid visibility: #{visibility}"
-      end
+      Native::EnumHelper.coerce_flags(Native::ShaderStage, visibility, name: "shader visibility")
     end
   end
 end

data/lib/wgpu/pipeline/compute_pipeline.rb

@@ -4,34 +4,14 @@ 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
-      @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
-      if label
-        label_ptr = FFI::MemoryPointer.from_string(label)
-        @pointers << label_ptr
-        desc[:label][:data] = label_ptr
-        desc[:label][:length] = label.bytesize
-      else
-        desc[:label][:data] = nil
-        desc[:label][:length] = 0
-      end
-      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])
+      desc, @pointers = build_descriptor(label:, layout:, compute:)
 
       device.push_error_scope(:validation)
       @handle = Native.wgpuDeviceCreateComputePipeline(device.handle, desc)
@@ -43,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)
@@ -57,32 +45,34 @@ module WGPU
 
     private
 
+    def build_descriptor(label:, layout:, compute:)
+      DescriptorHelpers.validate_keys!(
+        compute,
+        allowed: %i[module entry_point constants],
+        required: [:module],
+        context: "compute pipeline stage"
+      )
+      @pointers = []
+
+      desc = Native::ComputePipelineDescriptor.new
+      desc[:next_in_chain] = nil
+      DescriptorHelpers.set_label(desc, label, keepalive: @pointers)
+      desc[:layout] = normalize_layout(layout)
+      desc[:compute][:next_in_chain] = nil
+      desc[:compute][:module] = compute.fetch(:module).handle
+      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
+
     def normalize_layout(layout)
       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