wgpu 1.1.0 → 1.2.0

data/lib/wgpu/descriptor_helpers.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module WGPU
+  module DescriptorHelpers
+    module_function
+
+    def set_label(descriptor, label, keepalive:)
+      if label
+        pointer = FFI::MemoryPointer.from_string(label)
+        keepalive << pointer
+        descriptor[:label][:data] = pointer
+        descriptor[:label][:length] = label.bytesize
+      else
+        descriptor[:label][:data] = nil
+        descriptor[:label][:length] = 0
+      end
+    end
+
+    def uint32_array(values, keepalive:)
+      return nil if values.empty?
+
+      pointer = FFI::MemoryPointer.new(:uint32, values.length)
+      pointer.write_array_of_uint32(values)
+      keepalive << pointer
+      pointer
+    end
+
+    def validate_keys!(options, allowed:, required: [], context: "descriptor")
+      return options unless options.is_a?(Hash)
+
+      missing = required - options.keys
+      raise ArgumentError, "#{context} is missing required keys: #{missing.map(&:inspect).join(", ")}" unless missing.empty?
+
+      unknown = options.keys - allowed
+      warn "Unknown #{context} keys: #{unknown.map(&:inspect).join(", ")}" unless unknown.empty?
+      options
+    end
+  end
+end

data/lib/wgpu/error.rb

@@ -2,6 +2,11 @@
 
 module WGPU
   class Error < StandardError; end
+  class ValidationError < Error; end
+  class OutOfMemoryError < Error; end
+  class InternalError < Error; end
+  class DeviceLostError < Error; end
+  class TimeoutError < Error; end
   class InitializationError < Error; end
   class AdapterError < Error; end
   class DeviceError < Error; end
@@ -12,5 +17,55 @@ module WGPU
   class PipelineError < Error; end
   class CommandError < Error; end
   class SurfaceError < Error; end
+  class SurfaceAcquisitionError < SurfaceError
+    attr_reader :status
+
+    def initialize(status, message = nil)
+      @status = status
+      super(message || "Failed to get current surface texture: #{status}")
+    end
+  end
   class RenderBundleError < Error; end
+
+  GPUError = Data.define(:type, :message) do
+    def self.from_hash(error)
+      return if error.nil? || error[:type].nil? || error[:type] == :no_error
+
+      new(type: error[:type], message: error[:message].to_s)
+    end
+
+    def exception_class
+      {
+        validation: ValidationError,
+        out_of_memory: OutOfMemoryError,
+        internal: InternalError,
+        device_lost: DeviceLostError
+      }.fetch(type, Error)
+    end
+
+    def raise!
+      raise exception_class, "GPU error (#{type}): #{message}"
+    end
+
+    def to_h
+      { type:, message: }
+    end
+  end
+
+  CompilationMessage = Data.define(
+    :type,
+    :message,
+    :line_num,
+    :line_pos,
+    :offset,
+    :length
+  ) do
+    alias line line_num
+    alias column line_pos
+
+    def to_s
+      location = line_num&.positive? ? "#{line_num}:#{line_pos}" : "unknown location"
+      "#{location}: #{type}: #{message}"
+    end
+  end
 end

data/lib/wgpu/logging.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module WGPU
+  class << self
+    # Returns the configured wgpu-native log level.
+    attr_reader :log_level
+
+    # Sets the wgpu-native log level.
+    #
+    # @param level [Symbol, Integer] one of `:off`, `:error`, `:warn`, `:info`,
+    #   `:debug`, or `:trace`
+    # @return [Symbol, Integer] the supplied level
+    def log_level=(level)
+      ensure_native_logging!
+      value = Native::EnumHelper.coerce(Native::LogLevel, level, name: "log level")
+      Native.wgpuSetLogLevel(value)
+      @log_level = Native::LogLevel[value]
+    end
+
+    # Registers a process-wide wgpu-native log handler.
+    #
+    # The native callback is retained by the WGPU module for the rest of the
+    # process, or until this method replaces it.
+    #
+    # @yieldparam level [Symbol] native log severity
+    # @yieldparam message [String] UTF-8 log message
+    # @return [WGPU]
+    def on_log(&handler)
+      raise ArgumentError, "block is required" unless handler
+
+      ensure_native_logging!
+      @log_handler = handler
+      @native_log_callback = FFI::Function.new(
+        :void,
+        [:uint32, Native::StringView.by_value, :pointer]
+      ) do |level, message, _userdata|
+        text =
+          if message[:data] && !message[:data].null? && message[:length].positive?
+            message[:data].read_string(message[:length])
+          else
+            ""
+          end
+        @log_handler.call(Native::LogLevel[level] || level, text)
+      rescue StandardError => e
+        warn "WGPU log handler failed: #{e.class}: #{e.message}"
+      end
+      Native.wgpuSetLogCallback(@native_log_callback, nil)
+      self
+    end
+
+    private
+
+    def ensure_native_logging!
+      return if Native.logging_available?
+
+      raise Error,
+        "wgpu-native logging is unavailable in the loaded library " \
+        "(expected #{Native::Distribution::VERSION})"
+    end
+  end
+
+  @log_level = :warn
+end

data/lib/wgpu/native/abi_verifier.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module WGPU
+  module Native
+    class AbiVerifier
+      FORCE32_KEY = "force32"
+      EXTENSION_ENTRIES = {
+        "SType" => %w[invalid shadersourceglsl],
+        "FeatureName" => %w[
+          pushconstants textureadapterspecificformatfeatures multidrawindirectcount
+          vertexwritablestorage texturebindingarray
+          sampledtextureandstoragebufferarraynonuniformindexing
+          pipelinestatisticsquery storageresourcebindingarray
+          partiallyboundbindingarray textureformat16bitnorm
+          texturecompressionastchdr mappableprimarybuffers bufferbindingarray
+          uniformbufferandstoragetexturearraynonuniformindexing polygonmodeline
+          polygonmodepoint conservativerasterization spirvshaderpassthrough
+          vertexattribute64bit textureformatnv12 rayquery shaderf64 shaderi16
+          shaderprimitiveindex shaderearlydepthtest subgroup subgroupvertex
+          subgroupbarrier timestampqueryinsideencoders timestampqueryinsidepasses
+          shaderint64
+        ]
+      }.freeze
+
+      def initialize(header_path: nil, native: Native)
+        @header_path = header_path || self.class.default_header_path
+        @native = native
+      end
+
+      def verify!
+        differences = enum_differences
+        return true if differences.empty?
+
+        raise WGPU::Error, "wgpu-native ABI enum differences:\n#{differences.join("\n")}"
+      end
+
+      def enum_differences
+        header_enums = parse_header
+        ruby_enums.filter_map do |name, mapping|
+          header_mapping = header_enums[name]
+          next unless header_mapping
+
+          compare_enum(name, ruby_mapping(mapping), header_mapping)
+        end
+      end
+
+      def self.default_header_path
+        override = ENV["WGPU_HEADER_PATH"]
+        return File.expand_path(override) if override && !override.empty?
+
+        candidates = Distribution.cache_directories.map do |cache_dir|
+          File.join(cache_dir, "include", "webgpu", "webgpu.h")
+        end
+        path = candidates.find { |candidate| File.file?(candidate) }
+        return path if path
+
+        raise WGPU::Error, <<~MSG.chomp
+          Pinned #{Distribution::VERSION} webgpu.h was not found.
+          Run `bundle exec rake wgpu:install`, or set WGPU_HEADER_PATH.
+          Searched: #{candidates.join(", ")}
+        MSG
+      end
+
+      private
+
+      def parse_header
+        source = File.read(@header_path)
+        source.scan(
+          /typedef enum WGPU(\w+)\s*\{(.*?)\}\s*WGPU\1(?:\s+WGPU_ENUM_ATTRIBUTE)?;/m
+        ).to_h do |name, body|
+          entries = body.scan(
+            /WGPU#{Regexp.escape(name)}_([A-Za-z0-9_]+)\s*=\s*(0x[0-9A-Fa-f]+|\d+)/
+          ).to_h { |entry, value| [normalize(entry), Integer(value)] }
+          entries.delete(FORCE32_KEY)
+          [name, entries]
+        end
+      end
+
+      def ruby_enums
+        @native.constants(false).sort.filter_map do |constant_name|
+          value = @native.const_get(constant_name)
+          [constant_name.to_s, value.to_h] if value.is_a?(FFI::Enum)
+        end
+      end
+
+      def ruby_mapping(mapping)
+        mapping.to_h { |key, value| [normalize(key), value] }
+      end
+
+      def normalize(name)
+        normalized = name.to_s.delete("_").downcase
+        normalized.sub(/\A([123])d/, 'd\1')
+      end
+
+      def compare_enum(name, ruby_mapping, header_mapping)
+        missing = header_mapping.keys - ruby_mapping.keys
+        extra = ruby_mapping.keys - header_mapping.keys - EXTENSION_ENTRIES.fetch(name, [])
+        wrong = (header_mapping.keys & ruby_mapping.keys).filter_map do |key|
+          next if header_mapping[key] == ruby_mapping[key]
+
+          "#{key}=#{ruby_mapping[key]} (header #{header_mapping[key]})"
+        end
+        return if missing.empty? && extra.empty? && wrong.empty?
+
+        "#{name}: missing=#{missing.inspect}, extra=#{extra.inspect}, mismatched=#{wrong.inspect}"
+      end
+    end
+  end
+end

data/lib/wgpu/native/callbacks.rb

@@ -15,12 +15,15 @@ module WGPU
              [:pointer, ErrorType, StringView.by_value, :pointer, :pointer], :void
 
     callback :device_lost_callback,
-             [:pointer, :uint32, StringView.by_value, :pointer, :pointer], :void
+             [:pointer, DeviceLostReason, StringView.by_value, :pointer, :pointer], :void
 
     callback :pop_error_scope_callback,
              [PopErrorScopeStatus, ErrorType, StringView.by_value, :pointer, :pointer], :void
 
     callback :queue_work_done_callback,
              [QueueWorkDoneStatus, :pointer, :pointer], :void
+
+    callback :log_callback,
+             [LogLevel, StringView.by_value, :pointer], :void
   end
 end

data/lib/wgpu/native/capabilities.rb

@@ -4,11 +4,27 @@ module WGPU
   module Native
     class << self
       def future_api?
-        respond_to?(:wgpuInstanceWaitAny)
+        optional_function_available?(:wgpuInstanceWaitAny)
       end
 
       def device_poll_available?
-        respond_to?(:wgpuDevicePoll)
+        optional_function_available?(:wgpuDevicePoll)
+      end
+
+      # wgpu-native v27 exports wgpuShaderModuleGetCompilationInfo, but the
+      # implementation is a Rust panic stub. Calling it aborts the process, so
+      # symbol presence alone cannot be used as a capability check.
+      def compilation_info_available?
+        Distribution::VERSION != "v27.0.4.0"
+      end
+
+      def buffer_map_state_available?
+        Distribution::VERSION != "v27.0.4.0"
+      end
+
+      def logging_available?
+        optional_function_available?(:wgpuSetLogCallback) &&
+          optional_function_available?(:wgpuSetLogLevel)
       end
     end
   end

data/lib/wgpu/native/distribution.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module WGPU
+  module Native
+    module Distribution
+      VERSION = "v27.0.4.0"
+      RELEASE_BASE_URL = "https://github.com/gfx-rs/wgpu-native/releases/download/#{VERSION}"
+
+      ARTIFACTS = [
+        {
+          pattern: /x86_64-linux/,
+          archive: "wgpu-linux-x86_64-release.zip",
+          library: "libwgpu_native.so",
+          sha256: "271481ef76fbf3ea09631a6079e9493636ecf813cd9c92306c44a1a452991ba1"
+        },
+        {
+          pattern: /aarch64-linux/,
+          archive: "wgpu-linux-aarch64-release.zip",
+          library: "libwgpu_native.so",
+          sha256: "a2f22248200997b69373273b10d50a58164f6ed840877289f3e46bff317b134e"
+        },
+        {
+          pattern: /x86_64-darwin/,
+          archive: "wgpu-macos-x86_64-release.zip",
+          library: "libwgpu_native.dylib",
+          sha256: "660fe9be59b555ec1d7c839e5cf8b6c71762938af61ab444a7a58dd87970dba2"
+        },
+        {
+          pattern: /arm64-darwin/,
+          archive: "wgpu-macos-aarch64-release.zip",
+          library: "libwgpu_native.dylib",
+          sha256: "15367c26fdbe6892db35007d39f3883593384e777360b70e6bd704cb5dedde53"
+        },
+        {
+          pattern: /(?:x64|x86_64)-(?:mingw|mswin)/,
+          archive: "wgpu-windows-x86_64-msvc-release.zip",
+          library: "wgpu_native.dll",
+          sha256: "f14ca334b4d253881bde2605bd147f332178d705f56fbd74f81458797c77fce1"
+        }
+      ].map(&:freeze).freeze
+
+      module_function
+
+      def artifact_for(platform = RUBY_PLATFORM)
+        raise LoadError, unsupported_platform_message(platform) if platform.include?("musl")
+
+        artifact = ARTIFACTS.find { |candidate| candidate[:pattern].match?(platform) }
+        return artifact if artifact
+
+        raise LoadError, unsupported_platform_message(platform)
+      end
+
+      def primary_cache_dir(env: ENV, home: Dir.home, host_os: RbConfig::CONFIG["host_os"])
+        override = present_value(env["WGPU_CACHE_DIR"])
+        return File.join(File.expand_path(override), VERSION) if override
+
+        xdg_cache = present_value(env["XDG_CACHE_HOME"])
+        return File.join(File.expand_path(xdg_cache), "wgpu-ruby", VERSION) if xdg_cache
+
+        File.join(default_cache_base(env:, home:, host_os:), "wgpu-ruby", VERSION)
+      end
+
+      def legacy_cache_dir(home: Dir.home)
+        File.join(File.expand_path(home), ".cache", "wgpu-ruby", VERSION)
+      end
+
+      def cache_directories(env: ENV, home: Dir.home, host_os: RbConfig::CONFIG["host_os"])
+        [primary_cache_dir(env:, home:, host_os:), legacy_cache_dir(home:)].uniq
+      end
+
+      def library_paths(platform: RUBY_PLATFORM, env: ENV, home: Dir.home,
+                        host_os: RbConfig::CONFIG["host_os"])
+        library = artifact_for(platform)[:library]
+        cache_directories(env:, home:, host_os:).map { |directory| File.join(directory, "lib", library) }
+      end
+
+      def release_url(artifact)
+        "#{RELEASE_BASE_URL}/#{artifact.fetch(:archive)}"
+      end
+
+      def unsupported_platform_message(platform)
+        supported = ARTIFACTS.map { |artifact| artifact[:pattern].inspect }.join(", ")
+        <<~MESSAGE.chomp
+          Unsupported platform: #{platform}
+          Supported 64-bit platforms: #{supported}
+          Build wgpu-native for this host and set WGPU_LIB_PATH to the shared library.
+        MESSAGE
+      end
+
+      def default_cache_base(env:, home:, host_os:)
+        case host_os
+        when /darwin/
+          File.join(File.expand_path(home), "Library", "Caches")
+        when /mingw|mswin/
+          local_app_data = present_value(env["LOCALAPPDATA"])
+          local_app_data || File.join(File.expand_path(home), "AppData", "Local")
+        else
+          File.join(File.expand_path(home), ".cache")
+        end
+      end
+      private_class_method :default_cache_base
+
+      def present_value(value)
+        value unless value.nil? || value.empty?
+      end
+      private_class_method :present_value
+    end
+
+    WGPU_VERSION = Distribution::VERSION
+  end
+end

data/lib/wgpu/native/enum_helper.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module WGPU
+  module Native
+    module EnumHelper
+      module_function
+
+      def coerce(enum, value, name: "enum")
+        return value if value.is_a?(Integer)
+        raise ArgumentError, "#{name} must be a Symbol or Integer, got #{value.class}" unless value.is_a?(Symbol)
+
+        mapping = mapping_for(enum)
+        result = mapping[value]
+        return result unless result.nil?
+
+        raise ArgumentError, unknown_value_message(name, value, mapping.keys)
+      end
+
+      def coerce_flags(enum, value, name: "flags")
+        return value if value.is_a?(Integer)
+
+        values = value.is_a?(Array) ? value : [value]
+        unless values.all? { |item| item.is_a?(Symbol) }
+          raise ArgumentError, "#{name} must be a Symbol, Integer, or Array of Symbols"
+        end
+
+        values.reduce(0) { |flags, item| flags | coerce(enum, item, name:) }
+      end
+
+      def decompose_flags(enum, value)
+        raise ArgumentError, "flag value must be an Integer" unless value.is_a?(Integer)
+
+        mapping = mapping_for(enum)
+        return [:none] if value.zero? && mapping.key?(:none)
+
+        mapping.filter_map do |symbol, bit|
+          symbol if bit.positive? && power_of_two?(bit) && (value & bit) == bit
+        end
+      end
+
+      def mapping_for(enum)
+        mapping = enum.respond_to?(:to_h) ? enum.to_h : enum
+        unless mapping.respond_to?(:key?) && mapping.respond_to?(:keys)
+          raise ArgumentError, "enum must be an FFI::Enum or Hash"
+        end
+
+        mapping
+      end
+      private_class_method :mapping_for
+
+      def unknown_value_message(name, value, candidates)
+        formatted = candidates.grep(Symbol).sort.map(&:inspect).join(", ")
+        "Unknown #{name} #{value.inspect}. Valid values: #{formatted}"
+      end
+      private_class_method :unknown_value_message
+
+      def power_of_two?(value)
+        (value & (value - 1)).zero?
+      end
+      private_class_method :power_of_two?
+    end
+  end
+end

data/lib/wgpu/native/enums.rb

@@ -61,6 +61,13 @@ module WGPU
       :unknown, 0x00000004
     )
 
+    DeviceLostReason = enum(
+      :unknown, 0x00000001,
+      :destroyed, 0x00000002,
+      :instance_dropped, 0x00000003,
+      :failed_creation, 0x00000004
+    )
+
     BufferMapState = enum(
       :unmapped, 0x00000001,
       :pending, 0x00000002,
@@ -283,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(
@@ -366,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
     )
 
@@ -467,7 +476,9 @@ module WGPU
       :timeout, 0x00000003,
       :outdated, 0x00000004,
       :lost, 0x00000005,
-      :error, 0x00000006
+      :out_of_memory, 0x00000006,
+      :device_lost, 0x00000007,
+      :error, 0x00000008
     )
 
     QueryType = enum(
@@ -523,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,
@@ -540,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

@@ -17,11 +17,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
@@ -77,11 +74,8 @@ module WGPU
     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 +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