wgpu 1.1.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,32 +4,23 @@ 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
-      @pointers = []
-
-      desc = Native::RenderPipelineDescriptor.new
-      desc[:next_in_chain] = nil
-      setup_label(desc, label)
-      desc[:layout] = normalize_layout(layout)
-
-      setup_vertex_state(desc[:vertex], vertex)
-      setup_primitive_state(desc[:primitive], primitive)
-      setup_multisample_state(desc[:multisample], multisample)
-
-      if depth_stencil
-        ds_ptr = setup_depth_stencil_state(depth_stencil)
-        desc[:depth_stencil] = ds_ptr
-      else
-        desc[:depth_stencil] = nil
-      end
-
-      if fragment
-        frag_ptr = setup_fragment_state(fragment)
-        desc[:fragment] = frag_ptr
-      else
-        desc[:fragment] = nil
-      end
+      desc, @pointers = build_descriptor(
+        label:,
+        layout:,
+        vertex:,
+        primitive:,
+        depth_stencil:,
+        multisample:,
+        fragment:
+      )
 
       device.push_error_scope(:validation)
       @handle = Native.wgpuDeviceCreateRenderPipeline(device.handle, desc)
@@ -41,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)
@@ -55,31 +54,38 @@ module WGPU
 
     private
 
-    def setup_label(desc, label)
-      if label
-        ptr = FFI::MemoryPointer.from_string(label)
-        @pointers << ptr
-        desc[:label][:data] = ptr
-        desc[:label][:length] = label.bytesize
-      else
-        desc[:label][:data] = nil
-        desc[:label][:length] = 0
-      end
+    def build_descriptor(label:, layout:, vertex:, primitive:, depth_stencil:, multisample:, fragment:)
+      @pointers = []
+      desc = Native::RenderPipelineDescriptor.new
+      desc[:next_in_chain] = nil
+      DescriptorHelpers.set_label(desc, label, keepalive: @pointers)
+      desc[:layout] = normalize_layout(layout)
+
+      setup_vertex_state(desc[:vertex], vertex)
+      setup_primitive_state(desc[:primitive], primitive)
+      setup_multisample_state(desc[:multisample], multisample)
+      desc[:depth_stencil] = depth_stencil ? setup_depth_stencil_state(depth_stencil) : nil
+      desc[:fragment] = fragment ? setup_fragment_state(fragment) : nil
+
+      [desc, @pointers]
     end
 
     def setup_vertex_state(vertex_state, vertex)
+      DescriptorHelpers.validate_keys!(
+        vertex,
+        allowed: %i[module entry_point constants buffers],
+        required: [:module],
+        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[: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?
@@ -97,8 +103,18 @@ module WGPU
       @pointers << layouts_ptr
 
       buffers.each_with_index do |buf, i|
-        layout = Native::VertexBufferLayout.new(layouts_ptr + i * Native::VertexBufferLayout.size)
-        layout[:step_mode] = buf[:step_mode] || :vertex
+        DescriptorHelpers.validate_keys!(
+          buf,
+          allowed: %i[array_stride step_mode attributes],
+          required: [:array_stride],
+          context: "vertex buffer layout"
+        )
+        layout = Native::VertexBufferLayout.new(layouts_ptr + (i * Native::VertexBufferLayout.size))
+        layout[:step_mode] = Native::EnumHelper.coerce(
+          Native::VertexStepMode,
+          buf[:step_mode] || :vertex,
+          name: "vertex step mode"
+        )
         layout[:array_stride] = buf[:array_stride]
 
         attrs = buf[:attributes] || []
@@ -109,8 +125,18 @@ module WGPU
           attrs_ptr = FFI::MemoryPointer.new(Native::VertexAttribute, attrs.size)
           @pointers << attrs_ptr
           attrs.each_with_index do |attr, j|
-            a = Native::VertexAttribute.new(attrs_ptr + j * Native::VertexAttribute.size)
-            a[:format] = attr[:format]
+            DescriptorHelpers.validate_keys!(
+              attr,
+              allowed: %i[format offset shader_location],
+              required: %i[format offset shader_location],
+              context: "vertex attribute"
+            )
+            a = Native::VertexAttribute.new(attrs_ptr + (j * Native::VertexAttribute.size))
+            a[:format] = Native::EnumHelper.coerce(
+              Native::VertexFormat,
+              attr[:format],
+              name: "vertex format"
+            )
             a[:offset] = attr[:offset]
             a[:shader_location] = attr[:shader_location]
           end
@@ -123,15 +149,41 @@ module WGPU
     end
 
     def setup_primitive_state(primitive_state, primitive)
+      DescriptorHelpers.validate_keys!(
+        primitive,
+        allowed: %i[topology strip_index_format front_face cull_mode unclipped_depth],
+        context: "primitive state"
+      )
       primitive_state[:next_in_chain] = nil
-      primitive_state[:topology] = primitive[:topology] || :triangle_list
-      primitive_state[:strip_index_format] = primitive[:strip_index_format] || :undefined
-      primitive_state[:front_face] = primitive[:front_face] || :ccw
-      primitive_state[:cull_mode] = primitive[:cull_mode] || :none
+      primitive_state[:topology] = Native::EnumHelper.coerce(
+        Native::PrimitiveTopology,
+        primitive[:topology] || :triangle_list,
+        name: "primitive topology"
+      )
+      primitive_state[:strip_index_format] = Native::EnumHelper.coerce(
+        Native::IndexFormat,
+        primitive[:strip_index_format] || :undefined,
+        name: "strip index format"
+      )
+      primitive_state[:front_face] = Native::EnumHelper.coerce(
+        Native::FrontFace,
+        primitive[:front_face] || :ccw,
+        name: "front face"
+      )
+      primitive_state[:cull_mode] = Native::EnumHelper.coerce(
+        Native::CullMode,
+        primitive[:cull_mode] || :none,
+        name: "cull mode"
+      )
       primitive_state[:unclipped_depth] = primitive[:unclipped_depth] ? 1 : 0
     end
 
     def setup_multisample_state(multisample_state, multisample)
+      DescriptorHelpers.validate_keys!(
+        multisample,
+        allowed: %i[count mask alpha_to_coverage_enabled],
+        context: "multisample state"
+      )
       multisample_state[:next_in_chain] = nil
       multisample_state[:count] = multisample[:count] || 1
       multisample_state[:mask] = multisample[:mask] || 0xFFFFFFFF
@@ -139,12 +191,29 @@ module WGPU
     end
 
     def setup_depth_stencil_state(depth_stencil)
+      DescriptorHelpers.validate_keys!(
+        depth_stencil,
+        allowed: %i[
+          format depth_write_enabled depth_compare stencil_front stencil_back
+          stencil_read_mask stencil_write_mask depth_bias depth_bias_slope_scale depth_bias_clamp
+        ],
+        required: [:format],
+        context: "depth stencil state"
+      )
       ds = Native::DepthStencilState.new
       @pointers << ds
       ds[:next_in_chain] = nil
-      ds[:format] = depth_stencil[:format]
+      ds[:format] = Native::EnumHelper.coerce(
+        Native::TextureFormat,
+        depth_stencil[:format],
+        name: "depth stencil format"
+      )
       ds[:depth_write_enabled] = depth_stencil[:depth_write_enabled] ? 1 : 0
-      ds[:depth_compare] = depth_stencil[:depth_compare] || :always
+      ds[:depth_compare] = Native::EnumHelper.coerce(
+        Native::CompareFunction,
+        depth_stencil[:depth_compare] || :always,
+        name: "depth compare function"
+      )
 
       setup_stencil_face(ds[:stencil_front], depth_stencil[:stencil_front] || {})
       setup_stencil_face(ds[:stencil_back], depth_stencil[:stencil_back] || {})
@@ -159,27 +228,51 @@ module WGPU
     end
 
     def setup_stencil_face(face, config)
-      face[:compare] = config[:compare] || :always
-      face[:fail_op] = config[:fail_op] || :keep
-      face[:depth_fail_op] = config[:depth_fail_op] || :keep
-      face[:pass_op] = config[:pass_op] || :keep
+      DescriptorHelpers.validate_keys!(
+        config,
+        allowed: %i[compare fail_op depth_fail_op pass_op],
+        context: "stencil face state"
+      )
+      face[:compare] = Native::EnumHelper.coerce(
+        Native::CompareFunction,
+        config[:compare] || :always,
+        name: "stencil compare function"
+      )
+      face[:fail_op] = Native::EnumHelper.coerce(
+        Native::StencilOperation,
+        config[:fail_op] || :keep,
+        name: "stencil fail operation"
+      )
+      face[:depth_fail_op] = Native::EnumHelper.coerce(
+        Native::StencilOperation,
+        config[:depth_fail_op] || :keep,
+        name: "stencil depth fail operation"
+      )
+      face[:pass_op] = Native::EnumHelper.coerce(
+        Native::StencilOperation,
+        config[:pass_op] || :keep,
+        name: "stencil pass operation"
+      )
     end
 
     def setup_fragment_state(fragment)
+      DescriptorHelpers.validate_keys!(
+        fragment,
+        allowed: %i[module entry_point constants targets],
+        required: [:module],
+        context: "render pipeline fragment descriptor"
+      )
       frag = Native::FragmentState.new
       @pointers << frag
       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?
@@ -199,9 +292,19 @@ module WGPU
       @pointers << targets_ptr
 
       targets.each_with_index do |target, i|
-        ct = Native::ColorTargetState.new(targets_ptr + i * Native::ColorTargetState.size)
+        DescriptorHelpers.validate_keys!(
+          target,
+          allowed: %i[format blend write_mask],
+          required: [:format],
+          context: "color target state"
+        )
+        ct = Native::ColorTargetState.new(targets_ptr + (i * Native::ColorTargetState.size))
         ct[:next_in_chain] = nil
-        ct[:format] = target[:format]
+        ct[:format] = Native::EnumHelper.coerce(
+          Native::TextureFormat,
+          target[:format],
+          name: "color target format"
+        )
         ct[:write_mask] = normalize_write_mask(target[:write_mask])
 
         if target[:blend]
@@ -216,63 +319,57 @@ module WGPU
     end
 
     def setup_blend_state(blend)
+      DescriptorHelpers.validate_keys!(
+        blend,
+        allowed: %i[color alpha],
+        context: "blend state"
+      )
       bs = Native::BlendState.new
       @pointers << bs
 
       color = blend[:color] || {}
-      bs[:color][:operation] = color[:operation] || :add
-      bs[:color][:src_factor] = color[:src_factor] || :one
-      bs[:color][:dst_factor] = color[:dst_factor] || :zero
+      setup_blend_component(bs[:color], color, "color")
 
       alpha = blend[:alpha] || {}
-      bs[:alpha][:operation] = alpha[:operation] || :add
-      bs[:alpha][:src_factor] = alpha[:src_factor] || :one
-      bs[:alpha][:dst_factor] = alpha[:dst_factor] || :zero
+      setup_blend_component(bs[:alpha], alpha, "alpha")
 
       bs.to_ptr
     end
 
+    def setup_blend_component(component, config, name)
+      DescriptorHelpers.validate_keys!(
+        config,
+        allowed: %i[operation src_factor dst_factor],
+        context: "#{name} blend component"
+      )
+      component[:operation] = Native::EnumHelper.coerce(
+        Native::BlendOperation,
+        config[:operation] || :add,
+        name: "#{name} blend operation"
+      )
+      component[:src_factor] = Native::EnumHelper.coerce(
+        Native::BlendFactor,
+        config[:src_factor] || :one,
+        name: "#{name} source blend factor"
+      )
+      component[:dst_factor] = Native::EnumHelper.coerce(
+        Native::BlendFactor,
+        config[:dst_factor] || :zero,
+        name: "#{name} destination blend factor"
+      )
+    end
+
     def normalize_write_mask(mask)
-      case mask
-      when nil
-        Native::ColorWriteMask[:all]
-      when Integer
-        mask
-      when Symbol
-        Native::ColorWriteMask[mask]
-      when Array
-        mask.reduce(0) { |acc, m| acc | Native::ColorWriteMask[m] }
-      else
-        raise ArgumentError, "Invalid write_mask: #{mask}"
-      end
+      Native::EnumHelper.coerce_flags(
+        Native::ColorWriteMask,
+        mask || :all,
+        name: "color write mask"
+      )
     end
 
     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
-    end
   end
 end

data/lib/wgpu/pipeline/shader_module.rb

@@ -4,12 +4,19 @@ module WGPU
   class ShaderModule
     attr_reader :handle
 
-    def initialize(device, label: nil, code:, compilation_hints: [])
+    # 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 = []
-      compilation_hints # currently unused by wgpu-native API
+      @compilation_hints = compilation_hints
+      source = select_source(code, spirv)
 
-      source_ptr = build_shader_source(code, label: label)
+      source_ptr = build_shader_source(source, label: label)
 
       desc = Native::ShaderModuleDescriptor.new
       desc[:next_in_chain] = source_ptr
@@ -29,42 +36,66 @@ module WGPU
 
       if @handle.null? || (error[:type] && error[:type] != :no_error)
         msg = error[:message] || "Failed to create shader module"
-        raise ShaderError, msg
+        raise ShaderError, shader_error_message(msg, label)
+      end
+
+      return unless validate
+
+      begin
+        validate_compilation!(label)
+      rescue StandardError
+        release
+        raise
       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,
+          "Shader compilation info is not implemented by wgpu-native #{Native::Distribution::VERSION}"
+      end
+
       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] << {
-                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
 
@@ -75,7 +106,15 @@ module WGPU
       callback_info[:userdata1] = nil
       callback_info[:userdata2] = nil
 
-      future = Native.wgpuShaderModuleGetCompilationInfo(@handle, callback_info)
+      callback_token = CallbackKeepalive.retain(self, callback)
+      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)
 
       {
@@ -84,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)
@@ -96,6 +141,28 @@ module WGPU
 
     private
 
+    def select_source(code, spirv)
+      sources = [code, spirv].reject(&:nil?)
+      raise ArgumentError, "provide exactly one of code: or spirv:" unless sources.one?
+
+      sources.first
+    end
+
+    def validate_compilation!(label)
+      info = get_compilation_info
+      errors = info[:messages].select { |message| message.type == :error }
+      return if errors.empty?
+
+      details = errors.map(&:to_s).join("\n")
+      release
+      raise ShaderError, shader_error_message(details, label)
+    end
+
+    def shader_error_message(message, label)
+      context = label ? " for #{label.inspect}" : ""
+      "Shader compilation failed#{context}: #{message}"
+    end
+
     def build_shader_source(code, label:)
       if code.is_a?(String)
         if spirv_binary?(code)