ruby2d 0.12.0 → 1.0.0

data/lib/ruby2d/circle.rb

@@ -1,58 +1,235 @@
-# frozen_string_literal: true
-
 # Ruby2D::Circle
 
 module Ruby2D
-  #
-  # Create a circle using +Circle.new+
-  #
+  # A circle
   class Circle
     include Renderable
 
-    attr_accessor :x, :y, :radius, :sectors
+    attr_accessor :radius, :sectors, :rotate, :fill, :stroke_width
+    attr_reader :x, :y, :stroke_color
+    alias_method :stroke_colour, :stroke_color
+
+    # Set the x position (the center). Pass a symbol (`:left`, `:center`,
+    # `:right`) to set alignment intent — resolved at draw time against the
+    # window, with the circle's bounding box hugging the chosen edge.
+    def x=(value)
+      return self.x_align = value if value.is_a?(Symbol)
+      @x_align = nil unless @_resolving_alignment
+      @x = value
+    end
+
+    # Set the y position (the center). Pass a symbol (`:top`, `:center`,
+    # `:bottom`) to set alignment intent.
+    def y=(value)
+      return self.y_align = value if value.is_a?(Symbol)
+      @y_align = nil unless @_resolving_alignment
+      @y = value
+    end
 
     # Create a circle
-    #
-    # @param [Numeric] x
-    # @param [Numeric] y
-    # @param [Numeric] z
-    # @param [Numeric] radius
-    # @param [Numeric] sectors Smoothness of the circle is better when more +sectors+ are used.
-    # @param [String | Color] color Or +colour+
-    # @param [Float] opacity
-    def initialize(x: 25, y: 25, z: 0, radius: 50, sectors: 30,
-                   color: nil, colour: nil, opacity: nil)
+    def initialize(x: 0, y: 0, z: 0, radius: 50, sectors: 30,
+                   rotate: 0, rx: nil, ry: nil,
+                   color: nil, colour: nil, opacity: nil,
+                   fill: true, stroke_width: 0, stroke_color: nil, stroke_colour: nil,
+                   add: true, visible: true,
+                   padding: nil, padding_top: nil, padding_right: nil,
+                   padding_bottom: nil, padding_left: nil)
+      x, y = _extract_alignment(x, y)
+      _apply_padding(padding, padding_top, padding_right, padding_bottom, padding_left)
+      _validate_dimensions(radius: radius)
       @x = x
       @y = y
       @z = z
       @radius = radius
       @sectors = sectors
+      @rotate = rotate
+      @_user_rx = rx
+      @_user_ry = ry
       self.color = color || colour || 'white'
-      self.color.opacity = opacity unless opacity.nil?
-      add
+      self.opacity = opacity unless opacity.nil?
+      @fill = fill
+      @stroke_width = stroke_width
+      self.stroke_color = stroke_color || stroke_colour || (color || colour)
+      self.stroke_color.opacity = opacity unless opacity.nil?
+      @visible = visible
+      self.add if add
+    end
+
+    # Set the stroke color. Single-color only — a per-vertex array is rejected.
+    def stroke_color=(c)
+      resolved = c.nil? ? nil : Color.set(c)
+      if resolved.is_a?(Color::Set)
+        raise ArgumentError, "`#{self.class}` does not support per-vertex stroke colors; pass a single color"
+      end
+
+      @stroke_color = resolved || Color.new('white')
+      @_stroke_cc = nil
+    end
+    alias_method :stroke_colour=, :stroke_color=
+
+    # Get the rotation center x coordinate
+    def rx
+      @_user_rx.nil? ? @x : @_user_rx
+    end
+
+    # Get the rotation center y coordinate
+    def ry
+      @_user_ry.nil? ? @y : @_user_ry
+    end
+
+    # Set the rotation center x coordinate
+    def rx=(val)
+      @_user_rx = val
+    end
+
+    # Set the rotation center y coordinate
+    def ry=(val)
+      @_user_ry = val
+    end
+
+    # Bounding-box width and height (the diameter)
+    def width
+      @radius * 2
+    end
+
+    def height
+      @radius * 2
     end
 
-    # Check if the circle contains the point at +(x, y)+
+    # Set the color value. Single-color only — a per-vertex color array is
+    # rejected with a clear message rather than a generic "not a valid color".
+    def color=(color)
+      c = Color.set(color)
+      if c.is_a?(Color::Set)
+        raise ArgumentError, "`#{self.class}` does not support per-vertex colors; pass a single color"
+      end
+
+      @color = c
+      @_cc = nil # invalidate cached color components
+    end
+
+    # Check if the circle contains the given point. Compares squared distance
+    # to squared radius to skip the square root on this per-event hit path. A
+    # negative radius (reachable via the unguarded runtime setter) contains
+    # nothing, matching the old `sqrt(...) <= @radius` behavior the squared form
+    # would otherwise lose.
     def contains?(x, y)
-      Math.sqrt((x - @x)**2 + (y - @y)**2) <= @radius
+      return false if @radius.negative?
+      x, y = _unrotate(x, y) if @rotate != 0
+      dx = x - @x
+      dy = y - @y
+      dx * dx + dy * dy <= @radius * @radius
     end
 
-    def self.draw(opts = {})
+    # Render a circle without creating an instance
+    def self.render(x: 0, y: 0, radius: 50, sectors: 30, rotate: 0,
+                    rx: nil, ry: nil, color: nil, colour: nil, opacity: nil,
+                    fill: true, stroke_width: 0, stroke_color: nil, stroke_colour: nil)
+      fill_input = color || colour
+      explicit_stroke = stroke_color || stroke_colour
+      stroke_input = explicit_stroke || fill_input
+      # Reject a per-vertex stroke color, matching the instance setter — circles
+      # have a single stroke color. Only check when the stroke is drawn or an
+      # explicit stroke color was given, so an invalid one still raises.
+      if (stroke_width > 0 || !explicit_stroke.nil?) && !stroke_input.nil? &&
+         Color.set(stroke_input).is_a?(Color::Set)
+        raise ArgumentError, "`#{self}` does not support per-vertex stroke colors; pass a single color"
+      end
+
       Window.render_ready_check
+      # Resolve the fill color once (as Quad#draw_immediate does). The common
+      # case — a single Color with scalar opacity — reads the resolved
+      # channels directly; only a `Color::Set` or per-vertex opacity array
+      # pays for the flattened array (and gets the arity errors it raises).
+      # `for_render` returns a shared cached instance — read-only here.
+      resolved = Color.for_render(fill_input.nil? ? 'white' : fill_input)
+      uniform = !resolved.is_a?(Color::Set) && !opacity.is_a?(Array)
+      c = uniform ? nil : Renderable.flatten_resolved_color(resolved, 1, opacity, label: self)
 
-      ext_draw([
-                 opts[:x], opts[:y], opts[:radius], opts[:sectors],
-                 opts[:color][0], opts[:color][1], opts[:color][2], opts[:color][3]
-               ])
+      if rotate != 0
+        cx = rx || x
+        cy = ry || y
+        rad = rotate * Math::PI / 180.0
+        sa = Math.sin(rad); ca = Math.cos(rad)
+        dx = x - cx; dy = y - cy
+        x = dx * ca - dy * sa + cx
+        y = dx * sa + dy * ca + cy
+      end
+
+      if fill
+        if uniform
+          Ext.draw_circle(x, y, radius, sectors,
+                          resolved.r, resolved.g, resolved.b, opacity || resolved.a)
+        else
+          Ext.draw_circle(x, y, radius, sectors, c[0], c[1], c[2], c[3])
+        end
+      end
+      # Resolve the stroke color only when actually stroking.
+      if stroke_width > 0
+        sc = Renderable.resolve_single_color(stroke_input) || Color.new('white')
+        sc = Color.new(sc)
+        sc.opacity = opacity if opacity
+        Ext.stroke_circle(x, y, radius, sectors, stroke_width, sc.r, sc.g, sc.b, sc.a)
+      end
     end
 
     private
 
+    # Circle is center-anchored, so shift the alignment resolver's bounding-box
+    # top-left result by the radius to land on the center.
+    def _alignment_anchor_dx
+      @radius
+    end
+
+    def _alignment_anchor_dy
+      @radius
+    end
+
     def render
-      self.class.ext_draw([
-                            @x, @y, @radius, @sectors,
-                            @color.r, @color.g, @color.b, @color.a
-                          ])
+      _resolve_alignment
+      ensure_cc
+      ensure_scc if @stroke_width && @stroke_width > 0
+
+      x = @x; y = @y
+
+      if @rotate != 0
+        cx = rx; cy = ry
+        rad = @rotate * Math::PI / 180.0
+        sa = Math.sin(rad); ca = Math.cos(rad)
+        dx = x - cx; dy = y - cy
+        x = dx * ca - dy * sa + cx
+        y = dx * sa + dy * ca + cy
+      end
+
+      if @fill
+        cc = @_cc
+        Ext.draw_circle(x, y, @radius, @sectors, cc[0], cc[1], cc[2], cc[3])
+      end
+
+      if @stroke_width && @stroke_width > 0
+        scc = @_stroke_cc
+        Ext.stroke_circle(x, y, @radius, @sectors, @stroke_width, scc[0], scc[1], scc[2], scc[3])
+      end
+    end
+
+    # Scene-graph draw hook (see Renderable#_render_scene). Circle's `render` is
+    # already zero-arg, so the hook is the same method under the scene name.
+    alias_method :_render_scene, :render
+    public :_render_scene
+
+    # Build/rebuild flat color cache for the native extension
+    def ensure_cc
+      if @_cc.nil? || @_cc[0] != @color.r || @_cc[1] != @color.g || @_cc[2] != @color.b || @_cc[3] != @color.a
+        @_cc = [@color.r, @color.g, @color.b, @color.a]
+      end
+    end
+
+    # Build/rebuild flat stroke color cache for the native extension
+    def ensure_scc
+      c = @stroke_color
+      if @_stroke_cc.nil? || @_stroke_cc[0] != c.r || @_stroke_cc[1] != c.g || @_stroke_cc[2] != c.b || @_stroke_cc[3] != c.a
+        @_stroke_cc = [c.r, c.g, c.b, c.a]
+      end
     end
   end
 end

data/lib/ruby2d/cli/browser.rb

@@ -0,0 +1,314 @@
+require 'io/console'
+require_relative 'colorize'
+
+module Ruby2D
+  module CLI
+    # Generic interactive arrow-key TUI for browsing a list of items. Used by
+    # both `ruby2d examples` and `ruby2d usage`. Items are hashes with at least
+    # `:title` (shown in the list) and `:description` (shown beneath the list).
+    module Browser
+
+      RED   = "\e[38;2;246;60;56m"
+      RESET = "\e[0m"
+      BOLD  = "\e[1m"
+      DIM   = "\e[2m"
+
+      # Native-Windows Ruby (RubyInstaller) needs its own input handling: on some
+      # builds `IO.console.raw` doesn't drop line/echo input, and even in raw
+      # mode the console won't emit arrow keys as bytes unless virtual-terminal
+      # input is on. `WinConsole` sets both directly; `read_key` then parses the
+      # `\e[A`-style sequences that result. POSIX terminals are untouched.
+      WINDOWS = Gem.win_platform?
+
+      # Drives the Win32 console input mode through `SetConsoleMode`, because
+      # native-Windows Ruby's `io/console` `raw` is unreliable here (confirmed on
+      # `aarch64-mingw-ucrt`: `raw` left LINE/ECHO input enabled). Enabling
+      # `VIRTUAL_TERMINAL_INPUT` is what makes arrow keys arrive as `\e[A`
+      # sequences instead of being swallowed. All Fiddle use is lazy and
+      # failure-tolerant: any problem returns nil and the caller falls back to
+      # the plain `io/console` path.
+      module WinConsole
+        STD_INPUT_HANDLE = -10
+        PROCESSED_INPUT  = 0x0001
+        LINE_INPUT       = 0x0002
+        ECHO_INPUT       = 0x0004
+        VT_INPUT         = 0x0200
+
+        # Lazily resolve the three kernel32 calls we need; memoize the result
+        # (nil if Fiddle or the console API is unavailable).
+        def self.api
+          unless @resolved
+            @resolved = true
+            @api =
+              begin
+                require 'fiddle'
+                k32 = Fiddle.dlopen('kernel32')
+                {
+                  get_handle: Fiddle::Function.new(k32['GetStdHandle'],   [Fiddle::TYPE_LONG], Fiddle::TYPE_VOIDP),
+                  get_mode:   Fiddle::Function.new(k32['GetConsoleMode'],  [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT),
+                  set_mode:   Fiddle::Function.new(k32['SetConsoleMode'],  [Fiddle::TYPE_VOIDP, Fiddle::TYPE_LONG], Fiddle::TYPE_INT)
+                }
+              rescue LoadError, StandardError
+                nil
+              end
+          end
+          @api
+        end
+
+        # Switch the console to raw + virtual-terminal input. Returns the prior
+        # mode (to hand back to `restore`), or nil when there's no console to set
+        # (Fiddle missing, stdin redirected, `GetConsoleMode` failed).
+        def self.enable_raw
+          fns = api or return nil
+          handle = fns[:get_handle].call(STD_INPUT_HANDLE)
+          buf = Fiddle::Pointer.malloc(Fiddle::SIZEOF_INT, Fiddle::RUBY_FREE)
+          return nil if fns[:get_mode].call(handle, buf) == 0
+          prev = buf[0, Fiddle::SIZEOF_INT].unpack1('L')
+          fns[:set_mode].call(handle, (prev & ~(LINE_INPUT | ECHO_INPUT | PROCESSED_INPUT)) | VT_INPUT)
+          prev
+        end
+
+        # Re-apply raw + VT without disturbing the saved prior mode — used after
+        # a child example returns, in case it left the shared console mode
+        # changed.
+        def self.reassert_raw
+          enable_raw
+        end
+
+        def self.restore(prev)
+          return if prev.nil?
+          fns = api or return
+          fns[:set_mode].call(fns[:get_handle].call(STD_INPUT_HANDLE), prev)
+        end
+      end
+
+      # Run the interactive browser.
+      #   list           array of item hashes with :title and :description
+      #   label          header label, e.g. 'Examples' or 'Usage Guide'
+      #   footer_action  verb after 'Enter to', e.g. 'run' or 'view'
+      #   fallback       called when there is no usable TTY
+      #   block          invoked with the selected item when Enter is pressed
+      def self.run(list:, label:, footer_action:, fallback: nil, &on_select)
+        return if list.empty?
+
+        unless $stdout.tty? && IO.console
+          fallback&.call
+          return
+        end
+
+        selected = 0
+        prev_mode = nil
+        begin
+          enter_alt_screen
+          # On Windows, take over the console mode ourselves; `managed` is true
+          # only when that succeeded (otherwise fall back to `io/console` raw).
+          prev_mode = WinConsole.enable_raw if WINDOWS
+          managed = !prev_mode.nil?
+          # Managed mode reads IO.console directly; binmode stops Windows CRLF
+          # read-translation from stalling Enter (it holds the CR of CR+LF
+          # waiting to see whether an LF follows).
+          IO.console.binmode if managed
+          loop do
+            render(list, selected, label, footer_action)
+            case read_key(managed)
+            when :up    then selected = (selected - 1) % list.length
+            when :down  then selected = (selected + 1) % list.length
+            when :pgup  then selected = [selected - 10, 0].max
+            when :pgdn  then selected = [selected + 10, list.length - 1].min
+            when :home  then selected = 0
+            when :last  then selected = list.length - 1
+            when :enter
+              print "\e[2J\e[H\e[?25h\e[?1000l\e[?1006l"
+              on_select.call(list[selected])
+              # The example shared this console; re-assert our mode and drop
+              # anything typed while it ran so stray keys (e.g. a queued Enter)
+              # don't fire actions back in the picker.
+              WinConsole.reassert_raw if managed
+              IO.console.iflush if IO.console.respond_to?(:iflush)
+              print "\e[?25l\e[?1000h\e[?1006h"
+            when :quit
+              break
+            end
+          end
+        ensure
+          WinConsole.restore(prev_mode) if WINDOWS
+          leave_alt_screen
+        end
+      end
+
+      # Enabling mouse-event reporting (1000 + 1006/SGR) stops most terminals
+      # from translating the scroll wheel into arrow keys while the alt screen
+      # is active. Mouse sequences are ignored in `read_key`.
+      def self.enter_alt_screen
+        print "\e[?1049h\e[?25l\e[?1000h\e[?1006h"
+      end
+
+      def self.leave_alt_screen
+        print "\e[?1006l\e[?1000l\e[?1049l\e[?25h"
+      end
+
+      # Block for one keypress and map it to an action.
+      # `managed` is true when `WinConsole` already put the console in raw + VT
+      # input mode, so we read `IO.console` directly. Otherwise (POSIX, or
+      # Windows without a settable console) we go through `io/console`'s `raw`.
+      def self.read_key(managed = false)
+        if managed
+          read_console(IO.console)
+        else
+          IO.console.raw { |io| read_console(io) }
+        end
+      end
+
+      # Classify one keypress from an already-raw stream. Windows and POSIX share
+      # the single-byte keys and diverge only on how escape sequences are read:
+      # POSIX's `read_escape_sequence` uses `IO.select`/`read_nonblock` (fine on
+      # a pty), which native-Windows Ruby can't use on a console handle.
+      def self.read_console(io)
+        c = io.getc
+        if    c.nil?                                   then :quit
+        elsif WINDOWS && c == "\n"                     then nil  # LF half of CR+LF; the CR already fired :enter
+        elsif (action = classify_char(c))             then action
+        elsif WINDOWS && (c == "\x00" || c == "\xE0") then classify_scancode(io.getc)
+        elsif c == "\e"
+          classify_escape(WINDOWS ? read_escape_windows(io) : read_escape_sequence(io))
+        end
+      end
+
+      # Single-byte keys, identical on every platform.
+      def self.classify_char(c)
+        case c
+        when "\r", "\n"               then :enter
+        when 'q', 'Q', "\x03", "\x04" then :quit
+        when 'k'                      then :up
+        when 'j'                      then :down
+        when 'g'                      then :home
+        when 'G'                      then :last
+        end
+      end
+
+      # Legacy (non-VT) Windows consoles report arrows and navigation keys as two
+      # bytes: a `\x00` or `\xE0` prefix, consumed by `read_console`, then the
+      # scan code mapped here. With `VIRTUAL_TERMINAL_INPUT` on they arrive as
+      # `\e[A` sequences instead, but this keeps the fallback working too.
+      # (Left/Right are unused and fall through.)
+      def self.classify_scancode(c)
+        case c
+        when 'H' then :up    # 0x48
+        when 'P' then :down  # 0x50
+        when 'I' then :pgup  # 0x49
+        when 'Q' then :pgdn  # 0x51
+        when 'G' then :home  # 0x47
+        when 'O' then :last  # 0x4F (End)
+        end
+      end
+
+      # Read a CSI/SS3 escape sequence on Windows without `IO.select` or
+      # `read_nonblock` (unsupported on a console handle). An arrow key's whole
+      # sequence lands in the input buffer at once, so a blocking `getc` returns
+      # each following byte right away. A lone ESC has no follow-on byte and
+      # would block here, so on Windows we quit with `q`, not ESC. If the byte
+      # after ESC isn't a CSI/SS3 introducer we stop at once, swallowing nothing
+      # extra.
+      def self.read_escape_windows(io)
+        seq = io.getc.to_s
+        return seq unless seq == '[' || seq == 'O'
+        14.times do
+          c = io.getc
+          break if c.nil?
+          seq << c
+          break if c.match?(/[A-Za-z~]/)
+        end
+        seq
+      end
+
+      # Read one CSI/SS3 escape sequence after the leading ESC. Waits briefly
+      # for each byte so chunked delivery doesn't cut us short, and stops at
+      # the first byte in the CSI final-byte range (0x40-0x7E).
+      def self.read_escape_sequence(io)
+        seq = ''
+        32.times do
+          break unless IO.select([io], nil, nil, 0.01)
+          c = io.read_nonblock(1, exception: false)
+          break if c.nil? || c == :wait_readable
+          seq << c
+          break if seq.length >= 2 && c.match?(/[A-Za-z~]/)
+        end
+        seq
+      end
+
+      def self.classify_escape(seq)
+        return nil if seq.start_with?('[<') && seq.end_with?('M', 'm')  # SGR mouse
+        return nil if seq.start_with?('[M')                              # X10 mouse
+        case seq
+        when ''                       then :quit  # bare ESC
+        when '[A', 'OA'               then :up
+        when '[B', 'OB'               then :down
+        when '[H', '[1~', '[7~', 'OH' then :home
+        when '[F', '[4~', '[8~', 'OF' then :last
+        when '[5~'                    then :pgup
+        when '[6~'                    then :pgdn
+        end
+      end
+
+      def self.wrap(text, width)
+        return [] if text.nil? || text.empty? || width <= 0
+        lines = []
+        current = ''
+        text.split(' ').each do |word|
+          if current.empty?
+            current = word
+          elsif current.length + 1 + word.length <= width
+            current << ' ' << word
+          else
+            lines << current
+            current = word
+          end
+        end
+        lines << current unless current.empty?
+        lines
+      end
+
+      def self.render(list, selected, label, footer_action)
+        rows, cols = IO.console.winsize
+        rows = 24 if rows.nil? || rows < 10
+        cols = 80 if cols.nil? || cols < 40
+
+        print "\e[2J\e[H"
+
+        title = "  #{'Ruby 2D'.ruby2d_red.bold} — #{label} #{"(#{selected + 1}/#{list.length})".dim}"
+        footer = "  #{"↑/↓ navigate · Enter to #{footer_action} · q to quit".dim}"
+        desc_height = 3
+        desc_lines = wrap(list[selected][:description], cols - 4)[0, desc_height]
+
+        # 1 (blank) + title + 1 + viewport + 1 + desc_height + 1 + footer = rows
+        viewport = rows - (5 + desc_height)
+        viewport = [viewport, 5].max
+        viewport = [viewport, list.length].min
+
+        start = [selected - viewport / 2, 0].max
+        start = [start, list.length - viewport].min
+        start = 0 if start.negative?
+
+        width = list.length.to_s.length
+
+        puts
+        puts title
+        puts
+        viewport.times do |i|
+          idx = start + i
+          item = list[idx]
+          num = (idx + 1).to_s.rjust(width)
+          if idx == selected
+            puts "  #{RED}◆ #{BOLD}#{num}#{RESET}  #{RED}#{BOLD}#{item[:title]}#{RESET}"
+          else
+            puts "    #{DIM}#{num}#{RESET}  #{item[:title]}"
+          end
+        end
+        puts
+        desc_height.times { |i| puts "  #{DIM}#{desc_lines[i] || ''}#{RESET}" }
+        puts
+        print footer
+      end
+    end
+  end
+end