wgpu 1.2.0 → 1.2.2

data/lib/wgpu/pipeline/compute_pipeline.rb

@@ -4,13 +4,18 @@ module WGPU
   class ComputePipeline
     attr_reader :handle
 
+    # Creates a compute pipeline.
+    # @param device [Device] owning device
+    # @param layout [PipelineLayout, :auto, nil] pipeline layout
+    # @param compute [Hash] programmable compute stage descriptor
+    # @raise [PipelineError] if native validation or creation fails
     def initialize(device, label: nil, layout:, compute:)
       @device = device
       desc, @pointers = build_descriptor(label:, layout:, compute:)
 
-      device.push_error_scope(:validation)
-      @handle = Native.wgpuDeviceCreateComputePipeline(device.handle, desc)
-      error = device.pop_error_scope
+      error = device.send(:capture_error_scope) do
+        @handle = Native.wgpuDeviceCreateComputePipeline(NativeResource.checked_handle(device, expected_class: Device), desc)
+      end
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
         msg = error[:message] || "Failed to create compute pipeline"
@@ -18,12 +23,20 @@ module WGPU
       end
     end
 
+    # Returns the bind group layout inferred or assigned at an index.
+    # @param index [Integer] bind group index
+    # @return [BindGroupLayout]
+    # @raise [PipelineError] if no native layout is returned
     def get_bind_group_layout(index)
       handle = Native.wgpuComputePipelineGetBindGroupLayout(@handle, index)
       raise PipelineError, "Failed to get bind group layout at index #{index}" if handle.null?
-      BindGroupLayout.from_handle(handle)
+      BindGroupLayout.from_handle(handle, device: @device)
     end
 
+    # Releases the native compute pipeline handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuComputePipelineRelease(@handle)
@@ -40,51 +53,26 @@ module WGPU
         context: "compute pipeline stage"
       )
       @pointers = []
-      entry_point = compute[:entry_point] || "main"
-      entry_point_ptr = FFI::MemoryPointer.from_string(entry_point)
-      @pointers << entry_point_ptr
 
       desc = Native::ComputePipelineDescriptor.new
       desc[:next_in_chain] = nil
       DescriptorHelpers.set_label(desc, label, keepalive: @pointers)
       desc[:layout] = normalize_layout(layout)
       desc[:compute][:next_in_chain] = nil
-      desc[:compute][:module] = compute.fetch(:module).handle
-      desc[:compute][:entry_point][:data] = entry_point_ptr
-      desc[:compute][:entry_point][:length] = entry_point.bytesize
-      desc[:compute][:constant_count] = 0
-      desc[:compute][:constants] = nil
-      setup_constants(desc[:compute], compute[:constants])
+      desc[:compute][:module] = NativeResource.checked_handle(compute.fetch(:module), expected_class: ShaderModule)
+      DescriptorHelpers.set_nullable_string_view(
+        desc[:compute][:entry_point],
+        compute[:entry_point],
+        keepalive: @pointers
+      )
+      DescriptorHelpers.set_constants(desc[:compute], compute[:constants], keepalive: @pointers)
 
       [desc, @pointers]
     end
 
     def normalize_layout(layout)
       return nil if layout.nil? || layout == :auto || layout == "auto"
-      layout.handle
-    end
-
-    def setup_constants(stage_desc, constants)
-      return if constants.nil? || constants.empty?
-
-      constants_ptr = FFI::MemoryPointer.new(Native::ConstantEntry, constants.size)
-      @pointers << constants_ptr
-
-      constants.each_with_index do |(key, value), i|
-        entry_ptr = constants_ptr + (i * Native::ConstantEntry.size)
-        entry = Native::ConstantEntry.new(entry_ptr)
-        entry[:next_in_chain] = nil
-
-        key_str = key.to_s
-        key_ptr = FFI::MemoryPointer.from_string(key_str)
-        @pointers << key_ptr
-        entry[:key][:data] = key_ptr
-        entry[:key][:length] = key_str.bytesize
-        entry[:value] = value.to_f
-      end
-
-      stage_desc[:constant_count] = constants.size
-      stage_desc[:constants] = constants_ptr
+      NativeResource.checked_handle(layout, expected_class: PipelineLayout)
     end
   end
 end

data/lib/wgpu/pipeline/pipeline_layout.rb

@@ -4,12 +4,16 @@ module WGPU
   class PipelineLayout
     attr_reader :handle
 
+    # Creates a pipeline layout from ordered bind group layouts.
+    # @param device [Device] owning device
+    # @param bind_group_layouts [Array<BindGroupLayout>] layouts by group index
+    # @raise [PipelineError] if native validation or creation fails
     def initialize(device, label: nil, bind_group_layouts:)
       @device = device
 
       layouts = Array(bind_group_layouts)
       layouts_ptr = FFI::MemoryPointer.new(:pointer, layouts.size)
-      layouts_ptr.write_array_of_pointer(layouts.map(&:handle))
+      layouts_ptr.write_array_of_pointer(layouts.map { |layout| NativeResource.checked_handle(layout, expected_class: BindGroupLayout) })
 
       desc = Native::PipelineLayoutDescriptor.new
       desc[:next_in_chain] = nil
@@ -24,9 +28,9 @@ module WGPU
       desc[:bind_group_layout_count] = layouts.size
       desc[:bind_group_layouts] = layouts_ptr
 
-      device.push_error_scope(:validation)
-      @handle = Native.wgpuDeviceCreatePipelineLayout(device.handle, desc)
-      error = device.pop_error_scope
+      error = device.send(:capture_error_scope) do
+        @handle = Native.wgpuDeviceCreatePipelineLayout(NativeResource.checked_handle(device, expected_class: Device), desc)
+      end
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
         msg = error[:message] || "Failed to create pipeline layout"
@@ -34,6 +38,10 @@ module WGPU
       end
     end
 
+    # Releases the native pipeline layout handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuPipelineLayoutRelease(@handle)

data/lib/wgpu/pipeline/render_pipeline.rb

@@ -4,6 +4,12 @@ module WGPU
   class RenderPipeline
     attr_reader :handle
 
+    # Creates a render pipeline.
+    # @param device [Device] owning device
+    # @param layout [PipelineLayout, :auto, nil] pipeline layout
+    # @param vertex [Hash] programmable vertex stage descriptor
+    # @param fragment [Hash, nil] optional fragment stage descriptor
+    # @raise [PipelineError] if native validation or creation fails
     def initialize(device, label: nil, layout:, vertex:, primitive: {}, depth_stencil: nil, multisample: {}, fragment: nil)
       @device = device
       desc, @pointers = build_descriptor(
@@ -16,9 +22,9 @@ module WGPU
         fragment:
       )
 
-      device.push_error_scope(:validation)
-      @handle = Native.wgpuDeviceCreateRenderPipeline(device.handle, desc)
-      error = device.pop_error_scope
+      error = device.send(:capture_error_scope) do
+        @handle = Native.wgpuDeviceCreateRenderPipeline(NativeResource.checked_handle(device, expected_class: Device), desc)
+      end
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
         msg = error[:message] || "Failed to create render pipeline"
@@ -26,12 +32,20 @@ module WGPU
       end
     end
 
+    # Returns the bind group layout inferred or assigned at an index.
+    # @param index [Integer] bind group index
+    # @return [BindGroupLayout]
+    # @raise [PipelineError] if no native layout is returned
     def get_bind_group_layout(index)
       handle = Native.wgpuRenderPipelineGetBindGroupLayout(@handle, index)
       raise PipelineError, "Failed to get bind group layout at index #{index}" if handle.null?
-      BindGroupLayout.from_handle(handle)
+      BindGroupLayout.from_handle(handle, device: @device)
     end
 
+    # Releases the native render pipeline handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuRenderPipelineRelease(@handle)
@@ -64,17 +78,14 @@ module WGPU
         context: "render pipeline vertex descriptor"
       )
       vertex_state[:next_in_chain] = nil
-      vertex_state[:module] = vertex[:module].handle
-
-      entry_point = vertex[:entry_point] || "main"
-      entry_ptr = FFI::MemoryPointer.from_string(entry_point)
-      @pointers << entry_ptr
-      vertex_state[:entry_point][:data] = entry_ptr
-      vertex_state[:entry_point][:length] = entry_point.bytesize
+      vertex_state[:module] = NativeResource.checked_handle(vertex[:module], expected_class: ShaderModule)
 
-      vertex_state[:constant_count] = 0
-      vertex_state[:constants] = nil
-      setup_constants(vertex_state, vertex[:constants])
+      DescriptorHelpers.set_nullable_string_view(
+        vertex_state[:entry_point],
+        vertex[:entry_point],
+        keepalive: @pointers
+      )
+      DescriptorHelpers.set_constants(vertex_state, vertex[:constants], keepalive: @pointers)
 
       buffers = vertex[:buffers] || []
       if buffers.empty?
@@ -254,17 +265,14 @@ module WGPU
       frag = Native::FragmentState.new
       @pointers << frag
       frag[:next_in_chain] = nil
-      frag[:module] = fragment[:module].handle
+      frag[:module] = NativeResource.checked_handle(fragment[:module], expected_class: ShaderModule)
 
-      entry_point = fragment[:entry_point] || "main"
-      entry_ptr = FFI::MemoryPointer.from_string(entry_point)
-      @pointers << entry_ptr
-      frag[:entry_point][:data] = entry_ptr
-      frag[:entry_point][:length] = entry_point.bytesize
-
-      frag[:constant_count] = 0
-      frag[:constants] = nil
-      setup_constants(frag, fragment[:constants])
+      DescriptorHelpers.set_nullable_string_view(
+        frag[:entry_point],
+        fragment[:entry_point],
+        keepalive: @pointers
+      )
+      DescriptorHelpers.set_constants(frag, fragment[:constants], keepalive: @pointers)
 
       targets = fragment[:targets] || []
       if targets.empty?
@@ -361,30 +369,7 @@ module WGPU
 
     def normalize_layout(layout)
       return nil if layout.nil? || layout == :auto || layout == "auto"
-      layout.handle
-    end
-
-    def setup_constants(stage_state, constants)
-      return if constants.nil? || constants.empty?
-
-      constants_ptr = FFI::MemoryPointer.new(Native::ConstantEntry, constants.size)
-      @pointers << constants_ptr
-
-      constants.each_with_index do |(key, value), i|
-        entry_ptr = constants_ptr + (i * Native::ConstantEntry.size)
-        entry = Native::ConstantEntry.new(entry_ptr)
-        entry[:next_in_chain] = nil
-
-        key_str = key.to_s
-        key_ptr = FFI::MemoryPointer.from_string(key_str)
-        @pointers << key_ptr
-        entry[:key][:data] = key_ptr
-        entry[:key][:length] = key_str.bytesize
-        entry[:value] = value.to_f
-      end
-
-      stage_state[:constant_count] = constants.size
-      stage_state[:constants] = constants_ptr
+      NativeResource.checked_handle(layout, expected_class: PipelineLayout)
     end
   end
 end

data/lib/wgpu/pipeline/shader_module.rb

@@ -4,6 +4,12 @@ module WGPU
   class ShaderModule
     attr_reader :handle
 
+    # Creates a shader module from WGSL, GLSL, or SPIR-V input.
+    # @param device [Device] owning device
+    # @param code [String, Array<Integer>, nil] shader source or binary
+    # @param spirv [String, Array<Integer>, nil] explicit SPIR-V input
+    # @param validate [Boolean] whether to fetch and raise compilation errors
+    # @raise [ShaderError] if native validation, creation, or compilation fails
     def initialize(device, label: nil, code: nil, spirv: nil, compilation_hints: [], validate: false)
       @device = device
       @pointers = []
@@ -24,9 +30,9 @@ module WGPU
         desc[:label][:length] = 0
       end
 
-      device.push_error_scope(:validation)
-      @handle = Native.wgpuDeviceCreateShaderModule(device.handle, desc)
-      error = device.pop_error_scope
+      error = device.send(:capture_error_scope) do
+        @handle = Native.wgpuDeviceCreateShaderModule(NativeResource.checked_handle(device, expected_class: Device), desc)
+      end
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
         msg = error[:message] || "Failed to create shader module"
@@ -43,6 +49,9 @@ module WGPU
       end
     end
 
+    # Fetches compiler diagnostics for the shader.
+    # @return [Hash] request status and compilation messages
+    # @raise [ShaderError] if the pinned native library cannot provide diagnostics
     def get_compilation_info
       unless Native.compilation_info_available?
         raise ShaderError,
@@ -52,34 +61,41 @@ module WGPU
       result_holder = { done: false, status: nil, messages: [] }
       instance = @device.adapter&.instance
 
+      callback_lifetime_release = device_callback_lifetime_lease
+      callback_token = nil
       callback = FFI::Function.new(
         :void, [:uint32, :pointer, :pointer, :pointer]
       ) do |status, compilation_info_ptr, _userdata1, _userdata2|
-        result_holder[:done] = true
-        result_holder[:status] = Native::CompilationInfoRequestStatus[status]
-
-        unless compilation_info_ptr.null?
-          info = Native::CompilationInfo.new(compilation_info_ptr)
-          count = info[:message_count]
-          if count > 0 && !info[:messages].null?
-            count.times do |i|
-              msg_ptr = info[:messages] + (i * Native::CompilationMessage.size)
-              msg = Native::CompilationMessage.new(msg_ptr)
-              message_text = if msg[:message][:data] && !msg[:message][:data].null? && msg[:message][:length] > 0
-                               msg[:message][:data].read_string(msg[:message][:length])
-                             else
-                               ""
-                             end
-              result_holder[:messages] << CompilationMessage.new(
-                type: msg[:type],
-                message: message_text,
-                line_num: msg[:line_num],
-                line_pos: msg[:line_pos],
-                offset: msg[:offset],
-                length: msg[:length]
-              )
+        begin
+          result_holder[:status] = Native::CompilationInfoRequestStatus[status]
+
+          unless compilation_info_ptr.null?
+            info = Native::CompilationInfo.new(compilation_info_ptr)
+            count = info[:message_count]
+            if count > 0 && !info[:messages].null?
+              count.times do |i|
+                msg_ptr = info[:messages] + (i * Native::CompilationMessage.size)
+                msg = Native::CompilationMessage.new(msg_ptr)
+                message_text = if msg[:message][:data] && !msg[:message][:data].null? && msg[:message][:length] > 0
+                                 msg[:message][:data].read_string(msg[:message][:length])
+                               else
+                                 ""
+                               end
+                result_holder[:messages] << CompilationMessage.new(
+                  type: msg[:type],
+                  message: message_text,
+                  line_num: msg[:line_num],
+                  line_pos: msg[:line_pos],
+                  offset: msg[:offset],
+                  length: msg[:length]
+                )
+              end
             end
           end
+          result_holder[:done] = true
+        ensure
+          CallbackKeepalive.release(self, callback_token)
+          callback_lifetime_release.call
         end
       end
 
@@ -91,12 +107,15 @@ module WGPU
       callback_info[:userdata2] = nil
 
       callback_token = CallbackKeepalive.retain(self, callback)
-      begin
-        future = Native.wgpuShaderModuleGetCompilationInfo(@handle, callback_info)
-        AsyncWaiter.wait(status_holder: result_holder, instance: instance, device: @device, future: future)
-      ensure
-        CallbackKeepalive.release(self, callback_token)
-      end
+      future =
+        begin
+          Native.wgpuShaderModuleGetCompilationInfo(@handle, callback_info)
+        rescue StandardError
+          CallbackKeepalive.release(self, callback_token)
+          callback_lifetime_release.call
+          raise
+        end
+      AsyncWaiter.wait(status_holder: result_holder, instance: instance, device: @device, future: future)
 
       {
         status: result_holder[:status],
@@ -104,10 +123,16 @@ module WGPU
       }
     end
 
+    # Fetches compiler diagnostics on a background task.
+    # @return [AsyncTask] task yielding compilation information
     def get_compilation_info_async
       AsyncTask.new { get_compilation_info }
     end
 
+    # Releases the native shader module handle.
+    #
+    # Calling this method more than once has no effect.
+    # @return [void]
     def release
       return if @handle.null?
       Native.wgpuShaderModuleRelease(@handle)