wgpu 1.2.0 → 1.2.1

data/lib/wgpu/pipeline/pipeline_layout.rb

@@ -4,6 +4,10 @@ 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
 
@@ -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(
@@ -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)
@@ -66,15 +80,12 @@ module WGPU
       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[: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?
@@ -256,15 +267,12 @@ module WGPU
       frag[:next_in_chain] = nil
       frag[:module] = fragment[:module].handle
 
-      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?
@@ -363,28 +371,5 @@ module WGPU
       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
-    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 = []
@@ -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)