ruby2d 0.11.3 → 0.12.0

data/lib/ruby2d/image.rb

@@ -1,48 +1,69 @@
+# frozen_string_literal: true
+
 # Ruby2D::Image
 
 module Ruby2D
+  # Images in many popular formats can be drawn in the window.
+  # To draw an image in the window, use the following, providing the image file path:
+  # +Image.new('star.png')+
   class Image
     include Renderable
 
     attr_reader :path
     attr_accessor :x, :y, :width, :height, :rotate, :data
 
-    def self.load_image(path)
-      unless File.exist? path
-        raise Error, "Cannot find image file `#{path}`"
-      end
-
-      ext_load_image(path)
+    # Load an image +path+ and return a Texture, using a pixmap atlas if provided
+    # @param path [#to_s] The location of the file to load as an image.
+    # @param atlas [PixmapAtlas] Pixmap atlas to use to manage the image file
+    # @return [Texture] loaded
+    def self.load_image_as_texture(path, atlas:)
+      pixmap = if atlas
+                 atlas.load_and_keep_image(path, as: path)
+               else
+                 Pixmap.new path
+               end
+      pixmap.texture
     end
 
-    def initialize(path, opts = {})
-      @path = path
+    # Create 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 x [Numeric]
+    # @param y [Numeric]
+    # @param z [Numeric]
+    # @param rotate [Numeric] Angle, default is 0
+    # @param color [Numeric] (or +colour+) Tint the image when rendering
+    # @param opacity [Numeric] Opacity of the image when rendering
+    # @param show [Boolean] If +true+ the image is added to +Window+ automatically.
+    def initialize(path, atlas: nil,
+                   width: nil, height: nil, x: 0, y: 0, z: 0,
+                   rotate: 0, color: nil, colour: nil,
+                   opacity: nil, show: true)
+      @path = path.to_s
 
-      @texture = Texture.new(*Image.load_image(@path))
-      @width = opts[:width] || @texture.width
-      @height = opts[:height] || @texture.height
+      # 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
 
-      @x = opts[:x] || 0
-      @y = opts[:y] || 0
-      @z = opts[:z] || 0
-      @rotate = opts[:rotate] || 0
-      self.color = opts[:color] || 'white'
-      self.color.opacity = opts[:opacity] if opts[:opacity]
+      @x = x
+      @y = y
+      @z = z
+      @rotate = rotate
+      self.color = color || colour || 'white'
+      self.color.opacity = opacity unless opacity.nil?
 
-      unless opts[:show] == false then add end
+      add if show
     end
 
-    def draw(opts = {})
+    def draw(x: 0, y: 0, width: nil, height: nil, rotate: 0, color: nil, colour: nil)
       Window.render_ready_check
 
-      opts[:width] = opts[:width] || @width
-      opts[:height] = opts[:height] || @height
-      opts[:rotate] = opts[:rotate] || @rotate
-      unless opts[:color]
-        opts[:color] = [1.0, 1.0, 1.0, 1.0]
-      end
-
-      render(x: opts[:x], y: opts[:y], width: opts[:width], height: opts[:height], color: Color.new(opts[:color]), rotate: opts[:rotate])
+      render(x: x, y: y, width:
+        width || @width, height: height || @height,
+             color: Color.new(color || colour || 'white'),
+             rotate: rotate || @rotate)
     end
 
     private

data/lib/ruby2d/line.rb

@@ -1,26 +1,52 @@
+# frozen_string_literal: true
+
 # Ruby2D::Line
 
 module Ruby2D
+  # A line between two points.
   class Line
     include Renderable
 
     attr_accessor :x1, :x2, :y1, :y2, :width
 
-    def initialize(opts = {})
-      @x1 = opts[:x1] || 0
-      @y1 = opts[:y1] || 0
-      @x2 = opts[:x2] || 100
-      @y2 = opts[:y2] || 100
-      @z = opts[:z] || 0
-      @width = opts[:width] || 2
-      self.color = opts[:color] || 'white'
-      self.color.opacity = opts[:opacity] if opts[:opacity]
+    # Create an Line
+    # @param [Numeric] x1
+    # @param [Numeric] y1
+    # @param [Numeric] x2
+    # @param [Numeric] y2
+    # @param [Numeric] width The +width+ or thickness of the line
+    # @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(x1: 0, y1: 0, x2: 100, y2: 100, z: 0,
+                   width: 2, color: nil, colour: nil, opacity: nil)
+      @x1 = x1
+      @y1 = y1
+      @x2 = x2
+      @y2 = y2
+      @z = z
+      @width = width
+      self.color = color || colour || 'white'
+      self.color.opacity = opacity unless opacity.nil?
       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 4 colours
+    # @raise [ArgumentError] if an array of colours does not have 4 entries
+    def color=(color)
+      # convert to Color or Color::Set
+      color = Color.set(color)
+
+      # require 4 colours if multiple colours provided
+      if color.is_a?(Color::Set) && color.length != 4
+        raise ArgumentError,
+              "`#{self.class}` requires 4 colors, one for each vertex. #{color.length} were given."
+      end
+
+      @color = color # converted above
+      invalidate_color_components
     end
 
     # Return the length of the line
@@ -33,57 +59,70 @@ module Ruby2D
     # the width. For reference:
     #   https://en.wikipedia.org/wiki/Distance_from_a_point_to_a_line
     def contains?(x, y)
-      points_distance(x1, y1, x, y) <= length &&
-      points_distance(x2, y2, x, y) <= length &&
-      (((@y2 - @y1) * x - (@x2 - @x1) * y + @x2 * @y1 - @y2 * @x1).abs / length) <= 0.5 * @width
+      line_len = length
+      points_distance(@x1, @y1, x, y) <= line_len &&
+        points_distance(@x2, @y2, x, y) <= line_len &&
+        (((@y2 - @y1) * x - (@x2 - @x1) * y + @x2 * @y1 - @y2 * @x1).abs / line_len) <= 0.5 * @width
     end
 
-    def self.draw(opts = {})
+    # Draw a line without creating a Line
+    # @param [Numeric] x1
+    # @param [Numeric] y1
+    # @param [Numeric] x2
+    # @param [Numeric] y2
+    # @param [Numeric] width The +width+ or thickness of the line
+    # @param [Array] colors An array or 4 arrays of colour components.
+    def self.draw(x1:, y1:, x2:, y2:, width:, color:)
       Window.render_ready_check
 
       ext_draw([
-        opts[:x1], opts[:y1], opts[:x2], opts[:y2], opts[:width],
-        opts[:color][0][0], opts[:color][0][1], opts[:color][0][2], opts[:color][0][3],
-        opts[:color][1][0], opts[:color][1][1], opts[:color][1][2], opts[:color][1][3],
-        opts[:color][2][0], opts[:color][2][1], opts[:color][2][2], opts[:color][2][3],
-        opts[:color][3][0], opts[:color][3][1], opts[:color][3][2], opts[:color][3][3]
-      ])
+                 x1, y1, x2, y2, width,
+                 # splat each colour's components
+                 *color[0], *color[1], *color[2], *color[3]
+               ])
     end
 
     private
 
     def render
       self.class.ext_draw([
-        @x1, @y1, @x2, @y2, @width,
-        @c1.r, @c1.g, @c1.b, @c1.a,
-        @c2.r, @c2.g, @c2.b, @c2.a,
-        @c3.r, @c3.g, @c3.b, @c3.a,
-        @c4.r, @c4.g, @c4.b, @c4.a
-      ])
+                            @x1, @y1, @x2, @y2, @width,
+                            # splat the colour components from helper
+                            *color_components
+                          ])
     end
 
     # Calculate the distance between two points
     def points_distance(x1, y1, x2, y2)
-      Math.sqrt((x1 - x2) ** 2 + (y1 - y2) ** 2)
+      Math.sqrt((x1 - x2).abs2 + (y1 - y2).abs2)
     end
 
-    def update_color(c)
-      if c.is_a? Color::Set
-        if c.length == 4
-          @c1 = c[0]
-          @c2 = c[1]
-          @c3 = c[2]
-          @c4 = c[3]
-        else
-          raise ArgumentError, "`#{self.class}` requires 4 colors, one for each vertex. #{c.length} were given."
-        end
-      else
-        @c1 = c
-        @c2 = c
-        @c3 = c
-        @c4 = c
-      end
+    # Return colours as a memoized flattened array of 4 x colour components
+    def color_components
+      check_if_opacity_changed
+      @color_components ||= if @color.is_a? Color::Set
+                              # Splat the colours from the set; see +def color=+ where colour set
+                              # size is enforced
+                              [
+                                *@color[0].to_a, *@color[1].to_a, *@color[2].to_a, *@color[3].to_a
+                              ]
+                            else
+                              # All vertex colours are the same
+                              c_a = @color.to_a
+                              [
+                                *c_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[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/music.rb

@@ -1,20 +1,25 @@
+# frozen_string_literal: true
+
 # Ruby2D::Music
 
 module Ruby2D
+  # Music is for longer pieces which can be played, paused, stopped, resumed,
+  # and faded out, like a background soundtrack.
   class Music
-
     attr_reader :path
     attr_accessor :loop, :data
 
-    def initialize(path, opts = {})
-      unless File.exist? path
-        raise Error, "Cannot find audio file `#{path}`"
-      end
+    #
+    # Load music from a file
+    # @param [String] path File to load the music from
+    # @param [true, false] loop If +true+ playback will loop automatically, default is +false+
+    # @raise [Error] if file cannot be found or music could not be successfully loaded.
+    def initialize(path, loop: false)
+      raise Error, "Cannot find audio file `#{path}`" unless File.exist? path
+
       @path = path
-      @loop = opts[:loop] || false
-      unless ext_init(@path)
-        raise Error, "Music `#{@path}` cannot be created"
-      end
+      @loop = loop
+      raise Error, "Music `#{@path}` cannot be created" unless ext_init(@path)
     end
 
     # Play the music
@@ -37,31 +42,36 @@ module Ruby2D
       ext_stop
     end
 
-    # Returns the volume, in percentage
-    def self.volume
-      self.ext_get_volume
-    end
+    class << self
+      # Returns the volume, in percentage
+      def volume
+        ext_get_volume
+      end
 
-    # Set music volume, 0 to 100%
-    def self.volume=(v)
-      # If a negative value, volume will be 0
-      if v < 0 then v = 0 end
-      self.ext_set_volume(v)
+      # Set music volume, 0 to 100%
+      def volume=(volume)
+        # Clamp value to between 0-100
+        ext_set_volume(volume.clamp(0, 100))
+      end
     end
 
     # Alias instance methods to class methods
-    def volume; Music.volume end
-    def volume=(v); Music.volume=(v) end
+    def volume
+      Music.volume
+    end
+
+    def volume=(volume)
+      Music.volume = (volume)
+    end
 
     # Fade out music over provided milliseconds
-    def fadeout(ms)
-      ext_fadeout(ms)
+    def fadeout(milliseconds)
+      ext_fadeout(milliseconds)
     end
 
     # Returns the length in seconds
     def length
       ext_length
     end
-
   end
 end

data/lib/ruby2d/pixel.rb

@@ -1,17 +1,18 @@
+# frozen_string_literal: true
+
 # Ruby2D::Pixel
 
 module Ruby2D
+  # Draw a single pixel by calling +Pixel.draw(...)+
   class Pixel
+    def self.draw(x:, y:, size:, color:)
+      color = color.to_a if color.is_a? Color
 
-    def self.draw(opts = {})
-      ext_draw([
-        opts[:x]              , opts[:y],
-        opts[:x] + opts[:size], opts[:y],
-        opts[:x] + opts[:size], opts[:y] + opts[:size],
-        opts[:x]              , opts[:y] + opts[:size],
-        opts[:color][0], opts[:color][1], opts[:color][2], opts[:color][3]
-      ])
+      ext_draw([x, y,
+                x + size, y,
+                x + size, y + size,
+                x, y + size,
+                color[0], color[1], color[2], color[3]])
     end
-
   end
 end

data/lib/ruby2d/pixmap.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Ruby2D::Pixmap
+
+module Ruby2D
+  # Error when failed to load an image
+  class InvalidImageFileError < Ruby2D::Error
+    def initialize(file_path)
+      super("Failed to load image file: #{file_path}")
+    end
+  end
+
+  # Error finding image file
+  class UnknownImageFileError < Ruby2D::Error
+    def initialize(file_path)
+      super "Cannot find image file `#{file_path}`"
+    end
+  end
+
+  #
+  # A pixmap represents an image made up of pixel data of fixed width and height.
+  class Pixmap
+    attr_reader :width, :height, :path
+
+    def initialize(file_path)
+      file_path = file_path.to_s
+      raise UnknownImageFileError, file_path unless File.exist? file_path
+
+      ext_load_pixmap(file_path)
+      raise InvalidImageFileError, file_path unless @ext_pixel_data
+
+      @path = file_path
+    end
+
+    def texture
+      @texture ||= Texture.new(@ext_pixel_data, @width, @height)
+    end
+  end
+end

data/lib/ruby2d/pixmap_atlas.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Ruby2D::PixmapAtlas
+
+module Ruby2D
+  #
+  # A pixmap is a 2D grid of pixel data of fixed width and height. A pixmap atlas
+  # is a dictionary of named pixmaps where each named pixmap is loaded once and can be re-used
+  # multiple times without the overhead of repeated loading and multiple copies.
+  class PixmapAtlas
+    def initialize
+      @atlas = {} # empty map
+    end
+
+    # Empty the atlas, eventually releasing all the loaded
+    # pixmaps (except for any that are referenced elsewhere)
+    def clear
+      @atlas.clear
+    end
+
+    # Find a previosly loaded Pixmap in the atlas by name
+    #
+    # @param [String] name
+    # @return [Pixmap, nil]
+    def [](name)
+      @atlas[name]
+    end
+
+    # Get the number of Pixmaps in the atlas
+    def count
+      @atlas.count
+    end
+
+    # Iterate through each Pixmap in the atlas
+    def each(&block)
+      @atlas.each(&block)
+    end
+
+    # Load a pixmap from an image +file_path+ and store it +as+ named for later lookup.
+    #
+    # @param [String] file_path The path to the image file to load as a +Pixmap+
+    # @param [String] as The name to associated with the Pixmap; if +nil+ then +file_path+ is used +as+ the name
+    #
+    # @raise [Pixmap::InvalidImageFileError] if the image file cannot be loaded
+    # @return [Pixmap] the new (or existing) Pixmap
+    def load_and_keep_image(file_path, as: nil)
+      name = as || file_path
+      if @atlas.member? name
+        @atlas[name]
+      else
+        pixmap = Pixmap.new file_path
+        @atlas[name] = pixmap
+      end
+    end
+  end
+end

data/lib/ruby2d/quad.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 # Ruby2D::Quad
 
 module Ruby2D
+  # A quadrilateral based on four points in clockwise order starting at the top left.
   class Quad
     include Renderable
 
@@ -9,29 +12,55 @@ module Ruby2D
     # x2,y2 == top right
     # x3,y3 == bottom right
     # x4,y4 == bottom left
-    attr_accessor :x1, :y1, :c1,
-                  :x2, :y2, :c2,
-                  :x3, :y3, :c3,
-                  :x4, :y4, :c4
-
-    def initialize(opts = {})
-      @x1 = opts[:x1] || 0
-      @y1 = opts[:y1] || 0
-      @x2 = opts[:x2] || 100
-      @y2 = opts[:y2] || 0
-      @x3 = opts[:x3] || 100
-      @y3 = opts[:y3] || 100
-      @x4 = opts[:x4] || 0
-      @y4 = opts[:y4] || 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,
+                  :x4, :y4
+
+    # Create an quadrilateral
+    # @param [Numeric] x1
+    # @param [Numeric] y1
+    # @param [Numeric] x2
+    # @param [Numeric] y2
+    # @param [Numeric] x3
+    # @param [Numeric] y3
+    # @param [Numeric] x4
+    # @param [Numeric] y4
+    # @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(x1: 0, y1: 0, x2: 100, y2: 0, x3: 100, y3: 100, x4: 0, y4: 100,
+                   z: 0, color: nil, colour: nil, opacity: nil)
+      @x1 = x1
+      @y1 = y1
+      @x2 = x2
+      @y2 = y2
+      @x3 = x3
+      @y3 = y3
+      @x4 = x4
+      @y4 = y4
+      @z  = z
+      self.color = color || colour || 'white'
+      self.color.opacity = opacity unless opacity.nil?
       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 4 colours
+    # @raise [ArgumentError] if an array of colours does not have 4 entries
+    def color=(color)
+      # convert to Color or Color::Set
+      color = Color.set(color)
+
+      # require 4 colours if multiple colours provided
+      if color.is_a?(Color::Set) && color.length != 4
+        raise ArgumentError,
+              "`#{self.class}` requires 4 colors, one for each vertex. #{color.length} were given."
+      end
+
+      @color = color # converted above
+      invalidate_color_components
     end
 
     # The logic is the same as for a triangle
@@ -48,49 +77,69 @@ module Ruby2D
       questioned_area <= self_area
     end
 
-    def self.draw(opts = {})
+    # Draw a line without creating a Line
+    # @param [Numeric] x1
+    # @param [Numeric] y1
+    # @param [Numeric] x2
+    # @param [Numeric] y2
+    # @param [Numeric] x3
+    # @param [Numeric] y3
+    # @param [Numeric] x4
+    # @param [Numeric] y4
+    # @param color [Array<Array<float,float,float,float>>] An array of 4 array of colour components
+    #                                       (e.g. [[1.0, 0, 0, 1.0], ...])
+    def self.draw(x1:, y1:, x2:, y2:, x3:, y3:, x4:, y4:, 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],
-        opts[:x4], opts[:y4], opts[:color][3][0], opts[:color][3][1], opts[:color][3][2], opts[:color][3][3]
-      ])
+                 x1, y1, *color[0], # splat the colour components
+                 x2, y2, *color[1],
+                 x3, y3, *color[2],
+                 x4, y4, *color[3]
+               ])
     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,
-        @x4, @y4, @c4.r, @c4.g, @c4.b, @c4.a
-      ])
+                            @x1, @y1, *color_comp_arrays[0], # splat the colour components
+                            @x2, @y2, *color_comp_arrays[1],
+                            @x3, @y3, *color_comp_arrays[2],
+                            @x4, @y4, *color_comp_arrays[3]
+                          ])
     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 == 4
-          @c1 = c[0]
-          @c2 = c[1]
-          @c3 = c[2]
-          @c4 = c[3]
-        else
-          raise ArgumentError, "`#{self.class}` requires 4 colors, one for each vertex. #{c.length} were given."
-        end
-      else
-        @c1 = c
-        @c2 = c
-        @c3 = c
-        @c4 = c
-      end
+    # Return colours as a memoized array of 4 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, @color[3].to_a
+                              ]
+                            else
+                              # All vertex colours are the same
+                              c_a = @color.to_a
+                              [
+                                c_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