wgpu 1.1.0 → 1.2.0

data/lib/wgpu/core/device.rb

@@ -6,9 +6,14 @@ module WGPU
 
     LIMIT_FIELDS = Native::Limits.members.freeze
 
-    def self.request(adapter, label: nil, required_features: [], required_limits: nil)
+    def self.request(adapter, label: nil, required_features: [], required_limits: nil, timeout: nil)
       device_ptr = FFI::MemoryPointer.new(:pointer)
       status_holder = { done: false, value: nil, message: nil }
+      device_callback_state = {
+        mutex: Mutex.new,
+        uncaptured_error: nil,
+        device_lost: nil
+      }
 
       callback = FFI::Function.new(
         :void, [:uint32, :pointer, Native::StringView.by_value, :pointer, :pointer]
@@ -28,14 +33,16 @@ module WGPU
 
       device_lost_info = Native::DeviceLostCallbackInfo.new
       device_lost_info[:next_in_chain] = nil
-      device_lost_info[:mode] = 0
-      device_lost_info[:callback] = nil
+      device_lost_info[:mode] = AsyncWaiter.callback_mode(instance: adapter.instance)
+      device_lost_callback = build_device_lost_callback(device_callback_state)
+      device_lost_info[:callback] = device_lost_callback
       device_lost_info[:userdata1] = nil
       device_lost_info[:userdata2] = nil
 
       error_info = Native::UncapturedErrorCallbackInfo.new
       error_info[:next_in_chain] = nil
-      error_info[:callback] = nil
+      uncaptured_error_callback = build_uncaptured_error_callback(device_callback_state)
+      error_info[:callback] = uncaptured_error_callback
       error_info[:userdata1] = nil
       error_info[:userdata2] = nil
 
@@ -74,8 +81,18 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      future = Native.wgpuAdapterRequestDevice(adapter.handle, desc, callback_info)
-      AsyncWaiter.wait(status_holder: status_holder, instance: adapter.instance, future: future)
+      callback_token = CallbackKeepalive.retain(adapter, callback)
+      begin
+        future = Native.wgpuAdapterRequestDevice(adapter.handle, desc, callback_info)
+        AsyncWaiter.wait(
+          status_holder: status_holder,
+          instance: adapter.instance,
+          future: future,
+          timeout: timeout
+        )
+      ensure
+        CallbackKeepalive.release(adapter, callback_token)
+      end
 
       handle = device_ptr.read_pointer
       if handle.null? || status_holder[:value] != :success
@@ -83,12 +100,22 @@ module WGPU
         raise DeviceError, "Failed to request device: #{msg}"
       end
 
-      new(handle, adapter: adapter)
+      device = new(handle, adapter: adapter, label: label, callback_state: device_callback_state)
+      device.send(:retain_device_callback, device_lost_callback)
+      device.send(:retain_device_callback, uncaptured_error_callback)
+      device
     end
 
-    def initialize(handle, adapter: nil)
+    def initialize(handle, adapter: nil, label: nil, callback_state: nil)
       @handle = handle
       @adapter = adapter
+      @label = label
+      @device_callback_state = callback_state || {
+        mutex: Mutex.new,
+        uncaptured_error: nil,
+        device_lost: nil
+      }
+      @device_callback_tokens = []
       @queue = Queue.new(Native.wgpuDeviceGetQueue(@handle), device: self)
     end
 
@@ -100,8 +127,15 @@ module WGPU
       Buffer.new(self, label: label, size: size, usage: usage, mapped_at_creation: mapped_at_creation)
     end
 
-    def create_shader_module(label: nil, code:, compilation_hints: [])
-      ShaderModule.new(self, label: label, code: code, compilation_hints: compilation_hints)
+    def create_shader_module(label: nil, code: nil, spirv: nil, compilation_hints: [], validate: false)
+      ShaderModule.new(
+        self,
+        label: label,
+        code: code,
+        spirv: spirv,
+        compilation_hints: compilation_hints,
+        validate: validate
+      )
     end
 
     def create_command_encoder(label: nil)
@@ -185,8 +219,9 @@ module WGPU
       )
     end
 
-    def create_buffer_with_data(label: nil, data:, usage:)
-      data_ptr, byte_size = data_to_pointer(data)
+    def create_buffer_with_data(label: nil, data:, usage:, type: :f32)
+      data_ptr, byte_size = DataTypes.to_pointer(data, type:)
+      DataTypes.validate_alignment!(byte_size, 4, name: "buffer data size")
       buffer = create_buffer(
         label: label,
         size: byte_size,
@@ -248,10 +283,11 @@ module WGPU
     end
 
     def push_error_scope(filter = :validation)
-      Native.wgpuDevicePushErrorScope(@handle, filter)
+      filter_value = Native::EnumHelper.coerce(Native::ErrorFilter, filter, name: "error filter")
+      Native.wgpuDevicePushErrorScope(@handle, filter_value)
     end
 
-    def pop_error_scope
+    def pop_error_scope(timeout: nil)
       error_holder = { done: false, status: nil, type: nil, message: nil }
 
       callback = FFI::Function.new(
@@ -272,26 +308,53 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      future = Native.wgpuDevicePopErrorScope(@handle, callback_info)
-      AsyncWaiter.wait(status_holder: error_holder, instance: @adapter&.instance, device: self, future: future)
+      callback_token = CallbackKeepalive.retain(self, callback)
+      begin
+        future = Native.wgpuDevicePopErrorScope(@handle, callback_info)
+        AsyncWaiter.wait(
+          status_holder: error_holder,
+          instance: @adapter&.instance,
+          device: self,
+          future: future,
+          timeout: timeout
+        )
+      ensure
+        CallbackKeepalive.release(self, callback_token)
+      end
 
       error_holder
     end
 
-    def pop_error_scope_async
-      AsyncTask.new { pop_error_scope }
+    def pop_error_scope_async(timeout: nil)
+      AsyncTask.new { pop_error_scope(timeout: timeout) }
+    end
+
+    def pop_error_scope_typed(timeout: nil)
+      GPUError.from_hash(pop_error_scope(timeout: timeout))
     end
 
     def with_error_scope(filter = :validation)
       push_error_scope(filter)
       result = yield
-      error = pop_error_scope
-      if error[:type] && error[:type] != :no_error
-        raise Error, "GPU error (#{error[:type]}): #{error[:message]}"
-      end
+      error = GPUError.from_hash(pop_error_scope)
+      error&.raise!
       result
     end
 
+    def on_uncaptured_error(&handler)
+      raise ArgumentError, "on_uncaptured_error requires a block" unless handler
+
+      set_device_callback(:uncaptured_error, handler)
+      self
+    end
+
+    def on_device_lost(&handler)
+      raise ArgumentError, "on_device_lost requires a block" unless handler
+
+      set_device_callback(:device_lost, handler)
+      self
+    end
+
     def destroy
       return if @handle.null?
       Native.wgpuDeviceDestroy(@handle)
@@ -302,10 +365,10 @@ module WGPU
       return if @handle.null?
       Native.wgpuDeviceRelease(@handle)
       @handle = FFI::Pointer::NULL
+      Array(@device_callback_tokens).each { |token| CallbackKeepalive.release(self, token) }
+      @device_callback_tokens&.clear
     end
 
-    private
-
     def self.normalize_required_features(required_features)
       Array(required_features).map do |feature|
         normalize_feature_name(feature)
@@ -316,10 +379,7 @@ module WGPU
       return feature if feature.is_a?(Integer)
 
       key = feature.to_s.strip.tr("-", "_").to_sym
-      value = Native::FeatureName[key]
-      raise ArgumentError, "Unknown feature name: #{feature}" if value.nil?
-
-      value
+      Native::EnumHelper.coerce(Native::FeatureName, key, name: "feature name")
     end
 
     def self.build_required_limits(adapter, required_limits)
@@ -352,23 +412,59 @@ module WGPU
       raise ArgumentError, "Unknown limit key: #{name}"
     end
 
-    def data_to_pointer(data)
-      case data
-      when String
-        ptr = FFI::MemoryPointer.new(:char, data.bytesize)
-        ptr.put_bytes(0, data)
-        [ptr, data.bytesize]
-      when Array
-        ptr = FFI::MemoryPointer.new(:float, data.size)
-        ptr.write_array_of_float(data)
-        [ptr, data.size * 4]
-      when FFI::Pointer
-        [data, data.size]
-      else
-        raise ArgumentError, "Unsupported data type: #{data.class}"
+    def self.build_uncaptured_error_callback(state)
+      FFI::Function.new(
+        :void, [:pointer, :uint32, Native::StringView.by_value, :pointer, :pointer]
+      ) do |_device, type, message, _userdata1, _userdata2|
+        error = GPUError.new(
+          type: Native::ErrorType[type] || :unknown,
+          message: string_from_callback(message)
+        )
+        dispatch_device_callback(state, :uncaptured_error, error) do
+          warn "Uncaptured GPU error (#{error.type}): #{error.message}"
+        end
+      end
+    end
+
+    def self.build_device_lost_callback(state)
+      FFI::Function.new(
+        :void, [:pointer, :uint32, Native::StringView.by_value, :pointer, :pointer]
+      ) do |_device, reason, message, _userdata1, _userdata2|
+        reason_name = Native::DeviceLostReason[reason] || :unknown
+        message_text = string_from_callback(message)
+        dispatch_device_callback(state, :device_lost, reason_name, message_text) do
+          warn "GPU device lost (#{reason_name}): #{message_text}" unless reason_name == :destroyed
+        end
       end
     end
 
+    def self.dispatch_device_callback(state, key, *args)
+      handler = state[:mutex].synchronize { state[key] }
+      handler ? handler.call(*args) : yield
+    rescue StandardError => e
+      warn "WGPU #{key} handler failed: #{e.class}: #{e.message}"
+    end
+
+    def self.string_from_callback(message)
+      return "" if message[:data].nil? || message[:data].null? || message[:length].zero?
+
+      message[:data].read_string(message[:length])
+    end
+
+    private_class_method :normalize_required_features, :normalize_feature_name,
+      :build_required_limits, :canonical_limit_key, :build_uncaptured_error_callback,
+      :build_device_lost_callback, :dispatch_device_callback, :string_from_callback
+
+    private
+
+    def retain_device_callback(callback)
+      @device_callback_tokens << CallbackKeepalive.retain(self, callback)
+    end
+
+    def set_device_callback(name, handler)
+      @device_callback_state[:mutex].synchronize { @device_callback_state[name] = handler }
+    end
+
     def limits_to_hash(limits)
       {
         max_texture_dimension_1d: limits[:max_texture_dimension_1d],

data/lib/wgpu/core/instance.rb

@@ -15,25 +15,29 @@ module WGPU
       raise InitializationError, "Failed to create WebGPU instance" if @handle.null?
     end
 
-    def request_adapter(power_preference: :high_performance, backend: nil, feature_level: :core, force_fallback_adapter: false, compatible_surface: nil)
+    def request_adapter(power_preference: :high_performance, backend: nil, feature_level: :core,
+                        force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
       Adapter.request(
         self,
         power_preference: power_preference,
         backend: backend,
         feature_level: feature_level,
         force_fallback_adapter: force_fallback_adapter,
-        compatible_surface: compatible_surface
+        compatible_surface: compatible_surface,
+        timeout: timeout
       )
     end
 
-    def request_adapter_async(power_preference: :high_performance, backend: nil, feature_level: :core, force_fallback_adapter: false, compatible_surface: nil)
+    def request_adapter_async(power_preference: :high_performance, backend: nil, feature_level: :core,
+                              force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
       AsyncTask.new do
         request_adapter(
           power_preference: power_preference,
           backend: backend,
           feature_level: feature_level,
           force_fallback_adapter: force_fallback_adapter,
-          compatible_surface: compatible_surface
+          compatible_surface: compatible_surface,
+          timeout: timeout
         )
       end
     end

data/lib/wgpu/core/queue.rb

@@ -13,15 +13,24 @@ module WGPU
       buffers = Array(command_buffers)
       return if buffers.empty?
 
+      if buffers.map(&:object_id).uniq.length != buffers.length
+        raise CommandError, "The same command buffer cannot appear twice in one submission"
+      end
+      buffers.each do |buffer|
+        raise CommandError, "Command buffer has already been submitted" if buffer.submitted?
+      end
+
       handles = buffers.map(&:handle)
       ptr = FFI::MemoryPointer.new(:pointer, handles.size)
       ptr.write_array_of_pointer(handles)
 
       Native.wgpuQueueSubmit(@handle, handles.size, ptr)
+      buffers.each(&:mark_submitted!)
     end
 
-    def write_buffer(buffer, buffer_offset, data, data_offset: 0, size: nil)
-      data_ptr, byte_size = data_to_pointer(data)
+    def write_buffer(buffer, buffer_offset, data, data_offset: 0, size: nil, type: :f32)
+      data_ptr, byte_size = DataTypes.to_pointer(data, type:)
+      DataTypes.validate_alignment!(buffer_offset, 4, name: "buffer_offset")
       data_offset = Integer(data_offset)
       raise ArgumentError, "data_offset must be non-negative" if data_offset.negative?
       raise ArgumentError, "data_offset out of range" if data_offset > byte_size
@@ -29,6 +38,7 @@ module WGPU
       write_size = size.nil? ? (byte_size - data_offset) : Integer(size)
       raise ArgumentError, "size must be non-negative" if write_size.negative?
       raise ArgumentError, "data_offset + size out of range" if data_offset + write_size > byte_size
+      DataTypes.validate_alignment!(write_size, 4, name: "size")
 
       Native.wgpuQueueWriteBuffer(
         @handle,
@@ -39,8 +49,8 @@ module WGPU
       )
     end
 
-    def write_texture(destination:, data:, data_layout:, size:)
-      data_ptr, byte_size = data_to_pointer(data)
+    def write_texture(destination:, data:, data_layout:, size:, type: :f32)
+      data_ptr, byte_size = DataTypes.to_pointer(data, type:)
 
       dst = Native::ImageCopyTexture.new
       dst[:texture] = destination[:texture].handle
@@ -48,7 +58,11 @@ module WGPU
       dst[:origin][:x] = destination.dig(:origin, :x) || 0
       dst[:origin][:y] = destination.dig(:origin, :y) || 0
       dst[:origin][:z] = destination.dig(:origin, :z) || 0
-      dst[:aspect] = destination[:aspect] || :all
+      dst[:aspect] = Native::EnumHelper.coerce(
+        Native::TextureAspect,
+        destination[:aspect] || :all,
+        name: "texture aspect"
+      )
 
       extent = Native::Extent3D.new
       if size.is_a?(Array)
@@ -69,14 +83,13 @@ module WGPU
       Native.wgpuQueueWriteTexture(@handle, dst, data_ptr, byte_size, layout, extent)
     end
 
-    def read_buffer(buffer, offset: 0, size: nil, device:)
-      size ||= buffer.size - offset
-
-      staging = Buffer.new(device,
-        size: size,
-        usage: [:map_read, :copy_dst]
-      )
+    def read_buffer(buffer, offset: 0, size: nil, device: nil, staging: nil)
+      device ||= @device
+      raise ArgumentError, "device is required when the queue has no owning device" unless device
 
+      size ||= buffer.size - offset
+      owns_staging = staging.nil?
+      staging ||= Buffer.new(device, size: size, usage: [:map_read, :copy_dst])
       encoder = CommandEncoder.new(device)
       encoder.copy_buffer_to_buffer(
         source: buffer,
@@ -89,26 +102,40 @@ module WGPU
       submit([command_buffer])
 
       staging.map_sync(:read)
-      data = staging.read_mapped_data
-      staging.unmap
-      staging.release
-
-      data
+      staging.read_mapped_data(size:)
+    ensure
+      staging&.unmap if staging && staging.map_state == :mapped
+      command_buffer&.release
+      encoder&.release
+      staging&.release if owns_staging
     end
 
-    def read_texture(source:, data_layout:, size:, device:)
-      width = size[:width] || size[0]
-      height = size[:height] || size[1] || 1
-      depth = size[:depth_or_array_layers] || size[2] || 1
+    def read_texture(source:, data_layout:, size:, device: nil, staging: nil)
+      device ||= @device
+      raise ArgumentError, "device is required when the queue has no owning device" unless device
+
+      width, height, depth = texture_extent(size)
       bytes_per_row = data_layout[:bytes_per_row]
-      rows_per_image = data_layout[:rows_per_image] || height
-      buffer_size = bytes_per_row * rows_per_image * depth
+      raise ArgumentError, "data_layout[:bytes_per_row] is required" unless bytes_per_row
 
-      staging = Buffer.new(device,
-        size: buffer_size,
-        usage: [:map_read, :copy_dst]
+      DataTypes.validate_alignment!(
+        bytes_per_row,
+        TextureFormat::COPY_ALIGNMENT,
+        name: "bytes_per_row"
       )
+      format = source[:format] || source[:texture].format
+      aspect = source[:aspect] || :all
+      minimum_bytes_per_row = TextureFormat.bytes_per_row(width, format, aspect:)
+      if bytes_per_row < minimum_bytes_per_row
+        raise ArgumentError,
+          "bytes_per_row must be at least #{minimum_bytes_per_row} for width #{width} and #{format.inspect}"
+      end
 
+      rows_per_image = data_layout[:rows_per_image] || height
+      buffer_size = bytes_per_row * rows_per_image * depth
+
+      owns_staging = staging.nil?
+      staging ||= Buffer.new(device, size: buffer_size, usage: [:map_read, :copy_dst])
       encoder = CommandEncoder.new(device)
       encoder.copy_texture_to_buffer(
         source: source,
@@ -124,14 +151,15 @@ module WGPU
       submit([command_buffer])
 
       staging.map_sync(:read)
-      data = staging.read_mapped_data
-      staging.unmap
-      staging.release
-
-      data
+      staging.read_mapped_data(size: buffer_size)
+    ensure
+      staging&.unmap if staging && staging.map_state == :mapped
+      command_buffer&.release
+      encoder&.release
+      staging&.release if owns_staging
     end
 
-    def on_submitted_work_done(device: nil)
+    def on_submitted_work_done(device: nil, timeout: nil)
       device ||= @device
       instance = device&.adapter&.instance
       status_holder = { done: false, status: nil }
@@ -150,15 +178,26 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      future = Native.wgpuQueueOnSubmittedWorkDone(@handle, callback_info)
-      AsyncWaiter.wait(status_holder: status_holder, instance: instance, device: device, future: future)
+      callback_token = CallbackKeepalive.retain(self, callback)
+      begin
+        future = Native.wgpuQueueOnSubmittedWorkDone(@handle, callback_info)
+        AsyncWaiter.wait(
+          status_holder: status_holder,
+          instance: instance,
+          device: device,
+          future: future,
+          timeout: timeout
+        )
+      ensure
+        CallbackKeepalive.release(self, callback_token)
+      end
 
       status_holder[:status]
     end
 
-    def on_submitted_work_done_async(device: nil)
+    def on_submitted_work_done_async(device: nil, timeout: nil)
       AsyncTask.new do
-        on_submitted_work_done(device: device)
+        on_submitted_work_done(device: device, timeout: timeout)
       end
     end
 
@@ -170,21 +209,13 @@ module WGPU
 
     private
 
-    def data_to_pointer(data)
-      case data
-      when String
-        ptr = FFI::MemoryPointer.new(:char, data.bytesize)
-        ptr.put_bytes(0, data)
-        [ptr, data.bytesize]
-      when Array
-        ptr = FFI::MemoryPointer.new(:float, data.size)
-        ptr.write_array_of_float(data)
-        [ptr, data.size * 4]
-      when FFI::Pointer
-        [data, data.size]
+    def texture_extent(size)
+      if size.is_a?(Array)
+        [size.fetch(0), size[1] || 1, size[2] || 1]
       else
-        raise ArgumentError, "Unsupported data type: #{data.class}"
+        [size.fetch(:width), size[:height] || 1, size[:depth_or_array_layers] || 1]
       end
     end
+
   end
 end

data/lib/wgpu/core/surface.rb

@@ -86,7 +86,7 @@ module WGPU
       config = Native::SurfaceConfiguration.new
       config[:next_in_chain] = nil
       config[:device] = device.handle
-      config[:format] = format
+      config[:format] = Native::EnumHelper.coerce(Native::TextureFormat, format, name: "surface format")
       config[:usage] = normalize_usage(usage)
       config[:width] = width
       config[:height] = height
@@ -95,15 +95,23 @@ module WGPU
         @view_formats_ptr = nil
         config[:view_formats] = nil
       else
-        format_values = view_formats.map do |vf|
-          vf.is_a?(Integer) ? vf : Native::TextureFormat[vf]
+        format_values = view_formats.map do |view_format|
+          Native::EnumHelper.coerce(Native::TextureFormat, view_format, name: "view format")
         end
         @view_formats_ptr = FFI::MemoryPointer.new(:uint32, format_values.size)
         @view_formats_ptr.write_array_of_uint32(format_values)
         config[:view_formats] = @view_formats_ptr
       end
-      config[:alpha_mode] = Native::CompositeAlphaMode[alpha_mode]
-      config[:present_mode] = Native::PresentMode[present_mode]
+      config[:alpha_mode] = Native::EnumHelper.coerce(
+        Native::CompositeAlphaMode,
+        alpha_mode,
+        name: "alpha mode"
+      )
+      config[:present_mode] = Native::EnumHelper.coerce(
+        Native::PresentMode,
+        present_mode,
+        name: "present mode"
+      )
 
       Native.wgpuSurfaceConfigure(@handle, config)
       @configured = true
@@ -134,7 +142,7 @@ module WGPU
 
       status = Native::SurfaceGetCurrentTextureStatus[surface_texture[:status]]
       unless status == :success_optimal || status == :success_suboptimal
-        raise SurfaceError, "Failed to get current texture: #{status}"
+        raise SurfaceAcquisitionError.new(status)
       end
 
       texture_ptr = surface_texture[:texture]
@@ -142,7 +150,7 @@ module WGPU
         raise SurfaceError, "Surface returned null texture"
       end
 
-      Texture.from_handle(texture_ptr)
+      Texture.from_handle(texture_ptr, surface_status: status)
     end
 
     def get_current_texture
@@ -206,16 +214,7 @@ module WGPU
     private
 
     def normalize_usage(usage)
-      case usage
-      when Integer
-        usage
-      when Symbol
-        Native::TextureUsage[usage]
-      when Array
-        usage.reduce(0) { |acc, u| acc | Native::TextureUsage[u] }
-      else
-        raise ArgumentError, "Invalid usage: #{usage}"
-      end
+      Native::EnumHelper.coerce_flags(Native::TextureUsage, usage, name: "surface usage")
     end
   end
 end

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