wgpu 1.1.0 → 1.2.0

data/lib/wgpu/native/installer.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "net/http"
+require "uri"
+
+require_relative "distribution"
+
+module WGPU
+  module Native
+    class InstallError < StandardError; end
+
+    class Installer
+      attr_reader :platform
+
+      def initialize(platform: RUBY_PLATFORM, env: ENV, home: Dir.home,
+                     host_os: RbConfig::CONFIG["host_os"], output: $stdout)
+        @platform = platform
+        @env = env
+        @home = home
+        @host_os = host_os
+        @output = output
+      end
+
+      def install
+        return custom_library_path if custom_library_path
+
+        artifact = Distribution.artifact_for(platform)
+        cached_path = existing_library_path(artifact)
+        if cached_path
+          @output.puts "wgpu-native already cached at #{cached_path}"
+          return cached_path
+        end
+
+        install_artifact(artifact)
+      rescue LoadError, InstallError => error
+        raise InstallError, "#{error.message}\n\n#{recovery_instructions}"
+      end
+
+      def clean_path
+        Distribution.primary_cache_dir(env: @env, home: @home, host_os: @host_os)
+      end
+
+      private
+
+      def custom_library_path
+        path = @env["WGPU_LIB_PATH"]
+        return if path.nil? || path.empty?
+        raise InstallError, "WGPU_LIB_PATH points to a non-existent file: #{path}" unless File.file?(path)
+
+        File.expand_path(path)
+      end
+
+      def existing_library_path(artifact)
+        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
+        nil
+      end
+
+      def install_artifact(artifact)
+        cache_dir = clean_path
+        archive_path = File.join(cache_dir, artifact.fetch(:archive))
+        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)
+        verify_checksum!(archive_path, artifact.fetch(:sha256))
+
+        @output.puts "Extracting to #{cache_dir}..."
+        extract_zip(archive_path, cache_dir)
+        raise InstallError, "Archive did not contain lib/#{artifact.fetch(:library)}" unless File.file?(library_path)
+
+        @output.puts "wgpu-native installed successfully!"
+        library_path
+      ensure
+        FileUtils.rm_f(archive_path) if archive_path
+      end
+
+      def verify_checksum!(path, expected)
+        actual = Digest::SHA256.file(path).hexdigest
+        return if actual == expected
+
+        FileUtils.rm_f(path)
+        raise InstallError, "SHA-256 mismatch for #{File.basename(path)} (expected #{expected}, got #{actual})"
+      end
+
+      def download_file(url, destination)
+        return if curl_available? && download_with_curl(url, destination)
+        return if download_with_ruby(url, destination)
+
+        raise InstallError, "Download failed: #{url}"
+      end
+
+      def curl_available?
+        system("curl", "--version", out: File::NULL, err: File::NULL)
+      end
+
+      def download_with_curl(url, destination)
+        system("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.use_ssl = uri.scheme == "https"
+        http.open_timeout = 10
+        http.read_timeout = 120
+
+        http.request(Net::HTTP::Get.new(uri.request_uri)) do |response|
+          case response
+          when Net::HTTPRedirection
+            location = response["location"]
+            raise InstallError, "Redirect response did not include a location" unless location
+
+            location = URI.join(url, location).to_s
+            return download_with_ruby(location, destination, redirects - 1)
+          when Net::HTTPSuccess
+            File.open(destination, "wb") do |file|
+              response.read_body { |chunk| file.write(chunk) }
+            end
+            return true
+          end
+        end
+
+        false
+      rescue SystemCallError, SocketError, URI::InvalidURIError => error
+        @output.puts "Ruby download failed: #{error.message}"
+        false
+      end
+
+      def extract_zip(archive_path, destination)
+        return if extract_with_rubyzip(archive_path, destination)
+        return if windows? && extract_with_powershell(archive_path, destination)
+        return if extract_with_unzip(archive_path, destination)
+
+        raise InstallError, "Failed to extract zip; install the rubyzip gem or a supported system extractor"
+      end
+
+      def extract_with_rubyzip(archive_path, destination)
+        require "zip"
+        destination_root = "#{File.expand_path(destination)}#{File::SEPARATOR}"
+
+        Zip::File.open(archive_path) do |zip_file|
+          zip_file.each do |entry|
+            target = File.expand_path(entry.name, destination)
+            unless target.start_with?(destination_root)
+              raise InstallError, "Archive entry escapes destination: #{entry.name}"
+            end
+
+            FileUtils.mkdir_p(entry.directory? ? target : File.dirname(target))
+            entry.extract(target) { true } unless entry.directory?
+          end
+        end
+        true
+      rescue LoadError
+        false
+      end
+
+      def extract_with_powershell(archive_path, destination)
+        system(
+          "powershell",
+          "-NoProfile",
+          "-Command",
+          "Expand-Archive -Force -LiteralPath '#{archive_path}' -DestinationPath '#{destination}'"
+        )
+      end
+
+      def extract_with_unzip(archive_path, destination)
+        system("unzip", "-o", "-q", archive_path, "-d", destination)
+      end
+
+      def windows?
+        /mingw|mswin/.match?(platform)
+      end
+
+      def recovery_instructions
+        <<~INSTRUCTIONS.chomp
+          Download the matching #{Distribution::VERSION} artifact manually and set:
+            WGPU_LIB_PATH=/absolute/path/to/the/wgpu-native/shared-library
+          See docs/installation.md for platform details.
+        INSTRUCTIONS
+      end
+    end
+  end
+end

data/lib/wgpu/native/loader.rb

@@ -1,53 +1,71 @@
 # frozen_string_literal: true
 
 require "ffi"
-require "rbconfig"
+require_relative "distribution"
 
 module WGPU
   module Native
-    extend FFI::Library
+    module OptionalFunctions
+      def attach_optional_function(name, arguments, result)
+        attach_function(name, arguments, result)
+        optional_functions[name] = true
+      rescue FFI::NotFoundError
+        optional_functions[name] = false
+        define_singleton_method(name) do |*|
+          raise WGPU::Error,
+            "Optional wgpu-native function #{name} is unavailable in the loaded library " \
+            "(expected #{Distribution::VERSION})"
+        end
+      end
+
+      def optional_function_available?(name)
+        optional_functions.fetch(name, false)
+      end
+
+      def optional_capabilities
+        optional_functions.dup.freeze
+      end
+
+      private
 
-    WGPU_VERSION = "v27.0.4.0"
+      def optional_functions
+        @optional_functions ||= {}
+      end
+    end
+
+    extend FFI::Library
+    extend OptionalFunctions
 
     class << self
       def library_path
-        if ENV["WGPU_LIB_PATH"]
-          path = ENV["WGPU_LIB_PATH"]
+        if ENV["WGPU_LIB_PATH"] && !ENV["WGPU_LIB_PATH"].empty?
+          path = File.expand_path(ENV["WGPU_LIB_PATH"])
           raise LoadError, "WGPU_LIB_PATH points to non-existent file: #{path}" unless File.exist?(path)
           return path
         end
 
-        cached_path = File.join(cache_dir, "lib", library_name)
-        return cached_path if File.exist?(cached_path)
+        cached_path = Distribution.library_paths.find { |path| File.file?(path) }
+        return cached_path if cached_path
 
         raise LoadError, <<~MSG
           wgpu-native library not found.
-          Expected at: #{cached_path}
+          Searched:
+            #{Distribution.library_paths.join("\n  ")}
 
           Try reinstalling the gem:
             gem install wgpu
 
           Or set WGPU_LIB_PATH environment variable to your custom wgpu-native build.
+          See docs/installation.md for manual installation instructions.
         MSG
       end
 
       def cache_dir
-        File.join(Dir.home, ".cache", "wgpu-ruby", WGPU_VERSION)
+        Distribution.primary_cache_dir
       end
 
       def library_name
-        case host_os
-        when /linux/ then "libwgpu_native.so"
-        when /darwin/ then "libwgpu_native.dylib"
-        when /mingw|mswin/ then "wgpu_native.dll"
-        else raise LoadError, "Unsupported OS: #{host_os}"
-        end
-      end
-
-      private
-
-      def host_os
-        RbConfig::CONFIG["host_os"]
+        Distribution.artifact_for.fetch(:library)
       end
     end
 

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