rbgl 0.1.0 → 1.0.1

data/examples/cube_spinning.rb

@@ -67,7 +67,7 @@ view = Mat4.look_at(
 
 window.on(:key_press) do |event|
   puts "Key pressed: #{event.key}"
-  window.stop if event.key == 12 || event.key == "q" || event.key == "Escape"
+  window.stop if %i[escape q].include?(event.key)
 end
 
 puts "Press 'q' or Escape to quit"

data/examples/gradient.rb

@@ -67,7 +67,7 @@ while running && !window.should_close?
   events.each do |e|
     case e[:type]
     when :key_press
-      running = false if e[:key] == 12 || e[:key] == "q"
+      running = false if %i[escape q].include?(e[:key])
     end
   end
 

data/examples/multi_return_test.rb

@@ -81,7 +81,7 @@ while running && !window.should_close?
   events.each do |e|
     case e[:type]
     when :key_press
-      running = false if e[:key] == 12 || e[:key] == "q"
+      running = false if %i[escape q].include?(e[:key])
     end
   end
 

data/examples/plasma.rb

@@ -60,7 +60,7 @@ while running && !window.should_close?
 
   events = window.poll_events_raw
   events.each do |e|
-    if e[:type] == :key_press && (e[:key] == 12 || e[:key] == "q")
+    if e[:type] == :key_press && %i[escape q].include?(e[:key])
       running = false
     end
   end

data/examples/sphere_raymarch.rb

@@ -108,7 +108,7 @@ while running && !window.should_close?
 
   events = window.poll_events_raw
   events.each do |e|
-    if e[:type] == :key_press && (e[:key] == 12 || e[:key] == "q")
+    if e[:type] == :key_press && %i[escape q].include?(e[:key])
       running = false
     end
   end

data/examples/triangle_window.rb

@@ -42,7 +42,7 @@ time = 0.0
 
 window.on(:key_press) do |event|
   puts "Key: #{event.key}"
-  window.stop if event.key == 12 || event.key == "q" || event.key == "Escape"
+  window.stop if %i[escape q].include?(event.key)
 end
 
 window.on(:mouse_move) do |event|

data/exe/rbgl

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require "optparse"
+
+lib_path = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib_path) unless $LOAD_PATH.include?(lib_path)
+
+require "rbgl"
+require "rbgl/cli/doctor"
+
+module RBGLCLI
+  def self.run(argv = ARGV, stdout: $stdout, stderr: $stderr)
+    options = { json: false }
+
+    parser = OptionParser.new do |parser|
+      parser.banner = "Usage: rbgl <command>\n\nCommands:\n  doctor [--json]\n"
+      parser.on("--json", "Output JSON") { options[:json] = true }
+      parser.on("-h", "--help", "Show this help") do
+        stdout.puts parser
+        return 0
+      end
+    end
+
+    parser.parse!(argv)
+
+    command = argv.shift
+    unless command == "doctor"
+      stderr.puts parser
+      return 1
+    end
+
+    RBGL::CLI::Doctor.new(json: options[:json], io: stdout).run
+  rescue OptionParser::InvalidOption, OptionParser::MissingArgument => error
+    stderr.puts error.message
+    stderr.puts parser
+    1
+  end
+end
+
+exit RBGLCLI.run

data/lib/rbgl/cli/doctor.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "tmpdir"
+
+module RBGL
+  module CLI
+    class Doctor
+      class << self
+        def default_checks
+          {
+            file_backend: ->(doctor, env, platform) { doctor.__send__(:check_file_backend, env, platform) },
+            wayland: ->(doctor, env, platform) { doctor.__send__(:check_wayland, env, platform) },
+            x11: ->(doctor, env, platform) { doctor.__send__(:check_x11, env, platform) },
+            cocoa: ->(doctor, env, platform) { doctor.__send__(:check_cocoa, env, platform) },
+            rlsl: ->(doctor, env, platform) { doctor.__send__(:check_rlsl, env, platform) }
+          }
+        end
+      end
+
+      def initialize(json: false, io: $stdout, env: ENV, platform: RUBY_PLATFORM, ruby_version: RUBY_VERSION, checks: {})
+        @json = json
+        @io = io
+        @env = env
+        @platform = platform
+        @ruby_version = ruby_version
+        @checks = self.class.default_checks.merge(checks)
+      end
+
+      def run
+        report = collect
+
+        if @json
+          output_json(report)
+        else
+          output_text(report)
+        end
+
+        0
+      end
+
+      def collect
+        {
+          rbgl_version: RBGL::VERSION,
+          ruby_version: @ruby_version,
+          platform: @platform,
+          file_backend: collect_component(:file_backend),
+          wayland: collect_component(:wayland),
+          x11: collect_component(:x11),
+          cocoa: collect_component(:cocoa),
+          rlsl: collect_component(:rlsl)
+        }
+      end
+
+      private
+
+      def collect_component(key)
+        @checks.fetch(key).call(self, @env, @platform)
+      rescue StandardError => e
+        { available: false, error: "#{e.class}: #{e.message}" }
+      end
+
+      def output_text(report)
+        @io.puts("RBGL version: #{report[:rbgl_version]}")
+        @io.puts("Ruby version: #{report[:ruby_version]}")
+        @io.puts("RUBY_PLATFORM: #{report[:platform]}")
+        @io.puts
+        dump_section("File backend", report[:file_backend])
+        dump_section("Wayland", report[:wayland])
+        dump_section("X11", report[:x11])
+        dump_section("Cocoa", report[:cocoa])
+        dump_section("RLSL", report[:rlsl])
+      end
+
+      def output_json(report)
+        @io.puts(JSON.pretty_generate(report))
+      end
+
+      def dump_section(name, values)
+        @io.puts("#{name}:")
+        values.each do |key, value|
+          @io.puts("  #{key}: #{format_value(value)}")
+        end
+        @io.puts
+      end
+
+      def format_value(value)
+        return value.is_a?(TrueClass) || value.is_a?(FalseClass) ? (value ? "yes" : "no") : value.inspect
+      end
+
+      def check_file_backend(_env, _platform)
+        output_dir = Dir.mktmpdir("rbgl-doctor")
+        backend = RBGL::GUI::FileBackend.new(1, 1, "rbgl-doctor", output_dir: output_dir)
+        backend.present(RBGL::Engine::Framebuffer.new(1, 1))
+
+        { available: true, output_dir: output_dir }
+      ensure
+        backend&.close
+        FileUtils.rm_rf(output_dir) if output_dir
+      end
+
+      def check_wayland(env, _platform)
+        require_ok, require_error = safe_require("rbgl/gui/wayland/connection")
+        {
+          display_env: env["WAYLAND_DISPLAY"],
+          display_available: !env["WAYLAND_DISPLAY"].nil?,
+          require_ok: require_ok,
+          require_error: require_error
+        }
+      end
+
+      def check_x11(env, _platform)
+        require_ok, require_error = safe_require("rbgl/gui/x11/connection")
+        {
+          display_env: env["DISPLAY"],
+          display_available: !env["DISPLAY"].nil?,
+          require_ok: require_ok,
+          require_error: require_error
+        }
+      end
+
+      def check_cocoa(_env, platform)
+        darwin = platform.include?("darwin")
+        return { platform: platform, supported: false } unless darwin
+
+        require_ok, require_error = safe_require("metaco")
+        {
+          platform: platform,
+          supported: true,
+          require_ok: require_ok,
+          require_error: require_error
+        }
+      end
+
+      def check_rlsl(_env, _platform)
+        begin
+          require "rlsl"
+          version = Gem.loaded_specs["rlsl"]&.version&.to_s
+
+          { require_ok: true, version: version }
+        rescue LoadError => e
+          { require_ok: false, error: "#{e.class}: #{e.message}" }
+        end
+      end
+
+      def safe_require(file)
+        require file
+        [true, nil]
+      rescue LoadError => e
+        [false, "#{e.class}: #{e.message}"]
+      end
+    end
+  end
+end

data/lib/rbgl/engine/buffer.rb

@@ -3,28 +3,132 @@
 module RBGL
   module Engine
     class VertexAttribute
-      attr_reader :name, :size, :offset
+      attr_reader :name, :size, :offset, :kind
+
+      def initialize(name, size, offset = 0, kind: nil)
+        unless size.is_a?(Integer) && size.positive?
+          raise ArgumentError, "Vertex attribute size must be a positive Integer"
+        end
 
-      def initialize(name, size, offset = 0)
         @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
 
     class VertexLayout
-      attr_reader :attributes, :stride
+      attr_reader :stride
 
       def initialize(&block)
         @attributes = {}
         @offset = 0
+        @stride = 0
+        @finalized = false
         instance_eval(&block) if block_given?
-        @stride = @offset
       end
 
-      def attribute(name, size)
-        @attributes[name.to_sym] = VertexAttribute.new(name, size, @offset)
+      def attribute(name, size, kind: nil)
+        raise ArgumentError, "Vertex layout is finalized" if @finalized
+
+        key = name.to_sym
+        raise ArgumentError, "Duplicate vertex attribute: #{key}" if @attributes.key?(key)
+
+        @attributes[key] = VertexAttribute.new(key, size, @offset, kind: kind)
         @offset += size
+        @stride = @offset
+      end
+
+      def attributes
+        @finalized ? @attributes : @attributes.dup.freeze
+      end
+
+      def finalize!
+        @finalized = true
+        @attributes.freeze
+        self
       end
 
       def self.position_only
@@ -60,31 +164,23 @@ module RBGL
       attr_reader :data, :layout, :vertex_count
 
       def initialize(layout)
-        @layout = layout
+        unless layout.is_a?(VertexLayout)
+          raise ArgumentError, "VertexBuffer layout must be an RBGL::Engine::VertexLayout"
+        end
+
+        @layout = layout.finalize!
         @data = []
         @vertex_count = 0
       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 +201,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,17 +212,28 @@ 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
-      attr_reader :indices
-
       def initialize(indices = [])
-        @indices = indices.map(&:to_i)
+        @indices = validate_indices!(indices)
+      end
+
+      def indices
+        @indices.dup.freeze
       end
 
       def add(*idx)
-        @indices.concat(idx.flatten.map(&:to_i))
+        @indices.concat(validate_indices!(idx.flatten))
         self
       end
 
@@ -146,6 +242,8 @@ module RBGL
       end
 
       def get_triangle(index)
+        return nil unless index.is_a?(Integer) && index >= 0
+
         start = index * 3
         @indices[start, 3]
       end
@@ -155,6 +253,18 @@ module RBGL
 
         (0...triangle_count).each { |i| yield get_triangle(i) }
       end
+
+      private
+
+      def validate_indices!(indices)
+        indices.map do |index|
+          unless index.is_a?(Integer) && index >= 0
+            raise ArgumentError, "Index must be a non-negative Integer: #{index.inspect}"
+          end
+
+          index
+        end
+      end
     end
   end
 end

data/lib/rbgl/engine/clip_space_clipper.rb

@@ -0,0 +1,163 @@
+# 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].map { |vertex| normalize_vertex(vertex) }
+        outcodes = polygon.map { |vertex| outcode(vertex) }
+        return [polygon] if outcodes.reduce(:|).zero?
+        return [] unless outcodes.reduce(:&).zero?
+
+        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
+
+      def clip_point(vertex)
+        point = normalize_vertex(vertex)
+        visible_point?(point) ? point : nil
+      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).tap do |copy|
+          copy[:position] = clip_position(vertex) if vertex[:position].is_a?(Larb::Vec2)
+        end
+      end
+
+      def normalize_vertex(vertex)
+        vertex[:position].is_a?(Larb::Vec2) ? duplicate_vertex(vertex) : vertex
+      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 outcode(vertex)
+        CLIP_PLANES.each_with_index.reduce(0) do |code, (plane, index)|
+          signed_distance(vertex, plane).negative? ? code | (1 << index) : code
+        end
+      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