wgpu 1.0.0 → 1.2.0

data/lib/wgpu/texture_format.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module WGPU
+  module TextureFormat
+    COPY_ALIGNMENT = 256
+
+    module_function
+
+    def block_size(format, aspect: :all)
+      block_info(format, aspect:).last
+    end
+
+    def block_dimensions(format)
+      block_info(format).first(2)
+    end
+
+    def bytes_per_row(width, format, aspect: :all)
+      block_width, _, bytes = block_info(format, aspect:)
+      ((Integer(width) + block_width - 1) / block_width) * bytes
+    end
+
+    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
+
+    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.0.0"
+  VERSION = "1.2.0"
 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

data/lib/wgpu.rb

@@ -3,7 +3,15 @@
 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"
 
 require_relative "wgpu/resources/buffer"
 require_relative "wgpu/resources/texture"
@@ -33,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

data/sig/wgpu.rbs

@@ -0,0 +1,381 @@
+module WGPU
+  VERSION: String
+
+  type enum_value = Symbol | Integer
+  type flags = enum_value | Array[Symbol]
+  type data = String | Array[Numeric] | untyped
+  type extent_3d = Hash[Symbol, Integer] | Array[Integer]
+
+  def self.log_level: () -> Symbol
+  def self.log_level=: (enum_value) -> enum_value
+  def self.on_log: () { (Symbol, String) -> void } -> singleton(WGPU)
+
+  class Error < StandardError
+  end
+
+  class InitializationError < Error
+  end
+
+  class AdapterError < Error
+  end
+
+  class DeviceError < Error
+  end
+
+  class BufferError < Error
+  end
+
+  class TextureError < Error
+  end
+
+  class ResourceError < Error
+  end
+
+  class ShaderError < Error
+  end
+
+  class PipelineError < Error
+  end
+
+  class CommandError < Error
+  end
+
+  class SurfaceError < Error
+  end
+
+  class SurfaceAcquisitionError < SurfaceError
+    attr_reader status: Symbol
+    def initialize: (Symbol status, ?String? message) -> void
+  end
+
+  class RenderBundleError < Error
+  end
+
+  class ValidationError < Error
+  end
+
+  class OutOfMemoryError < Error
+  end
+
+  class InternalError < Error
+  end
+
+  class DeviceLostError < Error
+  end
+
+  class TimeoutError < Error
+  end
+
+  class GPUError
+    attr_reader type: Symbol
+    attr_reader message: String
+
+    def self.from_hash: (Hash[Symbol, untyped]? error) -> GPUError?
+    def exception_class: () -> singleton(Error)
+    def raise!: () -> bot
+    def to_h: () -> { type: Symbol, message: String }
+  end
+
+  class CompilationMessage
+    attr_reader type: Symbol
+    attr_reader message: String
+    attr_reader line_num: Integer
+    attr_reader line_pos: Integer
+    attr_reader line: Integer
+    attr_reader column: Integer
+    attr_reader offset: Integer
+    attr_reader length: Integer
+    def to_s: () -> String
+  end
+
+  module NativeResource
+    attr_reader label: String?
+    def released?: () -> bool
+    def use: [A] () { (self) -> A } -> A
+    def release: () -> void
+  end
+
+  class AsyncTask[A]
+    def initialize: () { () -> A } -> void
+    def wait: (?timeout: Numeric?) -> self
+    def value: (?timeout: Numeric?) -> A
+    def then: [B] () { (A) -> B } -> AsyncTask[B]
+    def complete?: () -> bool
+    def pending?: () -> bool
+    def error: () -> Exception?
+  end
+
+  module AsyncWaiter
+    def self.poll_interval: () -> Float
+    def self.poll_interval=: (Numeric) -> Numeric
+  end
+
+  module DataTypes
+    def self.pack: (Array[Numeric], ?type: Symbol) -> String
+    def self.unpack: (String, ?type: Symbol) -> Array[Numeric]
+    def self.byte_size: (Symbol) -> Integer
+    def self.to_pointer: (data, ?type: Symbol) -> [untyped, Integer]
+    def self.validate_alignment!: (Integer, Integer, name: String) -> Integer
+  end
+
+  module TextureFormat
+    COPY_ALIGNMENT: Integer
+    def self.block_size: (enum_value, ?aspect: Symbol) -> Integer
+    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
+  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 enumerate_adapters: (?backends: flags?) -> Array[Adapter]
+    def enumerate_adapters_async: (?backends: flags?) -> AsyncTask[Array[Adapter]]
+    def get_canvas_context: (Hash[Symbol, untyped]) -> CanvasContext
+    def process_events: () -> void
+  end
+
+  class Adapter
+    include NativeResource
+    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 info: () -> Hash[Symbol, untyped]
+    def name: () -> String
+    def vendor: () -> String
+    def backend_type: () -> Symbol
+    def adapter_type: () -> Symbol
+    def features: () -> Array[Symbol]
+    def has_feature?: (Symbol) -> bool
+    def limits: () -> Hash[Symbol, Integer]
+    def summary: () -> String
+  end
+
+  class Device
+    include NativeResource
+    attr_reader handle: untyped
+    attr_reader queue: Queue
+    attr_reader adapter: Adapter?
+    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
+    def create_shader_module: (**untyped) -> ShaderModule
+    def create_command_encoder: (?label: String?) -> CommandEncoder
+    def create_bind_group_layout: (?label: String?, entries: Array[Hash[Symbol, untyped]]) -> BindGroupLayout
+    def create_bind_group: (?label: String?, layout: BindGroupLayout, entries: Array[Hash[Symbol, untyped]]) -> BindGroup
+    def create_pipeline_layout: (?label: String?, bind_group_layouts: Array[BindGroupLayout]) -> PipelineLayout
+    def create_compute_pipeline: (**untyped) -> ComputePipeline
+    def create_compute_pipeline_async: (**untyped) -> AsyncTask[ComputePipeline]
+    def create_render_pipeline: (**untyped) -> RenderPipeline
+    def create_render_pipeline_async: (**untyped) -> AsyncTask[RenderPipeline]
+    def create_texture: (**untyped) -> Texture
+    def create_sampler: (**untyped) -> Sampler
+    def create_query_set: (?label: String?, type: enum_value, count: Integer) -> QuerySet
+    def create_render_bundle_encoder: (**untyped) -> RenderBundleEncoder
+    def features: () -> Array[Symbol]
+    def has_feature?: (Symbol) -> bool
+    def limits: () -> Hash[Symbol, Integer]
+    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_typed: (?timeout: Numeric?) -> GPUError?
+    def with_error_scope: [A] (?enum_value) { () -> A } -> A
+    def on_uncaptured_error: () { (GPUError) -> void } -> self
+    def on_device_lost: () { (Symbol, String) -> void } -> self
+    def destroy: () -> void
+  end
+
+  class Queue
+    include NativeResource
+    attr_reader handle: untyped
+    def submit: (CommandBuffer | Array[CommandBuffer]) -> void
+    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 on_submitted_work_done: (?device: Device?, ?timeout: Numeric?) -> Symbol
+    def on_submitted_work_done_async: (?device: Device?, ?timeout: Numeric?) -> AsyncTask[Symbol]
+  end
+
+  class Buffer
+    include NativeResource
+    attr_reader handle: untyped
+    attr_reader size: Integer
+    attr_reader usage: Integer
+    def write: (data, ?offset: Integer, ?type: Symbol) -> void
+    def mapped_range: (?offset: Integer, ?size: Integer?) -> BufferMappedRange
+    def get_mapped_range: (?offset: Integer, ?size: Integer?) -> BufferMappedRange
+    def unmap: () -> void
+    def map_sync: (enum_value, ?offset: Integer, ?size: Integer?, ?timeout: Numeric?) -> true
+    def map_async: (enum_value, ?offset: Integer, ?size: Integer?) -> AsyncTask[true]
+    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_values: (?type: Symbol, ?offset: Integer, ?count: Integer?) -> Array[Numeric]
+    def map_state: () -> Symbol
+    def destroy: () -> void
+  end
+
+  class BufferMappedRange
+    def read: (?type: Symbol, ?count: Integer?) -> Array[Numeric]
+    def write: (data, ?type: Symbol) -> void
+    def read_floats: (?Integer?) -> Array[Float]
+    def write_floats: (Array[Numeric]) -> void
+    def read_uint32s: (?Integer?) -> Array[Integer]
+    def write_uint32s: (Array[Integer]) -> void
+    def read_bytes: () -> String
+    def write_bytes: (String) -> void
+  end
+
+  class Texture
+    include NativeResource
+    attr_reader handle: untyped
+    attr_reader surface_status: Symbol?
+    def create_view: (**untyped) -> TextureView
+    def width: () -> Integer
+    def height: () -> Integer
+    def depth_or_array_layers: () -> Integer
+    def size: () -> Hash[Symbol, Integer]
+    def mip_level_count: () -> Integer
+    def sample_count: () -> Integer
+    def dimension: () -> Symbol
+    def format: () -> Symbol
+    def usage: () -> Integer
+    def destroy: () -> void
+  end
+
+  class TextureView
+    include NativeResource
+    attr_reader handle: untyped
+  end
+
+  class Sampler
+    include NativeResource
+    attr_reader handle: untyped
+  end
+
+  class QuerySet
+    include NativeResource
+    attr_reader handle: untyped
+    attr_reader count: Integer
+    attr_reader type: Symbol
+    def destroy: () -> void
+  end
+
+  class ShaderModule
+    include NativeResource
+    attr_reader handle: untyped
+    def get_compilation_info: () -> { status: Symbol, messages: Array[CompilationMessage] }
+    def get_compilation_info_async: () -> AsyncTask[Hash[Symbol, untyped]]
+  end
+
+  class BindGroupLayout
+    include NativeResource
+    attr_reader handle: untyped
+  end
+
+  class BindGroup
+    include NativeResource
+    attr_reader handle: untyped
+  end
+
+  class PipelineLayout
+    include NativeResource
+    attr_reader handle: untyped
+  end
+
+  class ComputePipeline
+    include NativeResource
+    attr_reader handle: untyped
+    def get_bind_group_layout: (Integer) -> BindGroupLayout
+  end
+
+  class RenderPipeline
+    include NativeResource
+    attr_reader handle: untyped
+    def get_bind_group_layout: (Integer) -> BindGroupLayout
+  end
+
+  class CommandEncoder
+    include NativeResource
+    attr_reader handle: untyped
+    def begin_compute_pass: (**untyped) -> ComputePass
+                          | [A] (**untyped) { (ComputePass) -> A } -> A
+    def begin_render_pass: (**untyped) -> RenderPass
+                         | [A] (**untyped) { (RenderPass) -> A } -> A
+    def copy_buffer_to_buffer: (**untyped) -> void
+    def copy_buffer_to_texture: (**untyped) -> void
+    def copy_texture_to_buffer: (**untyped) -> void
+    def copy_texture_to_texture: (**untyped) -> void
+    def resolve_query_set: (**untyped) -> void
+    def clear_buffer: (Buffer, ?offset: Integer, ?size: Integer?) -> void
+    def write_timestamp: (QuerySet, Integer) -> void
+    def finish: (?label: String?) -> CommandBuffer
+  end
+
+  class CommandBuffer
+    include NativeResource
+    attr_reader handle: untyped
+    def submitted?: () -> bool
+  end
+
+  class ComputePass
+    include NativeResource
+    attr_reader handle: untyped
+    def set_pipeline: (ComputePipeline) -> void
+    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 end_pass: () -> void
+    def end: () -> void
+    def ended?: () -> bool
+  end
+
+  class RenderPass
+    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, 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 end_pass: () -> void
+    def end: () -> void
+    def ended?: () -> bool
+  end
+
+  class RenderBundleEncoder
+    include NativeResource
+    attr_reader handle: untyped
+    def finish: (?label: String?) -> RenderBundle
+  end
+
+  class RenderBundle
+    include NativeResource
+    attr_reader handle: untyped
+  end
+
+  class Surface
+    include NativeResource
+    attr_reader handle: untyped
+    def configure: (**untyped) -> void
+    def unconfigure: () -> void
+    def current_texture: () -> Texture
+    def present: () -> void
+    def capabilities: (Adapter) -> Hash[Symbol, untyped]
+  end
+
+  class CanvasContext
+    include NativeResource
+    def configure: (**untyped) -> void
+    def unconfigure: () -> void
+    def get_current_texture: () -> Texture
+    def present: () -> void
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wgpu
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -37,20 +37,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.3'
-- !ruby/object:Gem::Dependency
-  name: sdl3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.0.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.0.0
 description: Ruby bindings for the WebGPU API, providing GPU compute and graphics
   capabilities through the wgpu-native library.
 email:
@@ -60,9 +46,27 @@ extensions:
 - ext/wgpu/extconf.rb
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE-APACHE
 - LICENSE-MIT
 - README.md
+- docs/README.md
+- docs/api_coverage.md
+- docs/async.md
+- docs/bind_groups.md
+- docs/buffer_data.md
+- docs/command_encoding.md
+- docs/errors.md
+- docs/getting_started_compute.md
+- docs/getting_started_rendering.md
+- docs/installation.md
+- docs/pipeline_descriptors.md
+- docs/releasing.md
+- docs/resource_lifetime.md
+- docs/shaders.md
+- docs/texture_readback.md
+- docs/troubleshooting.md
+- docs/upgrading_wgpu_native.md
 - ext/wgpu/Makefile
 - ext/wgpu/extconf.rb
 - lib/wgpu.rb
@@ -74,17 +78,27 @@ files:
 - lib/wgpu/commands/render_bundle_encoder.rb
 - lib/wgpu/commands/render_pass.rb
 - lib/wgpu/core/adapter.rb
+- lib/wgpu/core/async_waiter.rb
 - lib/wgpu/core/canvas_context.rb
 - lib/wgpu/core/device.rb
 - lib/wgpu/core/instance.rb
 - lib/wgpu/core/queue.rb
 - lib/wgpu/core/surface.rb
+- lib/wgpu/data_types.rb
+- lib/wgpu/descriptor_helpers.rb
 - lib/wgpu/error.rb
+- lib/wgpu/logging.rb
+- lib/wgpu/native/abi_verifier.rb
 - lib/wgpu/native/callbacks.rb
+- lib/wgpu/native/capabilities.rb
+- lib/wgpu/native/distribution.rb
+- lib/wgpu/native/enum_helper.rb
 - lib/wgpu/native/enums.rb
 - lib/wgpu/native/functions.rb
+- lib/wgpu/native/installer.rb
 - lib/wgpu/native/loader.rb
 - lib/wgpu/native/structs.rb
+- lib/wgpu/native_resource.rb
 - lib/wgpu/pipeline/bind_group.rb
 - lib/wgpu/pipeline/bind_group_layout.rb
 - lib/wgpu/pipeline/compute_pipeline.rb
@@ -96,15 +110,18 @@ files:
 - lib/wgpu/resources/sampler.rb
 - lib/wgpu/resources/texture.rb
 - lib/wgpu/resources/texture_view.rb
+- lib/wgpu/texture_format.rb
 - lib/wgpu/version.rb
 - lib/wgpu/window.rb
+- sig/wgpu.rbs
 homepage: https://github.com/ydah/wgpu-ruby
 licenses:
 - MIT
 - Apache-2.0
 metadata:
   homepage_uri: https://github.com/ydah/wgpu-ruby
-  source_code_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
 rdoc_options: []
 require_paths:
 - lib