wgpu 1.0.0 → 1.2.0

data/lib/wgpu/native_resource.rb

@@ -0,0 +1,171 @@
+# 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
+
+    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
+
+    def unregister(resource)
+      @mutex.synchronize { @resources.delete(resource.object_id) }
+    end
+
+    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 }
+
+  module CallbackKeepalive
+    INITIALIZATION_MUTEX = Mutex.new
+
+    module_function
+
+    def retain(owner, callback)
+      mutex, callbacks = storage_for(owner)
+      token = Object.new
+      mutex.synchronize { callbacks[token] = callback }
+      token
+    end
+
+    def release(owner, token)
+      return unless token
+
+      mutex, callbacks = storage_for(owner)
+      mutex.synchronize { callbacks.delete(token) }
+    end
+
+    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 Lifecycle
+      def initialize(*args, **kwargs, &block)
+        super
+        @released = false
+        @label = kwargs[:label] if kwargs.key?(:label)
+        LeakTracker.register(self)
+      end
+
+      def release(...)
+        return if released?
+
+        result = super
+        @released = true
+        LeakTracker.unregister(self)
+        result
+      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.prepend(guard)
+      base.prepend(Lifecycle)
+    end
+
+    attr_reader :label
+
+    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
+
+    def inspect
+      label_text = @label ? " label=#{@label.inspect}" : ""
+      "#<#{self.class}#{label_text} released=#{released?}>"
+    end
+
+    private
+
+    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

@@ -47,6 +47,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

@@ -13,30 +13,12 @@ module WGPU
 
     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"
@@ -52,7 +34,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 +92,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

@@ -6,32 +6,7 @@ module WGPU
 
     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)
@@ -57,6 +32,33 @@ 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 = []
+      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
+      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
+      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]
+    end
+
     def normalize_layout(layout)
       return nil if layout.nil? || layout == :auto || layout == "auto"
       layout.handle