wgpu 1.2.0 → 1.2.2

data/lib/wgpu/commands/render_pass.rb

@@ -4,6 +4,15 @@ module WGPU
   class RenderPass
     attr_reader :handle
 
+    # Begins a render pass owned by the command encoder.
+    # @param encoder [CommandEncoder] owning encoder
+    # @param label [String, nil] optional debug label
+    # @param color_attachments [Array<Hash>] color attachment descriptors
+    # @param depth_stencil_attachment [Hash, nil] depth/stencil attachment descriptor
+    # @param occlusion_query_set [QuerySet, nil] query set for occlusion queries
+    # @param timestamp_writes [Hash, nil] beginning and ending timestamp query settings
+    # @param max_draw_count [Integer, nil] implementation hint for the maximum draw count
+    # @raise [CommandError] if the native pass cannot be created
     def initialize(encoder, label: nil, color_attachments:, depth_stencil_attachment: nil, occlusion_query_set: nil, timestamp_writes: nil, max_draw_count: nil)
       @encoder = encoder
       @pointers = []
@@ -25,10 +34,10 @@ module WGPU
         desc[:depth_stencil_attachment] = nil
       end
 
-      desc[:occlusion_query_set] = occlusion_query_set&.handle
+      desc[:occlusion_query_set] = (occlusion_query_set && NativeResource.checked_handle(occlusion_query_set, expected_class: QuerySet))
       if timestamp_writes
         ts = Native::RenderPassTimestampWrites.new
-        ts[:query_set] = timestamp_writes.fetch(:query_set).handle
+        ts[:query_set] = NativeResource.checked_handle(timestamp_writes.fetch(:query_set), expected_class: QuerySet)
         ts[:beginning_of_pass_write_index] = timestamp_writes[:beginning_of_pass_write_index] || 0xFFFFFFFF
         ts[:end_of_pass_write_index] = timestamp_writes[:end_of_pass_write_index] || 0xFFFFFFFF
         @pointers << ts
@@ -37,51 +46,98 @@ module WGPU
         desc[:timestamp_writes] = nil
       end
 
-      @handle = Native.wgpuCommandEncoderBeginRenderPass(encoder.handle, desc)
+      @handle = Native.wgpuCommandEncoderBeginRenderPass(NativeResource.checked_handle(encoder, expected_class: CommandEncoder), desc)
       raise CommandError, "Failed to begin render pass" if @handle.null?
     end
 
+    # Selects the render pipeline used by subsequent draws.
+    # @param pipeline [RenderPipeline] pipeline to bind
+    # @return [void]
     def set_pipeline(pipeline)
-      Native.wgpuRenderPassEncoderSetPipeline(@handle, pipeline.handle)
+      Native.wgpuRenderPassEncoderSetPipeline(@handle, NativeResource.checked_handle(pipeline, expected_class: RenderPipeline))
     end
 
+    # Binds a resource group for subsequent draws.
+    # @param index [Integer] bind group index
+    # @param bind_group [BindGroup] group to bind
+    # @param dynamic_offsets [Array<Integer>] dynamic buffer offsets
+    # @return [void]
     def set_bind_group(index, bind_group, dynamic_offsets: [])
       if dynamic_offsets.empty?
-        Native.wgpuRenderPassEncoderSetBindGroup(@handle, index, bind_group.handle, 0, nil)
+        Native.wgpuRenderPassEncoderSetBindGroup(@handle, index, NativeResource.checked_handle(bind_group, expected_class: BindGroup), 0, nil)
       else
         offsets_ptr = FFI::MemoryPointer.new(:uint32, dynamic_offsets.size)
         offsets_ptr.write_array_of_uint32(dynamic_offsets)
-        Native.wgpuRenderPassEncoderSetBindGroup(@handle, index, bind_group.handle, dynamic_offsets.size, offsets_ptr)
+        Native.wgpuRenderPassEncoderSetBindGroup(@handle, index, NativeResource.checked_handle(bind_group, expected_class: BindGroup), dynamic_offsets.size, offsets_ptr)
       end
     end
 
+    # Binds a vertex buffer to a slot.
+    # @param slot [Integer] vertex buffer slot
+    # @param buffer [Buffer] vertex data buffer
+    # @param offset [Integer] first byte to bind
+    # @param size [Integer, nil] number of bytes to bind
+    # @return [void]
     def set_vertex_buffer(slot, buffer, offset: 0, size: nil)
       size ||= buffer.size - offset
-      Native.wgpuRenderPassEncoderSetVertexBuffer(@handle, slot, buffer.handle, offset, size)
+      Native.wgpuRenderPassEncoderSetVertexBuffer(@handle, slot, NativeResource.checked_handle(buffer, expected_class: Buffer), offset, size)
     end
 
+    # Binds an index buffer for indexed draws.
+    # @param buffer [Buffer] index data buffer
+    # @param format [Symbol, Integer] index element format
+    # @param offset [Integer] first byte to bind
+    # @param size [Integer, nil] number of bytes to bind
+    # @return [void]
     def set_index_buffer(buffer, format, offset: 0, size: nil)
       size ||= buffer.size - offset
       format_value = Native::EnumHelper.coerce(Native::IndexFormat, format, name: "index format")
-      Native.wgpuRenderPassEncoderSetIndexBuffer(@handle, buffer.handle, format_value, offset, size)
+      Native.wgpuRenderPassEncoderSetIndexBuffer(@handle, NativeResource.checked_handle(buffer, expected_class: Buffer), format_value, offset, size)
     end
 
+    # Records a non-indexed draw.
+    # @return [void]
     def draw(vertex_count, instance_count: 1, first_vertex: 0, first_instance: 0)
       Native.wgpuRenderPassEncoderDraw(@handle, vertex_count, instance_count, first_vertex, first_instance)
     end
 
+    # Records an indexed draw.
+    # @return [void]
     def draw_indexed(index_count, instance_count: 1, first_index: 0, base_vertex: 0, first_instance: 0)
       Native.wgpuRenderPassEncoderDrawIndexed(@handle, index_count, instance_count, first_index, base_vertex, first_instance)
     end
 
+    # Sets the viewport used by subsequent draw calls.
+    #
+    # @param x [Numeric] left coordinate in pixels
+    # @param y [Numeric] top coordinate in pixels
+    # @param width [Numeric] viewport width in pixels
+    # @param height [Numeric] viewport height in pixels
+    # @param min_depth [Numeric] minimum depth value
+    # @param max_depth [Numeric] maximum depth value
+    # @return [void]
     def set_viewport(x, y, width, height, min_depth: 0.0, max_depth: 1.0)
       Native.wgpuRenderPassEncoderSetViewport(@handle, x, y, width, height, min_depth, max_depth)
     end
 
+    # Restricts rasterization to a rectangular region.
+    #
+    # @param x [Integer] left coordinate in pixels
+    # @param y [Integer] top coordinate in pixels
+    # @param width [Integer] rectangle width in pixels
+    # @param height [Integer] rectangle height in pixels
+    # @return [void]
     def set_scissor_rect(x, y, width, height)
       Native.wgpuRenderPassEncoderSetScissorRect(@handle, x, y, width, height)
     end
 
+    # Sets the constant color used by blend factors.
+    #
+    # @param r [Numeric] red component
+    # @param g [Numeric] green component
+    # @param b [Numeric] blue component
+    # @param a [Numeric] alpha component
+    # @return [void]
     def set_blend_constant(r: 0.0, g: 0.0, b: 0.0, a: 1.0)
       color = Native::Color.new
       color[:r] = r
@@ -91,33 +147,62 @@ module WGPU
       Native.wgpuRenderPassEncoderSetBlendConstant(@handle, color.to_ptr)
     end
 
+    # Sets the stencil reference used by subsequent draw calls.
+    #
+    # @param reference [Integer] unsigned stencil reference
+    # @return [void]
     def set_stencil_reference(reference)
       Native.wgpuRenderPassEncoderSetStencilReference(@handle, reference)
     end
 
+    # Draws using non-indexed arguments stored in a buffer.
+    #
+    # @param buffer [Buffer] buffer containing the indirect arguments
+    # @param offset [Integer] byte offset of the arguments
+    # @return [void]
     def draw_indirect(buffer, offset: 0)
-      Native.wgpuRenderPassEncoderDrawIndirect(@handle, buffer.handle, offset)
+      Native.wgpuRenderPassEncoderDrawIndirect(@handle, NativeResource.checked_handle(buffer, expected_class: Buffer), offset)
     end
 
+    # Draws using indexed arguments stored in a buffer.
+    #
+    # @param buffer [Buffer] buffer containing the indirect arguments
+    # @param offset [Integer] byte offset of the arguments
+    # @return [void]
     def draw_indexed_indirect(buffer, offset: 0)
-      Native.wgpuRenderPassEncoderDrawIndexedIndirect(@handle, buffer.handle, offset)
+      Native.wgpuRenderPassEncoderDrawIndexedIndirect(@handle, NativeResource.checked_handle(buffer, expected_class: Buffer), offset)
     end
 
+    # Executes pre-recorded render bundles.
+    #
+    # @param bundles [Array<RenderBundle>] bundles to execute in order
+    # @return [void]
     def execute_bundles(bundles)
-      bundle_handles = bundles.map(&:handle)
+      bundle_handles = bundles.map { |bundle| NativeResource.checked_handle(bundle, expected_class: RenderBundle) }
       bundles_ptr = FFI::MemoryPointer.new(:pointer, bundle_handles.size)
       bundles_ptr.write_array_of_pointer(bundle_handles)
       Native.wgpuRenderPassEncoderExecuteBundles(@handle, bundle_handles.size, bundles_ptr)
     end
 
+    # Begins an occlusion query for subsequent draw calls.
+    #
+    # @param query_index [Integer] destination index in the pass query set
+    # @return [void]
     def begin_occlusion_query(query_index)
       Native.wgpuRenderPassEncoderBeginOcclusionQuery(@handle, query_index)
     end
 
+    # Ends the active occlusion query.
+    #
+    # @return [void]
     def end_occlusion_query
       Native.wgpuRenderPassEncoderEndOcclusionQuery(@handle)
     end
 
+    # Starts a labeled group in GPU debugging tools.
+    #
+    # @param label [String] group label
+    # @return [void]
     def push_debug_group(label)
       label_view = Native::StringView.new
       label_ptr = FFI::MemoryPointer.from_string(label)
@@ -126,10 +211,17 @@ module WGPU
       Native.wgpuRenderPassEncoderPushDebugGroup(@handle, label_view)
     end
 
+    # Ends the most recently pushed debug group.
+    #
+    # @return [void]
     def pop_debug_group
       Native.wgpuRenderPassEncoderPopDebugGroup(@handle)
     end
 
+    # Inserts a labeled point in GPU debugging tools.
+    #
+    # @param label [String] marker label
+    # @return [void]
     def insert_debug_marker(label)
       label_view = Native::StringView.new
       label_ptr = FFI::MemoryPointer.from_string(label)
@@ -138,6 +230,8 @@ module WGPU
       Native.wgpuRenderPassEncoderInsertDebugMarker(@handle, label_view)
     end
 
+    # Ends the pass if it has not already ended.
+    # @return [void]
     def end_pass
       return if @ended
 
@@ -146,14 +240,22 @@ module WGPU
       @encoder.send(:pass_ended, self)
     end
 
+    # Ends the pass.
+    # @return [void]
     def end
       end_pass
     end
 
+    # Reports whether the pass has ended.
+    # @return [Boolean]
     def ended?
       @ended
     end
 
+    # Releases the native render pass encoder handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuRenderPassEncoderRelease(@handle)
@@ -181,9 +283,9 @@ module WGPU
       attachments.each_with_index do |att, i|
         ca = Native::RenderPassColorAttachment.new(ptr + (i * Native::RenderPassColorAttachment.size))
         ca[:next_in_chain] = nil
-        ca[:view] = att[:view].handle
+        ca[:view] = NativeResource.checked_handle(att[:view], expected_class: TextureView)
         ca[:depth_slice] = att[:depth_slice] || 0xFFFFFFFF
-        ca[:resolve_target] = att[:resolve_target]&.handle
+        ca[:resolve_target] = (att[:resolve_target] && NativeResource.checked_handle(att[:resolve_target], expected_class: TextureView))
         ca[:load_op] = Native::EnumHelper.coerce(Native::LoadOp, att[:load_op] || :clear, name: "load op")
         ca[:store_op] = Native::EnumHelper.coerce(Native::StoreOp, att[:store_op] || :store, name: "store op")
 
@@ -201,7 +303,7 @@ module WGPU
       ds = Native::RenderPassDepthStencilAttachment.new
       @pointers << ds
 
-      ds[:view] = att[:view].handle
+      ds[:view] = NativeResource.checked_handle(att[:view], expected_class: TextureView)
       ds[:depth_load_op] = Native::EnumHelper.coerce(
         Native::LoadOp,
         att[:depth_load_op] || :clear,

data/lib/wgpu/core/adapter.rb

@@ -4,27 +4,63 @@ module WGPU
   class Adapter
     attr_reader :handle, :instance
 
+    # Wraps an existing native adapter handle.
+    # @param handle [FFI::Pointer] native adapter handle
+    # @param instance [Instance, nil] instance that owns the adapter
+    # @return [Adapter]
     def self.from_handle(handle, instance: nil)
-      adapter = allocate
-      adapter.instance_variable_set(:@handle, handle)
+      adapter = adopt_native_handle(handle)
       adapter.instance_variable_set(:@instance, instance)
       adapter
     end
 
+    # Requests an adapter and waits for the native callback.
+    #
+    # @param instance [Instance] instance used for discovery and callback progress
+    # @param power_preference [Symbol, Integer] preferred power profile
+    # @param backend [Symbol, Integer, nil] backend to restrict discovery to
+    # @param feature_level [Symbol, Integer] requested WebGPU feature level
+    # @param force_fallback_adapter [Boolean] whether to require a fallback adapter
+    # @param compatible_surface [Surface, nil] surface the adapter must support
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [Adapter] requested adapter
+    # @raise [AdapterError] if no adapter can be acquired
+    # @raise [TimeoutError] if the request exceeds +timeout+
     def self.request(instance, power_preference: :high_performance, backend: nil, feature_level: :core,
                      force_fallback_adapter: false, compatible_surface: nil, timeout: nil)
+      timeout = AsyncWaiter.normalize_timeout(timeout)
       adapter_ptr = FFI::MemoryPointer.new(:pointer)
-      status_holder = { value: nil, message: nil }
+      status_holder = {
+        done: false,
+        value: nil,
+        message: nil,
+        abandoned: false,
+        cleanup_claimed: false,
+        mutex: Mutex.new
+      }
 
+      callback_token = nil
       callback = FFI::Function.new(
         :void, [:uint32, :pointer, Native::StringView.by_value, :pointer, :pointer]
       ) do |status, adapter, message, _userdata1, _userdata2|
-        status_holder[:value] = Native::RequestAdapterStatus[status]
-        if message[:data] && !message[:data].null? && message[:length] > 0
-          status_holder[:message] = message[:data].read_string(message[:length])
+        abandoned_adapter = nil
+        begin
+          status_holder[:mutex].synchronize do
+            status_holder[:value] = Native::RequestAdapterStatus[status]
+            if message[:data] && !message[:data].null? && message[:length] > 0
+              status_holder[:message] = message[:data].read_string(message[:length])
+            end
+            adapter_ptr.write_pointer(adapter)
+            status_holder[:done] = true
+            if status_holder[:abandoned] && !status_holder[:cleanup_claimed]
+              status_holder[:cleanup_claimed] = true
+              abandoned_adapter = adapter
+            end
+          end
+          Native.wgpuAdapterRelease(abandoned_adapter) if abandoned_adapter && !abandoned_adapter.null?
+        ensure
+          CallbackKeepalive.release(instance, callback_token)
         end
-        adapter_ptr.write_pointer(adapter)
-        status_holder[:done] = true
       end
 
       options = Native::RequestAdapterOptions.new
@@ -45,7 +81,7 @@ module WGPU
         backend || :undefined,
         name: "backend type"
       )
-      options[:compatible_surface] = compatible_surface&.handle
+      options[:compatible_surface] = (compatible_surface && NativeResource.checked_handle(compatible_surface, expected_class: Surface))
 
       callback_info = Native::RequestAdapterCallbackInfo.new
       callback_info[:next_in_chain] = nil
@@ -55,12 +91,26 @@ module WGPU
       callback_info[:userdata2] = nil
 
       callback_token = CallbackKeepalive.retain(instance, callback)
+      future =
+        begin
+          Native.wgpuInstanceRequestAdapter(NativeResource.checked_handle(instance, expected_class: Instance), options, callback_info)
+        rescue StandardError
+          CallbackKeepalive.release(instance, callback_token)
+          raise
+        end
+
       begin
-        status_holder[:done] = false
-        future = Native.wgpuInstanceRequestAdapter(instance.handle, options, callback_info)
         AsyncWaiter.wait(status_holder: status_holder, instance: instance, future: future, timeout: timeout)
-      ensure
-        CallbackKeepalive.release(instance, callback_token)
+      rescue StandardError
+        abandoned_adapter = status_holder[:mutex].synchronize do
+          status_holder[:abandoned] = true
+          next unless status_holder[:done] && !status_holder[:cleanup_claimed]
+
+          status_holder[:cleanup_claimed] = true
+          adapter_ptr.read_pointer
+        end
+        Native.wgpuAdapterRelease(abandoned_adapter) if abandoned_adapter && !abandoned_adapter.null?
+        raise
       end
 
       handle = adapter_ptr.read_pointer
@@ -72,11 +122,16 @@ module WGPU
       new(handle, instance: instance)
     end
 
+    # Wraps a native adapter handle.
+    # @param handle [FFI::Pointer] native adapter handle
+    # @param instance [Instance, nil] instance that owns the adapter
     def initialize(handle, instance: nil)
       @handle = handle
       @instance = instance
     end
 
+    # Requests a logical device from this adapter.
+    # @return [Device]
     def request_device(label: nil, required_features: [], required_limits: nil, timeout: nil)
       Device.request(
         self,
@@ -87,6 +142,8 @@ module WGPU
       )
     end
 
+    # Requests a logical device on a background task.
+    # @return [AsyncTask] task yielding a {Device}
     def request_device_async(label: nil, required_features: [], required_limits: nil, timeout: nil)
       AsyncTask.new do
         request_device(
@@ -98,6 +155,8 @@ module WGPU
       end
     end
 
+    # Returns identifying and backend information for the adapter.
+    # @return [Hash]
     def info
       info_struct = Native::AdapterInfo.new
       Native.wgpuAdapterGetInfo(@handle, info_struct)
@@ -117,22 +176,32 @@ module WGPU
       result
     end
 
+    # Returns the adapter's device name.
+    # @return [String]
     def name
       info[:device]
     end
 
+    # Returns the adapter vendor name.
+    # @return [String]
     def vendor
       info[:vendor]
     end
 
+    # Returns the backend used by the adapter.
+    # @return [Symbol, Integer]
     def backend_type
       info[:backend_type]
     end
 
+    # Returns the adapter's device classification.
+    # @return [Symbol, Integer]
     def adapter_type
       info[:adapter_type]
     end
 
+    # Lists optional features supported by the adapter.
+    # @return [Array<Symbol>]
     def features
       supported = Native::SupportedFeatures.new
       Native.wgpuAdapterGetFeatures(@handle, supported)
@@ -144,12 +213,19 @@ module WGPU
         end
       end
       result
+    ensure
+      Native.wgpuSupportedFeaturesFreeMembers(supported) if supported
     end
 
+    # Reports whether the adapter supports a feature.
+    # @param feature [Symbol] feature name
+    # @return [Boolean]
     def has_feature?(feature)
       features.include?(feature)
     end
 
+    # Returns the adapter resource limits.
+    # @return [Hash{Symbol => Integer}]
     def limits
       supported = Native::SupportedLimits.new
       supported[:next_in_chain] = nil
@@ -157,11 +233,17 @@ module WGPU
       limits_to_hash(supported[:limits])
     end
 
+    # Returns a concise human-readable adapter description.
+    # @return [String]
     def summary
       info_hash = info
       "#{info_hash[:device]} (#{info_hash[:adapter_type]}) via #{info_hash[:backend_type]}"
     end
 
+    # Releases the native adapter handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuAdapterRelease(@handle)

data/lib/wgpu/core/async_waiter.rb

@@ -10,10 +10,16 @@ module WGPU
 
     module_function
 
+    # Returns the delay between callback progress polls.
+    # @return [Float] seconds
     def poll_interval
       @poll_interval ||= POLL_INTERVAL_SECONDS
     end
 
+    # Sets the delay between callback progress polls.
+    # @param seconds [Numeric] positive delay in seconds
+    # @return [Float]
+    # @raise [ArgumentError] if the delay is not positive
     def poll_interval=(seconds)
       value = Float(seconds)
       raise ArgumentError, "poll interval must be positive" unless value.positive?
@@ -21,6 +27,10 @@ module WGPU
       @poll_interval = value
     end
 
+    # Selects the native callback delivery mode for an operation.
+    #
+    # @param instance [Instance, nil] instance capable of processing events
+    # @return [Integer] native {Native::CallbackMode} value
     def callback_mode(instance:)
       if instance
         callback_mode_value(:allow_process_events)
@@ -29,9 +39,13 @@ module WGPU
       end
     end
 
+    # Drives native event processing until a callback completes.
+    # @param status_holder [Hash] state whose +:done+ flag is set by the callback
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [void]
+    # @raise [TimeoutError] if completion exceeds the timeout
     def wait(status_holder:, instance: nil, device: nil, future: nil, timeout: nil)
-      timeout = Float(timeout) if timeout
-      raise ArgumentError, "timeout must be non-negative" if timeout&.negative?
+      timeout = normalize_timeout(timeout)
 
       deadline = monotonic_time + timeout if timeout
       wait_info = build_wait_info(future) if instance && Native.future_api?
@@ -45,12 +59,24 @@ module WGPU
         elsif instance
           instance.process_events
         elsif device && Native.device_poll_available?
-          Native.wgpuDevicePoll(device.handle, 0, nil)
+          Native.wgpuDevicePoll(NativeResource.checked_handle(device, expected_class: Device), 0, nil)
         end
         sleep(poll_interval) unless status_holder[:done] || waited
       end
     end
 
+    # Validates a timeout before any native operation is started.
+    def normalize_timeout(timeout)
+      return nil if timeout.nil?
+
+      value = Float(timeout)
+      raise ArgumentError, "timeout must be finite and non-negative" unless value.finite? && value >= 0
+
+      value
+    rescue TypeError
+      raise ArgumentError, "timeout must be a number"
+    end
+
     def callback_mode_value(name)
       Native::CallbackMode[name] || CALLBACK_MODE_FALLBACK.fetch(name)
     end
@@ -72,7 +98,7 @@ module WGPU
     private_class_method :build_wait_info
 
     def wait_with_wait_any(instance, wait_info)
-      status = Native.wgpuInstanceWaitAny(instance.handle, 1, wait_info.to_ptr, 0)
+      status = Native.wgpuInstanceWaitAny(NativeResource.checked_handle(instance, expected_class: Instance), 1, wait_info.to_ptr, 0)
       return false if [:success, :timed_out].include?(status)
 
       raise Error, "wgpuInstanceWaitAny failed: #{status.inspect}"

data/lib/wgpu/core/canvas_context.rb

@@ -4,29 +4,52 @@ module WGPU
   class CanvasContext
     attr_reader :physical_size
 
+    # Creates a canvas context for platform presentation information.
+    # @param instance [Instance] owning WebGPU instance
+    # @param present_info [Hash] platform handles or an existing surface
     def initialize(instance, present_info = {})
       @instance = instance
       @present_info = present_info || {}
-      @surface = @present_info[:surface]
+      @surface = @present_info[:wgpu_surface]
+      if @present_info[:surface].is_a?(Surface) || ![:wayland, :linux_wayland].include?(@present_info[:platform]&.to_sym)
+        @surface ||= @present_info[:surface]
+      end
       @physical_size = [0, 0]
       @config = nil
     end
 
+    # Updates the drawable's physical pixel size.
+    # @param width [Integer] width in pixels
+    # @param height [Integer] height in pixels
+    # @return [Array<Integer>] stored width and height
+    # @raise [ArgumentError] if either dimension is negative
     def set_physical_size(width, height)
       raise ArgumentError, "width and height must be non-negative" if width.to_i.negative? || height.to_i.negative?
 
       @physical_size = [width.to_i, height.to_i]
     end
 
+    # Returns the surface format preferred by an adapter.
+    #
+    # @param adapter [Adapter] adapter used to query surface capabilities
+    # @return [Symbol] preferred texture format
     def get_preferred_format(adapter)
       ensure_surface
       @surface.get_preferred_format(adapter)
     end
 
+    # Returns the most recent canvas configuration.
+    #
+    # @return [Hash, nil] configuration options, or +nil+ when unconfigured
     def get_configuration
       @config
     end
 
+    # Configures the backing surface for presentation.
+    # @param device [Device] device used to render frames
+    # @param format [Symbol, nil] surface texture format
+    # @return [Hash] resolved canvas configuration
+    # @raise [SurfaceError] if no surface exists or dimensions are not positive
     def configure(device:, format: nil, usage: :render_attachment, view_formats: [], color_space: "srgb", tone_mapping: nil, alpha_mode: :opaque, width: nil, height: nil, present_mode: :fifo)
       ensure_surface
 
@@ -59,21 +82,33 @@ module WGPU
       }
     end
 
+    # Removes the current surface configuration.
+    # @return [void]
     def unconfigure
       @surface&.unconfigure
       @config = nil
     end
 
+    # Acquires the texture for the current presentation frame.
+    #
+    # @return [Texture] acquired surface texture
+    # @raise [SurfaceError] if the context has not been configured
+    # @raise [SurfaceAcquisitionError] if acquisition fails
     def get_current_texture
       raise SurfaceError, "Canvas context must be configured before get_current_texture" unless @config
 
       @surface.current_texture
     end
 
+    # Presents the current surface texture.
+    # @return [void]
     def present
       @surface&.present
     end
 
+    # Releases the backing surface and clears the configuration.
+    #
+    # @return [void]
     def release
       @surface&.release
       @surface = nil
@@ -93,7 +128,7 @@ module WGPU
                  when :x11, :linux_x11
                    Surface.from_xlib_window(@instance, @present_info.fetch(:display), @present_info.fetch(:window))
                  when :wayland, :linux_wayland
-                   Surface.from_wayland_surface(@instance, @present_info.fetch(:display), @present_info.fetch(:surface))
+                   Surface.from_wayland_surface(@instance, @present_info.fetch(:display), @present_info.fetch(:wl_surface) { @present_info.fetch(:surface) })
                  else
                    raise SurfaceError, "Cannot build surface from present_info: #{@present_info.inspect}"
                  end