wgpu 1.2.0 → 1.2.1

data/lib/wgpu/resources/texture.rb

@@ -4,6 +4,12 @@ module WGPU
   class Texture
     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
 
@@ -30,15 +36,23 @@ module WGPU
       end
     end
 
-    def self.from_handle(handle, surface_status: nil)
-      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,
@@ -47,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,
@@ -63,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)

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
@@ -32,22 +35,39 @@ module WGPU
       desc[:base_array_layer] = base_array_layer
       desc[:array_layer_count] = array_layer_count || 0xFFFFFFFF
       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

@@ -6,24 +6,38 @@ module WGPU
 
     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)

data/lib/wgpu/version.rb

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

data/lib/wgpu/window.rb

@@ -22,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
@@ -35,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
@@ -50,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|
@@ -58,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
@@ -78,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/sig/wgpu.rbs

@@ -5,10 +5,15 @@ module WGPU
   type flags = enum_value | Array[Symbol]
   type data = String | Array[Numeric] | untyped
   type extent_3d = Hash[Symbol, Integer] | Array[Integer]
+  type texture_copy = Hash[Symbol, untyped]
+  type texture_data_layout = Hash[Symbol, Integer]
+  type configuration = Hash[Symbol, untyped]
 
   def self.log_level: () -> Symbol
   def self.log_level=: (enum_value) -> enum_value
   def self.on_log: () { (Symbol, String) -> void } -> singleton(WGPU)
+  def self.debug_leaks: () -> bool
+  def self.debug_leaks=: (bool) -> bool
 
   class Error < StandardError
   end
@@ -70,6 +75,9 @@ module WGPU
     attr_reader type: Symbol
     attr_reader message: String
 
+    # Creates a typed GPU error with its native category and diagnostic message.
+    def initialize: (Symbol type, String message) -> void
+                  | (type: Symbol, message: String) -> void
     def self.from_hash: (Hash[Symbol, untyped]? error) -> GPUError?
     def exception_class: () -> singleton(Error)
     def raise!: () -> bot
@@ -92,6 +100,7 @@ module WGPU
     attr_reader label: String?
     def released?: () -> bool
     def use: [A] () { (self) -> A } -> A
+    # Releases the native handle and unregisters its leak-tracking entry.
     def release: () -> void
   end
 
@@ -124,14 +133,17 @@ module WGPU
     def self.block_dimensions: (enum_value) -> [Integer, Integer]
     def self.bytes_per_row: (Integer, enum_value, ?aspect: Symbol) -> Integer
     def self.aligned_bytes_per_row: (Integer, enum_value, ?aspect: Symbol, ?alignment: Integer) -> Integer
+    def self.block_info: (enum_value, ?aspect: Symbol) -> [Integer, Integer, Integer]
   end
 
   class Instance
     include NativeResource
     attr_reader handle: untyped
     def initialize: () -> void
-    def request_adapter: (**untyped) -> Adapter
-    def request_adapter_async: (**untyped) -> AsyncTask[Adapter]
+    def request_adapter: (?power_preference: enum_value, ?backend: enum_value?, ?feature_level: enum_value, ?force_fallback_adapter: bool, ?compatible_surface: Surface?, ?timeout: Numeric?) -> Adapter
+                       | (**untyped) -> Adapter
+    def request_adapter_async: (?power_preference: enum_value, ?backend: enum_value?, ?feature_level: enum_value, ?force_fallback_adapter: bool, ?compatible_surface: Surface?, ?timeout: Numeric?) -> AsyncTask[Adapter]
+                             | (**untyped) -> AsyncTask[Adapter]
     def enumerate_adapters: (?backends: flags?) -> Array[Adapter]
     def enumerate_adapters_async: (?backends: flags?) -> AsyncTask[Array[Adapter]]
     def get_canvas_context: (Hash[Symbol, untyped]) -> CanvasContext
@@ -143,8 +155,12 @@ module WGPU
     attr_reader handle: untyped
     attr_reader instance: Instance?
     def self.from_handle: (untyped, ?instance: Instance?) -> Adapter
-    def request_device: (**untyped) -> Device
-    def request_device_async: (**untyped) -> AsyncTask[Device]
+    def self.request: (Instance, ?power_preference: enum_value, ?backend: enum_value?, ?feature_level: enum_value, ?force_fallback_adapter: bool, ?compatible_surface: Surface?, ?timeout: Numeric?) -> Adapter
+                    | (Instance, **untyped) -> Adapter
+    def request_device: (?label: String?, ?required_features: Array[enum_value], ?required_limits: Hash[Symbol, Integer]?, ?timeout: Numeric?) -> Device
+                      | (**untyped) -> Device
+    def request_device_async: (?label: String?, ?required_features: Array[enum_value], ?required_limits: Hash[Symbol, Integer]?, ?timeout: Numeric?) -> AsyncTask[Device]
+                            | (**untyped) -> AsyncTask[Device]
     def info: () -> Hash[Symbol, untyped]
     def name: () -> String
     def vendor: () -> String
@@ -161,6 +177,8 @@ module WGPU
     attr_reader handle: untyped
     attr_reader queue: Queue
     attr_reader adapter: Adapter?
+    def self.request: (Adapter, ?label: String?, ?required_features: Array[enum_value], ?required_limits: Hash[Symbol, Integer]?, ?timeout: Numeric?) -> Device
+                    | (Adapter, **untyped) -> Device
     def adapter_info: () -> Hash[Symbol, untyped]?
     def create_buffer: (?label: String?, size: Integer, usage: flags, ?mapped_at_creation: bool) -> Buffer
     def create_buffer_with_data: (?label: String?, data: data, usage: flags, ?type: Symbol) -> Buffer
@@ -183,6 +201,7 @@ module WGPU
     def poll: (?wait: bool) -> Integer
     def push_error_scope: (?enum_value) -> void
     def pop_error_scope: (?timeout: Numeric?) -> Hash[Symbol, untyped]
+    def pop_error_scope_async: (?timeout: Numeric?) -> AsyncTask[Hash[Symbol, untyped]]
     def pop_error_scope_typed: (?timeout: Numeric?) -> GPUError?
     def with_error_scope: [A] (?enum_value) { () -> A } -> A
     def on_uncaptured_error: () { (GPUError) -> void } -> self
@@ -197,7 +216,8 @@ module WGPU
     def write_buffer: (Buffer, Integer, data, ?data_offset: Integer, ?size: Integer?, ?type: Symbol) -> void
     def write_texture: (**untyped) -> void
     def read_buffer: (Buffer, ?offset: Integer, ?size: Integer?, ?device: Device?, ?staging: Buffer?) -> String
-    def read_texture: (**untyped) -> String
+    def read_texture: (source: texture_copy, data_layout: texture_data_layout, size: extent_3d, ?device: Device?, ?staging: Buffer?) -> String
+                    | (**untyped) -> String
     def on_submitted_work_done: (?device: Device?, ?timeout: Numeric?) -> Symbol
     def on_submitted_work_done_async: (?device: Device?, ?timeout: Numeric?) -> AsyncTask[Symbol]
   end
@@ -216,6 +236,12 @@ module WGPU
     def read_mapped_data: (?offset: Integer, ?size: Integer?) -> String
     def read_mapped: (?offset: Integer, ?size: Integer?, ?type: Symbol?) -> (String | Array[Numeric])
     def write_mapped: (data, ?offset: Integer, ?type: Symbol) -> void
+    def read_mapped_floats: (?offset: Integer, ?count: Integer?) -> Array[Float]
+    def read_mapped_uint32s: (?offset: Integer, ?count: Integer?) -> Array[Integer]
+    def read_mapped_int32s: (?offset: Integer, ?count: Integer?) -> Array[Integer]
+    def read_mapped_float64s: (?offset: Integer, ?count: Integer?) -> Array[Float]
+    def read_mapped_uint16s: (?offset: Integer, ?count: Integer?) -> Array[Integer]
+    def read_mapped_uint8s: (?offset: Integer, ?count: Integer?) -> Array[Integer]
     def read_mapped_values: (?type: Symbol, ?offset: Integer, ?count: Integer?) -> Array[Numeric]
     def map_state: () -> Symbol
     def destroy: () -> void
@@ -228,6 +254,14 @@ module WGPU
     def write_floats: (Array[Numeric]) -> void
     def read_uint32s: (?Integer?) -> Array[Integer]
     def write_uint32s: (Array[Integer]) -> void
+    def read_int32s: (?Integer?) -> Array[Integer]
+    def write_int32s: (Array[Integer]) -> void
+    def read_float64s: (?Integer?) -> Array[Float]
+    def write_float64s: (Array[Numeric]) -> void
+    def read_uint16s: (?Integer?) -> Array[Integer]
+    def write_uint16s: (Array[Integer]) -> void
+    def read_uint8s: (?Integer?) -> Array[Integer]
+    def write_uint8s: (Array[Integer]) -> void
     def read_bytes: () -> String
     def write_bytes: (String) -> void
   end
@@ -236,6 +270,7 @@ module WGPU
     include NativeResource
     attr_reader handle: untyped
     attr_reader surface_status: Symbol?
+    def self.from_handle: (untyped, ?surface_status: Symbol?, ?device: Device?) -> Texture
     def create_view: (**untyped) -> TextureView
     def width: () -> Integer
     def height: () -> Integer
@@ -252,6 +287,9 @@ module WGPU
   class TextureView
     include NativeResource
     attr_reader handle: untyped
+    attr_reader texture: Texture?
+    def self.from_handle: (untyped, ?device: Device?) -> TextureView
+    def size: () -> Hash[Symbol, Integer]?
   end
 
   class Sampler
@@ -277,6 +315,7 @@ module WGPU
   class BindGroupLayout
     include NativeResource
     attr_reader handle: untyped
+    def self.from_handle: (untyped, ?device: Device?) -> BindGroupLayout
   end
 
   class BindGroup
@@ -315,6 +354,9 @@ module WGPU
     def resolve_query_set: (**untyped) -> void
     def clear_buffer: (Buffer, ?offset: Integer, ?size: Integer?) -> void
     def write_timestamp: (QuerySet, Integer) -> void
+    def push_debug_group: (String) -> void
+    def pop_debug_group: () -> void
+    def insert_debug_marker: (String) -> void
     def finish: (?label: String?) -> CommandBuffer
   end
 
@@ -331,6 +373,9 @@ module WGPU
     def set_bind_group: (Integer, BindGroup, ?dynamic_offsets: Array[Integer]) -> void
     def dispatch_workgroups: (Integer, ?Integer, ?Integer) -> void
     def dispatch_workgroups_indirect: (Buffer, ?offset: Integer) -> void
+    def push_debug_group: (String) -> void
+    def pop_debug_group: () -> void
+    def insert_debug_marker: (String) -> void
     def end_pass: () -> void
     def end: () -> void
     def ended?: () -> bool
@@ -345,6 +390,18 @@ module WGPU
     def set_index_buffer: (Buffer, enum_value, ?offset: Integer, ?size: Integer?) -> void
     def draw: (Integer, ?instance_count: Integer, ?first_vertex: Integer, ?first_instance: Integer) -> void
     def draw_indexed: (Integer, **untyped) -> void
+    def set_viewport: (Numeric, Numeric, Numeric, Numeric, ?min_depth: Numeric, ?max_depth: Numeric) -> void
+    def set_scissor_rect: (Integer, Integer, Integer, Integer) -> void
+    def set_blend_constant: (?r: Numeric, ?g: Numeric, ?b: Numeric, ?a: Numeric) -> void
+    def set_stencil_reference: (Integer) -> void
+    def draw_indirect: (Buffer, ?offset: Integer) -> void
+    def draw_indexed_indirect: (Buffer, ?offset: Integer) -> void
+    def execute_bundles: (Array[RenderBundle]) -> void
+    def begin_occlusion_query: (Integer) -> void
+    def end_occlusion_query: () -> void
+    def push_debug_group: (String) -> void
+    def pop_debug_group: () -> void
+    def insert_debug_marker: (String) -> void
     def end_pass: () -> void
     def end: () -> void
     def ended?: () -> bool
@@ -353,6 +410,17 @@ module WGPU
   class RenderBundleEncoder
     include NativeResource
     attr_reader handle: untyped
+    def set_pipeline: (RenderPipeline) -> void
+    def set_bind_group: (Integer, BindGroup, ?dynamic_offsets: Array[Integer]?) -> void
+    def set_vertex_buffer: (Integer, Buffer, ?offset: Integer, ?size: Integer?) -> void
+    def set_index_buffer: (Buffer, ?format: enum_value, ?offset: Integer, ?size: Integer?) -> void
+    def draw: (Integer, ?instance_count: Integer, ?first_vertex: Integer, ?first_instance: Integer) -> void
+    def draw_indexed: (Integer, ?instance_count: Integer, ?first_index: Integer, ?base_vertex: Integer, ?first_instance: Integer) -> void
+    def draw_indirect: (Buffer, ?offset: Integer) -> void
+    def draw_indexed_indirect: (Buffer, ?offset: Integer) -> void
+    def push_debug_group: (String) -> void
+    def pop_debug_group: () -> void
+    def insert_debug_marker: (String) -> void
     def finish: (?label: String?) -> RenderBundle
   end
 
@@ -364,15 +432,26 @@ module WGPU
   class Surface
     include NativeResource
     attr_reader handle: untyped
+    def self.from_metal_layer: (Instance, untyped) -> Surface
+    def self.from_windows_hwnd: (Instance, untyped, untyped) -> Surface
+    def self.from_xlib_window: (Instance, untyped, Integer) -> Surface
+    def self.from_wayland_surface: (Instance, untyped, untyped) -> Surface
     def configure: (**untyped) -> void
     def unconfigure: () -> void
     def current_texture: () -> Texture
+    def get_current_texture: () -> Texture
     def present: () -> void
+    def get_configuration: () -> configuration?
+    def get_preferred_format: (Adapter) -> Symbol
     def capabilities: (Adapter) -> Hash[Symbol, untyped]
   end
 
   class CanvasContext
     include NativeResource
+    attr_reader physical_size: [Integer, Integer]
+    def set_physical_size: (Integer, Integer) -> [Integer, Integer]
+    def get_preferred_format: (Adapter) -> Symbol
+    def get_configuration: () -> configuration?
     def configure: (**untyped) -> void
     def unconfigure: () -> void
     def get_current_texture: () -> Texture

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wgpu
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Yudai Takada
@@ -94,6 +94,7 @@ files:
 - lib/wgpu/native/distribution.rb
 - lib/wgpu/native/enum_helper.rb
 - lib/wgpu/native/enums.rb
+- lib/wgpu/native/fixtures/webgpu-v27.0.4.0-enums.h
 - lib/wgpu/native/functions.rb
 - lib/wgpu/native/installer.rb
 - lib/wgpu/native/loader.rb
@@ -122,6 +123,7 @@ metadata:
   homepage_uri: https://github.com/ydah/wgpu-ruby
   source_code_uri: https://github.com/ydah/wgpu-ruby/tree/main
   changelog_uri: https://github.com/ydah/wgpu-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/wgpu
 rdoc_options: []
 require_paths:
 - lib