wgpu 1.2.0 → 1.2.2

data/lib/wgpu/resources/buffer.rb

@@ -1,9 +1,17 @@
 # frozen_string_literal: true
 
+require "monitor"
+
 module WGPU
   class Buffer
     attr_reader :handle, :size, :usage
 
+    # Creates a GPU buffer with the requested size and usage.
+    # @param device [Device] owning device
+    # @param size [Integer] buffer size in bytes
+    # @param usage [Symbol, Array<Symbol>, Integer] usage flags
+    # @param mapped_at_creation [Boolean] whether to expose an initial mapped range
+    # @raise [BufferError] if native validation or creation fails
     def initialize(device, label: nil, size:, usage:, mapped_at_creation: false)
       @device = device
       @size = size
@@ -11,10 +19,14 @@ module WGPU
         begin
           normalize_usage(usage)
         rescue ArgumentError => e
-          raise BufferError, buffer_error_message(e.message, label)
+          raise ArgumentError, buffer_error_message(e.message, label)
         end
       @mapped = mapped_at_creation
       @map_state = mapped_at_creation ? :mapped : :unmapped
+      @map_generation = 0
+      @map_state_mutex = Monitor.new
+      @mapped_offset = 0
+      @mapped_size = mapped_at_creation ? size : 0
 
       desc, keepalive = build_descriptor(
         label:,
@@ -24,9 +36,9 @@ module WGPU
       )
       @descriptor_keepalive = keepalive
 
-      device.push_error_scope(:validation)
-      @handle = Native.wgpuDeviceCreateBuffer(device.handle, desc)
-      error = device.pop_error_scope
+      error = device.send(:capture_error_scope) do
+        @handle = Native.wgpuDeviceCreateBuffer(NativeResource.checked_handle(device, expected_class: Device), desc)
+      end
       @descriptor_keepalive = nil
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
@@ -35,123 +47,213 @@ module WGPU
       end
     end
 
+    # Writes typed data through the device's default queue.
+    # @param data [Array, String, FFI::Pointer] source data
+    # @param offset [Integer] destination byte offset
+    # @param type [Symbol] source element type
+    # @return [void]
     def write(data, offset: 0, type: :f32)
       ptr, byte_size = DataTypes.to_pointer(data, type:)
       DataTypes.validate_alignment!(offset, 4, name: "offset")
       DataTypes.validate_alignment!(byte_size, 4, name: "data size")
-      Native.wgpuQueueWriteBuffer(@device.queue.handle, @handle, offset, ptr, byte_size)
+      Native.wgpuQueueWriteBuffer(NativeResource.checked_handle(@device.queue, expected_class: Queue), @handle, offset, ptr, byte_size)
     end
 
+    # Returns a writable view of a mapped byte range.
+    # @return [BufferMappedRange]
+    # @raise [BufferError] if the buffer is not mapped or no range is available
     def mapped_range(offset: 0, size: nil)
-      raise BufferError, "Buffer is not mapped" unless @mapped
+      map_state_mutex.synchronize do
+        raise BufferError, "Buffer is not mapped" unless @mapped
 
-      size ||= @size - offset
-      validate_map_range!(offset, size)
-      ptr = Native.wgpuBufferGetMappedRange(@handle, offset, size)
-      raise BufferError, "Failed to get mapped range" if ptr.null?
+        size ||= @size - offset
+        offset, size = validate_mapped_access!(offset, size)
+        ptr = Native.wgpuBufferGetMappedRange(@handle, offset, size)
+        raise BufferError, "Failed to get mapped range" if ptr.null?
 
-      BufferMappedRange.new(ptr, size)
+        BufferMappedRange.new(ptr, size, buffer: self, generation: current_map_generation)
+      end
     end
 
+    # Returns a writable view of a mapped byte range.
+    # @return [BufferMappedRange]
     def get_mapped_range(offset: 0, size: nil)
       mapped_range(offset: offset, size: size)
     end
 
+    # Unmaps the buffer and invalidates its mapped ranges.
+    # @return [void]
     def unmap
-      Native.wgpuBufferUnmap(@handle)
-      @mapped = false
-      @map_state = :unmapped
+      map_state_mutex.synchronize do
+        Native.wgpuBufferUnmap(@handle)
+        invalidate_map_state
+      end
     end
 
+    # Maps a range and waits for native completion.
+    # @param mode [Symbol, Integer] map access mode
+    # @param timeout [Numeric, nil] maximum wait time in seconds
+    # @return [Boolean] true when mapped
+    # @raise [BufferError] if mapping fails
     def map_sync(mode, offset: 0, size: nil, timeout: nil)
-      status_holder, callback_token, future = begin_map_request(mode, offset: offset, size: size)
+      timeout = AsyncWaiter.normalize_timeout(timeout)
+      status_holder, _callback_token, future, generation =
+        begin_map_request(mode, offset: offset, size: size)
       wait_for_map(status_holder, future, timeout:)
-      finalize_map(status_holder)
-    ensure
-      CallbackKeepalive.release(self, callback_token)
+      finalize_map(status_holder, generation)
     end
 
+    # Maps a range on a background task.
+    # @param mode [Symbol, Integer] map access mode
+    # @return [AsyncTask] task yielding true when mapped
     def map_async(mode, offset: 0, size: nil)
-      status_holder, callback_token, future = begin_map_request(mode, offset: offset, size: size)
+      status_holder, _callback_token, future, generation =
+        begin_map_request(mode, offset: offset, size: size)
       AsyncTask.new do
         wait_for_map(status_holder, future)
-        finalize_map(status_holder)
-      ensure
-        CallbackKeepalive.release(self, callback_token)
+        finalize_map(status_holder, generation)
       end
     end
 
+    # Copies bytes from a const mapped range.
+    # @return [String] mapped bytes
+    # @raise [BufferError] if the buffer is not mapped
     def read_mapped_data(offset: 0, size: nil)
-      raise BufferError, "Buffer is not mapped" unless @mapped
+      map_state_mutex.synchronize do
+        raise BufferError, "Buffer is not mapped" unless @mapped
 
-      size ||= @size - offset
-      validate_map_range!(offset, size)
-      ptr = Native.wgpuBufferGetConstMappedRange(@handle, offset, size)
-      raise BufferError, "Failed to get mapped range" if ptr.null?
+        size ||= @size - offset
+        offset, size = validate_mapped_access!(offset, size)
+        ptr = Native.wgpuBufferGetConstMappedRange(@handle, offset, size)
+        raise BufferError, "Failed to get mapped range" if ptr.null?
 
-      ptr.read_bytes(size)
+        ptr.read_bytes(size)
+      end
     end
 
+    # Reads mapped bytes, optionally decoding typed values.
+    # @param type [Symbol, nil] element type, or +nil+ for raw bytes
+    # @return [String, Array]
     def read_mapped(offset: 0, size: nil, type: nil)
       bytes = read_mapped_data(offset: offset, size: size)
       type ? DataTypes.unpack(bytes, type:) : bytes
     end
 
+    # Writes typed data into a mapped range.
+    # @param data [Array, String, FFI::Pointer] source data
+    # @param type [Symbol] source element type
+    # @return [void]
     def write_mapped(data, offset: 0, type: :f32)
-      raise BufferError, "Buffer is not mapped" unless @mapped
+      map_state_mutex.synchronize do
+        raise BufferError, "Buffer is not mapped" unless @mapped
 
-      ptr, byte_size = DataTypes.to_pointer(data, type:)
-      validate_map_range!(offset, byte_size)
-      target = Native.wgpuBufferGetMappedRange(@handle, offset, byte_size)
-      raise BufferError, "Failed to get mapped range" if target.null?
+        ptr, byte_size = DataTypes.to_pointer(data, type:)
+        offset, byte_size = validate_mapped_access!(offset, byte_size)
+        target = Native.wgpuBufferGetMappedRange(@handle, offset, byte_size)
+        raise BufferError, "Failed to get mapped range" if target.null?
 
-      target.put_bytes(0, ptr.read_bytes(byte_size))
+        target.put_bytes(0, ptr.read_bytes(byte_size))
+      end
     end
 
+    # Reads mapped bytes as 32-bit floating-point values.
+    #
+    # @param offset [Integer] byte offset in the buffer
+    # @param count [Integer, nil] values to read; defaults to the remaining range
+    # @return [Array<Float>] decoded values
+    # @raise [BufferError] if the buffer is not mapped
     def read_mapped_floats(offset: 0, count: nil)
       read_mapped_values(type: :f32, offset:, count:)
     end
 
+    # Reads mapped bytes as unsigned 32-bit integers.
+    #
+    # @param offset [Integer] byte offset in the buffer
+    # @param count [Integer, nil] values to read; defaults to the remaining range
+    # @return [Array<Integer>] decoded values
+    # @raise [BufferError] if the buffer is not mapped
     def read_mapped_uint32s(offset: 0, count: nil)
       read_mapped_values(type: :u32, offset:, count:)
     end
 
+    # Reads mapped bytes as signed 32-bit integers.
+    #
+    # @param offset [Integer] byte offset in the buffer
+    # @param count [Integer, nil] values to read; defaults to the remaining range
+    # @return [Array<Integer>] decoded values
+    # @raise [BufferError] if the buffer is not mapped
     def read_mapped_int32s(offset: 0, count: nil)
       read_mapped_values(type: :i32, offset:, count:)
     end
 
+    # Reads mapped bytes as 64-bit floating-point values.
+    #
+    # @param offset [Integer] byte offset in the buffer
+    # @param count [Integer, nil] values to read; defaults to the remaining range
+    # @return [Array<Float>] decoded values
+    # @raise [BufferError] if the buffer is not mapped
     def read_mapped_float64s(offset: 0, count: nil)
       read_mapped_values(type: :f64, offset:, count:)
     end
 
+    # Reads mapped bytes as unsigned 16-bit integers.
+    #
+    # @param offset [Integer] byte offset in the buffer
+    # @param count [Integer, nil] values to read; defaults to the remaining range
+    # @return [Array<Integer>] decoded values
+    # @raise [BufferError] if the buffer is not mapped
     def read_mapped_uint16s(offset: 0, count: nil)
       read_mapped_values(type: :u16, offset:, count:)
     end
 
+    # Reads mapped bytes as unsigned 8-bit integers.
+    #
+    # @param offset [Integer] byte offset in the buffer
+    # @param count [Integer, nil] values to read; defaults to the remaining range
+    # @return [Array<Integer>] decoded values
+    # @raise [BufferError] if the buffer is not mapped
     def read_mapped_uint8s(offset: 0, count: nil)
       read_mapped_values(type: :u8, offset:, count:)
     end
 
+    # Reads mapped values of the requested element type.
+    # @param type [Symbol] element type
+    # @param count [Integer, nil] number of values
+    # @return [Array]
     def read_mapped_values(type: :f32, offset: 0, count: nil)
       element_size = DataTypes.byte_size(type)
       size = count ? count * element_size : @size - offset
       DataTypes.unpack(read_mapped_data(offset:, size:), type:)
     end
 
+    # Returns the current mapping state.
+    # @return [Symbol]
     def map_state
-      return @map_state unless Native.buffer_map_state_available?
+      return map_state_mutex.synchronize { @map_state } unless Native.buffer_map_state_available?
 
-      Native.wgpuBufferGetMapState(@handle) || @map_state
+      Native.wgpuBufferGetMapState(@handle) || map_state_mutex.synchronize { @map_state }
     end
 
+    # Destroys the buffer's storage.
+    # @return [void]
     def destroy
-      Native.wgpuBufferDestroy(@handle)
+      map_state_mutex.synchronize do
+        Native.wgpuBufferDestroy(@handle)
+        invalidate_map_state
+      end
     end
 
+    # Releases the native buffer handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
-      return if @handle.null?
-      Native.wgpuBufferRelease(@handle)
-      @handle = FFI::Pointer::NULL
+      map_state_mutex.synchronize do
+        return if @handle.null?
+        Native.wgpuBufferRelease(@handle)
+        @handle = FFI::Pointer::NULL
+        invalidate_map_state
+      end
     end
 
     private
@@ -169,15 +271,37 @@ module WGPU
 
     def begin_map_request(mode, offset:, size:)
       size ||= @size - offset
-      validate_map_range!(offset, size)
+      offset, size = validate_map_range!(offset, size)
       mode_flag = Native::EnumHelper.coerce(Native::MapMode, mode, name: "map mode")
 
       status_holder = { done: false, status: nil, message: nil }
+      generation = map_state_mutex.synchronize do
+        raise BufferError, "Buffer is already mapped or mapping" if @mapped || @map_state == :pending
+
+        @map_generation = current_map_generation + 1
+        @mapped_offset = offset
+        @mapped_size = size
+        @map_state = :pending
+        @map_generation
+      end
+      callback_lifetime_release = device_callback_lifetime_lease
+      callback_token = nil
       callback = FFI::Function.new(:void, [:uint32, Native::StringView.by_value, :pointer, :pointer]) do |status, message, _userdata1, _userdata2|
-        status_holder[:done] = true
-        status_holder[:status] = Native::MapAsyncStatus[status]
-        if message[:data] && !message[:data].null? && message[:length] > 0
-          status_holder[:message] = message[:data].read_string(message[:length])
+        begin
+          status_holder[:status] = Native::MapAsyncStatus[status]
+          if message[:data] && !message[:data].null? && message[:length] > 0
+            status_holder[:message] = message[:data].read_string(message[:length])
+          end
+          map_state_mutex.synchronize do
+            if generation == current_map_generation && !@handle.null?
+              @mapped = status_holder[:status] == :success
+              @map_state = @mapped ? :mapped : :unmapped
+            end
+          end
+          status_holder[:done] = true
+        ensure
+          CallbackKeepalive.release(self, callback_token)
+          callback_lifetime_release.call
         end
       end
       callback_token = CallbackKeepalive.retain(self, callback)
@@ -189,10 +313,17 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      future = Native.wgpuBufferMapAsync(@handle, mode_flag, offset, size, callback_info)
-      @map_state = :pending
+      future =
+        begin
+          Native.wgpuBufferMapAsync(@handle, mode_flag, offset, size, callback_info)
+        rescue StandardError
+          CallbackKeepalive.release(self, callback_token)
+          callback_lifetime_release.call
+          invalidate_map_state(generation)
+          raise
+        end
 
-      [status_holder, callback_token, future]
+      [status_holder, callback_token, future, generation]
     end
 
     def wait_for_map(status_holder, future, timeout: nil)
@@ -205,19 +336,41 @@ module WGPU
       )
     end
 
-    def finalize_map(status_holder)
+    def finalize_map(status_holder, generation)
       if status_holder[:status] == :success
-        @mapped = true
-        @map_state = :mapped
+        map_state_mutex.synchronize do
+          if generation == current_map_generation && !@handle.null?
+            @mapped = true
+            @map_state = :mapped
+          end
+        end
         true
       else
-        @map_state = :unmapped
+        invalidate_map_state(generation)
         detail = status_holder[:message]
         base = "Failed to map buffer: #{status_holder[:status]}"
         raise BufferError, detail && !detail.empty? ? "#{base} (#{detail})" : base
       end
     end
 
+    def invalidate_map_state(generation = nil)
+      map_state_mutex.synchronize do
+        return if generation && generation != current_map_generation
+
+        @map_generation = current_map_generation + 1
+        @mapped = false
+        @map_state = :unmapped
+      end
+    end
+
+    def current_map_generation
+      @map_generation ||= 0
+    end
+
+    def map_state_mutex
+      @map_state_mutex ||= Monitor.new
+    end
+
     def normalize_usage(usage)
       Native::EnumHelper.coerce_flags(Native::BufferUsage, usage, name: "buffer usage")
     end
@@ -227,85 +380,203 @@ module WGPU
       "create buffer#{context}: #{message}"
     end
 
+    def with_mapped_generation(generation)
+      map_state_mutex.synchronize do
+        unless @mapped && !released? && generation == current_map_generation
+          raise BufferError, "Mapped range is no longer valid"
+        end
+
+        yield
+      end
+    end
+
+    def validate_mapped_access!(offset, size)
+      offset, size = validate_map_range!(offset, size)
+      if offset < @mapped_offset || offset + size > @mapped_offset + @mapped_size
+        raise BufferError, "Requested range is outside the current mapping"
+      end
+
+      [offset, size]
+    end
+
     def validate_map_range!(offset, size)
-      DataTypes.validate_alignment!(offset, 8, name: "map offset")
-      DataTypes.validate_alignment!(size, 4, name: "map size")
+      offset = DataTypes.validate_alignment!(offset, 8, name: "map offset")
+      size = DataTypes.validate_alignment!(size, 4, name: "map size")
+      if offset > @size || size > @size - offset
+        raise ArgumentError,
+          "mapped range (offset #{offset}, size #{size}) exceeds buffer size #{@size}"
+      end
+
+      [offset, size]
     end
   end
 
   class BufferMappedRange
-    def initialize(pointer, size)
+    # Wraps a native mapped memory range.
+    # @param pointer [FFI::Pointer] start of mapped memory
+    # @param size [Integer] range size in bytes
+    # @param buffer [Buffer] owner retaining the mapped allocation
+    # @param generation [Integer] mapping generation at acquisition
+    def initialize(pointer, size, buffer:, generation:)
       @pointer = pointer
       @size = size
+      @buffer = buffer
+      @generation = generation
     end
 
+    # Reads 32-bit floating-point values from the mapped range.
+    #
+    # @param count [Integer, nil] values to read; defaults to the full range
+    # @return [Array<Float>] decoded values
     def read_floats(count = nil)
       read(type: :f32, count:)
     end
 
+    # Writes 32-bit floating-point values into the mapped range.
+    #
+    # @param data [Array<Numeric>] values to write
+    # @return [void]
+    # @raise [ArgumentError] if the data exceeds the mapped range
     def write_floats(data)
       write(data, type: :f32)
     end
 
+    # Reads unsigned 32-bit integers from the mapped range.
+    #
+    # @param count [Integer, nil] values to read; defaults to the full range
+    # @return [Array<Integer>] decoded values
     def read_uint32s(count = nil)
       read(type: :u32, count:)
     end
 
+    # Writes unsigned 32-bit integers into the mapped range.
+    #
+    # @param data [Array<Integer>] values to write
+    # @return [void]
+    # @raise [ArgumentError] if the data exceeds the mapped range
     def write_uint32s(data)
       write(data, type: :u32)
     end
 
+    # Reads signed 32-bit integers from the mapped range.
+    #
+    # @param count [Integer, nil] values to read; defaults to the full range
+    # @return [Array<Integer>] decoded values
     def read_int32s(count = nil)
       read(type: :i32, count:)
     end
 
+    # Writes signed 32-bit integers into the mapped range.
+    #
+    # @param data [Array<Integer>] values to write
+    # @return [void]
+    # @raise [ArgumentError] if the data exceeds the mapped range
     def write_int32s(data)
       write(data, type: :i32)
     end
 
+    # Reads 64-bit floating-point values from the mapped range.
+    #
+    # @param count [Integer, nil] values to read; defaults to the full range
+    # @return [Array<Float>] decoded values
     def read_float64s(count = nil)
       read(type: :f64, count:)
     end
 
+    # Writes 64-bit floating-point values into the mapped range.
+    #
+    # @param data [Array<Numeric>] values to write
+    # @return [void]
+    # @raise [ArgumentError] if the data exceeds the mapped range
     def write_float64s(data)
       write(data, type: :f64)
     end
 
+    # Reads unsigned 16-bit integers from the mapped range.
+    #
+    # @param count [Integer, nil] values to read; defaults to the full range
+    # @return [Array<Integer>] decoded values
     def read_uint16s(count = nil)
       read(type: :u16, count:)
     end
 
+    # Writes unsigned 16-bit integers into the mapped range.
+    #
+    # @param data [Array<Integer>] values to write
+    # @return [void]
+    # @raise [ArgumentError] if the data exceeds the mapped range
     def write_uint16s(data)
       write(data, type: :u16)
     end
 
+    # Reads unsigned 8-bit integers from the mapped range.
+    #
+    # @param count [Integer, nil] values to read; defaults to the full range
+    # @return [Array<Integer>] decoded values
     def read_uint8s(count = nil)
       read(type: :u8, count:)
     end
 
+    # Writes unsigned 8-bit integers into the mapped range.
+    #
+    # @param data [Array<Integer>] values to write
+    # @return [void]
+    # @raise [ArgumentError] if the data exceeds the mapped range
     def write_uint8s(data)
       write(data, type: :u8)
     end
 
+    # Decodes typed values from the mapped range.
+    # @param type [Symbol] element type
+    # @param count [Integer, nil] number of values
+    # @return [Array]
     def read(type: :f32, count: nil)
       byte_size = DataTypes.byte_size(type)
       count ||= @size / byte_size
-      DataTypes.unpack(@pointer.read_bytes(count * byte_size), type:)
+      count = Integer(count)
+      raise ArgumentError, "count must be non-negative" if count.negative?
+
+      bytes_to_read = count * byte_size
+      validate_byte_length!(bytes_to_read)
+      DataTypes.unpack(with_valid_mapping { @pointer.read_bytes(bytes_to_read) }, type:)
     end
 
+    # Encodes typed values into the mapped range.
+    # @param data [Array, String] values or bytes to write
+    # @param type [Symbol] element type
+    # @return [void]
+    # @raise [ArgumentError] if the encoded data exceeds the range
     def write(data, type: :f32)
       bytes = data.is_a?(String) ? data : DataTypes.pack(data, type:)
       raise ArgumentError, "data exceeds mapped range" if bytes.bytesize > @size
 
-      @pointer.put_bytes(0, bytes)
+      with_valid_mapping { @pointer.put_bytes(0, bytes) }
     end
 
+    # Returns all bytes in the mapped range.
+    # @return [String]
     def read_bytes
-      @pointer.read_bytes(@size)
+      with_valid_mapping { @pointer.read_bytes(@size) }
     end
 
+    # Writes bytes at the start of the mapped range.
+    # @param data [String] bytes to write
+    # @return [void]
     def write_bytes(data)
-      @pointer.put_bytes(0, data)
+      validate_byte_length!(data.bytesize)
+      with_valid_mapping { @pointer.put_bytes(0, data) }
+    end
+
+    private
+
+    def with_valid_mapping(&block)
+      @buffer.send(:with_mapped_generation, @generation, &block)
+    end
+
+    def validate_byte_length!(byte_length)
+      return if byte_length <= @size
+
+      raise ArgumentError, "data exceeds mapped range"
     end
   end
 end

data/lib/wgpu/resources/query_set.rb

@@ -4,6 +4,11 @@ module WGPU
   class QuerySet
     attr_reader :handle, :count, :type
 
+    # Creates a set of GPU queries.
+    # @param device [Device] owning device
+    # @param type [Symbol, Integer] query type
+    # @param count [Integer] number of queries
+    # @raise [ResourceError] if native creation fails
     def initialize(device, label: nil, type:, count:)
       @device = device
       @count = Integer(count)
@@ -24,10 +29,12 @@ module WGPU
       desc[:type] = type_value
       desc[:count] = @count
 
-      @handle = Native.wgpuDeviceCreateQuerySet(device.handle, desc)
+      @handle = Native.wgpuDeviceCreateQuerySet(NativeResource.checked_handle(device, expected_class: Device), desc)
       raise ResourceError, "Failed to create query set" if @handle.null?
     end
 
+    # Destroys the query storage once.
+    # @return [void]
     def destroy
       return if @destroyed
 
@@ -35,6 +42,11 @@ module WGPU
       @destroyed = true
     end
 
+    # Releases the native query set handle.
+    #
+    # A query set destroyed through {#destroy} is only marked released because
+    # the pinned native implementation cannot safely release it afterward.
+    # @return [void]
     def release
       return if @handle.null?
 

data/lib/wgpu/resources/sampler.rb

@@ -4,6 +4,9 @@ module WGPU
   class Sampler
     attr_reader :handle
 
+    # Creates a texture sampler with address, filter, and comparison settings.
+    # @param device [Device] owning device
+    # @raise [ResourceError] if native validation or creation fails
     def initialize(device, label: nil, address_mode_u: :clamp_to_edge, address_mode_v: :clamp_to_edge, address_mode_w: :clamp_to_edge, mag_filter: :nearest, min_filter: :nearest, mipmap_filter: :nearest, lod_min_clamp: 0.0, lod_max_clamp: 32.0, compare: nil, max_anisotropy: 1)
       @device = device
 
@@ -22,9 +25,9 @@ module WGPU
       )
       @descriptor_keepalive = keepalive
 
-      device.push_error_scope(:validation)
-      @handle = Native.wgpuDeviceCreateSampler(device.handle, desc)
-      error = device.pop_error_scope
+      error = device.send(:capture_error_scope) do
+        @handle = Native.wgpuDeviceCreateSampler(NativeResource.checked_handle(device, expected_class: Device), desc)
+      end
       @descriptor_keepalive = nil
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
@@ -33,6 +36,10 @@ module WGPU
       end
     end
 
+    # Releases the native sampler handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuSamplerRelease(@handle)