wgpu 1.2.0 → 1.2.2

data/lib/wgpu/descriptor_helpers.rb

@@ -2,8 +2,38 @@
 
 module WGPU
   module DescriptorHelpers
+    SIZE_MAX = (1 << (FFI.type_size(:size_t) * 8)) - 1
+
     module_function
 
+    # Normalizes an Array or Hash texture extent to a native descriptor.
+    # @param size [Array<Integer>, Hash] width, height, and depth/layer count
+    # @return [Native::Extent3D]
+    def extent_3d(size)
+      values = case size
+               when Array
+                 [size.fetch(0), size[1] || 1, size[2] || 1]
+               when Hash
+                 [size.fetch(:width), size[:height] || 1, size[:depth_or_array_layers] || 1]
+               else
+                 raise ArgumentError, "texture size must be an Array or Hash"
+               end
+      extent = Native::Extent3D.new
+      [:width, :height, :depth_or_array_layers].zip(values).each do |field, value|
+        value = Integer(value)
+        raise ArgumentError, "#{field} must be between 0 and 4294967295" unless (0..0xFFFFFFFF).cover?(value)
+
+        extent[field] = value
+      end
+      extent
+    end
+
+    # 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)
@@ -16,6 +46,11 @@ module WGPU
       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?
 
@@ -25,6 +60,58 @@ module WGPU
       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)
 

data/lib/wgpu/error.rb

@@ -20,6 +20,9 @@ module WGPU
   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}")
@@ -28,12 +31,17 @@ module WGPU
   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,
@@ -43,10 +51,15 @@ module WGPU
       }.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
@@ -63,6 +76,8 @@ module WGPU
     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}"

data/lib/wgpu/native/abi_verifier.rb

@@ -22,18 +22,29 @@ module WGPU
         ]
       }.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 enum differences:\n#{differences.join("\n")}"
+        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|
@@ -44,10 +55,16 @@ module WGPU
         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
@@ -56,13 +73,30 @@ module WGPU
 
         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(", ")}
+          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(

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
 

data/lib/wgpu/native/capabilities.rb

@@ -3,10 +3,14 @@
 module WGPU
   module Native
     class << self
+      # Reports whether future-based callback waiting is available.
+      # @return [Boolean]
       def future_api?
         optional_function_available?(:wgpuInstanceWaitAny)
       end
 
+      # Reports whether explicit device polling is available.
+      # @return [Boolean]
       def device_poll_available?
         optional_function_available?(:wgpuDevicePoll)
       end
@@ -15,13 +19,23 @@ module WGPU
       # 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"
+        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::VERSION != "v27.0.4.0"
+        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)

data/lib/wgpu/native/distribution.rb

@@ -7,6 +7,17 @@ module WGPU
     module Distribution
       VERSION = "v27.0.4.0"
       RELEASE_BASE_URL = "https://github.com/gfx-rs/wgpu-native/releases/download/#{VERSION}"
+      VERSION_COMPONENTS = VERSION.delete_prefix("v").split(".").map { |part| Integer(part, 10) }.freeze
+      unless VERSION_COMPONENTS.length == 4 && VERSION_COMPONENTS.all? { |part| part.between?(0, 255) }
+        raise "wgpu-native VERSION must have four byte-sized components: #{VERSION}"
+      end
+      # wgpuGetVersion packs vMAJOR.MINOR.PATCH.BUILD into four big-endian bytes.
+      ENCODED_VERSION = VERSION_COMPONENTS.reduce(0) { |encoded, part| (encoded << 8) | part }
+      UNIMPLEMENTED_CAPABILITIES = {
+        compilation_info: [VERSION].freeze,
+        buffer_map_state: [VERSION].freeze,
+        pipeline_async: [VERSION].freeze
+      }.freeze
 
       ARTIFACTS = [
         {
@@ -43,6 +54,10 @@ module WGPU
 
       module_function
 
+      # Selects the native release artifact for a Ruby platform.
+      # @param platform [String] Ruby platform identifier
+      # @return [Hash] artifact metadata
+      # @raise [LoadError] if the platform is unsupported
       def artifact_for(platform = RUBY_PLATFORM)
         raise LoadError, unsupported_platform_message(platform) if platform.include?("musl")
 
@@ -52,6 +67,12 @@ module WGPU
         raise LoadError, unsupported_platform_message(platform)
       end
 
+      # Returns the preferred versioned native-library cache directory.
+      #
+      # @param env [Hash] environment used for cache overrides
+      # @param home [String] user home directory
+      # @param host_os [String] host operating-system identifier
+      # @return [String] absolute cache directory
       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
@@ -62,24 +83,66 @@ module WGPU
         File.join(default_cache_base(env:, home:, host_os:), "wgpu-ruby", VERSION)
       end
 
+      # Returns the legacy versioned cache directory.
+      #
+      # @param home [String] user home directory
+      # @return [String] absolute legacy cache directory
       def legacy_cache_dir(home: Dir.home)
         File.join(File.expand_path(home), ".cache", "wgpu-ruby", VERSION)
       end
 
+      # Returns cache directories in lookup order.
+      #
+      # @param env [Hash] environment used for cache overrides
+      # @param home [String] user home directory
+      # @param host_os [String] host operating-system identifier
+      # @return [Array<String>] unique cache directories
       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
 
+      # Returns candidate cached library paths for a platform.
+      #
+      # @param platform [String] Ruby platform identifier
+      # @param env [Hash] environment used for cache overrides
+      # @param home [String] user home directory
+      # @param host_os [String] host operating-system identifier
+      # @return [Array<String>] candidate shared-library paths
+      # @raise [LoadError] if the platform is unsupported
       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
 
+      # Builds the download URL for an artifact entry.
+      #
+      # @param artifact [Hash] entry from {ARTIFACTS}
+      # @return [String] release archive URL
       def release_url(artifact)
         "#{RELEASE_BASE_URL}/#{artifact.fetch(:archive)}"
       end
 
+      # Decodes the packed native version into a release tag.
+      #
+      # @param encoded_version [Integer] four-byte packed version
+      # @return [String] version in +vMAJOR.MINOR.PATCH.BUILD+ form
+      def version_string(encoded_version)
+        components = [24, 16, 8, 0].map { |shift| (encoded_version >> shift) & 0xFF }
+        "v#{components.join(".")}"
+      end
+
+      # Reports whether a native capability is implemented by the pinned release.
+      # @param name [Symbol] capability name
+      # @return [Boolean]
+      def capability_implemented?(name)
+        !UNIMPLEMENTED_CAPABILITIES.fetch(name, []).include?(VERSION)
+      end
+
+      # Builds an actionable unsupported-platform message.
+      #
+      # @param platform [String] Ruby platform identifier
+      # @return [String] diagnostic message
       def unsupported_platform_message(platform)
         supported = ARTIFACTS.map { |artifact| artifact[:pattern].inspect }.join(", ")
         <<~MESSAGE.chomp

data/lib/wgpu/native/enum_helper.rb

@@ -5,6 +5,12 @@ module WGPU
     module EnumHelper
       module_function
 
+      # Converts a symbolic enum member to its integer value.
+      # @param enum [FFI::Enum, Hash] enum mapping
+      # @param value [Symbol, Integer] member or native value
+      # @param name [String] name used in validation errors
+      # @return [Integer]
+      # @raise [ArgumentError] if the value is invalid
       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)
@@ -16,6 +22,13 @@ module WGPU
         raise ArgumentError, unknown_value_message(name, value, mapping.keys)
       end
 
+      # Converts symbolic flag names to their combined integer bitset.
+      #
+      # @param enum [FFI::Enum, Hash] flag mapping
+      # @param value [Symbol, Integer, Array<Symbol>] flags to convert
+      # @param name [String] name used in validation errors
+      # @return [Integer] combined bitset
+      # @raise [ArgumentError] if a flag is unknown or has an invalid type
       def coerce_flags(enum, value, name: "flags")
         return value if value.is_a?(Integer)
 
@@ -27,6 +40,10 @@ module WGPU
         values.reduce(0) { |flags, item| flags | coerce(enum, item, name:) }
       end
 
+      # Expands a bitset into its independent symbolic flags.
+      # @param enum [FFI::Enum, Hash] flag mapping
+      # @param value [Integer] combined bitset
+      # @return [Array<Symbol>]
       def decompose_flags(enum, value)
         raise ArgumentError, "flag value must be an Integer" unless value.is_a?(Integer)
 

data/lib/wgpu/native/enums.rb

@@ -61,6 +61,14 @@ module WGPU
       :unknown, 0x00000004
     )
 
+    CreatePipelineAsyncStatus = enum(
+      :success, 0x00000001,
+      :instance_dropped, 0x00000002,
+      :validation_error, 0x00000003,
+      :internal_error, 0x00000004,
+      :unknown, 0x00000005
+    )
+
     DeviceLostReason = enum(
       :unknown, 0x00000001,
       :destroyed, 0x00000002,