wgpu 1.0.0 → 1.2.0

data/lib/wgpu/data_types.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module WGPU
+  module DataTypes
+    FORMATS = {
+      f32: ["e*", 4],
+      f64: ["E*", 8],
+      u32: ["L<*", 4],
+      i32: ["l<*", 4],
+      u16: ["S<*", 2],
+      u8: ["C*", 1]
+    }.freeze
+
+    module_function
+
+    def pack(values, type: :f32)
+      format, = format_for(type)
+      Array(values).pack(format)
+    rescue RangeError => e
+      raise ArgumentError, "value is out of range for #{type}: #{e.message}"
+    end
+
+    def unpack(bytes, type: :f32)
+      format, byte_size = format_for(type)
+      unless (bytes.bytesize % byte_size).zero?
+        raise ArgumentError, "#{type} data size must be a multiple of #{byte_size} bytes"
+      end
+
+      bytes.unpack(format)
+    end
+
+    def byte_size(type)
+      format_for(type).last
+    end
+
+    def to_pointer(data, type: :f32)
+      return [data, pointer_size(data)] if data.is_a?(FFI::Pointer)
+
+      bytes = data.is_a?(String) ? data : pack(data, type:)
+      pointer = FFI::MemoryPointer.new(:char, bytes.bytesize)
+      pointer.put_bytes(0, bytes)
+      [pointer, bytes.bytesize]
+    end
+
+    def validate_alignment!(value, alignment, name:)
+      integer = Integer(value)
+      raise ArgumentError, "#{name} must be non-negative" if integer.negative?
+      return integer if (integer % alignment).zero?
+
+      raise ArgumentError, "#{name} must be aligned to #{alignment} bytes (got #{integer})"
+    end
+
+    def format_for(type)
+      FORMATS.fetch(type.to_sym)
+    rescue NoMethodError, KeyError
+      raise ArgumentError, "Unknown data type #{type.inspect}. Valid values: #{FORMATS.keys.map(&:inspect).join(", ")}"
+    end
+    private_class_method :format_for
+
+    def pointer_size(pointer)
+      pointer.size
+    rescue NoMethodError
+      raise ArgumentError, "FFI pointer must have a known size; pass size explicitly"
+    end
+    private_class_method :pointer_size
+  end
+end

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

@@ -3,24 +3,27 @@
 module WGPU
   module Native
     callback :request_adapter_callback,
-             [RequestAdapterStatus, :pointer, StringView.by_value, :pointer], :void
+             [RequestAdapterStatus, :pointer, StringView.by_value, :pointer, :pointer], :void
 
     callback :request_device_callback,
-             [RequestDeviceStatus, :pointer, StringView.by_value, :pointer], :void
+             [RequestDeviceStatus, :pointer, StringView.by_value, :pointer, :pointer], :void
 
     callback :buffer_map_callback,
-             [MapAsyncStatus, :pointer], :void
+             [MapAsyncStatus, StringView.by_value, :pointer, :pointer], :void
 
-    callback :error_callback,
-             [:uint32, StringView.by_value, :pointer], :void
+    callback :uncaptured_error_callback,
+             [:pointer, ErrorType, StringView.by_value, :pointer, :pointer], :void
 
     callback :device_lost_callback,
-             [:pointer, :uint32, StringView.by_value, :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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module WGPU
+  module Native
+    class << self
+      def future_api?
+        optional_function_available?(:wgpuInstanceWaitAny)
+      end
+
+      def device_poll_available?
+        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
+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