tea 0.6.1

data/lib/tea/m_event_mouse.rb

@@ -0,0 +1,189 @@
+# This file holds the mouse motion and button events.
+
+require 'sdl'
+
+#
+module Tea
+
+  module Mouse
+
+    # Mouse button constants for mouse events.
+    LEFT = :LEFT
+    MIDDLE = :MIDDLE
+    RIGHT = :RIGHT
+
+    # Event generated when the mouse cursor is moved.
+    #
+    # +x+, +y+::    coordinates of the mouse cursor
+    # +buttons+::   an array that may contain +:left+, +:middle+ and +:right+
+    class Move
+      attr_reader :x, :y, :buttons
+      def initialize(sdl_event)
+        @x = sdl_event.x
+        @y = sdl_event.y
+        @buttons = {}
+        @buttons[Mouse::LEFT]   = (sdl_event.state & SDL::Mouse::BUTTON_LMASK) != 0
+        @buttons[Mouse::MIDDLE] = (sdl_event.state & SDL::Mouse::BUTTON_MMASK) != 0
+        @buttons[Mouse::RIGHT]  = (sdl_event.state & SDL::Mouse::BUTTON_RMASK) != 0
+      end
+    end
+
+    # Event generated when a mouse button is held down.
+    #
+    # +x+, +y+::    coordinates of the mouse cursor
+    # +button+::    the mouse button that is down: +:left+, +:middle+ or +:right+
+    class Down
+      attr_reader :x, :y, :button
+      def initialize(sdl_event)
+        @x = sdl_event.x
+        @y = sdl_event.y
+        case sdl_event.button
+        when SDL::Mouse::BUTTON_LEFT   then @button = Mouse::LEFT
+        when SDL::Mouse::BUTTON_MIDDLE then @button = Mouse::MIDDLE
+        when SDL::Mouse::BUTTON_RIGHT  then @button = Mouse::RIGHT
+        end
+      end
+    end
+
+    # Event generated when a mouse button that was held down is released.
+    #
+    # +x+, +y+::    coordinates of the mouse cursor
+    # +button+::    the mouse button that was released: +:left+, +:middle+ or
+    #               +:right+
+    class Up
+      attr_reader :x, :y, :button
+      def initialize(sdl_event)
+        @x = sdl_event.x
+        @y = sdl_event.y
+        case sdl_event.button
+        when SDL::Mouse::BUTTON_LEFT   then @button = Mouse::LEFT
+        when SDL::Mouse::BUTTON_MIDDLE then @button = Mouse::MIDDLE
+        when SDL::Mouse::BUTTON_RIGHT  then @button = Mouse::RIGHT
+        end
+      end
+    end
+
+    # Event generated when the mouse wheel is scrolled.
+    #
+    # +x+, +y+::    coordinates of the mouse cursor.
+    # +delta+::     1 when scrolling down, -1 when scrolling up.
+    class Scroll
+      attr_reader :x, :y, :delta
+      def initialize(sdl_event)
+        @x = sdl_event.x
+        @y = sdl_event.y
+        case sdl_event.button
+        when Event::BUTTON_WHEELDOWN_ then @delta = 1
+        when Event::BUTTON_WHEELUP_   then @delta = -1
+        else
+          raise Tea::Error, "Tea::Mouse::Scroll given an unexpected event: #{sdl_event.inspect}", caller
+        end
+      end
+    end
+
+    # Defaults for Mouse.x, Mouse.y, Mouse.left?, Mouse.middle?, Mouse.right?
+    # and Mouse.in_app?
+    @x = 0
+    @y = 0
+    @left = false
+    @middle = false
+    @right = false
+    @in_app = false
+
+    # Report the x position of the mouse in the screen window.  Updated when
+    # Event.get is called.
+    def Mouse.x
+      @x
+    end
+
+    # Report the y position of the mouse in the screen window.  Updated when
+    # Event.get is called.
+    def Mouse.y
+      @y
+    end
+
+    # Returns true if the left mouse button is down.  Updated when Event.get is
+    # called.
+    def Mouse.left?
+      @left
+    end
+
+    # Returns true if the middle mouse button is down.  Updated when Event.get
+    # is called.
+    def Mouse.middle?
+      @middle
+    end
+
+    # Returns true if the right mouse button is down.  Updated when Event.get
+    # is called.
+    def Mouse.right?
+      @right
+    end
+
+    # Returns true if the mouse is in the screen window
+    def Mouse.in_app?
+      @in_app
+    end
+
+    # Update the mouse state, so that Mouse.x, Mouse.y, Mouse.left?,
+    # Mouse.middle? and Mouse.right? return recent data.
+    def Mouse.update_state(tea_event)
+      case tea_event
+      when Move
+        @x = tea_event.x
+        @y = tea_event.y
+      when Down
+        case tea_event.button
+        when LEFT   then @left = true
+        when MIDDLE then @middle = true
+        when RIGHT  then @right = true
+        end
+      when Up
+        case tea_event.button
+        when LEFT   then @left = false
+        when MIDDLE then @middle = false
+        when RIGHT  then @right = false
+        end
+      when Lost
+        @in_app = false
+      when Gained
+        @in_app = true
+      end
+    end
+  end
+
+  module Event
+
+    # Missing mouse wheel button constants from rubysdl.  For internal use only.
+    BUTTON_WHEELUP_ = 4
+    BUTTON_WHEELDOWN_ = 5
+
+    # Convert a mouse-related SDL::Event into a Tea event.  For internal use only.
+    def Event.translate_mouse_event(sdl_event)
+      out_events = []
+
+      case sdl_event
+      when SDL::Event::MouseMotion
+        out_events.push Mouse::Move.new(sdl_event)
+      when SDL::Event::MouseButtonDown
+        case sdl_event.button
+        when SDL::Mouse::BUTTON_LEFT, SDL::Mouse::BUTTON_MIDDLE, SDL::Mouse::BUTTON_RIGHT
+          out_events.push Mouse::Down.new(sdl_event)
+        when BUTTON_WHEELDOWN_, BUTTON_WHEELUP_
+          out_events.push Mouse::Scroll.new(sdl_event)
+        end
+      when SDL::Event::MouseButtonUp
+        # Ignore MouseButtonUp for the scroll wheel.
+        case sdl_event.button
+        when SDL::Mouse::BUTTON_LEFT, SDL::Mouse::BUTTON_MIDDLE, SDL::Mouse::BUTTON_RIGHT
+          out_events.push Mouse::Up.new(sdl_event)
+        end
+      end
+
+      out_events
+    end
+    private_class_method :translate_mouse_event
+
+  end
+
+end

data/lib/tea/mix_blitting.rb

@@ -0,0 +1,31 @@
+# This file contains the Blitting mixin.
+
+require 'sdl'
+
+#
+module Tea
+
+  # The Blitting mixin allows objects with SDL::Surface to draw or 'blit' onto
+  # each other.
+  #
+  # To use this mixin, include it and write/alias a blitting_buffer method
+  # that gets the SDL::Surface.
+  #
+  #   include Blitting
+  #   def blitting_buffer
+  #     @my_sdl_surface
+  #   end
+  module Blitting
+
+    # Draw the source_blittable onto the current object at (x, y).
+    #
+    # source_blittable needs to include the Blitting mixin too.
+    def blit(source_blittable, x, y)
+      src = source_blittable.blitting_buffer
+      dest = blitting_buffer
+      SDL::Surface.blit src, 0, 0, src.w, src.h, dest, x, y
+    end
+
+  end
+
+end

data/lib/tea/mix_clipping.rb

@@ -0,0 +1,71 @@
+# This file holds the Clipping mixin.
+
+require 'sdl'
+
+#
+module Tea
+
+  # The Clipping mixin enables anything with an SDL-like buffer can get, set
+  # and use a clipping rectangle to restrict where drawing takes place.
+  #
+  # To use the Clipping mixin, include it, and provide a clipping_buffer method
+  # that returns the buffer to be clipped.
+  #
+  #   include Tea::Clipping
+  #   def clipping_buffer
+  #     @sdl_buffer
+  #   end
+  module Clipping
+
+    # Get, set or run a block with a clipping rectangle that restricts where
+    # drawing can take place.
+    #
+    # Getting the current clipping rectangle:
+    #
+    #   x, y, width, height = clippable_object.clip
+    #
+    # Setting a new clipping rectangle:
+    #
+    #   old_x, old_y, old_w, old_h = clippable_object.clip(new_x, new_y, new_w, new_h)
+    #
+    # Running a block with a clipping rectangle temporarily set:
+    #
+    #   clippable_object.clip(clip_x, clip_y, clip_w, clip_h) do
+    #     # Draw onto clippable_object within clip rect here.
+    #   end
+    #
+    def clip(x=nil, y=nil, w=nil, h=nil)
+      buffer = clipping_buffer
+
+      # rubysdl's SDL::Surface#get_clip_rect doesn't return anything useful.
+      # Seems to be a bug, or at least compilation quirk.
+      @clipping_rect = [0, 0, buffer.w, buffer.h] unless @clipping_rect
+      old_clipping_rect = @clipping_rect
+
+      case
+      when !(x || y || w || h)                  # Get clip rect.
+        # Do nothing.
+      when x && y && w && h && !block_given?    # Set clip rect.
+        @clipping_rect = [x, y, w, h]
+        buffer.set_clip_rect *@clipping_rect
+      when x && y && w && h &&  block_given?    # Run block with clip rect.
+        @clipping_rect = [x, y, w, h]
+        buffer.set_clip_rect *@clipping_rect
+        begin
+          yield
+        ensure
+          @clipping_rect = old_clipping_rect
+          buffer.set_clip_rect *old_clipping_rect
+        end
+      else
+        arg_count = 0
+        [x, y, w, h].each { |arg| arg_count += 1 if arg == nil }
+        raise ArgumentError, "wrong number of arguments (#{arg_count} for 0 or 4)", caller
+      end
+
+      old_clipping_rect
+    end
+
+  end
+
+end

data/lib/tea/mix_grabbing.rb

@@ -0,0 +1,86 @@
+# This file contains the Grabbing mixin, which makes a new Bitmap object based
+# on some part of a bitmap-like pixel buffer.
+
+require 'sdl'
+
+require 'tea/c_bitmap'
+require 'tea/m_color'
+
+#
+module Tea
+
+  # This module gives bitmap-like objects a +grab+ method that takes a
+  # 'snapshot' of some part of it and returns it as a new Bitmap.
+  #
+  # To use this mixin, include it and define a +grabbing_buffer+ method:
+  #
+  #   include Grabbing
+  #   def grabbing_buffer
+  #     @my_sdl_buffer
+  #   end
+  #
+  module Grabbing
+
+    # Grab some part of the bitmap-like object, and return it as a new
+    # Tea::Bitmap object.
+    #
+    # This can be called in two ways:
+    #
+    # * ()::            create a deep-copy of the whole bitmap-like object.
+    # * (x, y, w, h)::  copy the pixels within the box at (x, y) of size w * h.
+    #
+    # May raise Tea::Error if the box given (if any) is outside the bitmap.
+    def grab(*box)
+      buffer = grabbing_buffer
+
+      case box.length
+      when 0
+        x = 0
+        y = 0
+        w = buffer.w
+        h = buffer.h
+      when 4
+        if clipped_box = grabbing_clip(*box, 0, 0, buffer.w, buffer.h)
+          x, y, w, h = clipped_box
+        else
+          raise Tea::Error, "cannot grab (#{x}, #{y}, #{w}, #{h}), not within (#{buffer.x}, #{buffer.y}, #{buffer.w}, #{buffer.h})", caller
+        end
+      else
+        raise ArgumentError, "wrong number of arguments (#{box.length} for 0 or 4)", caller
+      end
+
+      bitmap = Bitmap.new(w, h, Tea::Color::CLEAR)
+
+      for buf_y in y...(y + h)
+        for buf_x in x...(x + w)
+          bitmap[buf_x - x, buf_y - y] = Color.mix(*buffer.get_rgba(buffer[buf_x, buf_y]))
+        end
+      end
+
+      bitmap
+    end
+
+    # Keep the rect (x, y, w, h) within the rect (bound_x, bound_y, bound_w, bound_h).
+    #
+    # Returns [in_x, in_y, in_w, in_h], defining a rect like (x, y, w, h), but
+    # within the bounding rect.  Returns nil if the rect given is not within
+    # the bounding rect at all, i.e. w or h would be less than 1.
+    def grabbing_clip(x, y, w, h, bound_x, bound_y, bound_w, bound_h)
+      return nil if x + w <= bound_x || x >= bound_x + bound_w || y + h <= bound_y || y >= bound_y + bound_h
+
+      in_x = (x >= bound_x) ? x : bound_x
+      in_y = (y >= bound_y) ? y : bound_y
+
+      x2 = x + w
+      y2 = y + h
+      in_x2 = (x2 <= bound_x + bound_w) ? x2 : bound_x + bound_w
+      in_y2 = (y2 <= bound_y + bound_h) ? y2 : bound_y + bound_h
+      in_w = in_x2 - in_x
+      in_h = in_y2 - in_y
+
+      [in_x, in_y, in_w, in_h]
+    end
+
+  end
+
+end

data/lib/tea/mix_image_saving.rb

@@ -0,0 +1,70 @@
+# This file holds the ImageSaving mixin.
+
+require 'RMagick'
+require 'sdl'
+
+require 'tea/c_error'
+
+#
+module Tea
+
+  # This mixin allows SDL surface-backed classes to be saved as image files.
+  #
+  # To use, include the mixin and implement an image_saving_buffer method:
+  #
+  #   include ImageSaving
+  #   def image_saving_buffer
+  #     @my_sdl_buffer
+  #   end
+  module ImageSaving
+
+    # Save the object as an image file at the given path.
+    #
+    # The format is determined by the extension at the end of the path.  ".bmp"
+    # will save it as Windows Bitmap image.
+    #
+    # May raise Tea::Error if the desired image file format can't be
+    # determined, or isn't supported.
+    def save(path)
+      extension_match = /\..+$/.match(path)
+
+      if extension_match
+        ext = extension_match[0]
+        case ext
+        when '.bmp'
+          image_saving_buffer.save_bmp path
+        when '.png'
+          image_saving_cheat_save path
+        else
+          raise Tea::Error, "can't determine image format '#{ext}' for saving", caller
+        end
+      else
+        raise Tea::Error, "can't determine desired image file format for #{path}", caller
+      end
+
+    rescue SDL::Error => e
+      raise Tea::Error, e.message, e.backtrace
+    end
+
+    private
+
+    # Cheat by using RMagick to save in formats other than BMP.
+    def image_saving_cheat_save(path)
+      buffer = image_saving_buffer
+
+      buffer_string = String.new
+      for y in 0...buffer.h
+        for x in 0...buffer.w
+          r, g, b, a = buffer.get_rgba(buffer[x, y])
+          buffer_string << r << g << b << a
+        end
+      end
+
+      image = Magick::Image.new(buffer.w, buffer.h)
+      image.import_pixels 0, 0, buffer.h, buffer.w, 'RGBA', buffer_string, Magick::CharPixel
+      image.write path
+    end
+
+  end
+
+end