stagecraft 1.0.0

data/lib/stagecraft/animation/track.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  module Animation
+    class Track
+      PATH_COMPONENTS = { translation: 3, rotation: 4, scale: 3 }.freeze
+      INTERPOLATIONS = %i[linear step cubicspline].freeze
+
+      attr_reader :times, :values, :target, :target_path, :interpolation, :value_size
+
+      def initialize(times:, values:, target:, target_path:, interpolation: :linear, value_size: nil)
+        @times = unpack(times)
+        @values = unpack(values)
+        @target = target
+        @target_path = target_path.to_sym
+        @interpolation = interpolation.to_sym
+        raise ArgumentError, "unsupported interpolation #{interpolation.inspect}" unless INTERPOLATIONS.include?(@interpolation)
+        raise ArgumentError, "animation times cannot be empty" if @times.empty?
+        raise ArgumentError, "animation times must be sorted" unless @times.each_cons(2).all? { |left, right| left <= right }
+
+        @value_size = value_size || infer_value_size
+        expected = @times.length * @value_size * (cubicspline? ? 3 : 1)
+        raise ArgumentError, "animation value count #{values_count} does not match expected #{expected}" unless values_count == expected
+      end
+
+      def duration
+        times.last
+      end
+
+      def sample(time, out = nil)
+        value = sample_value(Float(time))
+        assign(out, value) if out
+        value
+      end
+
+      private
+
+      def unpack(value)
+        value.is_a?(String) ? value.unpack("e*") : value.to_a.map(&:to_f)
+      end
+
+      def infer_value_size
+        PATH_COMPONENTS[target_path] || begin
+          divisor = times.length * (cubicspline? ? 3 : 1)
+          values.length / divisor
+        end
+      end
+
+      def values_count
+        values.length
+      end
+
+      def cubicspline?
+        interpolation == :cubicspline
+      end
+
+      def sample_value(time)
+        return key_value(0) if time <= times.first
+        return key_value(times.length - 1) if time >= times.last
+
+        upper = times.bsearch_index { |key_time| key_time > time }
+        lower = upper - 1
+        duration = times[upper] - times[lower]
+        amount = duration.zero? ? 0.0 : (time - times[lower]) / duration
+        case interpolation
+        when :step then key_value(lower)
+        when :cubicspline then cubic_value(lower, upper, amount, duration)
+        else linear_value(lower, upper, amount)
+        end
+      end
+
+      def key_value(index)
+        value_index = cubicspline? ? ((index * 3) + 1) : index
+        slice(value_index)
+      end
+
+      def linear_value(lower, upper, amount)
+        first = key_value(lower)
+        second = key_value(upper)
+        return quaternion(first).slerp(quaternion(second), amount).to_a if target_path == :rotation
+
+        first.zip(second).map { |left, right| left + ((right - left) * amount) }
+      end
+
+      def cubic_value(lower, upper, amount, duration)
+        p0 = slice((lower * 3) + 1)
+        m0 = slice((lower * 3) + 2)
+        p1 = slice((upper * 3) + 1)
+        m1 = slice(upper * 3)
+        t2 = amount * amount
+        t3 = t2 * amount
+        h00 = (2 * t3) - (3 * t2) + 1
+        h10 = t3 - (2 * t2) + amount
+        h01 = (-2 * t3) + (3 * t2)
+        h11 = t3 - t2
+        result = value_size.times.map do |index|
+          (h00 * p0[index]) + (h10 * duration * m0[index]) +
+            (h01 * p1[index]) + (h11 * duration * m1[index])
+        end
+        target_path == :rotation ? quaternion(result).normalize.to_a : result
+      end
+
+      def slice(index)
+        values.slice(index * value_size, value_size)
+      end
+
+      def quaternion(value)
+        Larb::Quat.new(*value)
+      end
+
+      def assign(out, value)
+        if out.respond_to?(:set)
+          out.set(*value)
+        elsif out.respond_to?(:replace)
+          out.replace(value)
+        else
+          raise ArgumentError, "animation output must support #set or #replace"
+        end
+      end
+    end
+  end
+end

data/lib/stagecraft/app.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  class App
+    attr_reader :window, :renderer
+
+    def initialize(title: "Stagecraft", width: 800, height: 600, msaa: 4,
+                   window: :sdl3, renderer: nil, resizable: true)
+      @window = build_window(window, title:, width:, height:, resizable:)
+      @renderer = renderer || Renderer.new(window: @window, width:, height:, msaa:)
+    rescue StandardError
+      @window&.close
+      raise
+    end
+
+    def aspect
+      width, height = window.drawable_size
+      height.zero? ? 1.0 : width.to_f / height
+    end
+
+    def run
+      raise ArgumentError, "App#run requires a block" unless block_given?
+
+      previous = monotonic_time
+      loop do
+        window.poll_events
+        break if window.should_close?
+
+        now = monotonic_time
+        dt = (now - previous).clamp(0.0, 0.1)
+        previous = now
+        yield(dt)
+        break if ENV["STAGECRAFT_SMOKE"] == "1"
+      end
+      self
+    ensure
+      begin
+        renderer.dispose
+      ensure
+        window.close
+      end
+    end
+
+    private
+
+    def build_window(value, **options)
+      return value unless value.is_a?(Symbol) || value.is_a?(String)
+
+      case value.to_sym
+      when :sdl3 then Window::Sdl3.new(**options)
+      when :glfw then Window::Glfw.new(**options)
+      else
+        raise ArgumentError, "unknown window adapter #{value.inspect}"
+      end
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/stagecraft/cameras/camera.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  module Cameras
+    class Camera < Node
+      def view_matrix
+        world_matrix.inverse
+      end
+
+      def view_projection_matrix
+        projection_matrix * view_matrix
+      end
+    end
+  end
+end

data/lib/stagecraft/cameras/orthographic_camera.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  module Cameras
+    class Orthographic < Camera
+      PROPERTIES = %i[left right top bottom near far].freeze
+
+      attr_reader(*PROPERTIES)
+
+      def initialize(left: -1.0, right: 1.0, top: 1.0, bottom: -1.0, near: 0.1, far: 2_000.0, **)
+        super(**)
+        @projection_revision = 0
+        @cached_projection_revision = -1
+        { left:, right:, top:, bottom:, near:, far: }.each do |name, value|
+          public_send(:"#{name}=", value)
+        end
+        validate_extents!
+      end
+
+      PROPERTIES.each do |property|
+        define_method(:"#{property}=") do |value|
+          number = Float(value)
+          variable = :"@#{property}"
+          return number if instance_variable_defined?(variable) && instance_variable_get(variable) == number
+
+          instance_variable_set(variable, number)
+          @projection_revision += 1
+          number
+        end
+      end
+
+      def projection_matrix
+        return @projection_matrix if @cached_projection_revision == @projection_revision
+
+        validate_extents!
+        width = right - left
+        height = top - bottom
+        depth = far - near
+        @projection_matrix = Larb::Mat4.new([
+          2.0 / width, 0.0, 0.0, 0.0,
+          0.0, 2.0 / height, 0.0, 0.0,
+          0.0, 0.0, -1.0 / depth, 0.0,
+          -(right + left) / width, -(top + bottom) / height, -near / depth, 1.0
+        ])
+        @cached_projection_revision = @projection_revision
+        @projection_matrix
+      end
+
+      private
+
+      def validate_extents!
+        raise ArgumentError, "left and right must differ" if left == right
+        raise ArgumentError, "top and bottom must differ" if top == bottom
+        raise ArgumentError, "far must be greater than near" unless far > near
+      end
+    end
+
+    OrthographicCamera = Orthographic
+  end
+end

data/lib/stagecraft/cameras/perspective_camera.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  module Cameras
+    class Perspective < Camera
+      attr_reader :fov, :aspect, :near, :far
+
+      def initialize(fov: 50.0, aspect: 1.0, near: 0.1, far: 2_000.0, **)
+        super(**)
+        @projection_revision = 0
+        @cached_projection_revision = -1
+        self.fov = fov
+        self.aspect = aspect
+        self.near = near
+        self.far = far
+      end
+
+      def fov=(value)
+        assign_projection_value(:@fov, Float(value)) { |number| number.positive? && number < 180.0 }
+      end
+
+      def aspect=(value)
+        assign_projection_value(:@aspect, Float(value), &:positive?)
+      end
+
+      def near=(value)
+        assign_projection_value(:@near, Float(value), &:positive?)
+        validate_planes! if defined?(@far)
+      end
+
+      def far=(value)
+        assign_projection_value(:@far, Float(value), &:positive?)
+        validate_planes! if defined?(@near)
+      end
+
+      def projection_matrix
+        return @projection_matrix if @cached_projection_revision == @projection_revision
+
+        radians = fov * Math::PI / 180.0
+        f = 1.0 / Math.tan(radians / 2.0)
+        @projection_matrix = Larb::Mat4.new([
+          f / aspect, 0.0, 0.0, 0.0,
+          0.0, f, 0.0, 0.0,
+          0.0, 0.0, far / (near - far), -1.0,
+          0.0, 0.0, (near * far) / (near - far), 0.0
+        ])
+        @cached_projection_revision = @projection_revision
+        @projection_matrix
+      end
+
+      private
+
+      def assign_projection_value(variable, value)
+        raise ArgumentError, "invalid projection value #{value}" unless yield(value)
+        return value if instance_variable_defined?(variable) && instance_variable_get(variable) == value
+
+        instance_variable_set(variable, value)
+        @projection_revision += 1
+        value
+      end
+
+      def validate_planes!
+        raise ArgumentError, "far must be greater than near" unless far > near
+      end
+    end
+
+    PerspectiveCamera = Perspective
+  end
+end

data/lib/stagecraft/color.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  class Color
+    HEX_PATTERN = /\A#?([0-9a-f]{6})([0-9a-f]{2})?\z/i
+
+    attr_reader :r, :g, :b, :a
+
+    def initialize(value = 0.0, green = nil, blue = nil, alpha = 1.0)
+      components = normalize(value, green, blue, alpha)
+      @r, @g, @b, @a = components.map(&:to_f)
+    end
+
+    def self.coerce(value)
+      value.is_a?(self) ? value : new(value)
+    end
+
+    def to_a
+      [r, g, b, a]
+    end
+
+    def to_larb
+      Larb::Color.new(r, g, b, a)
+    end
+
+    def ==(other)
+      other.respond_to?(:to_a) && to_a == other.to_a
+    end
+
+    private
+
+    def normalize(value, green, blue, alpha)
+      return from_hex(value) if value.is_a?(String)
+      return normalize_array(value) if value.respond_to?(:to_ary)
+      return normalize_array(value.to_a) if green.nil? && value.respond_to?(:to_a)
+      return [value, value, value, alpha] if green.nil? && blue.nil?
+
+      [value, green, blue, alpha]
+    end
+
+    def from_hex(value)
+      match = HEX_PATTERN.match(value)
+      raise ArgumentError, "invalid color #{value.inspect}" unless match
+
+      rgb = match[1].scan(/../).map { |part| part.to_i(16) / 255.0 }
+      rgb << (match[2] ? match[2].to_i(16) / 255.0 : 1.0)
+    end
+
+    def normalize_array(value)
+      values = value.to_a
+      raise ArgumentError, "color requires 3 or 4 components" unless [3, 4].include?(values.length)
+
+      values.length == 3 ? [*values, 1.0] : values
+    end
+  end
+end

data/lib/stagecraft/controls/orbit_controls.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  module Controls
+    class Orbit
+      attr_reader :camera, :target
+      attr_accessor :enabled, :rotate_speed, :zoom_speed, :pan_speed, :damping,
+                    :min_distance, :max_distance, :min_polar_angle, :max_polar_angle
+
+      def initialize(camera, window = nil, target: Larb::Vec3.new)
+        @camera = camera
+        @target = vector(target)
+        @enabled = true
+        @rotate_speed = 0.005
+        @zoom_speed = 0.15
+        @pan_speed = 0.002
+        @damping = 12.0
+        @min_distance = 0.01
+        @max_distance = Float::INFINITY
+        @min_polar_angle = 1e-4
+        @max_polar_angle = Math::PI - 1e-4
+        @azimuth_delta = 0.0
+        @polar_delta = 0.0
+        @zoom_delta = 0.0
+        @pan_delta = Larb::Vec3.new
+        @dragging = false
+        sync_spherical
+        attach(window) if window
+      end
+
+      def target=(value)
+        @target = vector(value)
+        sync_spherical
+      end
+
+      def rotate(delta_x, delta_y)
+        return self unless enabled
+
+        @azimuth_delta -= Float(delta_x) * rotate_speed
+        @polar_delta -= Float(delta_y) * rotate_speed
+        self
+      end
+
+      def zoom(delta)
+        return self unless enabled
+
+        @zoom_delta += Float(delta) * zoom_speed
+        self
+      end
+
+      def pan(delta_x, delta_y)
+        return self unless enabled
+
+        rotation = camera.world_matrix.extract_rotation
+        right = rotation * Larb::Vec3.right
+        up = rotation * Larb::Vec3.up
+        scale = @radius * pan_speed
+        @pan_delta = @pan_delta + (right * (-Float(delta_x) * scale)) + (up * (Float(delta_y) * scale))
+        self
+      end
+
+      def update(dt = 1.0 / 60.0)
+        return self unless enabled
+
+        response = 1.0 - Math.exp(-damping * [Float(dt), 0.0].max)
+        @azimuth += @azimuth_delta * response
+        @polar = (@polar + (@polar_delta * response)).clamp(min_polar_angle, max_polar_angle)
+        @radius = (@radius * Math.exp(@zoom_delta * response)).clamp(min_distance, max_distance)
+        @target = @target + (@pan_delta * response)
+        decay = 1.0 - response
+        @azimuth_delta *= decay
+        @polar_delta *= decay
+        @zoom_delta *= decay
+        @pan_delta = @pan_delta * decay
+        update_camera
+        self
+      end
+
+      private
+
+      def attach(window)
+        window.on_pointer_button do |button, pressed, _x, _y|
+          @dragging = pressed if left_button?(button)
+        end
+        window.on_pointer_move do |_x, _y, relative_x, relative_y|
+          rotate(relative_x, relative_y) if @dragging
+        end
+        window.on_scroll { |_x, y| zoom(-y) }
+      end
+
+      def left_button?(button)
+        [1, :left, (defined?(GLFW::GLFW_MOUSE_BUTTON_LEFT) && GLFW::GLFW_MOUSE_BUTTON_LEFT)].include?(button)
+      end
+
+      def sync_spherical
+        offset = camera.world_position - target
+        @radius = [offset.length, min_distance].max
+        @azimuth = Math.atan2(offset.x, offset.z)
+        @polar = Math.acos((offset.y / @radius).clamp(-1.0, 1.0))
+      end
+
+      def update_camera
+        sin_polar = Math.sin(@polar)
+        camera.position.set(
+          target.x + (@radius * sin_polar * Math.sin(@azimuth)),
+          target.y + (@radius * Math.cos(@polar)),
+          target.z + (@radius * sin_polar * Math.cos(@azimuth))
+        )
+        camera.look_at(target)
+      end
+
+      def vector(value)
+        value.is_a?(Larb::Vec3) ? value : Larb::Vec3.new(*value.to_a)
+      end
+    end
+
+    OrbitControls = Orbit
+  end
+end

data/lib/stagecraft/core/attribute.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Stagecraft
+  class Attribute
+    FORMAT_COMPONENTS = {
+      float32: 1, float32x2: 2, float32x3: 3, float32x4: 4,
+      uint16: 1, uint16x2: 2, uint16x4: 4,
+      sint16x2: 2, sint16x4: 4, snorm16x2: 2, snorm16x4: 4,
+      unorm16x2: 2, unorm16x4: 4,
+      uint32: 1, uint32x2: 2, uint32x3: 3, uint32x4: 4,
+      unorm8x2: 2, unorm8x4: 4, uint8x2: 2, uint8x4: 4,
+      sint8x2: 2, sint8x4: 4, snorm8x2: 2, snorm8x4: 4
+    }.freeze
+    FORMAT_WIDTHS = {
+      float32: 4, uint32: 4, uint16: 2,
+      uint8: 1, unorm8: 1, sint8: 1, snorm8: 1,
+      sint16: 2, snorm16: 2, unorm16: 2
+    }.freeze
+
+    attr_reader :data, :format, :count, :version
+
+    def initialize(data:, format:, count:, &on_change)
+      @format = format.to_sym
+      @count = Integer(count)
+      @version = 0
+      @on_change = on_change
+      @initialized = false
+      validate!
+      self.data = data
+      @initialized = true
+    end
+
+    def data=(value)
+      raise ArgumentError, "attribute data must be a packed String" unless value.is_a?(String)
+
+      next_data = value.b.freeze
+      expected_size = count * byte_stride
+      unless next_data.bytesize == expected_size
+        raise ArgumentError, "attribute data must contain #{expected_size} bytes, got #{next_data.bytesize}"
+      end
+      @data = next_data
+      @version += 1
+      @on_change&.call if @initialized
+    end
+
+    def components
+      FORMAT_COMPONENTS.fetch(format) { raise ArgumentError, "unsupported vertex format #{format.inspect}" }
+    end
+
+    def byte_stride
+      prefix = FORMAT_WIDTHS.keys.find { |candidate| format.to_s.start_with?(candidate.to_s) }
+      FORMAT_WIDTHS.fetch(prefix) * components
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "attribute count must be non-negative" if count.negative?
+
+      components
+    end
+  end
+
+  class IndexAttribute
+    attr_reader :data, :format, :count, :version
+
+    def initialize(data:, format:, &on_change)
+      @format = format.to_sym
+      raise ArgumentError, "index format must be :uint16 or :uint32" unless %i[uint16 uint32].include?(@format)
+
+      @version = 0
+      @on_change = on_change
+      @initialized = false
+      self.data = data
+      @initialized = true
+    end
+
+    def data=(value)
+      raise ArgumentError, "index data must be a packed String" unless value.is_a?(String)
+
+      next_data = value.b.freeze
+      width = format == :uint16 ? 2 : 4
+      raise ArgumentError, "index data is not aligned to #{width} bytes" unless (next_data.bytesize % width).zero?
+
+      @data = next_data
+      @count = @data.bytesize / width
+      @version += 1
+      @on_change&.call if @initialized
+    end
+  end
+end