wgpu 1.1.0 → 1.2.1

data/lib/wgpu/commands/render_pass.rb

@@ -4,10 +4,20 @@ 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 = []
       @max_draw_count = max_draw_count
+      @ended = false
 
       desc = Native::RenderPassDescriptor.new
       desc[:next_in_chain] = nil
@@ -40,10 +50,18 @@ module WGPU
       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)
     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)
@@ -54,32 +72,72 @@ module WGPU
       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)
     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
-      Native.wgpuRenderPassEncoderSetIndexBuffer(@handle, buffer.handle, format, offset, size)
+      format_value = Native::EnumHelper.coerce(Native::IndexFormat, format, name: "index format")
+      Native.wgpuRenderPassEncoderSetIndexBuffer(@handle, buffer.handle, 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
@@ -89,18 +147,36 @@ 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)
     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)
     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)
       bundles_ptr = FFI::MemoryPointer.new(:pointer, bundle_handles.size)
@@ -108,14 +184,25 @@ module WGPU
       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)
@@ -124,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)
@@ -136,14 +230,32 @@ 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
+
       Native.wgpuRenderPassEncoderEnd(@handle)
+      @ended = true
+      @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)
@@ -169,13 +281,13 @@ module WGPU
       @pointers << ptr
 
       attachments.each_with_index do |att, i|
-        ca = Native::RenderPassColorAttachment.new(ptr + i * Native::RenderPassColorAttachment.size)
+        ca = Native::RenderPassColorAttachment.new(ptr + (i * Native::RenderPassColorAttachment.size))
         ca[:next_in_chain] = nil
         ca[:view] = att[:view].handle
         ca[:depth_slice] = att[:depth_slice] || 0xFFFFFFFF
         ca[:resolve_target] = att[:resolve_target]&.handle
-        ca[:load_op] = att[:load_op] || :clear
-        ca[:store_op] = att[:store_op] || :store
+        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")
 
         clear = att[:clear_value] || { r: 0.0, g: 0.0, b: 0.0, a: 1.0 }
         ca[:clear_value][:r] = clear[:r] || 0.0
@@ -192,12 +304,28 @@ module WGPU
       @pointers << ds
 
       ds[:view] = att[:view].handle
-      ds[:depth_load_op] = att[:depth_load_op] || :clear
-      ds[:depth_store_op] = att[:depth_store_op] || :store
+      ds[:depth_load_op] = Native::EnumHelper.coerce(
+        Native::LoadOp,
+        att[:depth_load_op] || :clear,
+        name: "depth load op"
+      )
+      ds[:depth_store_op] = Native::EnumHelper.coerce(
+        Native::StoreOp,
+        att[:depth_store_op] || :store,
+        name: "depth store op"
+      )
       ds[:depth_clear_value] = att[:depth_clear_value] || 1.0
       ds[:depth_read_only] = att[:depth_read_only] ? 1 : 0
-      ds[:stencil_load_op] = att[:stencil_load_op] || :clear
-      ds[:stencil_store_op] = att[:stencil_store_op] || :store
+      ds[:stencil_load_op] = Native::EnumHelper.coerce(
+        Native::LoadOp,
+        att[:stencil_load_op] || :clear,
+        name: "stencil load op"
+      )
+      ds[:stencil_store_op] = Native::EnumHelper.coerce(
+        Native::StoreOp,
+        att[:stencil_store_op] || :store,
+        name: "stencil store op"
+      )
       ds[:stencil_clear_value] = att[:stencil_clear_value] || 0
       ds[:stencil_read_only] = att[:stencil_read_only] ? 1 : 0
 

data/lib/wgpu/core/adapter.rb

@@ -4,34 +4,82 @@ 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
 
-    def self.request(instance, power_preference: :high_performance, backend: nil, feature_level: :core, force_fallback_adapter: false, compatible_surface: nil)
+    # 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)
       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
       options[:next_in_chain] = nil
-      options[:feature_level] = feature_level
-      options[:power_preference] = power_preference
+      options[:feature_level] = Native::EnumHelper.coerce(
+        Native::FeatureLevel,
+        feature_level,
+        name: "feature level"
+      )
+      options[:power_preference] = Native::EnumHelper.coerce(
+        Native::PowerPreference,
+        power_preference,
+        name: "power preference"
+      )
       options[:force_fallback_adapter] = force_fallback_adapter ? 1 : 0
-      options[:backend_type] = backend || :undefined
+      options[:backend_type] = Native::EnumHelper.coerce(
+        Native::BackendType,
+        backend || :undefined,
+        name: "backend type"
+      )
       options[:compatible_surface] = compatible_surface&.handle
 
       callback_info = Native::RequestAdapterCallbackInfo.new
@@ -41,9 +89,28 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      status_holder[:done] = false
-      future = Native.wgpuInstanceRequestAdapter(instance.handle, options, callback_info)
-      AsyncWaiter.wait(status_holder: status_holder, instance: instance, future: future)
+      callback_token = CallbackKeepalive.retain(instance, callback)
+      future =
+        begin
+          Native.wgpuInstanceRequestAdapter(instance.handle, options, callback_info)
+        rescue StandardError
+          CallbackKeepalive.release(instance, callback_token)
+          raise
+        end
+
+      begin
+        AsyncWaiter.wait(status_holder: status_holder, instance: instance, future: future, timeout: timeout)
+      rescue TimeoutError
+        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
       if handle.null? || status_holder[:value] != :success
@@ -54,25 +121,41 @@ 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
 
-    def request_device(label: nil, required_features: [], required_limits: nil)
-      Device.request(self, label: label, required_features: required_features, required_limits: required_limits)
+    # Requests a logical device from this adapter.
+    # @return [Device]
+    def request_device(label: nil, required_features: [], required_limits: nil, timeout: nil)
+      Device.request(
+        self,
+        label: label,
+        required_features: required_features,
+        required_limits: required_limits,
+        timeout: timeout
+      )
     end
 
-    def request_device_async(label: nil, required_features: [], required_limits: nil)
+    # 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(
           label: label,
           required_features: required_features,
-          required_limits: required_limits
+          required_limits: required_limits,
+          timeout: timeout
         )
       end
     end
 
+    # Returns identifying and backend information for the adapter.
+    # @return [Hash]
     def info
       info_struct = Native::AdapterInfo.new
       Native.wgpuAdapterGetInfo(@handle, info_struct)
@@ -92,22 +175,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)
@@ -121,10 +214,15 @@ module WGPU
       result
     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
@@ -132,11 +230,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,6 +10,27 @@ 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?
+
+      @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)
@@ -18,18 +39,30 @@ module WGPU
       end
     end
 
-    def wait(status_holder:, instance: nil, device: nil, future: nil)
+    # 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?
+
+      deadline = monotonic_time + timeout if timeout
       wait_info = build_wait_info(future) if instance && Native.future_api?
 
       until status_holder[:done]
+        raise_timeout!(timeout) if deadline && monotonic_time >= deadline
+
+        waited = false
         if instance && wait_info
-          wait_with_wait_any(instance, wait_info)
+          waited = wait_with_wait_any(instance, wait_info)
         elsif instance
           instance.process_events
         elsif device && Native.device_poll_available?
           Native.wgpuDevicePoll(device.handle, 0, nil)
         end
-        sleep(POLL_INTERVAL_SECONDS) unless status_holder[:done]
+        sleep(poll_interval) unless status_holder[:done] || waited
       end
     end
 
@@ -55,10 +88,20 @@ module WGPU
 
     def wait_with_wait_any(instance, wait_info)
       status = Native.wgpuInstanceWaitAny(instance.handle, 1, wait_info.to_ptr, 0)
-      return if [:success, :timed_out].include?(status)
+      return false if [:success, :timed_out].include?(status)
 
       raise Error, "wgpuInstanceWaitAny failed: #{status.inspect}"
     end
     private_class_method :wait_with_wait_any
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+    private_class_method :monotonic_time
+
+    def raise_timeout!(timeout)
+      raise TimeoutError, "GPU operation timed out after #{timeout} seconds"
+    end
+    private_class_method :raise_timeout!
   end
 end

data/lib/wgpu/core/canvas_context.rb

@@ -4,6 +4,9 @@ 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 || {}
@@ -12,25 +15,40 @@ module WGPU
       @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
-      color_space # reserved for API parity
-      tone_mapping # reserved for API parity
 
       width = width || @physical_size[0]
       height = height || @physical_size[1]
@@ -61,21 +79,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