wgpu 1.2.0 → 1.2.2

data/lib/wgpu/commands/command_encoder.rb

@@ -4,6 +4,10 @@ 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
@@ -20,10 +24,15 @@ module WGPU
         desc[:label][:length] = 0
       end
 
-      @handle = Native.wgpuDeviceCreateCommandEncoder(device.handle, desc)
+      @handle = Native.wgpuDeviceCreateCommandEncoder(NativeResource.checked_handle(device, expected_class: Device), desc)
       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)
       ensure_can_begin_pass!
       pass = ComputePass.new(self, label: label, timestamp_writes: timestamp_writes)
@@ -42,6 +51,10 @@ module WGPU
       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)
       ensure_can_begin_pass!
       pass = RenderPass.new(self,
@@ -67,32 +80,36 @@ module WGPU
       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(
         @handle,
-        source.handle, source_offset,
-        destination.handle, destination_offset,
+        NativeResource.checked_handle(source, expected_class: Buffer), source_offset,
+        NativeResource.checked_handle(destination, expected_class: Buffer), destination_offset,
         size
       )
     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
 
-      size = Native::Extent3D.new
-      size[:width] = copy_size[:width] || copy_size[0]
-      size[:height] = copy_size[:height] || copy_size[1] || 1
-      size[:depth_or_array_layers] = copy_size[:depth_or_array_layers] || copy_size[2] || 1
+      size = DescriptorHelpers.extent_3d(copy_size)
 
       src = Native::ImageCopyBuffer.new
       src[:layout][:offset] = source[:offset] || 0
       src[:layout][:bytes_per_row] = source[:bytes_per_row]
       src[:layout][:rows_per_image] = source[:rows_per_image] || size[:height]
-      src[:buffer] = source[:buffer].handle
+      src[:buffer] = NativeResource.checked_handle(source[:buffer], expected_class: Buffer)
 
       dst = Native::ImageCopyTexture.new
-      dst[:texture] = destination[:texture].handle
+      dst[:texture] = NativeResource.checked_handle(destination[:texture], expected_class: Texture)
       dst[:mip_level] = destination[:mip_level] || 0
       dst[:origin][:x] = destination.dig(:origin, :x) || 0
       dst[:origin][:y] = destination.dig(:origin, :y) || 0
@@ -106,16 +123,18 @@ module WGPU
       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
 
-      size = Native::Extent3D.new
-      size[:width] = copy_size[:width] || copy_size[0]
-      size[:height] = copy_size[:height] || copy_size[1] || 1
-      size[:depth_or_array_layers] = copy_size[:depth_or_array_layers] || copy_size[2] || 1
+      size = DescriptorHelpers.extent_3d(copy_size)
 
       src = Native::ImageCopyTexture.new
-      src[:texture] = source[:texture].handle
+      src[:texture] = NativeResource.checked_handle(source[:texture], expected_class: Texture)
       src[:mip_level] = source[:mip_level] || 0
       src[:origin][:x] = source.dig(:origin, :x) || 0
       src[:origin][:y] = source.dig(:origin, :y) || 0
@@ -130,16 +149,21 @@ module WGPU
       dst[:layout][:offset] = destination[:offset] || 0
       dst[:layout][:bytes_per_row] = destination[:bytes_per_row]
       dst[:layout][:rows_per_image] = destination[:rows_per_image] || size[:height]
-      dst[:buffer] = destination[:buffer].handle
+      dst[:buffer] = NativeResource.checked_handle(destination[:buffer], expected_class: Buffer)
 
       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
 
       src = Native::ImageCopyTexture.new
-      src[:texture] = source[:texture].handle
+      src[:texture] = NativeResource.checked_handle(source[:texture], expected_class: Texture)
       src[:mip_level] = source[:mip_level] || 0
       src[:origin][:x] = source.dig(:origin, :x) || 0
       src[:origin][:y] = source.dig(:origin, :y) || 0
@@ -151,7 +175,7 @@ module WGPU
       )
 
       dst = Native::ImageCopyTexture.new
-      dst[:texture] = destination[:texture].handle
+      dst[:texture] = NativeResource.checked_handle(destination[:texture], expected_class: Texture)
       dst[:mip_level] = destination[:mip_level] || 0
       dst[:origin][:x] = destination.dig(:origin, :x) || 0
       dst[:origin][:y] = destination.dig(:origin, :y) || 0
@@ -162,37 +186,55 @@ module WGPU
         name: "destination texture aspect"
       )
 
-      size = Native::Extent3D.new
-      size[:width] = copy_size[:width] || copy_size[0]
-      size[:height] = copy_size[:height] || copy_size[1] || 1
-      size[:depth_or_array_layers] = copy_size[:depth_or_array_layers] || copy_size[2] || 1
+      size = DescriptorHelpers.extent_3d(copy_size)
 
       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(
         @handle,
-        query_set.handle,
+        NativeResource.checked_handle(query_set, expected_class: QuerySet),
         first_query,
         query_count,
-        destination.handle,
+        NativeResource.checked_handle(destination, expected_class: Buffer),
         destination_offset
       )
     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)
+      buffer_handle = NativeResource.checked_handle(buffer, expected_class: Buffer)
+      offset = DataTypes.validate_alignment!(offset, 4, name: "clear offset")
+      size = DataTypes.validate_alignment!(size || (buffer.size - offset), 4, name: "clear size")
+      if offset > buffer.size || size > buffer.size - offset
+        raise ArgumentError, "clear range exceeds buffer size"
+      end
+      return if size.zero?
+
+      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)
+      Native.wgpuCommandEncoderWriteTimestamp(@handle, NativeResource.checked_handle(query_set, expected_class: QuerySet), 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
@@ -202,11 +244,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
@@ -216,6 +263,10 @@ 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?
@@ -235,9 +286,13 @@ 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)

data/lib/wgpu/commands/compute_pass.rb

@@ -4,6 +4,11 @@ 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
@@ -20,7 +25,7 @@ module WGPU
       @timestamp_writes = nil
       if timestamp_writes
         @timestamp_writes = Native::ComputePassTimestampWrites.new
-        @timestamp_writes[:query_set] = timestamp_writes.fetch(:query_set).handle
+        @timestamp_writes[:query_set] = NativeResource.checked_handle(timestamp_writes.fetch(:query_set), expected_class: QuerySet)
         @timestamp_writes[:beginning_of_pass_write_index] = timestamp_writes[:beginning_of_pass_write_index] || 0xFFFFFFFF
         @timestamp_writes[:end_of_pass_write_index] = timestamp_writes[:end_of_pass_write_index] || 0xFFFFFFFF
         desc[:timestamp_writes] = @timestamp_writes.to_ptr
@@ -28,32 +33,53 @@ module WGPU
         desc[:timestamp_writes] = nil
       end
 
-      @handle = Native.wgpuCommandEncoderBeginComputePass(encoder.handle, desc)
+      @handle = Native.wgpuCommandEncoderBeginComputePass(NativeResource.checked_handle(encoder, expected_class: CommandEncoder), desc)
       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)
+      Native.wgpuComputePassEncoderSetPipeline(@handle, NativeResource.checked_handle(pipeline, expected_class: ComputePipeline))
     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)
+        Native.wgpuComputePassEncoderSetBindGroup(@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.wgpuComputePassEncoderSetBindGroup(@handle, index, bind_group.handle, dynamic_offsets.size, offsets_ptr)
+        Native.wgpuComputePassEncoderSetBindGroup(@handle, index, NativeResource.checked_handle(bind_group, expected_class: BindGroup), dynamic_offsets.size, offsets_ptr)
       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)
+      Native.wgpuComputePassEncoderDispatchWorkgroupsIndirect(@handle, NativeResource.checked_handle(buffer, expected_class: Buffer), 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)
@@ -62,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)
@@ -74,6 +107,8 @@ 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
 
@@ -82,14 +117,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 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
@@ -38,67 +47,99 @@ module WGPU
       desc[:depth_read_only] = depth_read_only ? 1 : 0
       desc[:stencil_read_only] = stencil_read_only ? 1 : 0
 
-      @handle = Native.wgpuDeviceCreateRenderBundleEncoder(device.handle, desc)
+      @handle = Native.wgpuDeviceCreateRenderBundleEncoder(NativeResource.checked_handle(device, expected_class: Device), desc)
       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)
+      Native.wgpuRenderBundleEncoderSetPipeline(@handle, NativeResource.checked_handle(pipeline, expected_class: RenderPipeline))
     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
 
       if dynamic_offsets && !dynamic_offsets.empty?
         offsets_ptr = FFI::MemoryPointer.new(:uint32, dynamic_offsets.size)
         offsets_ptr.write_array_of_uint32(dynamic_offsets)
-        Native.wgpuRenderBundleEncoderSetBindGroup(@handle, index, bind_group.handle, dynamic_offsets.size, offsets_ptr)
+        Native.wgpuRenderBundleEncoderSetBindGroup(@handle, index, NativeResource.checked_handle(bind_group, expected_class: BindGroup), dynamic_offsets.size, offsets_ptr)
       else
-        Native.wgpuRenderBundleEncoderSetBindGroup(@handle, index, bind_group.handle, 0, nil)
+        Native.wgpuRenderBundleEncoderSetBindGroup(@handle, index, NativeResource.checked_handle(bind_group, expected_class: BindGroup), 0, nil)
       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
 
       size ||= buffer.size - offset
-      Native.wgpuRenderBundleEncoderSetVertexBuffer(@handle, slot, buffer.handle, offset, size)
+      Native.wgpuRenderBundleEncoderSetVertexBuffer(@handle, slot, NativeResource.checked_handle(buffer, expected_class: Buffer), 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
       format_value = Native::EnumHelper.coerce(Native::IndexFormat, format, name: "index format")
-      Native.wgpuRenderBundleEncoderSetIndexBuffer(@handle, buffer.handle, format_value, offset, size)
+      Native.wgpuRenderBundleEncoderSetIndexBuffer(@handle, NativeResource.checked_handle(buffer, expected_class: Buffer), 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)
+      Native.wgpuRenderBundleEncoderDrawIndirect(@handle, NativeResource.checked_handle(buffer, expected_class: Buffer), 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)
+      Native.wgpuRenderBundleEncoderDrawIndexedIndirect(@handle, NativeResource.checked_handle(buffer, expected_class: Buffer), 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
 
@@ -109,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
 
@@ -125,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
 
@@ -142,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?