denko 0.14.0 → 0.15.0

data/lib/denko/display/canvas.rb

@@ -1,181 +1,283 @@
 module Denko
   module Display
     class Canvas
-      include Denko::Fonts
-
-      attr_reader :columns, :rows, :framebuffer
-    
-      def initialize(columns, rows)
-        raise ArgumentError, "bitmap height must be divisible by 8" unless (rows % 8 == 0)
-
-        @columns     = columns
-        @rows        = rows
+      attr_reader :columns, :rows, :framebuffer, :framebuffers, :colors
 
+      def initialize(columns, rows, colors: 1)
+        @columns  = columns
+        @rows     = rows
+        @rows     = ((rows / 8.0).ceil * 8) if (rows % 8 != 0)
         # Use a byte array for the framebuffer. Each byte is 8 pixels arranged vertically.
         # Each slice @columns long represents an area @columns wide * 8 pixels tall.
-        @bytes       = @columns * (@rows / 8)
-        @framebuffer = Array.new(@bytes) { 0x00 }
+        @bytes = @columns * (@rows / 8)
+
+        # Framebuffer setup. 1-bit framebuffer for each color.
+        # Works for mono LCDs and OLEDs, or mono/multi-color e-paper.
+        @colors = colors
+        @framebuffers = []
+        @colors.times { @framebuffers << Array.new(@bytes) { 0x00 } }
+        # Only first framebuffer is used for mono displays.
+        @framebuffer = @framebuffers.first
+
+        # Default drawing state
+        self.font       = Denko::Display::Font::BMP_6X8
+        @font_scale     = 1
+        @current_color  = 1
+
+        # Transformation state
+        @swap_xy     = false
+        @invert_x    = false
+        @invert_y    = false
+        @rotation    = 0
+        calculate_bounds
+      end
+
+      def clear
+        @framebuffers.each { |fb| fb.fill 0x00 }
       end
 
       def fill
-        @framebuffer.fill(0xFF)
+        # Clear all buffers, then fill the first one, which is the only
+        # one for mono displays, black for multi-color e-paper.
+        clear
+        @framebuffers.first.fill 0xFF
       end
 
-      def clear
-        @framebuffer.fill(0x00)
+      #
+      # PIXEL OPERATIONS
+      #
+      def _get_pixel(x, y)
+        byte  = ((y / 8) * @columns) + x
+        bit   = y % 8
+
+        # Go through framebuffers and return that color when bit is set.
+        @framebuffers.each_with_index do |fb, index|
+          return index+1 if ((fb[byte] >> bit) & 0b1 == 1)
+        end
+
+        # If bit wasn't set in any framebuffer, color is 0.
+        return 0
       end
 
-      def get_pixel(x, y)
-        byte = ((y / 8) * @columns) + x
-        bit  = y % 8
-        (@framebuffer[byte] >> bit) & 0b00000001
+      def get_pixel(x:, y:)
+        _get_pixel(x, y)
       end
 
-      def set_pixel(x, y)
-        byte = ((y / 8) * @columns) + x
-        bit  = y % 8
-        @framebuffer[byte] |= (0b1 << bit)
+      def _set_pixel(x, y, color=current_color)
+        xt = (@invert_x) ? @x_max - x : x
+        yt = (@invert_y) ? @y_max - y : y
+        if (@swap_xy)
+          tt = xt
+          xt = yt
+          yt = tt
+        end
+
+        # Bounds check
+        return nil if (xt < 0 || yt < 0 || xt > @columns-1 || yt > @rows -1)
+        return nil if (color < 0) || (color > colors)
+
+        byte = ((yt / 8) * @columns) + xt
+        bit  = yt % 8
+
+        # Set pixel bit in that color's buffer. Clear in others.
+        # When color == 0, clears in all buffers and sets in none.
+        for i in 1..colors
+          if (color == i)
+            @framebuffers[i-1][byte] |= (0b1 << bit)
+          else
+            @framebuffers[i-1][byte] &= ~(0b1 << bit)
+          end
+        end
       end
 
-      def clear_pixel(x, y)
-        byte = ((y / 8) * @columns) + x
-        bit  = y % 8
-        @framebuffer[byte] &= ~(0b1 << bit)
+      def set_pixel(x:, y:, color:current_color)
+        _set_pixel(x, y, color)
       end
 
-      def pixel(x, y, state=0)
-        (state == 0) ? clear_pixel(x, y) : set_pixel(x, y)
+      def clear_pixel(x:, y:)
+        _set_pixel(x, y, 0)
       end
 
-      # Draw a line based on Bresenham's line algorithm.
-      def line(x1, y1, x2, y2, color=1)
+      #
+      # LINE
+      #
+      def _line(x1, y1, x2, y2, color=current_color)
         # Deltas in each axis.
         dy = y2 - y1
         dx = x2 - x1
 
-        # Catch vertical lines to avoid division by 0.
+        # Optimize vertical lines, and avoid division by 0.
         if (dx == 0)
           # Ensure y1 < y2.
           y1, y2 = y2, y1 if (y2 < y1)
-          (y1..y2).each do |y|
-            pixel(x1, y, color)
-          end
+          (y1..y2).each { |y| _set_pixel(x1, y, color) }
           return
         end
 
-        gradient = dy.to_f / dx
-
-        # Gradient magnitude <= 45 degrees: find y for each x.
-        if (gradient >= -1) && (gradient <= 1)
+        # Optimize horizontal lines.
+        if (dy == 0)
           # Ensure x1 < x2.
-          x1, y1, x2, y2 = x2, y2, x1, y1 if (x2 < x1)
-
-          # When x increments, add gradient to y.
-          y = y1
-          y_step = gradient
-          (x1..x2).each do |x|
-            pixel(x, y.round, color)
-            y = y + y_step
-          end
+          x1, x2 = x2, x1 if (x2 < x1)
+          (x1..x2).each { |x| _set_pixel(x, y1, color) }
+          return
+        end
 
-        # Gradient magnitude > 45 degrees: find x for each y.
-        else
-          # Ensure y1 < y2.
-          x1, y1, x2, y2 = x2, y2, x1, y1 if (y2 < y1)
-
-          # When y increments, add inverse of gradient to x.
-          x = x1
-          x_step = 1 / gradient
-          (y1..y2).each do |y|
-            pixel(x.round, y, color)
-            x = x + x_step
+        # Based on Bresenham's line algorithm
+        # Slope calculations
+        step_axis   = (dx.abs > dy.abs) ? :x : :y
+        step_count  = (step_axis == :x) ? dx.abs : dy.abs
+        x_step      = (dx > 0) ? 1 : -1
+        y_step      = (dy > 0) ? 1 : -1
+
+        # Error calculations
+        error_step      = (step_axis == :x) ? dy.abs : dx.abs
+        error_threshold = (step_axis == :x) ? dx.abs : dy.abs
+
+        x = x1
+        y = y1
+        error = 0
+        (0..step_count).each do |i|
+          _set_pixel(x, y, color)
+
+          if (step_axis == :x)
+            x += x_step
+            error += error_step
+            if (error >= error_threshold)
+              y += y_step
+              error -= error_threshold
+            end
+          else
+            y += y_step
+            error += error_step
+            if (error >= error_threshold)
+              x += x_step
+              error -= error_threshold
+            end
           end
         end
       end
 
-      # Rectangles and squares as a combination of lines.
-      def rectangle(x, y, width, height, color=1)
-        line(x,       y,        x+width, y,        color)
-        line(x+width, y,        x+width, y+height, color)
-        line(x+width, y+height, x,       y+height, color)
-        line(x,       y+height, x,       y,        color)
+      def line(x1:, y1:, x2:, y2:, color:current_color)
+        _line(x1, y1, x2, y2, color)
       end
 
-      # Draw a vertical line for every x value to get a filled rectangle.
-      def filled_rectangle(x, y_start, width, height, color=1)
-        y_end = y_start + height
-        y_start, y_end = y_end, y_start if (y_end < y_start)
-        (y_start..y_end).each do |y|
-          line(x, y, x+width, y, color)
+      #
+      # RECTANGLE & SQUARE
+      #
+      def _rectangle(x1, y1, x2, y2, filled=false, color=current_color)
+        if filled
+          y1, y2 = y2, y1 if (y2 < y1)
+          (y1..y2).each { |y| _line(x1, y, x2, y, color) }
+        else
+          _line(x1, y1, x2, y1, color)
+          _line(x2, y1, x2, y2, color)
+          _line(x2, y2, x1, y2, color)
+          _line(x1, y2, x1, y1, color)
         end
       end
 
-      # Open ended path
-      def path(points=[], color=1)
-        return unless points
+      def rectangle(x1:nil, y1:nil, x2:nil, y2:nil, x:nil, y:nil, w:nil, h:nil, filled:false, color:current_color)
+        if (x || y || w || h) && (x1 || x2 || y1 || y2)
+          raise ArgumentError, "#rectangle accepts x:, y:, w:, h: OR x1:, y1:, x2:, y2: not a combination of both"
+        end
+
+        if (w && h)
+          x1 = x
+          x2 = x1 + w
+          x2 += 1 if (x2 < x1)
+          x2 -= 1 if (x1 < x2)
+
+          y1 = y
+          y2 = y1 + h
+          y2 += 1 if (y2 < y1)
+          y2 -= 1 if (y1 < y2)
+        end
+
+        _rectangle(x1, y1, x2, y2, filled, color)
+      end
+
+      def square(x:, y:, size:, filled:false, color:current_color)
+        rectangle(x: x, y: y, w: size, h: size, filled: filled, color: color)
+      end
+
+      #
+      # PATH, POLYGON & TRIANGLE
+      #
+      def _path(points, color=current_color)
         start = points[0]
         (1..points.length-1).each do |i|
           finish = points[i]
-          line(start[0], start[1], finish[0], finish[1])
+          _line(start[0], start[1], finish[0], finish[1], color)
           start = finish
         end
       end
 
-      # Close paths by repeating the start value at the end.
-      def polygon(points=[], color=1)
-        points << points[0]
-        path(points)
+      def path(points, color:current_color)
+        _path(points, color)
       end
 
-      # Filled polygon using horizontal ray casting + stroked polygon.
-      def filled_polygon(points=[], color=1)
-        # Get all the X and Y coordinates from the points as floats.
-        coords_x = points.map { |point| point.first.to_f }
-        coords_y = points.map { |point| point.last.to_f  }
-
-        # Get Y bounds of the polygon to limit rows.
-        y_min = coords_y.min.to_i
-        y_max = coords_y.max.to_i
-
-        # Cast horizontal ray on each row, storing nodes where it intersects polygon edges.
-        (y_min..y_max).each do |y|
-          nodes = []
-          i = 0
-          j = points.count - 1
-
-          while (i < points.count) do
-            if (coords_y[i] < y && coords_y[j] >= y || coords_y[j] < y && coords_y[i] >= y)
-              nodes << (coords_x[i] + (y - coords_y[i]) / (coords_y[j] - coords_y[i]) *(coords_x[j] - coords_x[i])).round
+      def _polygon(points, filled=false, color=current_color)
+        if filled
+          # Get all the X and Y coordinates from the points as floats.
+          coords_x = points.map { |point| point.first.to_f }
+          coords_y = points.map { |point| point.last.to_f  }
+
+          # Get Y bounds of the polygon to limit rows.
+          y_min = coords_y.min.to_i
+          y_max = coords_y.max.to_i
+
+          # Cast horizontal ray on each row, storing nodes where it intersects polygon edges.
+          (y_min..y_max).each do |y|
+            nodes = []
+            i = 0
+            j = points.count - 1
+
+            while (i < points.count) do
+              # First condition excludes horizontal edges.
+              # Second and third check for +ve and -ve intersection respectively.
+              if (coords_y[i] != coords_y[j]) && ((coords_y[i] < y && coords_y[j] >= y) || (coords_y[j] < y && coords_y[i] >= y))
+                # Interoplate to find the intersection point (node).
+                nodes << (coords_x[i] + (y - coords_y[i]) / (coords_y[j] - coords_y[i]) * (coords_x[j] - coords_x[i])).round
+              end
+              j  = i
+              i += 1
             end
-            j  = i
-            i += 1
-          end
-          nodes = nodes.sort
+            nodes = nodes.sort
 
-          # Take pairs of nodes and fill between them. This automatically ignores the spaces
-          # between even then odd nodes, which are outside the polygon.
-          nodes.each_slice(2) do |pair|
-            next if pair.length < 2
-            line(pair.first, y,  pair.last, y, color)
+            # Take pairs of nodes and fill between them.
+            # This ignores the spaces between odd then even nodes (eg. 1->2), which are outside the polygon.
+            nodes.each_slice(2) do |pair|
+              _line(pair.first, y,  pair.last, y, color) if pair.length == 2
+            end
           end
         end
 
-        # Stroke the polygon anyway. Floating point math misses thin areas.
-        polygon(points, color)
+        # Stroke regardless, since floating point math misses thin areas of fill.
+        _path(points, color)
+        # Close open path by adding a line between the first and last points.
+        _line(points[-1][0], points[-1][1], points[0][0], points[0][1], color)
+      end
+
+      def polygon(points, filled:false, color:current_color)
+        _polygon(points, filled, color)
       end
-      
-      # Triangle with 3 points as 6 flat args.
-      def triangle(x1, y1, x2, y2, x3, y3, color=1)
-        polygon([[x1,y1], [x2,y2], [x3,y3]], color)
+
+      def _triangle(x1, y1, x2, y2, x3, y3, filled=false, color=current_color)
+        if filled
+          _polygon([[x1,y1], [x2,y2], [x3,y3]], filled, color)
+        else
+          _line(x1, y1, x2, y2, color)
+          _line(x2, y2, x3, y3, color)
+          _line(x3, y3, x1, y1, color)
+        end
       end
 
-      # Filled triangle with 3 points as 6 flat args.
-      def filled_triangle(x1, y1, x2, y2, x3, y3, color=1)
-        filled_polygon([[x1,y1], [x2,y2], [x3,y3]], color)
+      def triangle(x1:, y1:, x2:, y2:, x3:, y3:, filled:false, color:current_color)
+        _triangle(x1, y1, x2, y2, x3, y3, filled, color)
       end
 
-      # Midpoint ellipse / circle based on Bresenham's circle algorithm.
-      def ellipse(x_center, y_center, a, b, color=1, filled=false)
+      def _ellipse(x_center, y_center, a, b, filled=false, color=current_color)
+        # Midpoint ellipse / circle based on Bresenham's circle algorithm.
         # Start position
         x = -a
         y = 0
@@ -193,9 +295,15 @@ module Denko
         # Since starting at max negative X, continue until x is 0.
         while (x <= 0)
           if filled
-            fill_quadrants(x_center, y_center, x, y, color)
+            # Fill left and right quadrants in single line, alternating +ve and -ve y.
+            _line(x_center - x, y_center + y, x_center + x, y_center + y, color)
+            _line(x_center - x, y_center - y, x_center + x, y_center - y, color)
           else
-            stroke_quadrants(x_center, y_center, x, y, color)
+            # Stroke quadrants in order as if y-axis is reversed and going counter-clockwise from +ve X.
+            _set_pixel(x_center - x, y_center - y, color)
+            _set_pixel(x_center + x, y_center - y, color)
+            _set_pixel(x_center + x, y_center + y, color)
+            _set_pixel(x_center - x, y_center + y, color)
           end
 
           e2 = 2 * e1
@@ -214,69 +322,154 @@ module Denko
         # Continue if y hasn't reached the vertical size.
         while (y < b)
           y += 1
-          pixel(x_center, y_center + y, color)
-          pixel(x_center, y_center - y, color)
+          _set_pixel(x_center, y_center + y, color)
+          _set_pixel(x_center, y_center - y, color)
         end
       end
 
-      def stroke_quadrants(x_center, y_center, x, y, color)
-        # Quadrants in order as if y-axis is reversed and going counter-clockwise from +ve X.
-        pixel(x_center - x, y_center - y, color)
-        pixel(x_center + x, y_center - y, color)
-        pixel(x_center + x, y_center + y, color)
-        pixel(x_center - x, y_center + y, color)
+      def ellipse(x:, y:, a:, b:, filled:false, color:current_color)
+        _ellipse(x, y, a, b, filled, color)
       end
 
-      def fill_quadrants(x_center, y_center, x, y, color)
-        line(x_center - x, y_center + y, x_center + x, y_center + y, color)
-        line(x_center - x, y_center - y, x_center + x, y_center - y, color)
+      def circle(x:, y:, r:, filled:false, color:current_color)
+        _ellipse(x, y, r, r, filled, color)
       end
 
-      def circle(x_center, y_center, radius, color=1, filled=false)
-        ellipse(x_center, y_center, radius, radius, color, filled)
+      #
+      # BITMAP TEXT
+      #
+      def text(str, color:current_color)
+        str.to_s.split("").each { |char| draw_char(char, color: color) }
       end
 
-      def filled_circle(x_center, y_center, radius, color=1)
-        ellipse(x_center, y_center, radius, radius, color, true)
+      def draw_char(char, color:current_color)
+        # 0th character in font is SPACE. Offset ASCII code and show ? if character doesn't exist in font.
+        index = char.ord - 32
+        index = 31 if (index < 0 || index > @font_last_character)
+        char_map = @font_characters[index]
+
+        # Offset by scaled height, since bottom left of char starts at text cursor.
+        x = text_cursor[0]
+        y = text_cursor[1] + 1 - (@font_height * @font_scale)
+
+        # Draw it
+        _draw_char(char_map, x, y, @font_width, @font_scale, color)
+
+        # Increment the text cursor, scaling width.
+        self.text_cursor[0] += @font_width * @font_scale
       end
 
-      def text_cursor=(array=[])
-        @text_cursor = array
+      def _draw_char(byte_array, x, y, width, scale, color=current_color)
+        byte_array.each_slice(width) do |slice|
+          slice.each_with_index do |byte, col_offset|
+            8.times do |bit|
+              # Don't do anything if this bit isn't set in the font.
+              if (((byte >> bit) & 0b1) == 1)
+                scale.times do |x_offset|
+                  scale.times do |y_offset|
+                    _set_pixel(x + (col_offset * scale) + x_offset, y + (bit * scale) + y_offset, color)
+                  end
+                end
+              end
+            end
+          end
+          y = y + (8 * scale)
+        end
+      end
+
+      #
+      # DRAWING STATE
+      #
+      def current_color=(color)
+        raise Argument error, "color must be within (0..#{colors})" if (color < 0) || (color > colors)
+        @current_color = color
       end
 
+      attr_reader :current_color
+
+      DEFAULT_TEXT_CURSOR = [0, 7]
+
       def text_cursor
-        @text_cursor ||= [0, 7]
+        @text_cursor ||= DEFAULT_TEXT_CURSOR
       end
 
-      def print(str)
-        str.to_s.split("").each do |char|
-          print_char(char)
-        end
+      def text_cursor=(array=DEFAULT_TEXT_CURSOR)
+        @text_cursor = array
       end
 
-      def print_char(char)
-        # 0th character in font is SPACE. Offset and limit to printable chars.
-        index = char.ord - 32
-        index = 0 if (index < 0 || index > 94)
-        char_map = FONT_6x8[index]
+      def font=(font)
+        if font.class == Symbol
+          @font = Display::Font.const_get(font.to_s.upcase)
+        else
+          @font = font
+        end
 
-        raw_char(char_map)
+        @font_height = @font[:height]
+        @font_width = @font[:width]
+        @font_characters = @font[:characters]
+        @font_last_character = @font_characters.length - 1
       end
 
-      def raw_char(byte_array)
-        # Get the starting byte index.
-        page = text_cursor[1] / 8
-        byte_index = (@columns * page) + text_cursor[0]
+      def font_scale=(scale)
+        raise ArgumentError, "#font_scale must be a positive integer" unless (scale.class == Integer) && scale > 0
+        @font_scale = scale
+      end
 
-        # Replace those bytes in the framebuffer with the character.
-        byte_array.each do |byte| 
-          @framebuffer[byte_index] = byte
-          byte_index += 1
+      attr_reader :font, :font_scale
+
+      #
+      # TRANSFORMATION
+      #
+      def rotate(degrees=180)
+        raise ArgumentError, "Canvas can only be rotated in multiples of 90 degrees" unless (degrees % 90 == 0)
+        old_rotation = @rotation
+        @rotation = (old_rotation + degrees) % 360
+        change = (@rotation - old_rotation) % 360
+
+        (change / 90).times do
+          @swap_xy = !@swap_xy
+          if (!@invert_x && !@invert_y)
+            @invert_x = true
+            @invert_y = false
+          elsif (@invert_x && !@invert_y)
+            @invert_x = true
+            @invert_y = true
+          elsif (@invert_x && @invert_y)
+            @invert_x = false
+            @invert_y = true
+          elsif (!@invert_x && @invert_y)
+            @invert_x = false
+            @invert_y = false
+          end
         end
+        calculate_bounds
+      end
 
-        # Increment the text cursor.
-        self.text_cursor[0] += byte_array.length
+      def reflect(axis)
+        raise ArgumentError "Canvas can only be reflected in :x or :y axis" unless [:x, :y].include? (axis)
+        (axis == :x) ? @invert_x = !@invert_x : @invert_y = !@invert_y
+        calculate_bounds
       end
+
+      def reflect_x
+        reflect(:x)
+      end
+
+      def reflect_y
+        reflect(:y)
+      end
+
+      def calculate_bounds
+        if @swap_xy
+          @x_max = @rows - 1
+          @y_max = @columns - 1
+        else
+          @x_max = @columns - 1
+          @y_max = @rows - 1
+        end
+      end
+
+      attr_reader :x_max, :y_max
     end
   end
 end