ruby2d 0.12.1 → 1.0.0

data/lib/ruby2d/sprite_sheet.rb

@@ -0,0 +1,64 @@
+# Ruby2D::SpriteSheet
+
+module Ruby2D
+  # A texture atlas / sprite sheet loaded from a Sparrow XML or TexturePacker
+  # JSON file. Owns one shared `Image` so every `Sprite` built against the
+  # sheet draws from the same GPU texture.
+  class SpriteSheet
+    attr_reader :path, :image_path, :texture
+
+    # Load a sprite sheet. `path` is the atlas file (`.xml` or `.json`); the
+    # texture image referenced inside the atlas is resolved relative to that
+    # file's directory.
+    def initialize(path)
+      @path = path.to_s
+      raise Error, "SpriteSheet file `#{@path}` not found" unless File.exist?(@path)
+
+      atlas = AtlasParser.parse_file(@path)
+      @frames = atlas[:frames] || {}
+
+      atlas_image = atlas[:image_path]
+      raise Error, "SpriteSheet `#{@path}` does not specify an image path" unless atlas_image
+
+      @image_path = resolve_image_path(@path, atlas_image)
+      @texture = Image.new(@image_path, add: false)
+    end
+
+    # All frame names, in declaration order
+    def frame_names
+      @frames.keys
+    end
+
+    # Look up a frame's region by name. Always returns at least
+    # `{ x:, y:, width:, height: }`. When the atlas carries trim or
+    # rotation metadata, the hash also includes `source_width`,
+    # `source_height`, `trim_x`, `trim_y`, and/or `rotated: true`.
+    # Returns `nil` if no such frame exists.
+    def frame(name)
+      @frames[name.to_s]
+    end
+    alias [] frame
+
+    # Whether the sheet contains a frame with the given name
+    def frame?(name)
+      @frames.key?(name.to_s)
+    end
+
+    private
+
+    def resolve_image_path(atlas_path, image_name)
+      # Prefer the texture sitting next to the atlas file — the documented
+      # contract — so a like-named file in the process's working directory
+      # can't shadow it. Only fall back to `image_name` as given (an absolute
+      # path, or one relative to the working directory) when no atlas-relative
+      # file exists.
+      atlas_relative = File.join(File.dirname(atlas_path), image_name)
+      return atlas_relative if File.exist?(atlas_relative)
+
+      image_name
+    end
+  end
+
+  # Naming alias — both names refer to the same class.
+  TextureAtlas = SpriteSheet
+end

data/lib/ruby2d/square.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 # Ruby2D::Square
 
 module Ruby2D
@@ -7,18 +5,23 @@ module Ruby2D
   class Square < Rectangle
     attr_reader :size
 
-    # Create an square
-    # @param [Numeric] x
-    # @param [Numeric] y
-    # @param [Numeric] size is width and height
-    # @param [Numeric] z
-    # @param [String, Array] color A single colour or an array of exactly 4 colours
-    # @param [Numeric] opacity Opacity of the image when rendering
-    # @raise [ArgumentError] if an array of colours does not have 4 entries
-    def initialize(x: 0, y: 0, size: 100, z: 0, color: nil, colour: nil, opacity: nil)
+    # Create a square
+    def initialize(x: 0, y: 0, size: 100, z: 0, 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)
+      _validate_dimensions(size: size)
       @size = size
-      super(x: x, y: y, width: size, height: size, z: z,
-            color: color, colour: colour, opacity: opacity)
+      super(x: x, y: y, width: size, height: size, z: z, rotate: rotate,
+            rx: rx, ry: ry,
+            color: color, colour: colour, opacity: opacity,
+            fill: fill, stroke_width: stroke_width,
+            stroke_color: stroke_color, stroke_colour: stroke_colour,
+            add: add, visible: visible,
+            padding: padding, padding_top: padding_top, padding_right: padding_right,
+            padding_bottom: padding_bottom, padding_left: padding_left)
     end
 
     # Set the size of the square
@@ -26,10 +29,19 @@ module Ruby2D
       self.width = self.height = @size = size
     end
 
-    def self.draw(x:, y:, size:, color:)
-      super(x: x, y: y,
-            width: size, height: size,
-            color: color)
+    # Render a square without creating an instance
+    # Render a square without creating an instance. Calls the positional
+    # internal directly rather than `super` — see `Quad.draw_immediate`.
+    def self.render(x: 0, y: 0, size: 100, rotate: 0,
+                    rx: nil, ry: nil, color: nil, colour: nil, opacity: nil,
+                    fill: true, stroke_width: 0, stroke_color: nil, stroke_colour: nil)
+      draw_immediate(x, y,
+                     x + size, y,
+                     x + size, y + size,
+                     x, y + size,
+                     rotate, rx || x + size / 2.0, ry || y + size / 2.0,
+                     color || colour, opacity, fill, stroke_width,
+                     stroke_color || stroke_colour)
     end
 
     # Make the inherited width and height attribute accessors private

data/lib/ruby2d/text.rb

@@ -1,104 +1,235 @@
-# frozen_string_literal: true
-
 # Ruby2D::Text
 
 module Ruby2D
-  # Text string drawn using the specified font and size
+  # A text string drawn with a specified font and size
   class Text
     include Renderable
 
-    attr_reader :text, :size
-    attr_accessor :x, :y, :rotate, :data
-
-    # Create a text string
-    # @param text The text to show
-    # @param [Numeric] size The font +size+
-    # @param [String] font Path to font file to use to draw the text
-    # @param [String] style Font style
-    # @param [Numeric] x
-    # @param [Numeric] y
-    # @param [Numeric] z
-    # @param [Numeric] rotate Angle, default is 0
-    # @param [Numeric] color or +colour+ Colour the text when rendering
-    # @param [Numeric] opacity Opacity of the image when rendering
-    # @param [true, false] show If +true+ the Text is added to +Window+ automatically.
-    def initialize(text, size: 20, style: nil, font: Font.default,
+    # Font style name → TTF style flag bit (mirrors SDL3_ttf's `TTF_STYLE_*`).
+    STYLE_FLAGS = {
+      normal: 0, bold: 1, italic: 2, underline: 4, strikethrough: 8
+    }.freeze
+
+    # Frozen NUL string for the content scan below. A bare `"\0"` literal would
+    # allocate a throwaway string on every `content=` — 360×/frame under a
+    # dynamic-text HUD — since the library doesn't enable frozen string literals.
+    NUL = "\0".freeze
+
+    attr_reader :content, :size, :font, :style
+    attr_accessor :rotate
+
+    # Set the x position. Pass a symbol (`:left`, `:center`, `:right`) to
+    # set alignment intent — resolved at draw time against the window.
+    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. Pass a symbol (`:top`, `:center`, `:bottom`) to
+    # set alignment intent — resolved at draw time against the window.
+    def y=(value)
+      return self.y_align = value if value.is_a?(Symbol)
+      @y_align = nil unless @_resolving_alignment
+      @y = value
+    end
+
+    # Get the rotation center x coordinate
+    def rx
+      @_user_rx.nil? ? @x + @width / 2.0 : @_user_rx
+    end
+
+    # Get the rotation center y coordinate
+    def ry
+      @_user_ry.nil? ? @y + @height / 2.0 : @_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
+
+    # Create a text object
+    def initialize(content, size: 20, style: nil, font: Font.default,
                    x: 0, y: 0, z: 0,
-                   rotate: 0, color: nil, colour: nil,
-                   opacity: nil, show: true)
+                   rotate: 0, rx: nil, ry: nil, color: nil, colour: nil,
+                   opacity: 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)
       @x = x
       @y = y
       @z = z
-      @text = text.to_s
-      @size = size
+      @content = validate_content(content).dup.freeze
+      @size = validate_size(size)
       @rotate = rotate
+      @_user_rx = rx
+      @_user_ry = ry
       @style = style
-      self.color = color || colour || 'white'
-      self.color.opacity = opacity unless opacity.nil?
-      @font_path = font
-      @texture = nil
-      create_font
-      create_texture
+      @style_flags = compute_style_flags(style)
+      @font = normalize_font_path(font)
 
-      add if show
-    end
+      self.color = color || colour || 'white'
+      self.opacity = opacity unless opacity.nil?
+      Ext.text_create(self)
 
-    # Returns the path of the font as a string
-    def font
-      @font_path
+      @visible = visible
+      self.add if add
     end
 
-    def text=(msg)
-      @text = msg.to_s
-      create_texture
+    # Set the text content. A no-op when the content is unchanged — rebuilding
+    # the texture is the expensive part, and per-frame assignments of the same
+    # string (HUDs, score counters) are common. Validation still runs first so
+    # invalid input raises regardless; the frozen copy is only allocated when
+    # the content actually changes, so a same-string per-frame assignment costs
+    # a coerce and a compare, not a string copy.
+    def content=(msg)
+      str = validate_content(msg)
+      return if str == @content
+
+      @content = str.dup.freeze
+      Ext.text_create(self)
     end
 
+    # Set the font size. A no-op when unchanged, like `content=` — rebuilding
+    # the texture is the expensive part, and per-frame assignments of the same
+    # value are common.
     def size=(size)
+      size = validate_size(size)
+      return if size == @size
+
       @size = size
-      create_font
-      create_texture
+      Ext.text_create(self)
     end
 
-    def draw(x:, y:, color:, rotate:)
-      Window.render_ready_check
+    # Set the font style. Accepts `:normal`, `:bold`, `:italic`, `:underline`,
+    # `:strikethrough`, an array combining them (e.g. `[:bold, :italic]`), or
+    # `nil` for normal. Re-renders the text; a no-op when the computed style
+    # flags are unchanged (`:bold` and `[:bold]` are the same style).
+    def style=(style)
+      flags = compute_style_flags(style)
+      @style = style
+      return if flags == @style_flags
+
+      @style_flags = flags
+      Ext.text_create(self)
+    end
 
-      x ||= @rotate
-      color ||= [1.0, 1.0, 1.0, 1.0]
+    # Set the font, given a path to a `.ttf` file. Re-renders the text; a
+    # no-op when the resolved path is unchanged.
+    def font=(font)
+      font = normalize_font_path(font)
+      return if font == @font
 
-      render(x: x, y: y, color: Color.new(color), rotate: rotate)
+      @font = font
+      Ext.text_create(self)
     end
 
-    class << self
-      # Create a texture for the specified text
-      # @param text The text to show
-      # @param [Numeric] size The font +size+
-      # @param [String] font Path to font file to use to draw the text
-      # @param [String] style Font style
-      def create_texture(text, size: 20, style: nil, font: Font.default)
-        font = Font.load(font, size, style)
-        Texture.new(*Text.ext_load_text(font.ttf_font, text))
+    # Render the text. Called with overrides for one-shot rendering inside a
+    # render block; with no arguments it draws the same frame the scene graph
+    # does (delegating to `_render_scene`).
+    def render(x: nil, y: nil, rotate: nil, color: nil, colour: nil, opacity: nil)
+      if x.nil? && y.nil? && rotate.nil? && color.nil? && colour.nil? && opacity.nil?
+        return _render_scene
+      end
+
+      Window.render_ready_check
+
+      saved_x, saved_y = @x, @y
+      saved_rotate = @rotate
+      saved_color = @color
+
+      @x = x if x
+      @y = y if y
+      @rotate = rotate if rotate
+
+      c = color || colour
+      if c || opacity
+        @color = c ? Color.new(c) : Color.new(saved_color)
+        @color.opacity = opacity if opacity
+      end
+
+      begin
+        Ext.text_draw(self, rx, ry)
+      ensure
+        @x, @y = saved_x, saved_y
+        @rotate = saved_rotate
+        @color = saved_color
       end
     end
 
     private
 
-    def render(x: @x, y: @y, color: @color, rotate: @rotate)
-      vertices = Vertices.new(x, y, @width, @height, rotate)
+    # Scene-graph draw hook (see Renderable#_render_scene): `render` with no
+    # overrides, minus its keyword handling — a zero-arg call into a
+    # keyword-heavy `render` still pays microseconds of keyword setup on wasm
+    # mruby.
+    def _render_scene
+      _resolve_alignment
+      Ext.text_draw(self, rx, ry)
+    end
+    public :_render_scene
 
-      @texture.draw(
-        vertices.coordinates, vertices.texture_coordinates, color
-      )
+    # Coerce a font argument to a usable path: stringify, expand a leading `~`
+    # on CRuby, and raise a clear error if the file is missing.
+    def normalize_font_path(font)
+      font = font.to_s
+      font = File.expand_path(font) if RUBY_ENGINE == 'ruby' && font.start_with?('~')
+      raise Error, "Font file `#{font}` not found" unless File.exist?(font)
+
+      font
     end
 
-    def create_font
-      @font = Font.load(@font_path, @size, @style)
+    # Ensure the font size is a positive number, raising a clear error instead
+    # of letting an invalid value reach the native font loader (where it would
+    # surface as a cryptic `TypeError`/`TTF_OpenFont failed`). Coerce to the same
+    # integer the native renderer uses (truncation toward zero) so the `size`
+    # reader equals the size actually rendered — e.g. `size: 10.9` renders and
+    # reports 10, not 10.9.
+    def validate_size(size)
+      unless size.is_a?(Numeric) && size > 0
+        raise Error, "Text size must be a positive number, got #{size.inspect}"
+      end
+
+      size.to_i
+    end
+
+    # Coerce content to a string and reject embedded NUL bytes. NUL has no glyph
+    # and SDL_ttf cannot render it — passing one to the native rasterizer
+    # hangs/over-allocates on U+0000 — while silently truncating at the NUL (the
+    # historical behavior) hides the caller's corrupt data. So fail loudly.
+    # Returns the coerced string as-is (which may be the caller's own object for
+    # a String argument); callers that store it own the `dup.freeze`, so the
+    # cheap no-op comparison in `content=` runs before anything is allocated.
+    # Freezing at the store site stops in-place mutation (`text.content << 'x'`)
+    # from desyncing the native surface, which only rerasterizes via `content=`.
+    def validate_content(content)
+      str = content.to_s
+      raise Error, 'Text content cannot contain NUL (\0) bytes' if str.include?(NUL)
+
+      str
     end
 
-    def create_texture
-      @texture&.delete
-      @texture = Texture.new(*Text.ext_load_text(@font.ttf_font, @text))
-      @width = @texture.width
-      @height = @texture.height
+    # Combine a style (nil, a symbol, a string, or an array of them) into the
+    # integer TTF style flags the native renderer expects. Raises a clear error
+    # on an unknown style name rather than silently ignoring it.
+    def compute_style_flags(style)
+      return 0 if style.nil?
+
+      Array(style).reduce(0) do |flags, s|
+        bit = STYLE_FLAGS[s.to_s.to_sym]
+        if bit.nil?
+          raise Error,
+                "Unknown text style #{s.inspect}; expected one of #{STYLE_FLAGS.keys}"
+        end
+        flags | bit
+      end
     end
   end
 end