wgpu 1.1.0 → 1.2.1

data/lib/wgpu/async_task.rb

@@ -4,6 +4,8 @@ require "timeout"
 
 module WGPU
   class AsyncTask
+    # Starts a background task that evaluates the given block.
+    # @raise [ArgumentError] if no block is supplied
     def initialize(&block)
       raise ArgumentError, "block is required" unless block
 
@@ -18,12 +20,20 @@ module WGPU
       end
     end
 
+    # Waits until the task finishes.
+    # @param timeout [Numeric, nil] maximum number of seconds to wait
+    # @return [AsyncTask] this task
+    # @raise [Timeout::Error] if the task does not finish in time
     def wait(timeout: nil)
       joined = timeout ? @thread.join(timeout) : @thread.join
       raise Timeout::Error, "async task timeout" unless joined
       self
     end
 
+    # Waits for and returns the task result.
+    # @param timeout [Numeric, nil] maximum number of seconds to wait
+    # @return [Object] block result
+    # @raise [StandardError] re-raises an exception raised by the block
     def value(timeout: nil)
       wait(timeout: timeout)
       raise @error if @error
@@ -31,20 +41,29 @@ module WGPU
       @value
     end
 
+    # Creates a task that transforms this task's result.
+    # @yieldparam value [Object] completed task result
+    # @return [AsyncTask] chained task
     def then(&block)
       AsyncTask.new do
         block.call(value)
       end
     end
 
+    # Reports whether the task has finished.
+    # @return [Boolean]
     def complete?
       !@thread.alive?
     end
 
+    # Reports whether the task is still running.
+    # @return [Boolean]
     def pending?
       @thread.alive?
     end
 
+    # Returns the exception raised by the task, if any.
+    # @return [StandardError, nil]
     def error
       value
       nil

data/lib/wgpu/commands/command_buffer.rb

@@ -4,10 +4,34 @@ module WGPU
   class CommandBuffer
     attr_reader :handle
 
-    def initialize(handle)
+    # Wraps an encoded native command buffer.
+    # @param handle [FFI::Pointer] native command buffer handle
+    # @param device [Device, nil] device whose callbacks the command buffer may use
+    def initialize(handle, device: nil)
       @handle = handle
+      @device = device
+      @submitted = false
     end
 
+    # Reports whether this command buffer has been submitted.
+    # @return [Boolean]
+    def submitted?
+      @submitted
+    end
+
+    # Marks this command buffer as submitted.
+    # @raise [CommandError] if it was already submitted
+    # @return [void]
+    def mark_submitted!
+      raise CommandError, "Command buffer has already been submitted" if @submitted
+
+      @submitted = true
+    end
+
+    # Releases the native command buffer handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuCommandBufferRelease(@handle)

data/lib/wgpu/commands/command_encoder.rb

@@ -4,9 +4,14 @@ module WGPU
   class CommandEncoder
     attr_reader :handle
 
+    # Creates an encoder for commands submitted to a device queue.
+    # @param device [Device] owning device
+    # @param label [String, nil] optional debug label
+    # @raise [CommandError] if the native encoder cannot be created
     def initialize(device, label: nil)
       @device = device
       @finished = false
+      @active_pass = nil
 
       desc = Native::CommandEncoderDescriptor.new
       desc[:next_in_chain] = nil
@@ -23,14 +28,36 @@ module WGPU
       raise CommandError, "Failed to create command encoder" if @handle.null?
     end
 
+    # Begins a compute pass, optionally yielding it for scoped recording.
+    # @param label [String, nil] optional debug label
+    # @param timestamp_writes [Hash, nil] timestamp query settings
+    # @yieldparam pass [ComputePass] newly created pass
+    # @return [ComputePass, Object] pass without a block, otherwise the block result
     def begin_compute_pass(label: nil, timestamp_writes: nil)
-      raise CommandError, "Encoder already finished" if @finished
-      ComputePass.new(self, label: label, timestamp_writes: timestamp_writes)
+      ensure_can_begin_pass!
+      pass = ComputePass.new(self, label: label, timestamp_writes: timestamp_writes)
+      @active_pass = pass
+      return pass unless block_given?
+
+      begin
+        yield pass
+      ensure
+        begin
+          pass.end_pass unless pass.ended?
+        ensure
+          pass.release
+          pass_ended(pass)
+        end
+      end
     end
 
+    # Begins a render pass, optionally yielding it for scoped recording.
+    # @param color_attachments [Array<Hash>] color attachment descriptors
+    # @yieldparam pass [RenderPass] newly created pass
+    # @return [RenderPass, Object] pass without a block, otherwise the block result
     def begin_render_pass(color_attachments:, depth_stencil_attachment: nil, occlusion_query_set: nil, timestamp_writes: nil, max_draw_count: nil, label: nil)
-      raise CommandError, "Encoder already finished" if @finished
-      RenderPass.new(self,
+      ensure_can_begin_pass!
+      pass = RenderPass.new(self,
         color_attachments: color_attachments,
         depth_stencil_attachment: depth_stencil_attachment,
         occlusion_query_set: occlusion_query_set,
@@ -38,8 +65,23 @@ module WGPU
         max_draw_count: max_draw_count,
         label: label
       )
+      @active_pass = pass
+      return pass unless block_given?
+
+      begin
+        yield pass
+      ensure
+        begin
+          pass.end_pass unless pass.ended?
+        ensure
+          pass.release
+          pass_ended(pass)
+        end
+      end
     end
 
+    # Copies bytes between buffers.
+    # @return [void]
     def copy_buffer_to_buffer(source:, source_offset: 0, destination:, destination_offset: 0, size:)
       raise CommandError, "Encoder already finished" if @finished
       Native.wgpuCommandEncoderCopyBufferToBuffer(
@@ -50,6 +92,11 @@ module WGPU
       )
     end
 
+    # Copies buffer data into a texture region.
+    # @param source [Hash] buffer and layout descriptor
+    # @param destination [Hash] texture and origin descriptor
+    # @param copy_size [Hash, Array] extent to copy
+    # @return [void]
     def copy_buffer_to_texture(source:, destination:, copy_size:)
       raise CommandError, "Encoder already finished" if @finished
 
@@ -70,11 +117,20 @@ module WGPU
       dst[:origin][:x] = destination.dig(:origin, :x) || 0
       dst[:origin][:y] = destination.dig(:origin, :y) || 0
       dst[:origin][:z] = destination.dig(:origin, :z) || 0
-      dst[:aspect] = destination[:aspect] || :all
+      dst[:aspect] = Native::EnumHelper.coerce(
+        Native::TextureAspect,
+        destination[:aspect] || :all,
+        name: "texture aspect"
+      )
 
       Native.wgpuCommandEncoderCopyBufferToTexture(@handle, src, dst, size)
     end
 
+    # Copies a texture region into a buffer.
+    # @param source [Hash] texture and origin descriptor
+    # @param destination [Hash] buffer and layout descriptor
+    # @param copy_size [Hash, Array] extent to copy
+    # @return [void]
     def copy_texture_to_buffer(source:, destination:, copy_size:)
       raise CommandError, "Encoder already finished" if @finished
 
@@ -89,7 +145,11 @@ module WGPU
       src[:origin][:x] = source.dig(:origin, :x) || 0
       src[:origin][:y] = source.dig(:origin, :y) || 0
       src[:origin][:z] = source.dig(:origin, :z) || 0
-      src[:aspect] = source[:aspect] || :all
+      src[:aspect] = Native::EnumHelper.coerce(
+        Native::TextureAspect,
+        source[:aspect] || :all,
+        name: "texture aspect"
+      )
 
       dst = Native::ImageCopyBuffer.new
       dst[:layout][:offset] = destination[:offset] || 0
@@ -100,6 +160,11 @@ module WGPU
       Native.wgpuCommandEncoderCopyTextureToBuffer(@handle, src, dst, size)
     end
 
+    # Copies one texture region into another texture.
+    # @param source [Hash] source texture and origin descriptor
+    # @param destination [Hash] destination texture and origin descriptor
+    # @param copy_size [Hash, Array] extent to copy
+    # @return [void]
     def copy_texture_to_texture(source:, destination:, copy_size:)
       raise CommandError, "Encoder already finished" if @finished
 
@@ -109,7 +174,11 @@ module WGPU
       src[:origin][:x] = source.dig(:origin, :x) || 0
       src[:origin][:y] = source.dig(:origin, :y) || 0
       src[:origin][:z] = source.dig(:origin, :z) || 0
-      src[:aspect] = source[:aspect] || :all
+      src[:aspect] = Native::EnumHelper.coerce(
+        Native::TextureAspect,
+        source[:aspect] || :all,
+        name: "source texture aspect"
+      )
 
       dst = Native::ImageCopyTexture.new
       dst[:texture] = destination[:texture].handle
@@ -117,7 +186,11 @@ module WGPU
       dst[:origin][:x] = destination.dig(:origin, :x) || 0
       dst[:origin][:y] = destination.dig(:origin, :y) || 0
       dst[:origin][:z] = destination.dig(:origin, :z) || 0
-      dst[:aspect] = destination[:aspect] || :all
+      dst[:aspect] = Native::EnumHelper.coerce(
+        Native::TextureAspect,
+        destination[:aspect] || :all,
+        name: "destination texture aspect"
+      )
 
       size = Native::Extent3D.new
       size[:width] = copy_size[:width] || copy_size[0]
@@ -127,6 +200,8 @@ module WGPU
       Native.wgpuCommandEncoderCopyTextureToTexture(@handle, src, dst, size)
     end
 
+    # Resolves query results into a destination buffer.
+    # @return [void]
     def resolve_query_set(query_set:, first_query:, query_count:, destination:, destination_offset:)
       raise CommandError, "Encoder already finished" if @finished
       Native.wgpuCommandEncoderResolveQuerySet(
@@ -139,17 +214,29 @@ module WGPU
       )
     end
 
+    # Clears a byte range in a buffer to zero.
+    # @param buffer [Buffer] buffer to clear
+    # @param offset [Integer] first byte to clear
+    # @param size [Integer, nil] number of bytes to clear
+    # @return [void]
     def clear_buffer(buffer, offset: 0, size: nil)
       raise CommandError, "Encoder already finished" if @finished
       size ||= buffer.size - offset
       Native.wgpuCommandEncoderClearBuffer(@handle, buffer.handle, offset, size)
     end
 
+    # Writes a GPU timestamp to a query set.
+    # @param query_set [QuerySet] timestamp query set
+    # @param query_index [Integer] destination query index
+    # @return [void]
     def write_timestamp(query_set, query_index)
       raise CommandError, "Encoder already finished" if @finished
       Native.wgpuCommandEncoderWriteTimestamp(@handle, query_set.handle, query_index)
     end
 
+    # Starts a labeled group in GPU debugging tools.
+    # @param label [String] group label
+    # @return [void]
     def push_debug_group(label)
       raise CommandError, "Encoder already finished" if @finished
       label_view = Native::StringView.new
@@ -159,11 +246,16 @@ module WGPU
       Native.wgpuCommandEncoderPushDebugGroup(@handle, label_view)
     end
 
+    # Ends the most recently pushed debug group.
+    # @return [void]
     def pop_debug_group
       raise CommandError, "Encoder already finished" if @finished
       Native.wgpuCommandEncoderPopDebugGroup(@handle)
     end
 
+    # Inserts a labeled point in GPU debugging tools.
+    # @param label [String] marker label
+    # @return [void]
     def insert_debug_marker(label)
       raise CommandError, "Encoder already finished" if @finished
       label_view = Native::StringView.new
@@ -173,8 +265,15 @@ module WGPU
       Native.wgpuCommandEncoderInsertDebugMarker(@handle, label_view)
     end
 
+    # Finishes recording and returns a command buffer.
+    # @param label [String, nil] optional command buffer label
+    # @return [CommandBuffer]
+    # @raise [CommandError] if the encoder is finished, has an active pass, or native creation fails
     def finish(label: nil)
       raise CommandError, "Encoder already finished" if @finished
+      if @active_pass && !@active_pass.ended?
+        raise CommandError, "Cannot finish command encoder while a pass is active"
+      end
       @finished = true
 
       desc = nil
@@ -189,13 +288,28 @@ module WGPU
       buffer_handle = Native.wgpuCommandEncoderFinish(@handle, desc)
       raise CommandError, "Failed to finish command encoder" if buffer_handle.null?
 
-      CommandBuffer.new(buffer_handle)
+      CommandBuffer.new(buffer_handle, device: @device)
     end
 
+    # Releases the native command encoder handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuCommandEncoderRelease(@handle)
       @handle = FFI::Pointer::NULL
     end
+
+    private
+
+    def ensure_can_begin_pass!
+      raise CommandError, "Encoder already finished" if @finished
+      raise CommandError, "A command pass is already active" if @active_pass && !@active_pass.ended?
+    end
+
+    def pass_ended(pass)
+      @active_pass = nil if @active_pass.equal?(pass)
+    end
   end
 end

data/lib/wgpu/commands/compute_pass.rb

@@ -4,7 +4,14 @@ module WGPU
   class ComputePass
     attr_reader :handle
 
+    # Begins a compute pass owned by the command encoder.
+    # @param encoder [CommandEncoder] owning encoder
+    # @param label [String, nil] optional debug label
+    # @param timestamp_writes [Hash, nil] beginning and ending timestamp query settings
+    # @raise [CommandError] if the native pass cannot be created
     def initialize(encoder, label: nil, timestamp_writes: nil)
+      @encoder = encoder
+      @ended = false
       desc = Native::ComputePassDescriptor.new
       desc[:next_in_chain] = nil
       if label
@@ -30,10 +37,18 @@ module WGPU
       raise CommandError, "Failed to begin compute pass" if @handle.null?
     end
 
+    # Selects the compute pipeline used by subsequent dispatches.
+    # @param pipeline [ComputePipeline] pipeline to bind
+    # @return [void]
     def set_pipeline(pipeline)
       Native.wgpuComputePassEncoderSetPipeline(@handle, pipeline.handle)
     end
 
+    # Binds a resource group for subsequent dispatches.
+    # @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.wgpuComputePassEncoderSetBindGroup(@handle, index, bind_group.handle, 0, nil)
@@ -44,14 +59,27 @@ module WGPU
       end
     end
 
+    # Dispatches a three-dimensional compute workgroup grid.
+    # @param x [Integer] workgroup count on the x axis
+    # @param y [Integer] workgroup count on the y axis
+    # @param z [Integer] workgroup count on the z axis
+    # @return [void]
     def dispatch_workgroups(x, y = 1, z = 1)
       Native.wgpuComputePassEncoderDispatchWorkgroups(@handle, x, y, z)
     end
 
+    # Dispatches workgroups using arguments read from a buffer.
+    # @param buffer [Buffer] indirect argument buffer
+    # @param offset [Integer] byte offset of the arguments
+    # @return [void]
     def dispatch_workgroups_indirect(buffer, offset: 0)
       Native.wgpuComputePassEncoderDispatchWorkgroupsIndirect(@handle, buffer.handle, offset)
     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)
@@ -60,10 +88,17 @@ module WGPU
       Native.wgpuComputePassEncoderPushDebugGroup(@handle, label_view)
     end
 
+    # Ends the most recently pushed debug group.
+    #
+    # @return [void]
     def pop_debug_group
       Native.wgpuComputePassEncoderPopDebugGroup(@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)
@@ -72,14 +107,32 @@ module WGPU
       Native.wgpuComputePassEncoderInsertDebugMarker(@handle, label_view)
     end
 
+    # Ends the pass if it has not already ended.
+    # @return [void]
     def end_pass
+      return if @ended
+
       Native.wgpuComputePassEncoderEnd(@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 compute pass encoder handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuComputePassEncoderRelease(@handle)

data/lib/wgpu/commands/render_bundle.rb

@@ -4,10 +4,18 @@ module WGPU
   class RenderBundle
     attr_reader :handle
 
-    def initialize(handle)
+    # Wraps a reusable native render bundle.
+    # @param handle [FFI::Pointer] native render bundle handle
+    # @param device [Device, nil] device whose callbacks the render bundle may use
+    def initialize(handle, device: nil)
       @handle = handle
+      @device = device
     end
 
+    # Releases the native render bundle handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
 

data/lib/wgpu/commands/render_bundle_encoder.rb

@@ -4,6 +4,15 @@ module WGPU
   class RenderBundleEncoder
     attr_reader :handle
 
+    # Creates an encoder for reusable render commands.
+    # @param device [Device] owning device
+    # @param color_formats [Array<Symbol, Integer>] color attachment formats
+    # @param depth_stencil_format [Symbol, Integer, nil] optional depth/stencil format
+    # @param sample_count [Integer] multisample count
+    # @param depth_read_only [Boolean] whether depth writes are disabled
+    # @param stencil_read_only [Boolean] whether stencil writes are disabled
+    # @param label [String, nil] optional debug label
+    # @raise [RenderBundleError] if the native encoder cannot be created
     def initialize(device, color_formats:, depth_stencil_format: nil, sample_count: 1,
                    depth_read_only: false, stencil_read_only: false, label: nil)
       @device = device
@@ -21,13 +30,19 @@ module WGPU
         desc[:label][:length] = 0
       end
 
-      formats = Array(color_formats).map { |f| Native::TextureFormat[f] }
+      formats = Array(color_formats).map do |format|
+        Native::EnumHelper.coerce(Native::TextureFormat, format, name: "color format")
+      end
       @formats_ptr = FFI::MemoryPointer.new(:uint32, formats.size)
       @formats_ptr.write_array_of_uint32(formats)
       desc[:color_format_count] = formats.size
       desc[:color_formats] = @formats_ptr
 
-      desc[:depth_stencil_format] = depth_stencil_format || :undefined
+      desc[:depth_stencil_format] = Native::EnumHelper.coerce(
+        Native::TextureFormat,
+        depth_stencil_format || :undefined,
+        name: "depth stencil format"
+      )
       desc[:sample_count] = sample_count
       desc[:depth_read_only] = depth_read_only ? 1 : 0
       desc[:stencil_read_only] = stencil_read_only ? 1 : 0
@@ -36,12 +51,21 @@ module WGPU
       raise RenderBundleError, "Failed to create render bundle encoder" if @handle.null?
     end
 
+    # Selects the pipeline used by subsequent bundle draws.
+    # @param pipeline [RenderPipeline] pipeline to bind
+    # @raise [RenderBundleError] if the encoder is finished
+    # @return [void]
     def set_pipeline(pipeline)
       raise RenderBundleError, "Encoder already finished" if @finished
 
       Native.wgpuRenderBundleEncoderSetPipeline(@handle, pipeline.handle)
     end
 
+    # Binds a resource group for subsequent bundle draws.
+    # @param index [Integer] bind group index
+    # @param bind_group [BindGroup] group to bind
+    # @param dynamic_offsets [Array<Integer>, nil] dynamic buffer offsets
+    # @return [void]
     def set_bind_group(index, bind_group, dynamic_offsets: nil)
       raise RenderBundleError, "Encoder already finished" if @finished
 
@@ -54,6 +78,10 @@ module WGPU
       end
     end
 
+    # Binds a vertex buffer to a slot.
+    # @param slot [Integer] vertex buffer slot
+    # @param buffer [Buffer] vertex data buffer
+    # @return [void]
     def set_vertex_buffer(slot, buffer, offset: 0, size: nil)
       raise RenderBundleError, "Encoder already finished" if @finished
 
@@ -61,37 +89,57 @@ module WGPU
       Native.wgpuRenderBundleEncoderSetVertexBuffer(@handle, slot, buffer.handle, offset, size)
     end
 
+    # Binds an index buffer for indexed bundle draws.
+    # @param buffer [Buffer] index data buffer
+    # @param format [Symbol, Integer] index element format
+    # @return [void]
     def set_index_buffer(buffer, format: :uint32, offset: 0, size: nil)
       raise RenderBundleError, "Encoder already finished" if @finished
 
       size ||= buffer.size - offset
-      Native.wgpuRenderBundleEncoderSetIndexBuffer(@handle, buffer.handle, format, offset, size)
+      format_value = Native::EnumHelper.coerce(Native::IndexFormat, format, name: "index format")
+      Native.wgpuRenderBundleEncoderSetIndexBuffer(@handle, buffer.handle, format_value, offset, size)
     end
 
+    # Records a non-indexed draw in the bundle.
+    # @return [void]
     def draw(vertex_count, instance_count: 1, first_vertex: 0, first_instance: 0)
       raise RenderBundleError, "Encoder already finished" if @finished
 
       Native.wgpuRenderBundleEncoderDraw(@handle, vertex_count, instance_count, first_vertex, first_instance)
     end
 
+    # Records an indexed draw in the bundle.
+    # @return [void]
     def draw_indexed(index_count, instance_count: 1, first_index: 0, base_vertex: 0, first_instance: 0)
       raise RenderBundleError, "Encoder already finished" if @finished
 
       Native.wgpuRenderBundleEncoderDrawIndexed(@handle, index_count, instance_count, first_index, base_vertex, first_instance)
     end
 
+    # Records a non-indexed draw using buffer arguments.
+    # @param buffer [Buffer] indirect argument buffer
+    # @param offset [Integer] byte offset of the arguments
+    # @return [void]
     def draw_indirect(buffer, offset: 0)
       raise RenderBundleError, "Encoder already finished" if @finished
 
       Native.wgpuRenderBundleEncoderDrawIndirect(@handle, buffer.handle, offset)
     end
 
+    # Records an indexed draw using buffer arguments.
+    # @param buffer [Buffer] indirect argument buffer
+    # @param offset [Integer] byte offset of the arguments
+    # @return [void]
     def draw_indexed_indirect(buffer, offset: 0)
       raise RenderBundleError, "Encoder already finished" if @finished
 
       Native.wgpuRenderBundleEncoderDrawIndexedIndirect(@handle, buffer.handle, offset)
     end
 
+    # Starts a labeled group in GPU debugging tools.
+    # @param label [String] group label
+    # @return [void]
     def push_debug_group(label)
       raise RenderBundleError, "Encoder already finished" if @finished
 
@@ -102,12 +150,17 @@ module WGPU
       Native.wgpuRenderBundleEncoderPushDebugGroup(@handle, label_view)
     end
 
+    # Ends the most recently pushed debug group.
+    # @return [void]
     def pop_debug_group
       raise RenderBundleError, "Encoder already finished" if @finished
 
       Native.wgpuRenderBundleEncoderPopDebugGroup(@handle)
     end
 
+    # Inserts a labeled point in GPU debugging tools.
+    # @param label [String] marker label
+    # @return [void]
     def insert_debug_marker(label)
       raise RenderBundleError, "Encoder already finished" if @finished
 
@@ -118,6 +171,10 @@ module WGPU
       Native.wgpuRenderBundleEncoderInsertDebugMarker(@handle, label_view)
     end
 
+    # Finishes recording and creates an immutable render bundle.
+    # @param label [String, nil] optional bundle label
+    # @return [RenderBundle]
+    # @raise [RenderBundleError] if already finished or native creation fails
     def finish(label: nil)
       raise RenderBundleError, "Encoder already finished" if @finished
 
@@ -135,9 +192,13 @@ module WGPU
       bundle_handle = Native.wgpuRenderBundleEncoderFinish(@handle, desc)
       raise RenderBundleError, "Failed to finish render bundle encoder" if bundle_handle.null?
 
-      RenderBundle.new(bundle_handle)
+      RenderBundle.new(bundle_handle, device: @device)
     end
 
+    # Releases the native render bundle encoder handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?