tung-tea 0.0.4 → 0.1.0

data/README.rdoc

@@ -1,4 +1,4 @@
-= tea
+= Tea
 
 <i>For simpler games from a simpler age.</i>
 
@@ -18,7 +18,15 @@ many game engines and APIs.
 
 == Installing
 
-TODO
+First, get Ruby (http://www.ruby-lang.org) if you don't have it already.  Ruby
+1.9 or later is recommended.
+
+Tea is available as a gem on GitHub, so you can install it like so:
+
+  gem install tung-tea -s http://gems.github.com
+
+The rubysdl gem (http://www.kmc.gr.jp/~ohai/rubysdl.en.html) will be installed
+automatically as a dependency of Tea.
 
 
 == Using Tea
@@ -34,7 +42,7 @@ Below is a simple bouncing circle demo.
   Tea::Screen.set_mode 640, 480
 
   x, y = 320, 240
-  dx, dy = rand() * 2 - 1, rand() * 2 - 1
+  dx, dy = rand() * 4 - 2, rand() * 4 - 2
   r = 20
 
   loop do
@@ -77,10 +85,11 @@ What isn't done yet:
 * Screen resizing
 * Handling of alpha in colours for primitives
 
-What's still on the drawing board:
 
-* Timed game loop code
-* Resource management
+== More information
+
+Project page:: http://github.com/tung/tea
+Wiki::         http://wiki.github.com/tung/tea
 
 
 == License
@@ -94,6 +103,6 @@ FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
 details.
 
 You should have received a copy of the GNU Lesser General Public License along
-with Tea.  If not, see <http://www.gnu.org/licenses/>.
+with Tea.  If not, see (http://www.gnu.org/licenses).
 
 Copyright (c) 2009 Tung Nguyen.

data/doc/key_constants.textile

@@ -0,0 +1,129 @@
+These key constants are returned by key events and can be passed into keyboard status checking methods.  The all live in Tea::Kbd, so the 'A' key on your keyboard would be Tea::Kbd::A, for example.
+
+The value of each constant is a Ruby symbol with the same name, which should make debugging easier.
+
+BACKSPACE
+TAB
+ENTER
+PAUSE
+ESCAPE
+SPACE
+EXCLAMATION_MARK
+DOUBLE_QUOTE
+HASH
+DOLLAR
+AMPERSAND
+QUOTE
+OPEN_PAREN
+CLOSE_PAREN
+ASTERISK
+PLUS
+COMMA
+MINUS
+PERIOD
+SLASH
+K0
+K1
+K2
+K3
+K4
+K5
+K6
+K7
+K8
+K9
+COLON
+SEMICOLON
+LESS_THAN
+EQUALS
+GREATER_THAN
+QUESTION_MARK
+AT
+OPEN_SQUARE_BRACKET
+BACKSLASH
+CLOSE_SQUARE_BRACKET
+CARET
+UNDERSCORE
+BACKTICK
+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
+DELETE
+NP0
+NP1
+NP2
+NP3
+NP4
+NP5
+NP6
+NP7
+NP8
+NP9
+NP_PERIOD
+NP_DIVIDE
+NP_MULTIPLY
+NP_MINUS
+NP_PLUS
+NP_ENTER
+NP_EQUALS
+UP
+DOWN
+RIGHT
+LEFT
+INSERT
+HOME
+END
+PAGE_UP
+PAGE_DOWN
+F1
+F2
+F3
+F4
+F5
+F6
+F7
+F8
+F9
+F10
+F11
+F12
+NUM_LOCK
+CAPS_LOCK
+SCROLL_LOCK
+R_SHIFT
+L_SHIFT
+R_CTRL
+L_CTRL
+R_ALT
+L_ALT
+L_SUPER
+R_SUPER
+ALT_GR
+PRINT_SCREEN
+SYS_REQ
+BREAK
+MENU
+EURO

data/doc/key_modifiers.textile

@@ -0,0 +1,19 @@
+Key modifiers are things like Shift or Num Lock that change the meaning of some keys when they're held down or toggled on.  Tea::Kbd::Down and Tea::Kbd::Up events provide modifier information.
+
+The following constants are valid modifiers that also happen to match their keys.  Like the [[Key Constants]], they also live in Tea::Kbd, so the left Shift  key would be Tea::Kbd::L_SHIFT.
+
+L_SHIFT
+R_SHIFT
+L_CTRL
+R_CTRL
+L_ALT
+R_ALT
+NUM_LOCK
+CAPS_LOCK
+ALT_GR
+
+These extra constants can used for convenience. They also live in Tea::Kbd, but aren't physical keys.
+
+SHIFT
+CTRL
+ALT

data/doc/reference.textile

@@ -0,0 +1,204 @@
+This page is manually assembled, so parts of it may become out of date. If something's missing or doesn't exist, let me know.
+
+
+h1. Tea
+
+h2. Tea.init()
+
+Intialise Tea.  This needs to be called before using any of Tea's objects or methods.  May throw Tea::Error if initialisation fails.
+
+h2. Tea::Error
+
+This is the exception class raised when Bad Things happen in any of Tea's objects or methods.
+
+
+h1. Graphics
+
+h2. Tea::Bitmap
+
+A Bitmap is a grid of pixels that holds graphics.  It can be drawn onto and drawn with.
+
+h3. Tea::Bitmap included mixins
+
+Instances of Tea::Bitmap share methods from the following modules:
+
+Tea::Blitting:
+* blit(source_blittable, x, y)
+
+Tea::PrimitiveDrawing:
+* clear()
+* point(x, y, color)
+* rect(x, y, w, h, color)
+* line(x1, y1, x2, y2, color[, {:antialias => false}])
+* circle(x, y, radius, color[, {:outline => false, :antialias => false}])
+
+Note that colours are of the form 0xRRGGBBAA.
+
+h3. Tea::Bitmap.new(image_path)
+
+Create a new Bitmap from an image file.  May raise Tea::Error if it fails.
+
+h3. Tea::Bitmap#w()
+
+The width of the Bitmap in pixels.
+
+h3. Tea::Bitmap#h()
+
+The height of the Bitmap in pixels.
+
+h2. Tea::Screen
+
+Tea::Screen acts much like a Bitmap, except things drawn to it will be displayed on the screen once Tea::Screen.update() is called.
+
+h3. Tea::Screen mixins
+
+Since Tea::Screen is an object and not a class, its mixins add methods to Tea::Screen itself.
+
+Tea::Blitting:
+* blit(source_blittable, x, y)
+
+Tea::PrimitiveDrawing:
+* clear()
+* point(x, y, color)
+* rect(x, y, w, h, color)
+* line(x1, y1, x2, y2, color[, {:antialias => false}])
+* circle(x, y, radius, color[, {:outline => false, :antialias => false}])
+
+Note that colours are of the form 0xRRGGBBAA.
+
+h3. Tea::Screen.set_mode(width, height)
+
+Create a screen window with the given dimensions.  After this, you can start drawing on the screen.  May raise Tea::Error if it fails.
+
+h3. Tea::Screen.update()
+
+Make what has been drawn on the screen visible.
+
+h3. Tea::Screen.w()
+
+The width of the screen in pixels.
+
+h3. Tea::Screen.h()
+
+The height of the screen in pixels.
+
+
+h1. Input and other events
+
+Event handling is the heart and soul of most games, so this subsystem is quite important.
+
+h2. Tea::Event
+
+The Event module allows access to the event queue, and the classes of events that come out.
+
+Events rely on having a screen window, so call Tea::Screen.set_mode before using any of these.
+
+h3. Tea::Event.get(wait=false)
+
+Get the next event in the event queue.  If wait is true and there are no events to return, this method will wait until there is one and return it.  Otherwise, an empty event queue will return nil.  The events that can be returned include:
+
+* *Tea::App::Exit*
+* *Tea::App::Minimized*
+* *Tea::App::Restored*
+
+* *Tea::Kbd::Lost*
+  - i.e. keyboard input focus lost
+* *Tea::Kbd::Gained*
+  - i.e. keyboard input focus gained
+* *Tea::Kbd::Down*
+  - key - keyboard key that was pressed (see [[Key Constants]])
+  - mods - a hash of modifiers active when key was pressed (see [[Key Modifiers]])
+  - char - character generated when the key is typed
+* *Tea::Kbd::Up*
+  - key - keyboard key that was released (see [[Key Constants]])
+  - mods - modifiers active when the key was released (see [[Key Modifiers]])
+
+* *Tea::Mouse::Move*
+  - x, y - coordinates of the mouse
+  - buttons - a hash of mouse buttons to true/false: Tea::Mouse::LEFT, MIDDLE and RIGHT
+* *Tea::Mouse::Lost*
+  - i.e. mouse is no longer in the screen window
+* *Tea::Mouse::Gained*
+  - i.e. mouse is within the screen window
+* *Tea::Mouse::Down*
+  - x, y - coordinates of the mouse when the button was pressed
+  - button - one of Tea::Mouse::LEFT, MIDDLE or RIGHT
+* *Tea::Mouse::Up*
+  - x, y - coordinates of the mouse when the button was released
+  - button - mouse button constant, same as for Tea::Mouse::Down#button
+* *Tea::Mouse::Scroll*
+  - x, y - coordinates of the mouse when the scroll wheel was used
+  - delta - 1 for a downward scroll, -1 for an upward scroll
+
+These returned event objects may have methods that give extra information about the event itself.
+
+May raise Tea::Error if getting an event fails.
+
+h2. Tea::App
+
+As well as the app-related events that spawn from here, this module also provides some app-related status checking.
+
+The methods below will only return different values when Tea::Event.get() is called.
+
+h3. Tea::App.visible?
+
+Returns true if the screen window is visible, i.e. not minimised.
+
+h2. Tea::Kbd
+
+As well as the keyboard-related events that spawn from here, this module also lets you check the status of keys and modifiers.
+
+The methods below will only return different values when Tea::Event.get() is called.
+
+h3. Tea::Kbd.in_app?()
+
+Returns true if the keyboard focus is within the screen window. Most of the time, this means the screen window is in the foreground.
+
+h3. Tea::Kbd.key_down?(key)
+
+Returns true if the key given is being pressed.  See [[Key Constants]].
+
+h3. Tea::Kbd.mod_active?(mod)
+
+Returns true if the modifier is 'active'.
+
+For Shift, Ctrl, Alt and AltGr (not sure on the last one) this means they're being held down.
+
+For Num Lock and Caps Lock, this means their toggle is on.
+
+Tea::Kbd::SHIFT, CTRL and ALT can be passed in for convenience.  See [[Key Modifiers]].
+
+h2. Tea::Mouse
+
+As well as the mouse-related events that spawn from here, this module also lets you check the state of the mouse.
+
+The methods below will only return different values when Tea::Event.get() is called.
+
+h3. Tea::Mouse.in_app?()
+
+Returns true if the mouse cursor is over the screen window.  If there are other windows in front of the screen window, this can still return true, depending on your environment.
+
+h3. Tea::Mouse.x()
+
+Get the x part of the mouse coordinates.
+
+h3. Tea::Mouse.y()
+
+Get the y part of the mouse coordinates.
+
+h3. Tea::Mouse.left?()
+
+Returns true when the left mouse button is held down.
+
+h3. Tea::Mouse.middle?()
+
+Returns true when the middle mouse button is held down.
+
+h3. Tea::Mouse.right?()
+
+Returns true when the right mouse button is held down.
+
+
+h1. Sound
+
+Nothing yet.

data/lib/tea/m_primitive_drawing.rb

@@ -47,8 +47,8 @@ module Tea
                                  (options[:antialias] if options)
     end
 
-    # Draw a circle centred at (x, y) with the given radius and color.
-    # Optional hash arguments:
+    # Draw a circle centred at (x, y) with the given radius and color
+    # (0xRRGGBBAA).  Optional hash arguments:
     #
     # +:outline+::    If true, do not fill the circle, just draw an outline.
     # +:antialias+::  If true, smooth the edges of the circle with
@@ -67,10 +67,20 @@ module Tea
     # Convert hex_color of the form 0xRRGGBBAA to a color value the
     # primitive_buffer understands.
     def primitive_color(hex_color)
+      primitive_rgba_to_color(*primitive_hex_to_rgba(hex_color))
+    end
+
+    # Break hex_color from the form 0xRRGGBBAA to [red, green, blue, alpha].
+    def primitive_hex_to_rgba(hex_color)
       red   = (hex_color & 0xff000000) >> 24
       green = (hex_color & 0x00ff0000) >> 16
       blue  = (hex_color & 0x0000ff00) >>  8
       alpha = (hex_color & 0x000000ff)
+      [red, green, blue, alpha]
+    end
+
+    # Generate a colour compatible with the primitive buffer.
+    def primitive_rgba_to_color(red, green, blue, alpha=255)
       primitive_buffer.map_rgba(red, green, blue, alpha)
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tung-tea
 version: !ruby/object:Gem::Version 
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors: 
 - Tung Nguyen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-07-25 00:00:00 -07:00
+date: 2009-07-26 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -52,6 +52,9 @@ files:
 - doc/example/state_app.rb
 - doc/example/state_keyboard.rb
 - doc/example/state_mouse.rb
+- doc/key_constants.textile
+- doc/key_modifiers.textile
+- doc/reference.textile
 - lib/tea.rb
 - lib/tea/c_bitmap.rb
 - lib/tea/c_error.rb
@@ -63,7 +66,7 @@ files:
 - lib/tea/m_primitive_drawing.rb
 - lib/tea/screen.rb
 has_rdoc: false
-homepage: 
+homepage: http://github.com/tung/tea
 post_install_message: 
 rdoc_options: 
 - --charset=UTF-8