wgpu 1.0.0 → 1.2.0

data/lib/wgpu/native/enums.rb

@@ -50,13 +50,22 @@ module WGPU
       :success, 0x00000001,
       :instance_dropped, 0x00000002,
       :unavailable, 0x00000003,
-      :error, 0x00000004
+      :error, 0x00000004,
+      :unknown, 0x00000005
     )
 
     RequestDeviceStatus = enum(
       :success, 0x00000001,
       :instance_dropped, 0x00000002,
-      :error, 0x00000003
+      :error, 0x00000003,
+      :unknown, 0x00000004
+    )
+
+    DeviceLostReason = enum(
+      :unknown, 0x00000001,
+      :destroyed, 0x00000002,
+      :instance_dropped, 0x00000003,
+      :failed_creation, 0x00000004
     )
 
     BufferMapState = enum(
@@ -65,11 +74,18 @@ module WGPU
       :mapped, 0x00000003
     )
 
+    CallbackMode = enum(
+      :wait_any_only, 0x00000001,
+      :allow_process_events, 0x00000002,
+      :allow_spontaneous, 0x00000003
+    )
+
     MapAsyncStatus = enum(
       :success, 0x00000001,
       :instance_dropped, 0x00000002,
       :error, 0x00000003,
-      :aborted, 0x00000004
+      :aborted, 0x00000004,
+      :unknown, 0x00000005
     )
 
     BufferUsage = {
@@ -274,7 +290,9 @@ module WGPU
       :sint32, 0x00000024,
       :sint32x2, 0x00000025,
       :sint32x3, 0x00000026,
-      :sint32x4, 0x00000027
+      :sint32x4, 0x00000027,
+      :unorm10_10_10_2, 0x00000028,
+      :unorm8x4_bgra, 0x00000029
     )
 
     IndexFormat = enum(
@@ -357,11 +375,11 @@ module WGPU
       :undefined, 0x00000000,
       :never, 0x00000001,
       :less, 0x00000002,
-      :less_equal, 0x00000003,
-      :greater, 0x00000004,
-      :greater_equal, 0x00000005,
-      :equal, 0x00000006,
-      :not_equal, 0x00000007,
+      :equal, 0x00000003,
+      :less_equal, 0x00000004,
+      :greater, 0x00000005,
+      :not_equal, 0x00000006,
+      :greater_equal, 0x00000007,
       :always, 0x00000008
     )
 
@@ -458,7 +476,9 @@ module WGPU
       :timeout, 0x00000003,
       :outdated, 0x00000004,
       :lost, 0x00000005,
-      :error, 0x00000006
+      :out_of_memory, 0x00000006,
+      :device_lost, 0x00000007,
+      :error, 0x00000008
     )
 
     QueryType = enum(
@@ -482,8 +502,16 @@ module WGPU
 
     PopErrorScopeStatus = enum(
       :success, 0x00000001,
-      :callback_cancelled, 0x00000002,
-      :error, 0x00000003
+      :instance_dropped, 0x00000002,
+      :empty_stack, 0x00000003
+    )
+
+    WaitStatus = enum(
+      :success, 0x00000001,
+      :timed_out, 0x00000002,
+      :unsupported_timeout, 0x00000003,
+      :unsupported_count, 0x00000004,
+      :unsupported_mixed_sources, 0x00000005
     )
 
     QueueWorkDoneStatus = enum(
@@ -506,6 +534,15 @@ module WGPU
       :info, 0x00000003
     )
 
+    LogLevel = enum(
+      :off, 0x00000000,
+      :error, 0x00000001,
+      :warn, 0x00000002,
+      :info, 0x00000003,
+      :debug, 0x00000004,
+      :trace, 0x00000005
+    )
+
     FeatureName = enum(
       :undefined, 0x00000000,
       :depth_clip_control, 0x00000001,
@@ -523,7 +560,39 @@ module WGPU
       :float32_filterable, 0x0000000D,
       :float32_blendable, 0x0000000E,
       :clip_distances, 0x0000000F,
-      :dual_source_blending, 0x00000010
+      :dual_source_blending, 0x00000010,
+      # wgpu-native extensions from wgpu.h.
+      :push_constants, 0x00030001,
+      :texture_adapter_specific_format_features, 0x00030002,
+      :multi_draw_indirect_count, 0x00030004,
+      :vertex_writable_storage, 0x00030005,
+      :texture_binding_array, 0x00030006,
+      :sampled_texture_and_storage_buffer_array_non_uniform_indexing, 0x00030007,
+      :pipeline_statistics_query, 0x00030008,
+      :storage_resource_binding_array, 0x00030009,
+      :partially_bound_binding_array, 0x0003000A,
+      :texture_format_16bit_norm, 0x0003000B,
+      :texture_compression_astc_hdr, 0x0003000C,
+      :mappable_primary_buffers, 0x0003000E,
+      :buffer_binding_array, 0x0003000F,
+      :uniform_buffer_and_storage_texture_array_non_uniform_indexing, 0x00030010,
+      :polygon_mode_line, 0x00030013,
+      :polygon_mode_point, 0x00030014,
+      :conservative_rasterization, 0x00030015,
+      :spirv_shader_passthrough, 0x00030017,
+      :vertex_attribute_64bit, 0x00030019,
+      :texture_format_nv12, 0x0003001A,
+      :ray_query, 0x0003001C,
+      :shader_f64, 0x0003001D,
+      :shader_i16, 0x0003001E,
+      :shader_primitive_index, 0x0003001F,
+      :shader_early_depth_test, 0x00030020,
+      :subgroup, 0x00030021,
+      :subgroup_vertex, 0x00030022,
+      :subgroup_barrier, 0x00030023,
+      :timestamp_query_inside_encoders, 0x00030024,
+      :timestamp_query_inside_passes, 0x00030025,
+      :shader_int64, 0x00030026
     )
   end
 end

data/lib/wgpu/native/functions.rb

@@ -9,7 +9,7 @@ module WGPU
                     [:pointer], :void
 
     attach_function :wgpuInstanceRequestAdapter,
-                    [:pointer, RequestAdapterOptions.by_ref, RequestAdapterCallbackInfo.by_value], :pointer
+                    [:pointer, RequestAdapterOptions.by_ref, RequestAdapterCallbackInfo.by_value], Future.by_value
 
     attach_function :wgpuInstanceEnumerateAdapters,
                     [:pointer, :pointer, :pointer], :size_t
@@ -17,6 +17,9 @@ module WGPU
     attach_function :wgpuInstanceProcessEvents,
                     [:pointer], :void
 
+    attach_optional_function :wgpuInstanceWaitAny,
+                             [:pointer, :size_t, :pointer, :uint64], WaitStatus
+
     attach_function :wgpuAdapterRelease,
                     [:pointer], :void
 
@@ -24,7 +27,7 @@ module WGPU
                     [:pointer, AdapterInfo.by_ref], :void
 
     attach_function :wgpuAdapterRequestDevice,
-                    [:pointer, DeviceDescriptor.by_ref, RequestDeviceCallbackInfo.by_value], :pointer
+                    [:pointer, DeviceDescriptor.by_ref, RequestDeviceCallbackInfo.by_value], Future.by_value
 
     attach_function :wgpuAdapterGetFeatures,
                     [:pointer, :pointer], :void
@@ -71,8 +74,8 @@ module WGPU
     attach_function :wgpuDeviceCreateCommandEncoder,
                     [:pointer, CommandEncoderDescriptor.by_ref], :pointer
 
-    attach_function :wgpuDevicePoll,
-                    [:pointer, :uint32, :pointer], :uint32
+    attach_optional_function :wgpuDevicePoll,
+                             [:pointer, :uint32, :pointer], :uint32
 
     attach_function :wgpuQueueRelease,
                     [:pointer], :void
@@ -81,7 +84,7 @@ module WGPU
                     [:pointer, :size_t, :pointer], :void
 
     attach_function :wgpuQueueOnSubmittedWorkDone,
-                    [:pointer, QueueWorkDoneCallbackInfo.by_value], :pointer
+                    [:pointer, QueueWorkDoneCallbackInfo.by_value], Future.by_value
 
     attach_function :wgpuQueueWriteBuffer,
                     [:pointer, :pointer, :uint64, :pointer, :size_t], :void
@@ -96,7 +99,7 @@ module WGPU
                     [:pointer], :void
 
     attach_function :wgpuBufferMapAsync,
-                    [:pointer, :uint64, :size_t, :size_t, BufferMapCallbackInfo.by_value], :pointer
+                    [:pointer, :uint64, :size_t, :size_t, BufferMapCallbackInfo.by_value], Future.by_value
 
     attach_function :wgpuBufferUnmap,
                     [:pointer], :void
@@ -120,7 +123,7 @@ module WGPU
                     [:pointer], :void
 
     attach_function :wgpuShaderModuleGetCompilationInfo,
-                    [:pointer, CompilationInfoCallbackInfo.by_value], :pointer
+                    [:pointer, CompilationInfoCallbackInfo.by_value], Future.by_value
 
     attach_function :wgpuCommandEncoderRelease,
                     [:pointer], :void
@@ -363,7 +366,7 @@ module WGPU
                     [:pointer, ErrorFilter], :void
 
     attach_function :wgpuDevicePopErrorScope,
-                    [:pointer, PopErrorScopeCallbackInfo.by_value], :pointer
+                    [:pointer, PopErrorScopeCallbackInfo.by_value], Future.by_value
 
     attach_function :wgpuComputePipelineGetBindGroupLayout,
                     [:pointer, :uint32], :pointer
@@ -415,5 +418,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,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
 
@@ -59,3 +77,4 @@ require_relative "enums"
 require_relative "structs"
 require_relative "callbacks"
 require_relative "functions"
+require_relative "capabilities"

data/lib/wgpu/native/structs.rb

@@ -17,6 +17,15 @@ module WGPU
              :s_type, SType
     end
 
+    class Future < FFI::Struct
+      layout :id, :uint64
+    end
+
+    class FutureWaitInfo < FFI::Struct
+      layout :future, Future.by_value,
+             :completed, :uint32
+    end
+
     class InstanceCapabilities < FFI::Struct
       layout :next_in_chain, :pointer,
              :timed_wait_any_enable, :uint32,
@@ -58,13 +67,15 @@ module WGPU
       layout :next_in_chain, :pointer,
              :mode, :uint32,
              :callback, :pointer,
-             :userdata, :pointer
+             :userdata1, :pointer,
+             :userdata2, :pointer
     end
 
     class UncapturedErrorCallbackInfo < FFI::Struct
       layout :next_in_chain, :pointer,
              :callback, :pointer,
-             :userdata, :pointer
+             :userdata1, :pointer,
+             :userdata2, :pointer
     end
 
     class PopErrorScopeCallbackInfo < FFI::Struct
@@ -355,21 +366,24 @@ module WGPU
       layout :next_in_chain, :pointer,
              :mode, :uint32,
              :callback, :pointer,
-             :userdata, :pointer
+             :userdata1, :pointer,
+             :userdata2, :pointer
     end
 
     class RequestDeviceCallbackInfo < FFI::Struct
       layout :next_in_chain, :pointer,
              :mode, :uint32,
              :callback, :pointer,
-             :userdata, :pointer
+             :userdata1, :pointer,
+             :userdata2, :pointer
     end
 
     class BufferMapCallbackInfo < FFI::Struct
       layout :next_in_chain, :pointer,
              :mode, :uint32,
              :callback, :pointer,
-             :userdata, :pointer
+             :userdata1, :pointer,
+             :userdata2, :pointer
     end
 
     class TextureViewDescriptor < FFI::Struct