ruby2d 0.11.3 → 0.12.0

data/lib/ruby2d/text.rb

@@ -1,27 +1,46 @@
+# frozen_string_literal: true
+
 # Ruby2D::Text
 
 module Ruby2D
+  # Text string drawn using the specified font and size
   class Text
     include Renderable
 
     attr_reader :text, :size
     attr_accessor :x, :y, :rotate, :data
 
-    def initialize(text, opts = {})
-      @x = opts[:x] || 0
-      @y = opts[:y] || 0
-      @z = opts[:z] || 0
+    # 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,
+                   x: 0, y: 0, z: 0,
+                   rotate: 0, color: nil, colour: nil,
+                   opacity: nil, show: true)
+      @x = x
+      @y = y
+      @z = z
       @text = text.to_s
-      @size = opts[:size] || 20
-      @rotate = opts[:rotate] || 0
-      @style = opts[:style]
-      self.color = opts[:color] || 'white'
-      self.color.opacity = opts[:opacity] if opts[:opacity]
-      @font_path = opts[:font] || Font.default
+      @size = size
+      @rotate = rotate
+      @style = style
+      self.color = color || colour || 'white'
+      self.color.opacity = opacity unless opacity.nil?
+      @font_path = font
+      @texture = nil
       create_font
       create_texture
 
-      unless opts[:show] == false then add end
+      add if show
     end
 
     # Returns the path of the font as a string
@@ -40,15 +59,25 @@ module Ruby2D
       create_texture
     end
 
-    def draw(opts = {})
+    def draw(x:, y:, color:, rotate:)
       Window.render_ready_check
 
-      opts[:rotate] = opts[:rotate] || @rotate
-      unless opts[:color]
-        opts[:color] = [1.0, 1.0, 1.0, 1.0]
-      end
+      x ||= @rotate
+      color ||= [1.0, 1.0, 1.0, 1.0]
 
-      render(x: opts[:x], y: opts[:y], color: Color.new(opts[:color]), rotate: opts[:rotate])
+      render(x: x, y: y, color: Color.new(color), rotate: rotate)
+    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))
+      end
     end
 
     private
@@ -66,8 +95,7 @@ module Ruby2D
     end
 
     def create_texture
-      if @texture then @texture.delete end
-
+      @texture&.delete
       @texture = Texture.new(*Text.ext_load_text(@font.ttf_font, @text))
       @width = @texture.width
       @height = @texture.height

data/lib/ruby2d/texture.rb

@@ -1,9 +1,15 @@
+# frozen_string_literal: true
+
 # Ruby2D::Texture
 
 module Ruby2D
+  # This internal class is used to hold raw pixel data which in turn is used to
+  # render textures via openGL rendering code.
   class Texture
     attr_reader :width, :height, :texture_id
 
+    WHITE_OPAQUE_AR = [1.0, 1.0, 1.0, 1.0].freeze
+
     def initialize(pixel_data, width, height)
       @pixel_data = pixel_data
       @width = width
@@ -11,13 +17,17 @@ module Ruby2D
       @texture_id = 0
     end
 
-    def draw(coordinates, texture_coordinates, color)
-      if @texture_id == 0
+    # Draw the texture
+    # @param coordinates [Array(x1, y1, x2, y2, x3, y3, x4, y4)] Destination coordinates
+    # @param texture_coordinates [Array(tx1, ty1, tx2, ty2, tx3, ty3, tx1, ty3)] Source (texture) coordinates
+    # @param color [Ruby2D::Color] Tint/blend the texture when it's drawn
+    def draw(coordinates, texture_coordinates, color = nil)
+      if @texture_id.zero?
         @texture_id = ext_create(@pixel_data, @width, @height)
         @pixel_data = nil
       end
 
-      color = [color.r, color.g, color.b, color.a]
+      color = color.nil? ? WHITE_OPAQUE_AR : [color.r, color.g, color.b, color.a]
       ext_draw(coordinates, texture_coordinates, color, @texture_id)
     end
 

data/lib/ruby2d/tileset.rb

@@ -1,50 +1,95 @@
+# frozen_string_literal: true
+
 # Ruby2D::Tileset
 
 module Ruby2D
+  # Tilesets are images containing multiple unique tiles. These tiles can be drawn to the
+  # screen multiple times in interesting combinations to produce things like backgrounds
+  # or draw larger objects.
   class Tileset
     DEFAULT_COLOR = Color.new([1.0, 1.0, 1.0, 1.0])
 
     include Renderable
 
-    def initialize(path, opts = {})
-      @path = path
+    # Setup a Tileset with an image.
+    # @param path [#to_s] The location of the file to load as an image.
+    # @param width [Numeric] The +width+ of image, or default is width from image file
+    # @param height [Numeric] The +height+ of image, or default is height from image file
+    # @param z [Numeric]
+    # @param padding [Numeric]
+    # @param spacing [Numeric]
+    # @param tile_width [Numeric] Width of each tile in pixels
+    # @param tile_height [Numeric] Height of each tile in pixels
+    # @param scale [Numeric] Default is 1
+    # @param show [Boolean] If +true+ the image is added to +Window+ automatically.
+    def initialize(path, tile_width: 32, tile_height: 32, atlas: nil,
+                   width: nil, height: nil, z: 0,
+                   padding: 0, spacing: 0,
+                   scale: 1, show: true)
+      @path = path.to_s
 
       # Initialize the tileset texture
-      @texture = Texture.new(*Image.load_image(@path))
-      @width = opts[:width] || @texture.width
-      @height = opts[:height] || @texture.height
-      @z = opts[:z] || 0
+      # Consider input pixmap atlas if supplied to load image file
+      @texture = Image.load_image_as_texture @path, atlas: atlas
+      @width = width || @texture.width
+      @height = height || @texture.height
+      @z = z
 
       @tiles = []
-      @defined_tiles = {}
-      @padding = opts[:padding] || 0
-      @spacing = opts[:spacing] || 0
-      @tile_width = opts[:tile_width]
-      @tile_height = opts[:tile_height]
-      @scale = opts[:scale] || 1
-
-      unless opts[:show] == false then add end
+      @tile_definitions = {}
+      @padding = padding
+      @spacing = spacing
+      @tile_width = tile_width
+      @tile_height = tile_height
+      @scale = scale
+
+      _calculate_scaled_sizes
+
+      add if show
     end
 
+    # Define and name a tile in the tileset image by its position. The actual tiles
+    # to be drawn are declared using {#set_tile}
+    #
+    # @param name [String] A unique name for the tile in the tileset
+    # @param x [Numeric] Column position of the tile
+    # @param y [Numeric] Row position of the tile
+    # @param rotate [Numeric] Angle of the title when drawn, default is 0
+    # @param flip [nil, :vertical, :horizontal, :both] Direction to flip the tile if desired
     def define_tile(name, x, y, rotate: 0, flip: nil)
-      @defined_tiles[name] = { x: x, y: y , rotate: rotate, flip: flip }
+      @tile_definitions[name] = { x: x, y: y, rotate: rotate, flip: flip }
     end
 
+    # Select and "stamp" or set/place a tile to be drawn
+    # @param name [String] The name of the tile defined using +#define_tile+
+    # @param coordinates [Array<{"x", "y" => Numeric}>] one or more +{x:, y:}+ coordinates to draw the tile
     def set_tile(name, coordinates)
-      tile = @defined_tiles.fetch(name)
+      tile_def = @tile_definitions.fetch(name)
+      crop = _calculate_tile_crop(tile_def)
 
       coordinates.each do |coordinate|
+        # Use Vertices object for tile placement so we can use them
+        # directly when drawing the textures instead of making them for
+        # every tile placement for each draw, and re-use the crop from
+        # the tile definition
+        vertices = Vertices.new(
+          coordinate.fetch(:x), coordinate.fetch(:y),
+          @scaled_tile_width, @scaled_tile_height,
+          tile_def.fetch(:rotate),
+          crop: crop,
+          flip: tile_def.fetch(:flip)
+        )
+        # Remember the referenced tile for if we ever want to recalculate
+        # them all due to change to scale etc (currently n/a since
+        # scale is immutable)
         @tiles.push({
-          tile_x: tile.fetch(:x), 
-          tile_y: tile.fetch(:y), 
-          tile_rotate: tile.fetch(:rotate),
-          tile_flip: tile.fetch(:flip),
-          x: coordinate.fetch(:x),
-          y: coordinate.fetch(:y)
-        })
+                      tile_def: tile_def,
+                      vertices: vertices
+                    })
       end
     end
 
+    # Removes all stamped tiles so nothing is drawn.
     def clear_tiles
       @tiles = []
     end
@@ -57,28 +102,36 @@ module Ruby2D
 
     private
 
-    def render
-      scaled_padding = @padding * @scale
-      scaled_spacing = @spacing * @scale
-      scaled_tile_width = @tile_width * @scale
-      scaled_tile_height = @tile_height * @scale
-      scaled_width = @width * @scale
-      scaled_height = @height * @scale
-
-      @tiles.each do |tile|
-        crop = {
-          x: scaled_padding + (tile.fetch(:tile_x) * (scaled_spacing + scaled_tile_width)),
-          y: scaled_padding + (tile.fetch(:tile_y) * (scaled_spacing + scaled_tile_height)),
-          width: scaled_tile_width,
-          height: scaled_tile_height,
-          image_width: scaled_width,
-          image_height: scaled_height,
-        }
-
-        color = defined?(@color) ? @color : DEFAULT_COLOR
-
-        vertices = Vertices.new(tile.fetch(:x), tile.fetch(:y), scaled_tile_width, scaled_tile_height, tile.fetch(:tile_rotate), crop: crop, flip: tile.fetch(:tile_flip))
+    def _calculate_tile_crop(tile_def)
+      # Re-use if crop has already been calculated
+      return tile_def.fetch(:scaled_crop) if tile_def.key?(:scaled_crop)
+
+      # Calculate the crop for each tile definition the first time a tile
+      # is placed/set, so that we can later re-use when placing tiles,
+      # avoiding creating the crop object for every placement.
+      tile_def[:scaled_crop] = {
+        x: @scaled_padding + (tile_def.fetch(:x) * (@scaled_spacing + @scaled_tile_width)),
+        y: @scaled_padding + (tile_def.fetch(:y) * (@scaled_spacing + @scaled_tile_height)),
+        width: @scaled_tile_width,
+        height: @scaled_tile_height,
+        image_width: @scaled_width,
+        image_height: @scaled_height
+      }.freeze
+    end
+
+    def _calculate_scaled_sizes
+      @scaled_padding = @padding * @scale
+      @scaled_spacing = @spacing * @scale
+      @scaled_tile_width = @tile_width * @scale
+      @scaled_tile_height = @tile_height * @scale
+      @scaled_width = @width * @scale
+      @scaled_height = @height * @scale
+    end
 
+    def render
+      color = defined?(@color) ? @color : DEFAULT_COLOR
+      @tiles.each do |placement|
+        vertices = placement.fetch(:vertices)
         @texture.draw(
           vertices.coordinates, vertices.texture_coordinates, color
         )

data/lib/ruby2d/triangle.rb

@@ -1,29 +1,57 @@
+# frozen_string_literal: true
+
 # Ruby2D::Triangle
 
 module Ruby2D
+  # A triangle
   class Triangle
     include Renderable
 
-    attr_accessor :x1, :y1, :c1,
-                  :x2, :y2, :c2,
-                  :x3, :y3, :c3
-
-    def initialize(opts= {})
-      @x1 = opts[:x1] || 50
-      @y1 = opts[:y1] || 0
-      @x2 = opts[:x2] || 100
-      @y2 = opts[:y2] || 100
-      @x3 = opts[:x3] || 0
-      @y3 = opts[:y3] || 100
-      @z  = opts[:z]  || 0
-      self.color = opts[:color] || 'white'
-      self.color.opacity = opts[:opacity] if opts[:opacity]
+    attr_accessor :x1, :y1,
+                  :x2, :y2,
+                  :x3, :y3
+    attr_reader :color
+
+    # Create a triangle
+    # @param x1 [Numeric]
+    # @param y1 [Numeric]
+    # @param x2 [Numeric]
+    # @param y2 [Numeric]
+    # @param x3 [Numeric]
+    # @param y3 [Numeric]
+    # @param z [Numeric]
+    # @param color [String, Array] A single colour or an array of exactly 3 colours
+    # @param opacity [Numeric] Opacity of the image when rendering
+    # @raise [ArgumentError] if an array of colours does not have 3 entries
+    def initialize(x1: 50, y1: 0, x2: 100, y2: 100, x3: 0, y3: 100,
+                   z: 0, color: 'white', colour: nil, opacity: nil)
+      @x1 = x1
+      @y1 = y1
+      @x2 = x2
+      @y2 = y2
+      @x3 = x3
+      @y3 = y3
+      @z  = z
+      self.color = color || colour
+      self.color.opacity = opacity if opacity
       add
     end
 
-    def color=(c)
-      @color = Color.set(c)
-      update_color(@color)
+    # Change the colour of the line
+    # @param [String, Array] color A single colour or an array of exactly 3 colours
+    # @raise [ArgumentError] if an array of colours does not have 3 entries
+    def color=(color)
+      # convert to Color or Color::Set
+      color = Color.set(color)
+
+      # require 3 colours if multiple colours provided
+      if color.is_a?(Color::Set) && color.length != 3
+        raise ArgumentError,
+              "`#{self.class}` requires 3 colors, one for each vertex. #{color.length} were given."
+      end
+
+      @color = color # converted above
+      invalidate_color_components
     end
 
     # A point is inside a triangle if the area of 3 triangles, constructed from
@@ -38,45 +66,66 @@ module Ruby2D
       questioned_area <= self_area
     end
 
-    def self.draw(opts = {})
+    # Draw a triangle
+    # @param x1 [Numeric]
+    # @param y1 [Numeric]
+    # @param x2 [Numeric]
+    # @param y2 [Numeric]
+    # @param x3 [Numeric]
+    # @param y3 [Numeric]
+    # @param z [Numeric]
+    # @param color [Array<Array<float,float,float,float>>] An array of 3 arrays of colour components
+    #                                  (e.g. [[1.0, 0, 0, 1.0], ...])
+    def self.draw(x1:, y1:, x2:, y2:, x3:, y3:, color:)
       Window.render_ready_check
-
       ext_draw([
-        opts[:x1], opts[:y1], opts[:color][0][0], opts[:color][0][1], opts[:color][0][2], opts[:color][0][3],
-        opts[:x2], opts[:y2], opts[:color][1][0], opts[:color][1][1], opts[:color][1][2], opts[:color][1][3],
-        opts[:x3], opts[:y3], opts[:color][2][0], opts[:color][2][1], opts[:color][2][2], opts[:color][2][3]
-      ])
+                 x1, y1, *color[0], # splat the colour components
+                 x2, y2, *color[1],
+                 x3, y3, *color[2]
+               ])
     end
 
     private
 
     def render
+      color_comp_arrays = color_components
       self.class.ext_draw([
-        @x1, @y1, @c1.r, @c1.g, @c1.b, @c1.a,
-        @x2, @y2, @c2.r, @c2.g, @c2.b, @c2.a,
-        @x3, @y3, @c3.r, @c3.g, @c3.b, @c3.a
-      ])
+                            @x1, @y1, *color_comp_arrays[0], # splat the colour components
+                            @x2, @y2, *color_comp_arrays[1],
+                            @x3, @y3, *color_comp_arrays[2]
+                          ])
     end
 
     def triangle_area(x1, y1, x2, y2, x3, y3)
-      (x1*y2 + x2*y3 + x3*y1 - x3*y2 - x1*y3 - x2*y1).abs / 2
+      (x1 * y2 + x2 * y3 + x3 * y1 - x3 * y2 - x1 * y3 - x2 * y1).abs / 2
     end
 
-    def update_color(c)
-      if c.is_a? Color::Set
-        if c.length == 3
-          @c1 = c[0]
-          @c2 = c[1]
-          @c3 = c[2]
-        else
-          raise ArgumentError, "`#{self.class}` requires 3 colors, one for each vertex. #{c.length} were given."
-        end
-      else
-        @c1 = c
-        @c2 = c
-        @c3 = c
-      end
+    # Return colours as a memoized array of 3 x colour component arrays
+    def color_components
+      check_if_opacity_changed
+      @color_components ||= if @color.is_a? Color::Set
+                              # Extract colour component arrays; see +def color=+ where colour set
+                              # size is enforced
+                              [
+                                @color[0].to_a, @color[1].to_a, @color[2].to_a
+                              ]
+                            else
+                              # All vertex colours are the same
+                              c_a = @color.to_a
+                              [
+                                c_a, c_a, c_a
+                              ]
+                            end
     end
 
+    # Invalidate memoized colour components if opacity has been changed via +color=+
+    def check_if_opacity_changed
+      @color_components = nil if @color_components && @color_components.first[3] != @color.opacity
+    end
+
+    # Invalidate the memoized colour components. Called when Line's colour is changed
+    def invalidate_color_components
+      @color_components = nil
+    end
   end
 end

data/lib/ruby2d/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 # Ruby2D::VERSION
 
 module Ruby2D
-  VERSION = '0.11.3'
+  VERSION = '0.12.0'
 end

data/lib/ruby2d/vertices.rb

@@ -1,10 +1,11 @@
-# Ruby2D::Vertices
+# frozen_string_literal: true
 
-# This class generates a vertices array which are passed to the openGL rendering code.
-# The vertices array is split up into 4 groups (1 - top left, 2 - top right, 3 - bottom right, 4 - bottom left)
-# This class is responsible for transforming textures, it can scale / crop / rotate and flip textures
+# Ruby2D::Vertices
 
 module Ruby2D
+  # This internal class generates a vertices array which are passed to the openGL rendering code.
+  # The vertices array is split up into 4 groups (1 - top left, 2 - top right, 3 - bottom right, 4 - bottom left)
+  # This class is responsible for transforming textures, it can scale / crop / rotate and flip textures
   class Vertices
     def initialize(x, y, width, height, rotate, crop: nil, flip: nil)
       @flip = flip
@@ -12,53 +13,36 @@ module Ruby2D
       @y = y
       @width = width.to_f
       @height = height.to_f
-
-      if @flip == :horizontal || @flip == :both
-        @x = @x + @width
-        @width = -@width
-      end
-
-      if @flip == :vertical || @flip == :both
-        @y = y + @height
-        @height = -@height
-      end
-
       @rotate = rotate
       @rx = @x + (@width / 2.0)
       @ry = @y + (@height / 2.0)
       @crop = crop
+      @coordinates = nil
+      @texture_coordinates = nil
+      _apply_flip unless @flip.nil?
     end
 
     def coordinates
-      if @rotate == 0
-        x1, y1 = @x,          @y;           # Top left
-        x2, y2 = @x + @width, @y;           # Top right
-        x3, y3 = @x + @width, @y + @height; # Bottom right
-        x4, y4 = @x,          @y + @height; # Bottom left
-      else
-        x1, y1 = rotate(@x,          @y);           # Top left
-        x2, y2 = rotate(@x + @width, @y);           # Top right
-        x3, y3 = rotate(@x + @width, @y + @height); # Bottom right
-        x4, y4 = rotate(@x,          @y + @height); # Bottom left
-      end
-
-      [ x1, y1, x2, y2, x3, y3, x4, y4 ]
+      @coordinates ||= if @rotate.zero?
+                         _unrotated_coordinates
+                       else
+                         _calculate_coordinates
+                       end
     end
 
-    def texture_coordinates
-      if @crop.nil?
-        tx1 = 0.0; ty1 = 0.0 # Top left
-        tx2 = 1.0; ty2 = 0.0 # Top right
-        tx3 = 1.0; ty3 = 1.0 # Bottom right
-        tx4 = 0.0; ty4 = 1.0 # Bottom left
-      else
-        tx1 = @crop[:x] / @crop[:image_width].to_f; ty1 = @crop[:y] / @crop[:image_height].to_f # Top left
-        tx2 = tx1 + (@crop[:width] / @crop[:image_width].to_f); ty2 = ty1                       # Top right
-        tx3 = tx2; ty3 = ty1 + (@crop[:height] / @crop[:image_height].to_f)                     # Botttom right
-        tx4 = tx1; ty4 = ty3                                                                    # Bottom left
-      end
+    TEX_UNCROPPED_COORDS = [
+      0.0, 0.0, # top left
+      1.0, 0.0,   # top right
+      1.0, 1.0,   # bottom right
+      0.0, 1.0    # bottom left
+    ].freeze
 
-      [ tx1, ty1, tx2, ty2, tx3, ty3, tx4, ty4 ]
+    def texture_coordinates
+      @texture_coordinates ||= if @crop.nil?
+                                 TEX_UNCROPPED_COORDS
+                               else
+                                 _calculate_texture_coordinates
+                               end
     end
 
     private
@@ -76,14 +60,66 @@ module Ruby2D
       y -= @ry
 
       # Rotate point
-      xnew = x * ca - y * sa;
-      ynew = x * sa + y * ca;
+      xnew = x * ca - y * sa
+      ynew = x * sa + y * ca
 
       # Translate point back
-      x = xnew + @rx;
-      y = ynew + @ry;
+      x = xnew + @rx
+      y = ynew + @ry
 
       [x, y]
     end
+
+    def _unrotated_coordinates
+      x1 = @x
+      y1 = @y;           # Top left
+      x2 = @x + @width
+      y2 = @y;           # Top right
+      x3 = @x + @width
+      y3 = @y + @height; # Bottom right
+      x4 = @x
+      y4 = @y + @height; # Bottom left
+      [x1, y1, x2, y2, x3, y3, x4, y4]
+    end
+
+    def _calculate_coordinates
+      x1, y1 = rotate(@x,          @y);           # Top left
+      x2, y2 = rotate(@x + @width, @y);           # Top right
+      x3, y3 = rotate(@x + @width, @y + @height); # Bottom right
+      x4, y4 = rotate(@x,          @y + @height); # Bottom left
+      [x1, y1, x2, y2, x3, y3, x4, y4]
+    end
+
+    def _calculate_texture_coordinates
+      img_width = @crop[:image_width].to_f
+      img_height = @crop[:image_height].to_f
+
+      # Top left
+      tx1 = @crop[:x] / img_width
+      ty1 = @crop[:y] / img_height
+      # Top right
+      tx2 = tx1 + (@crop[:width] / img_width)
+      ty2 = ty1
+      # Botttom right
+      tx3 = tx2
+      ty3 = ty1 + (@crop[:height] / img_height)
+      # Bottom left
+      # tx4 = tx1
+      # ty4 = ty3
+
+      [tx1, ty1, tx2, ty2, tx3, ty3, tx1, ty3]
+    end
+
+    def _apply_flip
+      if @flip == :horizontal || @flip == :both
+        @x += @width
+        @width = -@width
+      end
+
+      return unless @flip == :vertical || @flip == :both
+
+      @y += @height
+      @height = -@height
+    end
   end
 end