wgpu 1.1.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
 
@@ -17,11 +20,8 @@ module WGPU
     attach_function :wgpuInstanceProcessEvents,
                     [:pointer], :void
 
-    begin
-      attach_function :wgpuInstanceWaitAny,
-                      [:pointer, :size_t, :pointer, :uint64], WaitStatus
-    rescue FFI::NotFoundError
-    end
+    attach_optional_function :wgpuInstanceWaitAny,
+                             [:pointer, :size_t, :pointer, :uint64], WaitStatus
 
     attach_function :wgpuAdapterRelease,
                     [:pointer], :void
@@ -71,17 +71,22 @@ 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
 
-    begin
-      attach_function :wgpuDevicePoll,
-                      [:pointer, :uint32, :pointer], :uint32
-    rescue FFI::NotFoundError
-    end
+    attach_optional_function :wgpuDevicePoll,
+                             [:pointer, :uint32, :pointer], :uint32
 
     attach_function :wgpuQueueRelease,
                     [:pointer], :void
@@ -424,5 +429,11 @@ module WGPU
 
     attach_function :wgpuRenderBundleEncoderInsertDebugMarker,
                     [:pointer, StringView.by_value], :void
+
+    attach_optional_function :wgpuSetLogCallback,
+                             [:log_callback, :pointer], :void
+
+    attach_optional_function :wgpuSetLogLevel,
+                             [LogLevel], :void
   end
 end

data/lib/wgpu/native/installer.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "net/http"
+require "uri"
+
+require_relative "distribution"
+
+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,
+                     command_runner: nil, http_factory: nil, zip_file_loader: nil,
+                     distribution: Distribution)
+        @platform = platform
+        @env = env
+        @home = home
+        @host_os = host_os
+        @output = output
+        @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)
+        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
+
+      # Returns the primary versioned cache directory.
+      #
+      # @return [String]
+      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.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}..."
+        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?
+        @command_runner.call("curl", "--version", out: File::NULL, err: File::NULL)
+      end
+
+      def download_with_curl(url, destination)
+        @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 = @http_factory.call(uri)
+        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)
+        zip_file_class = @zip_file_loader.call
+        destination_root = "#{File.expand_path(destination)}#{File::SEPARATOR}"
+
+        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)
+              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)
+        @command_runner.call(
+          "powershell",
+          "-NoProfile",
+          "-Command",
+          "Expand-Archive -Force -LiteralPath '#{archive_path}' -DestinationPath '#{destination}'"
+        )
+      end
+
+      def extract_with_unzip(archive_path, destination)
+        @command_runner.call("unzip", "-o", "-q", archive_path, "-d", destination)
+      end
+
+      def windows?
+        /mingw|mswin/.match?(platform)
+      end
+
+      def recovery_instructions
+        <<~INSTRUCTIONS.chomp
+          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
+      end
+    end
+  end
+end

data/lib/wgpu/native/loader.rb

@@ -1,53 +1,93 @@
 # frozen_string_literal: true
 
 require "ffi"
-require "rbconfig"
+require_relative "distribution"
 
 module WGPU
   module Native
-    extend FFI::Library
+    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
+      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
+
+      # 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
+
+      private
 
-    WGPU_VERSION = "v27.0.4.0"
+      def optional_functions
+        @optional_functions ||= {}
+      end
+    end
+
+    extend FFI::Library
+    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"]
-          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
 
+      # Returns the preferred native-library cache directory.
+      #
+      # @return [String] absolute cache directory
       def cache_dir
-        File.join(Dir.home, ".cache", "wgpu-ruby", WGPU_VERSION)
+        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
-        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/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