wgpu 1.1.0 → 1.2.1

data/lib/wgpu/data_types.rb

@@ -0,0 +1,83 @@
+# 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
+
+    # Encodes Ruby values in little-endian native transfer format.
+    # @param values [Array] values to encode
+    # @param type [Symbol] element type
+    # @return [String] encoded bytes
+    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
+
+    # Decodes little-endian transfer bytes into Ruby values.
+    # @param bytes [String] encoded bytes
+    # @param type [Symbol] element type
+    # @return [Array]
+    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
+
+    # Returns the byte width of one typed value.
+    # @param type [Symbol] element type
+    # @return [Integer]
+    def byte_size(type)
+      format_for(type).last
+    end
+
+    # Converts data to an FFI pointer and reports its byte length.
+    # @return [Array(FFI::Pointer, Integer)] pointer and byte length
+    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
+
+    # Validates a non-negative aligned byte value.
+    # @return [Integer] normalized value
+    # @raise [ArgumentError] if negative or misaligned
+    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,104 @@
+# frozen_string_literal: true
+
+module WGPU
+  module DescriptorHelpers
+    SIZE_MAX = (1 << (FFI.type_size(:size_t) * 8)) - 1
+
+    module_function
+
+    # Writes an optional Ruby label into a native descriptor.
+    #
+    # @param descriptor [FFI::Struct] descriptor with a +label+ member
+    # @param label [String, nil] label text
+    # @param keepalive [Array] receives allocated pointers that must remain alive
+    # @return [void]
+    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
+
+    # Allocates and fills a native uint32 array.
+    #
+    # @param values [Array<Integer>] values to copy
+    # @param keepalive [Array] receives the allocated pointer
+    # @return [FFI::MemoryPointer, nil] pointer, or +nil+ for an empty array
+    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
+
+    # Writes a nullable string into a native string view.
+    #
+    # @param string_view [Native::StringView] destination view
+    # @param value [String, nil] string value; +nil+ uses the native null sentinel
+    # @param keepalive [Array] receives allocated pointers that must remain alive
+    # @return [void]
+    def set_nullable_string_view(string_view, value, keepalive:)
+      if value.nil?
+        string_view[:data] = nil
+        string_view[:length] = SIZE_MAX
+        return
+      end
+
+      string = value
+      pointer = FFI::MemoryPointer.from_string(string)
+      keepalive << pointer
+      string_view[:data] = pointer
+      string_view[:length] = string.bytesize
+    end
+
+    # Writes pipeline-overridable constants into a stage descriptor.
+    #
+    # @param stage_descriptor [FFI::Struct] programmable stage descriptor
+    # @param constants [Hash{#to_s => Numeric}, nil] constant names and values
+    # @param keepalive [Array] receives allocated pointers that must remain alive
+    # @return [void]
+    def set_constants(stage_descriptor, constants, keepalive:)
+      stage_descriptor[:constant_count] = 0
+      stage_descriptor[:constants] = nil
+      return if constants.nil? || constants.empty?
+
+      constants_pointer = FFI::MemoryPointer.new(Native::ConstantEntry, constants.size)
+      keepalive << constants_pointer
+
+      constants.each_with_index do |(key, value), index|
+        entry_pointer = constants_pointer + (index * Native::ConstantEntry.size)
+        entry = Native::ConstantEntry.new(entry_pointer)
+        entry[:next_in_chain] = nil
+        set_nullable_string_view(entry[:key], key.to_s, keepalive:)
+        entry[:value] = value.to_f
+      end
+
+      stage_descriptor[:constant_count] = constants.size
+      stage_descriptor[:constants] = constants_pointer
+    end
+
+    # Checks required keys and warns about unsupported descriptor keys.
+    # @param options [Hash] descriptor options
+    # @param allowed [Array<Symbol>] supported keys
+    # @param required [Array<Symbol>] mandatory keys
+    # @return [Hash] original options
+    # @raise [ArgumentError] when required keys are missing
+    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,70 @@ module WGPU
   class PipelineError < Error; end
   class CommandError < Error; end
   class SurfaceError < Error; end
+  class SurfaceAcquisitionError < SurfaceError
+    attr_reader :status
+
+    # Creates an acquisition error for a native surface status.
+    # @param status [Symbol] native acquisition status
+    # @param message [String, nil] optional override message
+    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
+    # Converts a native error-scope result into a typed error.
+    # @param error [Hash, nil] native error result
+    # @return [GPUError, nil]
+    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
+
+    # Returns the Ruby exception class matching this GPU error type.
+    # @return [Class<Error>]
+    def exception_class
+      {
+        validation: ValidationError,
+        out_of_memory: OutOfMemoryError,
+        internal: InternalError,
+        device_lost: DeviceLostError
+      }.fetch(type, Error)
+    end
+
+    # Raises this error as its matching Ruby exception.
+    # @return [void]
+    # @raise [Error]
+    def raise!
+      raise exception_class, "GPU error (#{type}): #{message}"
+    end
+
+    # Returns a serializable representation of the error.
+    # @return [Hash]
+    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
+
+    # Formats the diagnostic with source location, severity, and message.
+    # @return [String]
+    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,143 @@
+# 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
+
+      # Creates a verifier for a header and native binding.
+      # @param header_path [String, nil] header fixture to compare
+      # @param native [Module] native binding module
+      def initialize(header_path: nil, native: Native)
+        @header_path = header_path || self.class.default_header_path
+        @native = native
+      end
+
+      # Verifies the runtime version and Ruby enum ABI against the header.
+      # @return [true]
+      # @raise [WGPU::Error] when differences are detected
+      def verify!
+        differences = enum_differences
+        version_difference = native_version_difference
+        differences.unshift(version_difference) if version_difference
+        return true if differences.empty?
+
+        raise WGPU::Error, "wgpu-native ABI differences:\n#{differences.join("\n")}"
+      end
+
+      # Compares Ruby enum values with the pinned native header.
+      #
+      # @return [Array<String>] human-readable differences
+      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
+
+      # Locates the pinned header used for ABI verification.
+      # @return [String] absolute header path
+      # @raise [WGPU::Error] if no header is available
+      def self.default_header_path
+        override = ENV["WGPU_HEADER_PATH"]
+        return File.expand_path(override) if override && !override.empty?
+
+        fixture = fixture_header_path
+        return fixture if File.file?(fixture)
+
+        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.
+          Restore the repository ABI fixture, run `bundle exec rake wgpu:install`,
+          or set WGPU_HEADER_PATH.
+          Searched: #{([fixture] + candidates).join(", ")}
+        MSG
+      end
+
+      # Returns the repository's pinned enum fixture path.
+      #
+      # @return [String] absolute header fixture path
+      def self.fixture_header_path
+        File.expand_path("fixtures/webgpu-#{Distribution::VERSION}-enums.h", __dir__)
+      end
+
+      private
+
+      def native_version_difference
+        actual = @native.wgpuGetVersion
+        expected = Distribution::ENCODED_VERSION
+        return if actual == expected
+
+        "version: runtime #{Distribution.version_string(actual)} (0x#{format("%08x", actual)}) " \
+          "does not match pinned #{Distribution::VERSION} (0x#{format("%08x", expected)})"
+      end
+
+      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

@@ -8,6 +8,12 @@ module WGPU
     callback :request_device_callback,
              [RequestDeviceStatus, :pointer, StringView.by_value, :pointer, :pointer], :void
 
+    callback :create_compute_pipeline_async_callback,
+             [CreatePipelineAsyncStatus, :pointer, StringView.by_value, :pointer, :pointer], :void
+
+    callback :create_render_pipeline_async_callback,
+             [CreatePipelineAsyncStatus, :pointer, StringView.by_value, :pointer, :pointer], :void
+
     callback :buffer_map_callback,
              [MapAsyncStatus, StringView.by_value, :pointer, :pointer], :void
 
@@ -15,12 +21,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

@@ -3,12 +3,42 @@
 module WGPU
   module Native
     class << self
+      # Reports whether future-based callback waiting is available.
+      # @return [Boolean]
       def future_api?
-        respond_to?(:wgpuInstanceWaitAny)
+        optional_function_available?(:wgpuInstanceWaitAny)
       end
 
+      # Reports whether explicit device polling is available.
+      # @return [Boolean]
       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.capability_implemented?(:compilation_info)
+      end
+
+      # Reports whether querying buffer map state is safe in the pinned runtime.
+      # @return [Boolean]
+      def buffer_map_state_available?
+        Distribution.capability_implemented?(:buffer_map_state)
+      end
+
+      # Reports whether native asynchronous pipeline creation is implemented.
+      # @return [Boolean]
+      def pipeline_async_available?
+        Distribution.capability_implemented?(:pipeline_async)
+      end
+
+      # Reports whether native logging callbacks and levels are available.
+      # @return [Boolean]
+      def logging_available?
+        optional_function_available?(:wgpuSetLogCallback) &&
+          optional_function_available?(:wgpuSetLogLevel)
       end
     end
   end