wgpu 1.1.0 → 1.2.1

data/lib/wgpu/resources/sampler.rb

@@ -4,33 +4,31 @@ module WGPU
   class Sampler
     attr_reader :handle
 
+    # Creates a texture sampler with address, filter, and comparison settings.
+    # @param device [Device] owning device
+    # @raise [ResourceError] if native validation or creation fails
     def initialize(device, label: nil, address_mode_u: :clamp_to_edge, address_mode_v: :clamp_to_edge, address_mode_w: :clamp_to_edge, mag_filter: :nearest, min_filter: :nearest, mipmap_filter: :nearest, lod_min_clamp: 0.0, lod_max_clamp: 32.0, compare: nil, max_anisotropy: 1)
       @device = device
 
-      desc = Native::SamplerDescriptor.new
-      desc[:next_in_chain] = nil
-      if label
-        @label_ptr = FFI::MemoryPointer.from_string(label)
-        desc[:label][:data] = @label_ptr
-        desc[:label][:length] = label.bytesize
-      else
-        desc[:label][:data] = nil
-        desc[:label][:length] = 0
-      end
-      desc[:address_mode_u] = address_mode_u
-      desc[:address_mode_v] = address_mode_v
-      desc[:address_mode_w] = address_mode_w
-      desc[:mag_filter] = mag_filter
-      desc[:min_filter] = min_filter
-      desc[:mipmap_filter] = mipmap_filter
-      desc[:lod_min_clamp] = lod_min_clamp
-      desc[:lod_max_clamp] = lod_max_clamp
-      desc[:compare] = compare || :undefined
-      desc[:max_anisotropy] = max_anisotropy
+      desc, keepalive = build_descriptor(
+        label:,
+        address_mode_u:,
+        address_mode_v:,
+        address_mode_w:,
+        mag_filter:,
+        min_filter:,
+        mipmap_filter:,
+        lod_min_clamp:,
+        lod_max_clamp:,
+        compare:,
+        max_anisotropy:
+      )
+      @descriptor_keepalive = keepalive
 
       device.push_error_scope(:validation)
       @handle = Native.wgpuDeviceCreateSampler(device.handle, desc)
       error = device.pop_error_scope
+      @descriptor_keepalive = nil
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
         msg = error[:message] || "Failed to create sampler"
@@ -38,10 +36,35 @@ module WGPU
       end
     end
 
+    # Releases the native sampler handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuSamplerRelease(@handle)
       @handle = FFI::Pointer::NULL
     end
+
+    private
+
+    def build_descriptor(label:, address_mode_u:, address_mode_v:, address_mode_w:, mag_filter:, min_filter:,
+                         mipmap_filter:, lod_min_clamp:, lod_max_clamp:, compare:, max_anisotropy:)
+      keepalive = []
+      desc = Native::SamplerDescriptor.new
+      desc[:next_in_chain] = nil
+      DescriptorHelpers.set_label(desc, label, keepalive:)
+      desc[:address_mode_u] = Native::EnumHelper.coerce(Native::AddressMode, address_mode_u, name: "address mode")
+      desc[:address_mode_v] = Native::EnumHelper.coerce(Native::AddressMode, address_mode_v, name: "address mode")
+      desc[:address_mode_w] = Native::EnumHelper.coerce(Native::AddressMode, address_mode_w, name: "address mode")
+      desc[:mag_filter] = Native::EnumHelper.coerce(Native::FilterMode, mag_filter, name: "mag filter")
+      desc[:min_filter] = Native::EnumHelper.coerce(Native::FilterMode, min_filter, name: "min filter")
+      desc[:mipmap_filter] = Native::EnumHelper.coerce(Native::MipmapFilterMode, mipmap_filter, name: "mipmap filter")
+      desc[:lod_min_clamp] = lod_min_clamp
+      desc[:lod_max_clamp] = lod_max_clamp
+      desc[:compare] = Native::EnumHelper.coerce(Native::CompareFunction, compare || :undefined, name: "compare function")
+      desc[:max_anisotropy] = max_anisotropy
+      [desc, keepalive]
+    end
   end
 end

data/lib/wgpu/resources/texture.rb

@@ -2,45 +2,33 @@
 
 module WGPU
   class Texture
-    attr_reader :handle
-
+    attr_reader :handle, :surface_status
+
+    # Creates a GPU texture.
+    # @param device [Device] owning device
+    # @param size [Hash, Array] texture extent
+    # @param format [Symbol, Integer] texel format
+    # @param usage [Symbol, Array<Symbol>, Integer] usage flags
+    # @raise [ResourceError] if native validation or creation fails
     def initialize(device, label: nil, size:, format:, usage:, dimension: :d2, mip_level_count: 1, sample_count: 1, view_formats: [])
       @device = device
 
-      desc = Native::TextureDescriptor.new
-      desc[:next_in_chain] = nil
-      if label
-        @label_ptr = FFI::MemoryPointer.from_string(label)
-        desc[:label][:data] = @label_ptr
-        desc[:label][:length] = label.bytesize
-      else
-        desc[:label][:data] = nil
-        desc[:label][:length] = 0
-      end
-      desc[:usage] = normalize_usage(usage)
-      desc[:dimension] = dimension
-      desc[:size][:width] = size[:width] || size[0]
-      desc[:size][:height] = size[:height] || size[1] || 1
-      desc[:size][:depth_or_array_layers] = size[:depth_or_array_layers] || size[2] || 1
-      desc[:format] = format
-      desc[:mip_level_count] = mip_level_count
-      desc[:sample_count] = sample_count
-      desc[:view_format_count] = view_formats.size
-      if view_formats.empty?
-        @view_formats_ptr = nil
-        desc[:view_formats] = nil
-      else
-        format_values = view_formats.map do |vf|
-          vf.is_a?(Integer) ? vf : Native::TextureFormat[vf]
-        end
-        @view_formats_ptr = FFI::MemoryPointer.new(:uint32, format_values.size)
-        @view_formats_ptr.write_array_of_uint32(format_values)
-        desc[:view_formats] = @view_formats_ptr
-      end
+      desc, keepalive = build_descriptor(
+        label:,
+        size:,
+        format:,
+        usage:,
+        dimension:,
+        mip_level_count:,
+        sample_count:,
+        view_formats:
+      )
+      @descriptor_keepalive = keepalive
 
       device.push_error_scope(:validation)
       @handle = Native.wgpuDeviceCreateTexture(device.handle, desc)
       error = device.pop_error_scope
+      @descriptor_keepalive = nil
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
         msg = error[:message] || "Failed to create texture"
@@ -48,14 +36,23 @@ module WGPU
       end
     end
 
-    def self.from_handle(handle)
-      texture = allocate
-      texture.instance_variable_set(:@handle, handle)
-      texture.instance_variable_set(:@device, nil)
+    # Wraps a native texture handle, such as a surface-acquired texture.
+    #
+    # @param handle [FFI::Pointer] native texture handle
+    # @param surface_status [Symbol, nil] acquisition status associated with the texture
+    # @param device [Device, nil] device whose callbacks the texture may use
+    # @return [Texture] adopted wrapper
+    def self.from_handle(handle, surface_status: nil, device: nil)
+      texture = adopt_native_handle(handle)
+      texture.instance_variable_set(:@device, device)
+      texture.instance_variable_set(:@surface_status, surface_status)
+      texture.send(:attach_device_callback_lifetime, device)
       texture
     end
 
-    def create_view(label: nil, format: nil, dimension: nil, base_mip_level: 0, mip_level_count: nil, base_array_layer: 0, array_layer_count: nil, aspect: :all)
+    # Creates a view into this texture.
+    # @return [TextureView]
+    def create_view(label: nil, format: nil, dimension: nil, base_mip_level: 0, mip_level_count: nil, base_array_layer: 0, array_layer_count: nil, aspect: :all, usage: nil)
       TextureView.new(self,
         label: label,
         format: format,
@@ -64,14 +61,19 @@ module WGPU
         mip_level_count: mip_level_count,
         base_array_layer: base_array_layer,
         array_layer_count: array_layer_count,
-        aspect: aspect
+        aspect: aspect,
+        usage: usage
       )
     end
 
+    # Returns the texture width in texels.
+    # @return [Integer]
     def width
       Native.wgpuTextureGetWidth(@handle)
     end
 
+    # Returns the texture extent.
+    # @return [Hash{Symbol => Integer}]
     def size
       {
         width: width,
@@ -80,38 +82,58 @@ module WGPU
       }
     end
 
+    # Returns the texture height in texels.
+    # @return [Integer]
     def height
       Native.wgpuTextureGetHeight(@handle)
     end
 
+    # Returns the texture depth or array layer count.
+    # @return [Integer]
     def depth_or_array_layers
       Native.wgpuTextureGetDepthOrArrayLayers(@handle)
     end
 
+    # Returns the number of mip levels.
+    # @return [Integer]
     def mip_level_count
       Native.wgpuTextureGetMipLevelCount(@handle)
     end
 
+    # Returns the multisample count.
+    # @return [Integer]
     def sample_count
       Native.wgpuTextureGetSampleCount(@handle)
     end
 
+    # Returns the texture dimension.
+    # @return [Symbol, Integer]
     def dimension
       Native.wgpuTextureGetDimension(@handle)
     end
 
+    # Returns the texture format.
+    # @return [Symbol, Integer]
     def format
       Native.wgpuTextureGetFormat(@handle)
     end
 
+    # Returns the texture usage flags.
+    # @return [Integer]
     def usage
       Native.wgpuTextureGetUsage(@handle)
     end
 
+    # Destroys the texture's storage.
+    # @return [void]
     def destroy
       Native.wgpuTextureDestroy(@handle)
     end
 
+    # Releases the native texture handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuTextureRelease(@handle)
@@ -120,17 +142,36 @@ 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}"
+    def build_descriptor(label:, size:, format:, usage:, dimension:, mip_level_count:, sample_count:, view_formats:)
+      keepalive = []
+      DescriptorHelpers.validate_keys!(
+        size,
+        allowed: [:width, :height, :depth_or_array_layers],
+        required: [:width],
+        context: "texture size"
+      )
+
+      desc = Native::TextureDescriptor.new
+      desc[:next_in_chain] = nil
+      DescriptorHelpers.set_label(desc, label, keepalive:)
+      desc[:usage] = normalize_usage(usage)
+      desc[:dimension] = Native::EnumHelper.coerce(Native::TextureDimension, dimension, name: "texture dimension")
+      desc[:size][:width] = size[:width] || size[0]
+      desc[:size][:height] = size[:height] || size[1] || 1
+      desc[:size][:depth_or_array_layers] = size[:depth_or_array_layers] || size[2] || 1
+      desc[:format] = Native::EnumHelper.coerce(Native::TextureFormat, format, name: "texture format")
+      desc[:mip_level_count] = mip_level_count
+      desc[:sample_count] = sample_count
+      desc[:view_format_count] = view_formats.size
+      format_values = view_formats.map do |view_format|
+        Native::EnumHelper.coerce(Native::TextureFormat, view_format, name: "view format")
       end
+      desc[:view_formats] = DescriptorHelpers.uint32_array(format_values, keepalive:)
+      [desc, keepalive]
+    end
+
+    def normalize_usage(usage)
+      Native::EnumHelper.coerce_flags(Native::TextureUsage, usage, name: "texture usage")
     end
   end
 end

data/lib/wgpu/resources/texture_view.rb

@@ -4,7 +4,10 @@ module WGPU
   class TextureView
     attr_reader :handle, :texture
 
-    def initialize(texture, label: nil, format: nil, dimension: nil, base_mip_level: 0, mip_level_count: nil, base_array_layer: 0, array_layer_count: nil, aspect: :all)
+    # Creates a view selecting texture format, dimension, subresources, and aspect.
+    # @param texture [Texture] parent texture
+    # @raise [ResourceError] if native creation fails
+    def initialize(texture, label: nil, format: nil, dimension: nil, base_mip_level: 0, mip_level_count: nil, base_array_layer: 0, array_layer_count: nil, aspect: :all, usage: nil)
       @texture = texture
 
       desc = Native::TextureViewDescriptor.new
@@ -17,29 +20,54 @@ module WGPU
         desc[:label][:data] = nil
         desc[:label][:length] = 0
       end
-      desc[:format] = format || :undefined
-      desc[:dimension] = dimension || :undefined
+      desc[:format] = Native::EnumHelper.coerce(
+        Native::TextureFormat,
+        format || :undefined,
+        name: "texture view format"
+      )
+      desc[:dimension] = Native::EnumHelper.coerce(
+        Native::TextureViewDimension,
+        dimension || :undefined,
+        name: "texture view dimension"
+      )
       desc[:base_mip_level] = base_mip_level
       desc[:mip_level_count] = mip_level_count || 0xFFFFFFFF
       desc[:base_array_layer] = base_array_layer
       desc[:array_layer_count] = array_layer_count || 0xFFFFFFFF
-      desc[:aspect] = aspect
+      desc[:aspect] = Native::EnumHelper.coerce(Native::TextureAspect, aspect, name: "texture aspect")
+      desc[:usage] = Native::EnumHelper.coerce_flags(
+        Native::TextureUsage,
+        usage || :none,
+        name: "texture view usage"
+      )
 
       @handle = Native.wgpuTextureCreateView(texture.handle, desc)
       raise ResourceError, "Failed to create texture view" if @handle.null?
     end
 
-    def self.from_handle(handle)
-      view = allocate
-      view.instance_variable_set(:@handle, handle)
+    # Wraps a native texture view handle owned by the caller.
+    #
+    # @param handle [FFI::Pointer] native texture view handle
+    # @param device [Device, nil] device whose callbacks the view may use
+    # @return [TextureView] adopted wrapper without a parent texture
+    def self.from_handle(handle, device: nil)
+      view = adopt_native_handle(handle)
       view.instance_variable_set(:@texture, nil)
+      view.send(:attach_device_callback_lifetime, device)
       view
     end
 
+    # Returns the parent texture dimensions when known.
+    #
+    # @return [Hash, nil] texture extent, or +nil+ for an adopted standalone view
     def size
       @texture&.size
     end
 
+    # Releases the native texture view handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuTextureViewRelease(@handle)

data/lib/wgpu/texture_format.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module WGPU
+  module TextureFormat
+    COPY_ALIGNMENT = 256
+
+    module_function
+
+    # Returns the byte size of one texel block.
+    # @return [Integer]
+    def block_size(format, aspect: :all)
+      block_info(format, aspect:).last
+    end
+
+    # Returns a format's texel block width and height.
+    # @return [Array(Integer, Integer)]
+    def block_dimensions(format)
+      block_info(format).first(2)
+    end
+
+    # Returns the tightly packed bytes required for one texel row.
+    # @return [Integer]
+    def bytes_per_row(width, format, aspect: :all)
+      block_width, _, bytes = block_info(format, aspect:)
+      ((Integer(width) + block_width - 1) / block_width) * bytes
+    end
+
+    # Returns row bytes rounded up to the requested copy alignment.
+    # @return [Integer]
+    def aligned_bytes_per_row(width, format, aspect: :all, alignment: COPY_ALIGNMENT)
+      row_bytes = bytes_per_row(width, format, aspect:)
+      ((row_bytes + alignment - 1) / alignment) * alignment
+    end
+
+    # Returns the copy footprint of one texel block.
+    #
+    # @param format [Symbol, Integer] texture format
+    # @param aspect [Symbol] texture aspect for depth/stencil formats
+    # @return [Array(Integer, Integer, Integer)] block width, height, and byte size
+    # @raise [ArgumentError] if the format has no portable copy footprint
+    def block_info(format, aspect: :all)
+      name = normalize_format(format)
+      special = depth_stencil_block_info(name, aspect)
+      return special if special
+
+      case name.to_s
+      when /\Ar8_/
+        [1, 1, 1]
+      when /\A(?:r16_|rg8_)/
+        [1, 1, 2]
+      when /\A(?:r32_|rg16_|rgba8_|bgra8_|rgb10a2_|rg11b10_|rgb9e5_)/
+        [1, 1, 4]
+      when /\A(?:rg32_|rgba16_)/
+        [1, 1, 8]
+      when /\Argba32_/
+        [1, 1, 16]
+      when /\A(?:bc(?:1|4)|etc2_rgb8|etc2_rgb8a1|eac_r11)_/
+        [4, 4, 8]
+      when /\A(?:bc(?:2|3|5|6h|7)|etc2_rgba8|eac_rg11)_/
+        [4, 4, 16]
+      when /\Aastc_(\d+)x(\d+)_/
+        [Regexp.last_match(1).to_i, Regexp.last_match(2).to_i, 16]
+      else
+        raise ArgumentError, "No texel block copy footprint for #{name.inspect}"
+      end
+    end
+
+    def normalize_format(format)
+      return format if format.is_a?(Symbol) &&
+        Native::TextureFormat.to_h.key?(format)
+
+      value = Native::EnumHelper.coerce(Native::TextureFormat, format, name: "texture format")
+      Native::TextureFormat[value] || format
+    end
+    private_class_method :normalize_format
+
+    def depth_stencil_block_info(format, aspect)
+      case format
+      when :stencil8
+        [1, 1, 1]
+      when :depth16_unorm
+        [1, 1, 2]
+      when :depth32_float
+        [1, 1, 4]
+      when :depth32_float_stencil8
+        return [1, 1, 4] if aspect == :depth_only
+        return [1, 1, 1] if aspect == :stencil_only
+
+        raise ArgumentError, "depth32_float_stencil8 copies require :depth_only or :stencil_only aspect"
+      when :depth24_plus, :depth24_plus_stencil8
+        raise ArgumentError, "#{format} has no portable texel block copy footprint"
+      end
+    end
+    private_class_method :depth_stencil_block_info
+  end
+end

data/lib/wgpu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WGPU
-  VERSION = "1.1.0"
+  VERSION = "1.2.1"
 end

data/lib/wgpu/window.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
-require "sdl3"
+begin
+  require "sdl3"
+rescue LoadError => e
+  raise LoadError,
+    "wgpu/window requires the optional `sdl3` gem. " \
+    "Add `gem \"sdl3\", \"~> 1.0\"` and install the SDL3 system library. " \
+    "(original error: #{e.message})"
+end
 
 module WGPU
   module Window
@@ -15,6 +22,11 @@ module WGPU
       SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER = "SDL.window.wayland.display"
       SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER = "SDL.window.wayland.surface"
 
+      # Creates an SDL window suitable for WebGPU presentation.
+      # @param title [String] window title
+      # @param width [Integer] initial logical width
+      # @param height [Integer] initial logical height
+      # @param resizable [Boolean] whether the user may resize the window
       def initialize(title:, width: 800, height: 600, resizable: true)
         @width = width
         @height = height
@@ -28,6 +40,11 @@ module WGPU
         @window = SDL3::Window.new(title, width, height, flags)
       end
 
+      # Creates a presentation surface for this native window.
+      #
+      # @param instance [Instance] WebGPU instance that owns the surface
+      # @return [Surface] platform-specific presentation surface
+      # @raise [WindowError] if the platform or native window handle is unsupported
       def create_surface(instance)
         case platform
         when :macos
@@ -43,6 +60,9 @@ module WGPU
         end
       end
 
+      # Collects currently pending SDL events.
+      #
+      # @return [Array] events in delivery order
       def poll_events
         events = []
         SDL3::Event.each do |event|
@@ -51,10 +71,17 @@ module WGPU
         events
       end
 
+      # Reports whether a quit event is present.
+      # @param events [Array] SDL events to inspect
+      # @return [Boolean]
       def should_close?(events)
         events.any?(&:quit?)
       end
 
+      # Reports whether a key-down event matches the requested key.
+      # @param events [Array] SDL events to inspect
+      # @param key [Symbol, Integer] common key name or SDL scancode
+      # @return [Boolean]
       def key_pressed?(events, key)
         scancode = case key
                    when :escape then SDL3::Raw::SDL_SCANCODE_ESCAPE
@@ -71,12 +98,18 @@ module WGPU
         end
       end
 
+      # Returns the drawable size in physical pixels.
+      #
+      # @return [Array(Integer, Integer)] width and height
       def drawable_size
         @window.size_in_pixels
       rescue
         [@width, @height]
       end
 
+      # Destroys platform-specific resources and the SDL window.
+      #
+      # @return [void]
       def close
         if @metal_view && !@metal_view.null?
           SDL3::Raw.SDL_Metal_DestroyView(@metal_view)

data/lib/wgpu.rb

@@ -3,6 +3,13 @@
 require_relative "wgpu/version"
 require_relative "wgpu/error"
 require_relative "wgpu/native/loader"
+require_relative "wgpu/native/enum_helper"
+require_relative "wgpu/native/abi_verifier"
+require_relative "wgpu/logging"
+require_relative "wgpu/descriptor_helpers"
+require_relative "wgpu/data_types"
+require_relative "wgpu/texture_format"
+require_relative "wgpu/native_resource"
 require_relative "wgpu/async_task"
 require_relative "wgpu/core/async_waiter"
 
@@ -34,4 +41,29 @@ require_relative "wgpu/core/surface"
 require_relative "wgpu/core/canvas_context"
 
 module WGPU
+  [
+    Instance,
+    Adapter,
+    Device,
+    Queue,
+    Surface,
+    CanvasContext,
+    Buffer,
+    Texture,
+    TextureView,
+    Sampler,
+    QuerySet,
+    ShaderModule,
+    BindGroupLayout,
+    BindGroup,
+    PipelineLayout,
+    ComputePipeline,
+    RenderPipeline,
+    CommandEncoder,
+    CommandBuffer,
+    ComputePass,
+    RenderPass,
+    RenderBundleEncoder,
+    RenderBundle
+  ].each { |resource_class| resource_class.include(NativeResource) }
 end