rbgl 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ff09c0ce9d51c2c28146dbcfdb9eecbe2a9982e45a43fbb81cd8bc1de4b96fb
-  data.tar.gz: e58db1f718d9e8a8e1fb7cac8e3acffc026eedfc18e64d427f1669e95e7674be
+  metadata.gz: c17ca3e225ae4e0c8aff6550263d7c6fa8b741e5711bfe000b847e6630c62fed
+  data.tar.gz: 3a227d1b5bca1fd9f1e4ef8cfea35321cbf8f6ecf967a517086597f259574652
 SHA512:
-  metadata.gz: b6f662d84ba8b4f44063d9d09e3ce7154bea6547ea3a53ad383b06cf719edb62d0e79ae5b85046b408d1ffa7125100d80a2414dc3213c509d41d9d89cb2e0f2c
-  data.tar.gz: a04b7ce7b7c20502af090e26fcdf0514cfe37850266bfce5a5ad27885999c3bababe0c6089e8cf2f9f31921cdf5c27c2a1e523e03a07b31f40469e048625c3bd
+  metadata.gz: 9761c7b0a73c017941be0a4272c994151b2732faaa103b370e39d5d7255801ff0881ea55e50d3425c817e9e2becae43994a661dfb00fdf7414d156c2b1e0acae
+  data.tar.gz: 00fa09df593f73df4d2e3bb22e7c2c20f5e38b7a3fa04415e907de167a8a975950bd06febb298dedfa159b606f25efd88c6f50076e5b527a9c61040371c8c5b1

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 1.0.0 - 2026-04-05
+
+- Removed the legacy `Window#on_key`, `Window#on_mouse`, and `Window#on_resize` aliases. Register handlers with `window.on(:key_press)`, `window.on(:mouse_move)`, `window.on(:resize)`, and the other event types directly.
+- Removed the legacy `backend: :native` alias. Use `backend: :auto` for automatic native backend selection.
+- Changed file backend binary PPM output to `format: :ppm, ppm_mode: :binary`. The old `format: :ppm_binary` option is no longer accepted.
+- Added a runtime dependency on `rlsl`, so existing applications need it resolved during install and bundle steps.
+- Added binary (`P6`) and text (`P3`) PPM texture loading via `RBGL::Engine::Texture.from_ppm`, and added ASCII or binary PPM output selection for the file backend.
+- Added `RBGL::GUI::Window#dropped_frames` so applications can detect failed presents, including Wayland backpressure cases.
+- Improved automatic native backend selection on Linux: RBGL now prefers Wayland when available, falls back to X11 when needed, and raises clearer `BackendUnavailable` errors when no display server can be used.
+- Improved rendering correctness with view-frustum clipping for triangles, lines, and points, perspective-correct interpolation, point rasterization fixes, and pipeline render-state handling.
+- Tightened validation across pipelines, shaders, vertex buffers, textures, sampler settings, mipmaps, and texture writes so invalid rendering inputs fail earlier with explicit errors.
+
 ## 0.1.0 - 2026-01-04
 
-- Initial release.
+- Initial release.

data/lib/rbgl/engine/buffer.rb

@@ -3,12 +3,95 @@
 module RBGL
   module Engine
     class VertexAttribute
-      attr_reader :name, :size, :offset
+      attr_reader :name, :size, :offset, :kind
 
-      def initialize(name, size, offset = 0)
+      def initialize(name, size, offset = 0, kind: nil)
         @name = name.to_sym
         @size = size
         @offset = offset
+        @kind = (kind || infer_kind).to_sym
+        validate_kind!
+      end
+
+      def serialize(value)
+        values = extract_values(value)
+        validate_value_size!(values)
+        values.first(@size).map { |component| Float(component) }
+      rescue ArgumentError, TypeError => e
+        raise ArgumentError, "Invalid value for attribute #{name}: #{e.message}"
+      end
+
+      def deserialize(values)
+        case @kind
+        when :scalar
+          values[0]
+        when :vec2
+          Larb::Vec2.new(*values)
+        when :vec3
+          Larb::Vec3.new(*values)
+        when :vec4
+          Larb::Vec4.new(*values)
+        when :color
+          Larb::Color.new(*values)
+        when :array
+          values.dup
+        end
+      end
+
+      private
+
+      def infer_kind
+        return :color if @name == :color && @size == 4
+
+        case @size
+        when 1 then :scalar
+        when 2 then :vec2
+        when 3 then :vec3
+        when 4 then :vec4
+        else :array
+        end
+      end
+
+      def validate_kind!
+        expected_sizes = {
+          scalar: [1],
+          vec2: [2],
+          vec3: [3],
+          vec4: [4],
+          color: [4],
+          array: nil
+        }.fetch(@kind) do
+          raise ArgumentError, "Unsupported attribute kind: #{@kind}"
+        end
+
+        return if expected_sizes.nil? || expected_sizes.include?(@size)
+
+        raise ArgumentError, "Attribute #{name} kind #{@kind} requires size #{expected_sizes.join(' or ')}"
+      end
+
+      def extract_values(value)
+        case value
+        when Larb::Vec2
+          [value.x, value.y]
+        when Larb::Vec3
+          [value.x, value.y, value.z]
+        when Larb::Vec4
+          [value.x, value.y, value.z, value.w]
+        when Larb::Color
+          value.to_a
+        when Array
+          value
+        when Numeric
+          [value]
+        else
+          raise ArgumentError, "Unsupported attribute type #{value.class}"
+        end
+      end
+
+      def validate_value_size!(values)
+        return if values.size >= @size
+
+        raise ArgumentError, "Expected at least #{@size} components, got #{values.size}"
       end
     end
 
@@ -22,8 +105,8 @@ module RBGL
         @stride = @offset
       end
 
-      def attribute(name, size)
-        @attributes[name.to_sym] = VertexAttribute.new(name, size, @offset)
+      def attribute(name, size, kind: nil)
+        @attributes[name.to_sym] = VertexAttribute.new(name, size, @offset, kind: kind)
         @offset += size
       end
 
@@ -66,25 +149,13 @@ module RBGL
       end
 
       def add_vertex(**attributes)
+        validate_attribute_keys!(attributes)
+
         vertex_data = []
         @layout.attributes.each do |name, attr|
-          value = attributes[name]
-          raise "Missing attribute: #{name}" unless value
-
-          case value
-          when Larb::Vec2
-            vertex_data.concat([value.x, value.y])
-          when Larb::Vec3
-            vertex_data.concat([value.x, value.y, value.z])
-          when Larb::Vec4
-            vertex_data.concat([value.x, value.y, value.z, value.w])
-          when Larb::Color
-            vertex_data.concat(value.to_a)
-          when Array
-            vertex_data.concat(value)
-          when Numeric
-            vertex_data << value.to_f
-          end
+          raise ArgumentError, "Missing attribute: #{name}" unless attributes.key?(name)
+
+          vertex_data.concat(attr.serialize(attributes[name]))
         end
         @data.concat(vertex_data)
         @vertex_count += 1
@@ -105,18 +176,7 @@ module RBGL
         @layout.attributes.each do |name, attr|
           offset = start + attr.offset
           values = @data[offset, attr.size]
-
-          vertex[name] = case attr.size
-                         when 1 then values[0]
-                         when 2 then Larb::Vec2.new(*values)
-                         when 3 then Larb::Vec3.new(*values)
-                         when 4
-                           if name == :color
-                             Larb::Color.new(*values)
-                           else
-                             Larb::Vec4.new(*values)
-                           end
-                         end
+          vertex[name] = attr.deserialize(values)
         end
 
         vertex
@@ -127,6 +187,15 @@ module RBGL
         data.each { |vertex| buffer.add_vertex(**vertex) }
         buffer
       end
+
+      private
+
+      def validate_attribute_keys!(attributes)
+        unknown_attributes = attributes.keys.map(&:to_sym) - @layout.attributes.keys
+        return if unknown_attributes.empty?
+
+        raise ArgumentError, "Unknown attributes: #{unknown_attributes.join(', ')}"
+      end
     end
 
     class IndexBuffer

data/lib/rbgl/engine/clip_space_clipper.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module RBGL
+  module Engine
+    class ClipSpaceClipper
+      CLIP_PLANES = [
+        ->(position) { position.x + position.w },
+        ->(position) { position.w - position.x },
+        ->(position) { position.y + position.w },
+        ->(position) { position.w - position.y },
+        ->(position) { position.z + position.w },
+        ->(position) { position.w - position.z }
+      ].freeze
+
+      def clip(v0, v1, v2)
+        polygon = [v0, v1, v2]
+
+        CLIP_PLANES.each do |plane|
+          polygon = clip_against_plane(polygon, plane)
+          return [] if polygon.empty?
+        end
+
+        triangulate(polygon)
+      end
+
+      def clip_line(v0, v1)
+        segment = [duplicate_vertex(v0), duplicate_vertex(v1)]
+
+        CLIP_PLANES.each do |plane|
+          segment = clip_segment_against_plane(segment, plane)
+          return nil unless segment
+        end
+
+        segment
+      end
+
+      def visible_point?(vertex)
+        CLIP_PLANES.all? { |plane| signed_distance(vertex, plane) >= 0 }
+      end
+
+      private
+
+      def clip_against_plane(vertices, plane)
+        clipped = []
+        return clipped if vertices.empty?
+
+        previous_vertex = vertices.last
+        previous_distance = signed_distance(previous_vertex, plane)
+
+        vertices.each do |current_vertex|
+          current_distance = signed_distance(current_vertex, plane)
+          current_inside = current_distance >= 0
+          previous_inside = previous_distance >= 0
+
+          if current_inside != previous_inside
+            clipped << interpolate_vertex(previous_vertex, current_vertex, previous_distance, current_distance)
+          end
+
+          clipped << duplicate_vertex(current_vertex) if current_inside
+
+          previous_vertex = current_vertex
+          previous_distance = current_distance
+        end
+
+        clipped
+      end
+
+      def triangulate(polygon)
+        return [] if polygon.size < 3
+
+        polygon[1..].each_cons(2).map do |v1, v2|
+          [duplicate_vertex(polygon.first), duplicate_vertex(v1), duplicate_vertex(v2)]
+        end
+      end
+
+      def clip_segment_against_plane(segment, plane)
+        start_vertex, finish_vertex = segment
+        start_distance = signed_distance(start_vertex, plane)
+        finish_distance = signed_distance(finish_vertex, plane)
+        start_inside = start_distance >= 0
+        finish_inside = finish_distance >= 0
+
+        return [start_vertex, finish_vertex] if start_inside && finish_inside
+        return nil unless start_inside || finish_inside
+
+        intersection = interpolate_vertex(start_vertex, finish_vertex, start_distance, finish_distance)
+        start_inside ? [start_vertex, intersection] : [intersection, finish_vertex]
+      end
+
+      def interpolate_vertex(start_vertex, finish_vertex, start_distance, finish_distance)
+        denominator = start_distance - finish_distance
+        t = denominator.zero? ? 0.0 : start_distance / denominator
+        result = ShaderIO.new
+
+        interpolated_keys(start_vertex, finish_vertex).each do |key|
+          start_value = start_vertex[key]
+          finish_value = finish_vertex[key]
+          result[key] = interpolate_value(start_value, finish_value, t)
+        end
+
+        result
+      end
+
+      def duplicate_vertex(vertex)
+        ShaderIO.new(vertex.to_h)
+      end
+
+      def interpolated_keys(start_vertex, finish_vertex)
+        (start_vertex.to_h.keys + finish_vertex.to_h.keys).uniq
+      end
+
+      def interpolate_value(start_value, finish_value, t)
+        return finish_value if start_value.nil?
+        return start_value if finish_value.nil?
+
+        case start_value
+        when Numeric
+          start_value + (finish_value - start_value) * t
+        when Larb::Vec2, Larb::Vec3, Larb::Vec4, Larb::Color
+          start_value.lerp(finish_value, t)
+        else
+          t < 0.5 ? start_value : finish_value
+        end
+      end
+
+      def signed_distance(vertex, plane)
+        plane.call(clip_position(vertex))
+      end
+
+      def clip_position(vertex)
+        position = vertex[:position]
+
+        case position
+        when Larb::Vec4 then position
+        when Larb::Vec3 then Larb::Vec4.new(position.x, position.y, position.z, 1.0)
+        when Larb::Vec2 then Larb::Vec4.new(position.x, position.y, 0.0, 1.0)
+        else
+          raise ArgumentError, "Unsupported clip position type: #{position.class}"
+        end
+      end
+    end
+  end
+end

data/lib/rbgl/engine/context.rb

@@ -8,6 +8,7 @@ module RBGL
       def initialize(width:, height:)
         @framebuffer = Framebuffer.new(width, height)
         @rasterizer = Rasterizer.new(@framebuffer)
+        @clipper = ClipSpaceClipper.new
         @pipeline = nil
         @uniforms = Uniforms.new
         @vertex_buffer = nil
@@ -38,119 +39,171 @@ module RBGL
         @framebuffer.clear(color: color, depth: depth)
       end
 
+      def resize(width:, height:)
+        @framebuffer.resize(width, height)
+        @rasterizer.resize(width, height)
+      end
+
       def draw_arrays(mode, first, count)
+        validate_draw_state!
+        draw_vertices(mode, first...first + count)
+      end
+
+      def draw_elements(mode, count, offset = 0)
+        validate_draw_state!(indexed: true)
+        indices = @index_buffer.indices[offset, count] || []
+        draw_vertices(mode, indices, vertex_cache: {})
+      end
+
+      def width
+        @framebuffer.width
+      end
+
+      def height
+        @framebuffer.height
+      end
+
+      def aspect_ratio
+        width.to_f / height
+      end
+
+      private
+
+      def validate_draw_state!(indexed: false)
         raise "No pipeline bound" unless @pipeline
         raise "No vertex buffer bound" unless @vertex_buffer
+        raise "No index buffer bound" if indexed && !@index_buffer
+      end
 
-        vertices = (first...first + count).map { |i| process_vertex(i) }
+      def draw_vertices(mode, indices, vertex_cache: nil)
+        each_primitive(mode, indices) do |primitive_indices|
+          primitive = primitive_indices.map { |index| fetch_vertex(index, vertex_cache) }
+          draw_primitive(mode, primitive)
+        end
+      end
+
+      def each_primitive(mode, vertices)
+        return enum_for(:each_primitive, mode, vertices) unless block_given?
+
+        vertices = vertices.to_a unless vertices.respond_to?(:[])
 
         case mode
         when :triangles
-          (0...vertices.size).step(3) do |i|
-            draw_triangle(vertices[i], vertices[i + 1], vertices[i + 2])
-          end
+          each_slice(vertices, 3) { |triangle| yield triangle }
         when :lines
-          (0...vertices.size).step(2) do |i|
-            draw_line(vertices[i], vertices[i + 1])
-          end
+          each_slice(vertices, 2) { |line| yield line }
         when :points
-          vertices.each { |v| draw_point(v) }
+          vertices.each { |vertex| yield [vertex] }
         when :triangle_strip
-          (0...vertices.size - 2).each do |i|
-            if i.even?
-              draw_triangle(vertices[i], vertices[i + 1], vertices[i + 2])
+          (0...vertices.size - 2).each do |index|
+            if index.even?
+              yield [vertices[index], vertices[index + 1], vertices[index + 2]]
             else
-              draw_triangle(vertices[i], vertices[i + 2], vertices[i + 1])
+              yield [vertices[index], vertices[index + 2], vertices[index + 1]]
             end
           end
         when :triangle_fan
-          (1...vertices.size - 1).each do |i|
-            draw_triangle(vertices[0], vertices[i], vertices[i + 1])
+          (1...vertices.size - 1).each do |index|
+            yield [vertices[0], vertices[index], vertices[index + 1]]
           end
+        else
+          raise ArgumentError, "Unsupported primitive mode: #{mode}"
         end
       end
 
-      def draw_elements(mode, count, offset = 0)
-        raise "No pipeline bound" unless @pipeline
-        raise "No vertex buffer bound" unless @vertex_buffer
-        raise "No index buffer bound" unless @index_buffer
+      def each_slice(vertices, size)
+        vertices.each_slice(size) do |primitive|
+          next unless primitive.size == size
 
-        indices = @index_buffer.indices[offset, count]
-        vertices = indices.map { |i| process_vertex(i) }
+          yield primitive
+        end
+      end
 
+      def draw_primitive(mode, primitive)
         case mode
-        when :triangles
-          (0...vertices.size).step(3) do |i|
-            draw_triangle(vertices[i], vertices[i + 1], vertices[i + 2])
-          end
         when :lines
-          (0...vertices.size).step(2) do |i|
-            draw_line(vertices[i], vertices[i + 1])
-          end
+          draw_line(*primitive)
+        when :points
+          draw_point(primitive.first)
+        else
+          draw_triangle(*primitive)
         end
       end
 
-      def width
-        @framebuffer.width
-      end
-
-      def height
-        @framebuffer.height
-      end
-
-      def aspect_ratio
-        width.to_f / height
-      end
-
-      private
-
       def process_vertex(index)
         input = @vertex_buffer.get_vertex(index)
+        return nil unless input
+
         input_io = ShaderIO.new
         input.each { |k, v| input_io[k] = v }
 
         @pipeline.vertex_shader.process(input_io, @uniforms)
       end
 
+      def fetch_vertex(index, vertex_cache)
+        return process_vertex(index) unless vertex_cache
+        return vertex_cache[index] if vertex_cache.key?(index)
+
+        vertex_cache[index] = process_vertex(index)
+      end
+
       def draw_triangle(v0, v1, v2)
         return unless v0 && v1 && v2
-        return if clip_triangle?(v0, v1, v2)
 
-        @rasterizer.rasterize_triangle(
-          v0, v1, v2,
-          @pipeline.fragment_shader,
-          @uniforms,
-          cull_mode: @pipeline.cull_mode
-        )
+        clip_triangle(v0, v1, v2).each do |triangle|
+          @rasterizer.rasterize_triangle(
+            *triangle,
+            @pipeline.fragment_shader,
+            @uniforms,
+            **rasterizer_state
+          )
+        end
       end
 
       def draw_line(v0, v1)
         return unless v0 && v1
+        clipped = clip_line(v0, v1)
+        return unless clipped
 
-        @rasterizer.rasterize_line(v0, v1, @pipeline.fragment_shader, @uniforms)
+        @rasterizer.rasterize_line(*clipped, @pipeline.fragment_shader, @uniforms, **rasterizer_state)
       end
 
       def draw_point(v)
-        return unless v
+        return unless v && point_visible?(v)
 
-        @rasterizer.rasterize_point(v, @pipeline.fragment_shader, @uniforms)
+        @rasterizer.rasterize_point(
+          v,
+          @pipeline.fragment_shader,
+          @uniforms,
+          depth_test: @pipeline.depth_test,
+          depth_write: @pipeline.depth_write,
+          blend_mode: @pipeline.blend_mode
+        )
+      end
+
+      def clip_triangle(v0, v1, v2)
+        @clipper.clip(v0, v1, v2)
+      end
+
+      def clip_line(v0, v1)
+        @clipper.clip_line(v0, v1)
       end
 
       def clip_triangle?(v0, v1, v2)
-        positions = [v0[:position], v1[:position], v2[:position]].map do |p|
-          if p.is_a?(Larb::Vec4)
-            p.perspective_divide
-          else
-            p
-          end
-        end
+        clip_triangle(v0, v1, v2).empty?
+      end
+
+      def point_visible?(vertex)
+        @clipper.visible_point?(vertex)
+      end
 
-        positions.all? { |p| p.x < -1 } ||
-          positions.all? { |p| p.x > 1 } ||
-          positions.all? { |p| p.y < -1 } ||
-          positions.all? { |p| p.y > 1 } ||
-          positions.all? { |p| p.z < -1 } ||
-          positions.all? { |p| p.z > 1 }
+      def rasterizer_state
+        {
+          cull_mode: @pipeline.cull_mode,
+          depth_test: @pipeline.depth_test,
+          depth_write: @pipeline.depth_write,
+          blend_mode: @pipeline.blend_mode
+        }
       end
     end
   end