tea 0.6.1

data/lib/tea.rb

@@ -0,0 +1,34 @@
+# Tea is a simple 2D game development library for Ruby.
+
+require 'sdl'
+
+require 'tea/c_bitmap'
+require 'tea/c_error'
+require 'tea/c_font'
+require 'tea/c_sound'
+require 'tea/m_color'
+require 'tea/m_event'
+require 'tea/o_screen'
+
+# The Tea module acts as a namespace for all Tea-related objects and
+# methods.
+module Tea
+
+  # Initialise Tea.  This needs to be called before using any of Tea's
+  # objects or methods.
+  #
+  # May throw Tea::Error if initialisation fails.
+  def Tea.init
+    SDL.init(SDL::INIT_VIDEO | SDL::INIT_AUDIO)
+
+    # Get typed characters from keys when pressed.
+    SDL::Event.enable_unicode
+    SDL::Mixer.open 44100, SDL::Mixer::DEFAULT_FORMAT, SDL::Mixer::DEFAULT_CHANNELS, 1024
+  rescue SDL::Error => e
+    raise Tea::Error, e.message, e.backtrace
+  end
+
+  rv_match = RUBY_VERSION.match(/(\d+)\.(\d+)\.\d+/)
+  RUBY_1_9 = rv_match && rv_match[1].to_i >= 1 && rv_match[2].to_i >= 9
+
+end

data/lib/tea/c_bitmap.rb

@@ -0,0 +1,122 @@
+# This file holds the Bitmap class, which are grids of pixels that hold
+# graphics.
+
+require 'sdl'
+
+require 'tea/mix_blitting'
+require 'tea/mix_clipping'
+require 'tea/mix_grabbing'
+require 'tea/mix_image_saving'
+require 'tea/mix_primitive'
+
+#
+module Tea
+
+  # A Bitmap is a grid of pixels that holds graphics.
+  class Bitmap
+
+    # Create a new Bitmap.  This can be done in 2 ways:
+    #
+    # (image_path)::            loads from an image
+    # (width, height, color)::  creates with the given size and color
+    #
+    # May raise ArgumentError if the arguments passed in don't match one of the
+    # above, or Tea::Error if the Bitmap creation fails.
+    def initialize(*args)
+      case args.length
+      when 1 then from_image(*args)
+      when 3 then fresh(*args)
+      else
+        raise ArgumentError, "wrong number of arguments (#{args.length} for 1 or 3)", caller
+      end
+    end
+
+    # Get the width of the Bitmap in pixels.
+    def w
+      @buffer.w
+    end
+
+    # Get the height of the Bitmap in pixels.
+    def h
+      @buffer.h
+    end
+
+    # Convert the Bitmap's internal format to that of the screen to speed up
+    # drawing.  Intended for internal use, but calling it manually won't bring
+    # any harm.
+    def optimize_for_screen
+      @buffer = @buffer.display_format_alpha
+    end
+
+    include Blitting
+    def blitting_buffer
+      @buffer
+    end
+
+    include Clipping
+    def clipping_buffer
+      @buffer
+    end
+
+    include Grabbing
+    def grabbing_buffer
+      @buffer
+    end
+
+    include ImageSaving
+    def image_saving_buffer
+      @buffer
+    end
+
+    include Primitive
+    def primitive_buffer
+      @buffer
+    end
+
+    private
+
+    # Create a new Bitmap from an image file.
+    #
+    # May raise Tea::Error if it fails.
+    def from_image(image_path)
+      @buffer = SDL::Surface.load(image_path)
+
+      if Tea::Screen.mode_set?
+        optimize_for_screen
+      else
+        Tea::Screen.register_bitmap_for_optimizing self
+      end
+    rescue SDL::Error => e
+      raise Tea::Error, e.message, e.backtrace
+    end
+
+    # Create a new Bitmap of the given size and initialized with the color.
+    #
+    # May raise Tea::Error if it fails.
+    def fresh(width, height, color)
+      if width < 1 || height < 1
+        raise Tea::Error, "can't create bitmap smaller than 1x1 (#{width}x#{height})", caller
+      end
+
+      # Default to big endian, as it works better with SGE's anti-aliasing.
+      rmask = 0xff000000
+      gmask = 0x00ff0000
+      bmask = 0x0000ff00
+      amask = 0x000000ff
+      @buffer = SDL::Surface.new(SDL::SWSURFACE,
+                                 width, height, 32,
+                                 rmask, gmask, bmask, amask)
+      rect 0, 0, w, h, color, :mix => :replace
+
+      if Tea::Screen.mode_set?
+        optimize_for_screen
+      else
+        Tea::Screen.register_bitmap_for_optimizing self
+      end
+    rescue SDL::Error => e
+      raise Tea::Error, e.message, e.backtrace
+    end
+
+  end
+
+end

data/lib/tea/c_error.rb

@@ -0,0 +1,11 @@
+# This file holds the Error class.
+
+#
+module Tea
+
+  # Error is the exception class raised when Bad Things happen in any of
+  # Tea's objects or methods.
+  class Error < StandardError
+  end
+
+end

data/lib/tea/c_font.rb

@@ -0,0 +1,302 @@
+# This file holds the Font class, which is used for drawing text.
+
+require 'sdl'
+
+require 'tea/c_error'
+require 'tea/c_bitmap'
+require 'tea/m_color'
+
+#
+module Tea
+
+  # Fonts are used to draw text.  They do this by mapping characters to images
+  # that are loaded when the Font is created.
+  #
+  # Tea supports bitmap fonts, and Karl Bartel's SFont format.
+  #
+  # Bitmap fonts (Tea::Font::BITMAP_FONT) are a single row of 256 characters in
+  # a BMP or PNG image.  If the image has intrinsic transparency, it will be
+  # used by default.  Otherwise, loading the font with the color transparency
+  # option will consider one color as the 'transparent color' and no such
+  # pixels will be drawn.
+  #
+  # SFont fonts (Tea::Font::SFONT) are also a single row of character images,
+  # but ranging from ASCII 33 to ASCII 127:
+  #
+  #     ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @
+  #     A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ `
+  #     a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~
+  #
+  # SFont uses variable width characters.  Characters are separated by magenta
+  # (255, 0, 255) in the top pixel row, so the pixels directly under the
+  # magenta strips would be the gaps between characters, e.g.:
+  #
+  #     ____       ____       ____       ____   <-- magenta strips
+  #     ....   #   .... ####  ....  ###  ....
+  #     ....  # #  .... #   # .... #   # ....
+  #     .... ##### .... ####  .... #     ....   <-- gaps between characters
+  #     .... #   # .... #   # .... #   # ....       (can be any color)
+  #     .... #   # .... ####  ....  ###  ....
+  #
+  # The width of a space is not defined in the SFont format, so Tea uses the
+  # width of the first character, '!'.
+  class Font
+
+    # +font_type+ constant for bitmap fonts.
+    BITMAP_FONT = :BITMAP_FONT
+    SFONT = :SFONT
+
+    BITMAP_FONT_START = 0
+    BITMAP_FONT_LENGTH = 256
+    SFONT_START = 33
+    SFONT_LENGTH = 94
+
+    CODE_POINT_SPACE = 32
+
+    # Create a new font from a font file given by +path+.
+    #
+    # +font_type+ is one of Tea::Font::BITMAP_FONT or Tea::Font::SFONT.  See
+    # Tea::Font for font format details.
+    #
+    # Optional hash arguments:
+    #
+    #   +:transparent_color+::  If +font_type+ is Tea::Font::BITMAP_FONT, this
+    #                           is the color that should not be drawn when
+    #                           rendering text.  Default: Tea::Color::MAGENTA.
+    #
+    # May raise Tea::Error on failure.
+    def initialize(path, font_type, options=nil)
+      font = SDL::Surface.load(path)
+      transparent_color = options ? options[:transparent_color] : nil
+      @font_type = font_type
+
+      case font_type
+      when BITMAP_FONT
+        @glyphs = letters_from_bitmap_font(font, transparent_color)
+      when SFONT
+        @glyphs = letters_from_sfont(font, transparent_color)
+      end
+    rescue SDL::Error => e
+      raise Tea::Error, e.message, e.backtrace
+    end
+
+    # Calculate the pixel width of a string rendered with this font.
+    def string_w(string)
+      w = 0
+      each_code_point(string) { |pt| w += get_glyph_w(pt) }
+      w
+    end
+
+    # Get the height of the font's characters.
+    def h
+      # Nothing special about 0, all chars are the same height.
+      @glyphs[0].h
+    end
+
+    # Array-like return class of word_wrap().
+    # +end_x+ holds the position of the end of the final line.
+    class WrappedLines < Array
+      attr_accessor :end_x
+    end
+
+    # Split a string into an array of lines such that each line, when rendered
+    # using this font, is no wider than width.
+    #
+    # +initial_left_margin+ sets the starting position for the first line of
+    # wrapping.
+    #
+    # Returns an array of strings, representing the split lines.
+    def word_wrap(string, width, initial_left_margin=0)
+      # This is adapted from the Sphere RPG Engine's font word wrapping code.
+      # Rickety, but battle-tested.
+      space_w = string_w(" ")
+      tab = " " * 4
+      tab_w = string_w(tab)
+
+      x = initial_left_margin
+
+      lines = WrappedLines.new
+      lines.push ""
+      word = ""
+      word_w = 0
+
+      # No good string character iterators for Ruby 1.8, hence crappy O(n) access.
+      string.length.times do |i|
+        # Crappy O(n) access here.
+        char = string[i, 1]
+
+        case char
+        when " ", "\t"
+          if char == " "
+            spacing = " "
+            spacing_w = space_w
+          elsif char == "\t"
+            spacing = tab
+            spacing_w = tab_w
+          end
+
+          if x + word_w + spacing_w > width
+            lines.push word + spacing
+            x = word_w + spacing_w
+          else
+            lines[-1] += word + spacing
+            x += word_w + spacing_w
+          end
+
+          word = ""
+          word_w = 0
+
+        when "\n"
+          lines[-1] += word
+          lines.push ""
+          x = 0
+          word = ""
+          word_w = 0
+
+        else
+          char_w = string_w(char)
+
+          if word_w + char_w > width && x == 0
+            # Word is too long for a single line, so split it.
+            lines[-1] += word
+            lines.push ""
+            word = ""
+            word_w = 0
+          elsif x + word_w + char_w > width
+            # Start a new line.
+            x = 0
+            lines.push ""
+          end
+
+          word += char
+          word_w += char_w
+
+        end
+      end
+
+      lines[-1] += word
+      lines.end_x = x + word_w
+
+      lines
+    end
+
+    # Write the given string onto the bitmap at (x, y).
+    def draw_to(bitmap, x, y, string)
+      draw_x = x
+      each_code_point(string) do |pt|
+        glyph = get_glyph(pt)
+        if glyph
+          bitmap.blit glyph, draw_x, y
+          draw_x += glyph.w
+        else
+          draw_x += get_glyph_w(pt)
+        end
+      end
+
+      string
+    end
+
+    private
+
+    # Extract an array of letter glyph Bitmaps from a bitmap font.
+    def letters_from_bitmap_font(font_surface, transparent_color)
+      unless font_surface.w % BITMAP_FONT_LENGTH == 0
+        raise Tea::Error, "Bitmap font cannot be evenly divided into #{BITMAP_FONT_LENGTH} glyphs (w == #{font_surface.w})", caller
+      end
+
+      char_w = font_surface.w / BITMAP_FONT_LENGTH
+      char_h = font_surface.h
+      trans_rgba = transparent_color ? Color.split(transparent_color) : nil
+
+      glyphs = Array.new(BITMAP_FONT_LENGTH) do |char|
+        glyph = Bitmap.new(char_w, char_h, Color::CLEAR)
+        for gy in 0...char_h
+          for gx in 0...char_w
+            color = font_surface.get_rgba(font_surface[char_w * char + gx, gy])
+            glyph[gx, gy] = Color.mix(*color) unless color == trans_rgba
+          end
+        end
+        glyph
+      end
+
+      glyphs
+    end
+
+    # Extract an array of letter glyph Bitmaps from an SFont.
+    def letters_from_sfont(font_surface, transparent_color)
+      detect_x = 0
+      glyphs = Array.new(SFONT_LENGTH) do |i|
+        detect_x += 1 while Tea::Color.mix(*font_surface.get_rgba(font_surface[detect_x, 0])) == Tea::Color::MAGENTA && detect_x < font_surface.w
+        raise Tea::Error, "Expected #{SFONT_LENGTH} letters while loading SFont, got #{i}" if detect_x >= font_surface.w
+
+        char_right_x = detect_x
+        char_right_x += 1 while Tea::Color.mix(*font_surface.get_rgba(font_surface[char_right_x, 0])) != Tea::Color::MAGENTA && char_right_x < font_surface.w
+        char_w = char_right_x - detect_x
+        char_h = font_surface.h
+        trans_rgba = transparent_color ? Color.split(transparent_color) : nil
+
+        glyph = Bitmap.new(char_w, char_h, Color::CLEAR)
+        for gy in 0...char_h
+          for gx in 0...char_w
+            color = font_surface.get_rgba(font_surface[detect_x + gx, gy])
+            glyph[gx, gy] = Color.mix(*color) unless color == trans_rgba
+          end
+        end
+
+        detect_x = char_right_x
+
+        glyph
+      end
+
+      glyphs
+    end
+
+    # Run a block for each code point of the string.
+    def each_code_point(string)
+      if RUBY_1_9
+        string.codepoints do |pt|
+          yield pt
+        end
+      else
+        string.length.times do |i|
+          pt = string[i]
+          yield pt
+        end
+      end
+    end
+
+    # Get the designated width of the glyph associated with the code point.
+    def get_glyph_w(code_point)
+      case @font_type
+      when BITMAP_FONT
+        @glyphs[code_point].w
+      when SFONT
+        if SFONT_START <= code_point && code_point < SFONT_START + SFONT_LENGTH
+          @glyphs[code_point - SFONT_START].w
+        elsif code_point == CODE_POINT_SPACE
+          # Substitute with first char width, like SFont reference library.
+          @glyphs[0].w
+        else
+          0
+        end
+      end
+    end
+
+    # Get the glyph bitmap for the given code point.  May return nil if the
+    # code point doesn't map to any glyph.
+    def get_glyph(code_point)
+      case @font_type
+      when BITMAP_FONT
+        @glyphs[code_point]
+      when SFONT
+        if SFONT_START <= code_point && code_point < SFONT_START + SFONT_LENGTH
+          @glyphs[code_point - SFONT_START]
+        else
+          nil
+        end
+      end
+    end
+
+  end
+
+end