allegro4r 0.0.1

data/ext/a4r_API_graphics_modes.c

@@ -0,0 +1,155 @@
+#include "allegro4r.h"
+
+/*
+ * call-seq:
+ *   set_gfx_mode(card, w, h, v_w, v_h) -> int
+ *
+ * Switches into graphics mode. The card parameter should usually be one of the
+ * Allegro magic drivers (read introduction of chapter "Graphics modes") or see
+ * the platform specific documentation for a list of the available drivers. The
+ * w and h parameters specify what screen resolution you want. The color depth
+ * of the graphic mode has to be specified before calling this function with
+ * set_color_depth.
+ *
+ * The v_w and v_h parameters specify the minimum virtual screen size, in case
+ * you need a large virtual screen for hardware scrolling or page flipping. You
+ * should set them to zero if you don't care about the virtual screen size.
+ *
+ * When you call set_gfx_mode, the v_w and v_h parameters represent the minimum
+ * size of virtual screen that is acceptable for your program. The range of
+ * possible sizes is usually very restricted, and Allegro may end up creating a
+ * virtual screen much larger than the one you request. Allowed sizes are driver
+ * dependent and some drivers do not allow virtual screens that are larger than
+ * the visible screen at all: don't assume that whatever you pass will always
+ * work.
+ *
+ * In mode-X the virtual width can be any multiple of eight greater than or
+ * equal to the physical screen width, and the virtual height will be set
+ * accordingly (the VGA has 256k of vram, so the virtual height will be
+ * 256*1024/virtual_width).
+ *
+ * Currently, using a big virtual screen for page flipping is considered bad
+ * practice. There are platforms which don't support virtual screens bigger than
+ * the physical screen but can create different video pages to flip back and
+ * forth. This means that, if you want page flipping and aren't going to use
+ * hardware scrolling, you should call set_gfx_mode with (0,0) as the virtual
+ * screen size and later create the different video pages with
+ * create_video_bitmap. Otherwise your program will be limited to the platforms
+ * supporting hardware scrolling.
+ *
+ * After you select a graphics mode, the physical and virtual screen sizes can
+ * be checked with the macros SCREEN_W, SCREEN_H, VIRTUAL_W, and VIRTUAL_H.
+ *
+ * Return value: Returns zero on success. On failure returns a negative number
+ * and stores a description of the problem in allegro_error.
+ */
+VALUE a4r_API_set_gfx_mode(VALUE self, VALUE card, VALUE w, VALUE h, VALUE v_w, VALUE v_h)
+{
+  return INT2FIX(set_gfx_mode(NUM2INT(card), FIX2INT(w), FIX2INT(h), FIX2INT(v_w), FIX2INT(v_h)));
+}
+
+/*
+ * call-seq:
+ *   set_display_switch_mode(mode) -> int
+ *
+ * Sets how the program should handle being switched into the background, if the
+ * user tabs away from it. Not all of the possible modes will be supported by
+ * every graphics driver on every platform. The available modes are:
+ * SWITCH_NONE::
+ *   Disables switching. This is the default in single-tasking systems like DOS.
+ *   It may be supported on other platforms, but you should use it with caution,
+ *   because your users won't be impressed if they want to switch away from your
+ *   program, but you don't let them!
+ * SWITCH_PAUSE::
+ *   Pauses the program whenever it is in the background. Execution will be
+ *   resumed as soon as the user switches back to it. This is the default in
+ *   most fullscreen multitasking environments, for example the Linux console,
+ *   but not under Windows.
+ * SWITCH_AMNESIA::
+ *   Like SWITCH_PAUSE, but this mode doesn't bother to remember the contents of
+ *   video memory, so the screen, and any video bitmaps that you have created,
+ *   will be erased after the user switches away and then back to your program.
+ *   This is not a terribly useful mode to have, but it is the default for the
+ *   fullscreen drivers under Windows because DirectDraw is too dumb to
+ *   implement anything better.
+ * SWITCH_BACKGROUND::
+ *   The program will carry on running in the background, with the screen bitmap
+ *   temporarily being pointed at a memory buffer for the fullscreen drivers.
+ *   You must take special care when using this mode, because bad things will
+ *   happen if the screen bitmap gets changed around when your program isn't
+ *   expecting it (see below).
+ * SWITCH_BACKAMNESIA::
+ *   Like SWITCH_BACKGROUND, but this mode doesn't bother to remember the
+ *   contents of video memory (see SWITCH_AMNESIA). It is again the only mode
+ *   supported by the fullscreen drivers under Windows that lets the program
+ *   keep running in the background.
+ *
+ * Note that you should be very careful when you are using graphics routines in
+ * the switching context: you must always call acquire_screen before the start
+ * of any drawing code onto the screen and not release it until you are
+ * completely finished, because the automatic locking mechanism may not be good
+ * enough to work when the program runs in the background or has just been
+ * raised in the foreground.
+ *
+ * Return value: Returns zero on success, invalidating at the same time all
+ * callbacks previously registered with set_display_switch_callback. Returns -1
+ * if the requested mode is not currently possible. 
+ */
+VALUE a4r_API_set_display_switch_mode(VALUE self, VALUE mode)
+{
+  return INT2FIX(set_display_switch_mode(FIX2INT(mode)));
+}
+
+/*
+ * call-seq:
+ *   show_video_bitmap(bitmap) -> int
+ *
+ * Attempts to page flip the hardware screen to display the specified video
+ * bitmap object, which must be the same size as the physical screen, and should
+ * have been obtained by calling the create_video_bitmap function.
+ *
+ * Allegro will handle any necessary vertical retrace synchronisation when page
+ * flipping, so you don't need to call vsync before it. This means that
+ * show_video_bitmap has the same time delay effects as vsync by default. This
+ * can be adjusted with the "disable_vsync" config key in the [graphics] section
+ * of allegro.cfg. Example:
+ *   video_page = Array.new
+ *   ...
+ *   # Create pages for page flipping
+ *   video_page[0] = create_video_bitmap(SCREEN_W, SCREEN_H)
+ *   video_page[1] = create_video_bitmap(SCREEN_W, SCREEN_H)
+ *   current_page = 0
+ *   ...
+ *   # draw the screen and flip pages
+ *   draw_screen(video_page[current_page])
+ *   show_video_bitmap(video_page[current_page])
+ *   current_page = (current_page + 1) % 2
+ *   ...
+ *
+ * Return value: Returns zero on success and non-zero on failure.
+ */
+VALUE a4r_API_show_video_bitmap(VALUE self, VALUE bitmap)
+{
+  BITMAP *bmp;
+  Data_Get_Struct(bitmap, BITMAP, bmp);
+  return INT2FIX(show_video_bitmap(bmp));
+}
+
+/*
+ * call-seq:
+ *   vsync -> nil
+ *
+ * Waits for a vertical retrace to begin. The retrace happens when the electron
+ * beam in your monitor has reached the bottom of the screen and is moving back
+ * to the top ready for another scan. During this short period the graphics card
+ * isn't sending any data to the monitor, so you can do things to it that aren't
+ * possible at other times, such as altering the palette without causing
+ * flickering (snow). Allegro will automatically wait for a retrace before
+ * altering the palette or doing any hardware scrolling, though, so you don't
+ * normally need to bother with this function.
+ */
+VALUE a4r_API_vsync(VALUE self)
+{
+  vsync();
+  return Qnil;
+}

data/ext/a4r_API_joystick_routines.c

@@ -0,0 +1,213 @@
+#include "allegro4r.h"
+
+/*
+ * call-seq:
+ *   install_joystick(type) -> int
+ *
+ * Installs Allegro's joystick handler, and calibrates the centre position
+ * values. The type parameter should usually be JOY_TYPE_AUTODETECT, or see the
+ * platform specific documentation for a list of the available drivers. You must
+ * call this routine before using any other joystick functions, and you should
+ * make sure that all joysticks are in the middle position at the time. Example:
+ *   textout_centre_ex(screen, font,
+ *                     "Center the joystick and press a key",
+ *                     SCREEN_W()/2, SCREEN_H()/2, red_color, -1)
+ *   readkey
+ *   if install_joystick(JOY_TYPE_AUTODETECT) != 0
+ *     abort_on_error("Error initialising joystick!")
+ *   end
+ *
+ * Return value: Returns zero on success. As soon as you have installed the
+ * joystick module, you will be able to read the button state and digital
+ * (on/off toggle) direction information, which may be enough for some games. If
+ * you want to get full analogue input, though, you need to use the
+ * calibrate_joystick functions to measure the exact range of the inputs: see
+ * below.
+ */
+VALUE a4r_API_install_joystick(VALUE self, VALUE type)
+{
+  return INT2FIX(install_joystick(FIX2INT(type)));
+}
+
+/*
+ * call-seq:
+ *   poll_joystick -> int
+ *
+ * The joystick handler is not interrupt driven, so you need to call this
+ * function every now and again to update the global position values. Example:
+ *   loop do
+ *     # Get joystick input
+ *     poll_joystick
+ *
+ *     # Process input for the first joystick
+ *     if joy[0].button[0].b
+ *       first_button_pressed
+ *     end
+ *
+ *     if joy[0].button[1].b
+ *       second_button_pressed
+ *     end
+ *     ...
+ *     break if done
+ *   end
+ *
+ * Return value: Returns zero on success or a negative number on failure
+ * (usually because no joystick driver was installed).
+ */
+VALUE a4r_API_poll_joystick(VALUE self)
+{
+  return INT2FIX(poll_joystick());
+}
+
+/*
+ * call-seq:
+ *   num_joysticks -> int
+ *
+ * Global variable containing the number of active joystick devices. The current
+ * drivers support a maximum of eight controllers.
+ */
+VALUE a4r_API_num_joysticks(VALUE self)
+{
+  // TODO: Convert to data struct or cached or hooked variable?
+  return INT2FIX(num_joysticks);
+}
+
+/*
+ * call-seq:
+ *   joy -> ary
+ *
+ * Global array of joystick state information, which is updated by the
+ * poll_joystick function. Only the first num_joysticks elements will contain
+ * meaningful information. Joystick info is described by the JOYSTICK_INFO
+ * class.
+ *
+ * The button status is stored in the JOYSTICK_BUTTON_INFO class.
+ *
+ * You may wish to display the button names as part of an input configuration
+ * screen to let the user choose what game function will be performed by each
+ * button, but in simpler situations you can safely assume that the first two
+ * elements in the button array will always be the main trigger controls.
+ *
+ * Each joystick will provide one or more stick inputs, of varying types. These
+ * can be digital controls which snap to specific positions (eg. a gamepad
+ * controller, the coolie hat on a Flightstick Pro or Wingman Extreme, or a
+ * normal joystick which hasn't yet been calibrated), or they can be full
+ * analogue inputs with a smooth range of motion. Sticks may also have different
+ * numbers of axes, for example a normal directional control has two, but the
+ * Flightstick Pro throttle is only a single axis, and it is possible that the
+ * system could be extended in the future to support full 3d controllers. A
+ * stick input is described by the JOYSTICK_STICK_INFO class.
+ *
+ * A single joystick may provide several different stick inputs, but you can
+ * safely assume that the first element in the stick array will always be the
+ * main directional controller.
+ *
+ * Information about each of the stick axis is stored in the subclass
+ * JOYSTICK_AXIS_INFO.
+ *
+ * This provides both analogue input in the pos field (ranging from -128 to 128
+ * or from 0 to 255, depending on the type of the control), and digital values
+ * in the d1 and d2 fields. For example, when describing the X-axis position,
+ * the pos field will hold the horizontal position of the joystick, d1 will be
+ * set if it is moved left, and d2 will be set if it is moved right. Allegro
+ * will fill in all these values regardless of whether it is using a digital or
+ * analogue joystick, emulating the pos field for digital inputs by snapping it
+ * to the min, middle, and maximum positions, and emulating the d1 and d2 values
+ * for an analogue stick by comparing the current position with the centre
+ * point.
+ *
+ * The joystick flags field may contain any combination of the bit flags:
+ *
+ * JOYFLAG_DIGITAL
+ * This control is currently providing digital input.
+ *
+ * JOYFLAG_ANALOGUE
+ * This control is currently providing analogue input.
+ *
+ * JOYFLAG_CALIB_DIGITAL
+ * This control will be capable of providing digital input once it has been
+ * calibrated, but is not doing this at the moment.
+ *
+ * JOYFLAG_CALIB_ANALOGUE
+ * This control will be capable of providing analogue input once it has been
+ * calibrated, but is not doing this at the moment.
+ *
+ * JOYFLAG_CALIBRATE
+ * Indicates that this control needs to be calibrated. Many devices require
+ * multiple calibration steps, so you should call the calibrate_joystick
+ * function from a loop until this flag is cleared.
+ *
+ * JOYFLAG_SIGNED
+ * Indicates that the analogue axis position is in signed format, ranging from
+ * -128 to 128. This is the case for all 2d directional controls.
+ *
+ * JOYFLAG_UNSIGNED
+ * Indicates that the analogue axis position is in unsigned format, ranging from
+ * 0 to 255. This is the case for all 1d throttle controls.
+ *
+ * Note for people who spell funny: in case you don't like having to type
+ * "analogue", there are some aliases h that will allow you to write "analog"
+ * instead.
+ */
+VALUE a4r_API_joy(VALUE self)
+{
+  VALUE ret = rb_ary_new2(num_joysticks);
+  long x;
+  for (x = 0; x < num_joysticks; x++)
+  {
+    VALUE obj = Data_Wrap_Struct(cAPI_JOYSTICK_INFO, 0, 0, &(joy[x]));
+    rb_ary_store(ret, x, obj);
+  }
+
+  return ret;
+}
+
+/*
+ * call-seq:
+ *   calibrate_joystick_name(n) -> str
+ *
+ * Pass the number of the joystick you want to calibrate as the parameter.
+ *
+ * Return value: Returns a text description for the next type of calibration
+ * that will be done on the specified joystick, or nil if no more calibration is
+ * required.
+ */
+VALUE a4r_API_calibrate_joystick_name(VALUE self, VALUE n)
+{
+  const char *s = calibrate_joystick_name(FIX2INT(n));
+  if (s == NULL)
+    return Qnil;
+  else
+    return rb_str_new2(s);
+}
+
+/*
+ * call-seq:
+ *   calibrate_joystick(n) -> int
+ *
+ * Most joysticks need to be calibrated before they can provide full analogue
+ * input. This function performs the next operation in the calibration series
+ * for the specified stick, assuming that the joystick has been positioned in
+ * the manner described by a previous call to calibrate_joystick_name, returning
+ * zero on success. For example, a simple routine to fully calibrate all the
+ * joysticks might look like:
+ *   (0...num_joysticks).each do |i|
+ *     while joy[i].flags & JOYFLAG_CALIBRATE != 0
+ *       msg = calibrate_joystick_name(i)
+ *       textprintf_ex(..., "%s, and press a key\n" % msg)
+ *       readkey
+ *       if calibrate_joystick(i) != 0
+ *         textprintf_ex(..., "oops!\n")
+ *         readkey
+ *         exit 1
+ *       end
+ *     end
+ *   end
+ *
+ * Return value: Returns zero on success, non-zero if the calibration could not
+ * be performed successfully.
+ */
+VALUE a4r_API_calibrate_joystick(VALUE self, VALUE n)
+{
+  return INT2FIX(calibrate_joystick(FIX2INT(n)));
+}

data/ext/a4r_API_keyboard_routines.c

@@ -0,0 +1,420 @@
+#include "allegro4r.h"
+
+/*
+ * call-seq:
+ *   install_keyboard -> int
+ *
+ * Installs the Allegro keyboard interrupt handler. You must call this before
+ * using any of the keyboard input routines. Once you have set up the Allegro
+ * handler, you can no longer use operating system calls or C library functions
+ * to access the keyboard.
+ *
+ * Note that on some platforms the keyboard won't work unless you have set a
+ * graphics mode, even if this function returns a success value before calling
+ * set_gfx_mode. This can happen in environments with graphic windowed modes,
+ * since Allegro usually reads the keyboard through the graphical window (which
+ * appears after the set_gfx_mode call). Example:
+ *   allegro_init
+ *   install_timer
+ *   install_keyboard
+ *   # We are not 100% sure we can read the keyboard yet!
+ *   if set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0
+ *     abort_on_error("Couldn't set graphic mode!")
+ *   end
+ *
+ *   # Now we are guaranteed to be able to read the keyboard.
+ *   readkey
+ *
+ * Return value: Returns zero on success, or a negative number on failure (but
+ * you may decide not to check the return value as this function is very
+ * unlikely to fail).
+ */
+VALUE a4r_API_install_keyboard(VALUE self)
+{
+  return INT2FIX(install_keyboard());
+}
+
+/*
+ * call-seq:
+ *   poll_keyboard -> int
+ *
+ * Wherever possible, Allegro will read the keyboard input asynchronously (ie.
+ * from inside an interrupt handler), but on some platforms that may not be
+ * possible, in which case you must call this routine at regular intervals to
+ * update the keyboard state variables.
+ *
+ * To help you test your keyboard polling code even if you are programming on a
+ * platform that doesn't require it, after the first time that you call this
+ * function Allegro will switch into polling mode, so from that point onwards
+ * you will have to call this routine in order to get any keyboard input at all,
+ * regardless of whether the current driver actually needs to be polled or not.
+ *
+ * The keypressed, readkey, and ureadkey functions call poll_keyboard
+ * automatically, so you only need to use this function when accessing the
+ * key array and key_shifts variable.
+ *
+ * Return value: Returns zero on success, or a negative number on failure (ie.
+ * no keyboard driver installed).
+ */
+VALUE a4r_API_poll_keyboard(VALUE self)
+{
+  return INT2FIX(poll_keyboard());
+}
+
+/*
+ * call-seq:
+ *   key -> ary
+ *
+ * Array of flags indicating the state of each key, ordered by scancode.
+ * Wherever possible these values will be updated asynchronously, but if
+ * keyboard_needs_poll returns true, you must manually call poll_keyboard to
+ * update them with the current input state. The scancodes are defined as a
+ * series of KEY_* constants (and are also listed below). For example, you could
+ * write:
+ *   printf("Space is pressed\n") if key[KEY_SPACE]
+ *
+ * Note that the array is supposed to represent which keys are physically held
+ * down and which keys are not, so it is semantically read-only.
+ *
+ * These are the keyboard scancodes:
+ *   KEY_A ... KEY_Z,
+ *   KEY_0 ... KEY_9,
+ *   KEY_0_PAD ... KEY_9_PAD,
+ *   KEY_F1 ... KEY_F12,
+ *
+ *   KEY_ESC, KEY_TILDE, KEY_MINUS, KEY_EQUALS,
+ *   KEY_BACKSPACE, KEY_TAB, KEY_OPENBRACE, KEY_CLOSEBRACE,
+ *   KEY_ENTER, KEY_COLON, KEY_QUOTE, KEY_BACKSLASH,
+ *   KEY_BACKSLASH2, KEY_COMMA, KEY_STOP, KEY_SLASH,
+ *   KEY_SPACE,
+ *
+ *   KEY_INSERT, KEY_DEL, KEY_HOME, KEY_END, KEY_PGUP,
+ *   KEY_PGDN, KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN,
+ *
+ *   KEY_SLASH_PAD, KEY_ASTERISK, KEY_MINUS_PAD,
+ *   KEY_PLUS_PAD, KEY_DEL_PAD, KEY_ENTER_PAD,
+ *
+ *   KEY_PRTSCR, KEY_PAUSE,
+ *
+ *   KEY_ABNT_C1, KEY_YEN, KEY_KANA, KEY_CONVERT, KEY_NOCONVERT,
+ *   KEY_AT, KEY_CIRCUMFLEX, KEY_COLON2, KEY_KANJI,
+ *
+ *   KEY_LSHIFT, KEY_RSHIFT,
+ *   KEY_LCONTROL, KEY_RCONTROL,
+ *   KEY_ALT, KEY_ALTGR,
+ *   KEY_LWIN, KEY_RWIN, KEY_MENU,
+ *   KEY_SCRLOCK, KEY_NUMLOCK, KEY_CAPSLOCK
+ *
+ *   KEY_EQUALS_PAD, KEY_BACKQUOTE, KEY_SEMICOLON, KEY_COMMAND
+ *
+ * Finally, you may notice an 'odd' behaviour of the KEY_PAUSE key. This key
+ * only generates an interrupt when it is pressed, not when it is released. For
+ * this reason, Allegro pretends the pause key is a 'state' key, which is the
+ * only way to make it usable.
+ */
+VALUE a4r_API_key(VALUE self)
+{
+  // TODO: Convert to data struct or cached or hooked variable?
+  //       make [] access directly without array conversion?
+  VALUE ret = rb_ary_new2(KEY_MAX);
+  long x;
+  for (x = KEY_A; x <= KEY_MAX; x++)
+    rb_ary_store(ret, x, key[x] == 0 ? Qfalse : Qtrue);
+  return ret;
+}
+
+/*
+ * call-seq:
+ *   key_shifts -> int
+ *
+ * Bitmask containing the current state of shift/ctrl/alt, the special Windows
+ * keys, and the accent escape characters. Wherever possible this value will be
+ * updated asynchronously, but if keyboard_needs_poll returns true, you must
+ * manually call poll_keyboard to update it with the current input state. This
+ * can contain any of the flags:
+ *   KB_SHIFT_FLAG
+ *   KB_CTRL_FLAG
+ *   KB_ALT_FLAG
+ *   KB_LWIN_FLAG
+ *   KB_RWIN_FLAG
+ *   KB_MENU_FLAG
+ *   KB_COMMAND_FLAG
+ *   KB_SCROLOCK_FLAG
+ *   KB_NUMLOCK_FLAG
+ *   KB_CAPSLOCK_FLAG
+ *   KB_INALTSEQ_FLAG
+ *   KB_ACCENT1_FLAG
+ *   KB_ACCENT2_FLAG
+ *   KB_ACCENT3_FLAG
+ *   KB_ACCENT4_FLAG
+ *
+ * Example:
+ *   if key[KEY_W]
+ *     if key_shifts & KB_SHIFT_FLAG != 0
+ *        # User is pressing shift + W.
+ *     else
+ *        # Hmmm... lower case W then.
+ *     end
+ *   end
+ */
+VALUE a4r_API_key_shifts(VALUE self)
+{
+  // TODO: Convert to data struct or cached or hooked variable?
+  return INT2FIX(key_shifts);
+}
+
+/*
+ * call-seq:
+ *   keypressed -> true or false
+ *
+ * Returns true if there are keypresses waiting in the input buffer. You can use
+ * this to see if the next call to readkey is going to block or to simply wait
+ * for the user to press a key while you still update the screen possibly
+ * drawing some animation. Example:
+ *   while !keypressed do
+ *     # Show cool animated logo.
+ *   end
+ *   # So he skipped our title screen.
+ */
+VALUE a4r_API_keypressed(VALUE self)
+{
+  return keypressed() ? Qtrue : Qfalse;
+}
+
+/*
+ * call-seq:
+ *   readkey -> int
+ *
+ * Returns the next character from the keyboard buffer, in ASCII format. If the
+ * buffer is empty, it waits until a key is pressed. You can see if there are
+ * queued keypresses with keypressed.
+ *
+ * The low byte of the return value contains the ASCII code of the key, and the
+ * high byte the scancode. The scancode remains the same whatever the state of
+ * the shift, ctrl and alt keys, while the ASCII code is affected by shift and
+ * ctrl in the normal way (shift changes case, ctrl+letter gives the position of
+ * that letter in the alphabet, eg. ctrl+A = 1, ctrl+B = 2, etc). Pressing
+ * alt+key returns only the scancode, with a zero ASCII code in the low byte.
+ * For example:
+ *   val = readkey
+ *   if (val & 0xff) == 'd'      # by ASCII code
+ *     allegro_message("You pressed 'd'\n")
+ *   end
+ *
+ *   if (val >> 8) == KEY_SPACE  # by scancode
+ *     allegro_message("You pressed Space\n");
+ *   end
+ *
+ *   if (val & 0xff) == 3        # ctrl+letter
+ *     allegro_message("You pressed Control+C\n");
+ *   end
+ *
+ *   if val == (KEY_X << 8)      # alt+letter
+ *     allegro_message("You pressed Alt+X\n");
+ *   end
+ *
+ * This function cannot return character values greater than 255. If you need to
+ * read Unicode input, use ureadkey instead.
+ */
+VALUE a4r_API_readkey(VALUE self)
+{
+  return INT2FIX(readkey());
+}
+
+/*
+ * call-seq:
+ *   ureadkey(scancode) -> int
+ *   ureadkey(scancode) -> [int, int]
+ *
+ * Returns the next character from the keyboard buffer, in Unicode format. If
+ * the buffer is empty, it waits until a key is pressed. You can see if there
+ * are queued keypresses with keypressed. The return value contains the Unicode
+ * value of the key, and if not nil or false, the second return value will be
+ * set to the scancode. Unlike readkey, this function is able to return
+ * character values greater than 255. Example:
+ *   val, scancode = ureadkey(true)
+ *   if val == 0x00F1
+ *     allegro_message("You pressed n with tilde\n")
+ *   end
+ *
+ *   if val == 0x00DF
+ *     allegro_message("You pressed sharp s\n")
+ *   end
+ *
+ * You should be able to find Unicode character maps at http://www.unicode.org/.
+ * Remember that on DOS you must specify a custom keyboard map (like those found
+ * in 'keyboard.dat') usually with the help of a configuration file specifying
+ * the language mapping (keyboard variable in system section of 'allegro.cfg'),
+ * or you will get the default US keyboard mapping.
+ *
+ * *** The Ruby method signature differs from the Allegro method signature. The
+ * Allegro signature takes scancode by reference, but the Ruby signature takes a
+ * boolean.  If false or nil, the method returns only the read key, otherwise it
+ * returns an array containing the read key and the scancode.
+ */
+VALUE a4r_API_ureadkey(VALUE self, VALUE scancode)
+{
+  int s;
+  int *s_p = NULL;
+
+  if (RTEST(scancode))
+    s_p = &s;
+  int u = ureadkey(s_p);
+
+  VALUE ret;
+  if (s_p)
+    ret = rb_ary_new3(2, INT2FIX(u), INT2FIX(s));
+  else
+    ret = INT2FIX(u);
+
+  return ret;
+}
+
+/*
+ * call-seq:
+ *   scancode_to_name(scancode) -> str
+ *
+ * This function returns a string containing the name of they key with the given
+ * scancode. This is useful if you e.g. let the user choose a key for some
+ * action, and want to display something more meaningful than just the scancode.
+ * Example:
+ *   keyname = scancode_to_name(scancode)
+ *   allegro_message("You pressed the %s key." % keyname)
+ */
+VALUE a4r_API_scancode_to_name(VALUE self, VALUE scancode)
+{
+  return rb_str_new2(scancode_to_name(FIX2INT(scancode)));
+}
+
+/*
+ * call-seq:
+ *   keyboard_callback = proc
+ *
+ * If set, this function is called by the keyboard handler in response to every
+ * keypress. It is passed a copy of the value that is about to be added into the
+ * input buffer, and can either return this value unchanged, return zero to
+ * cause the key to be ignored, or return a modified value to change what
+ * readkey will later return. This routine executes in an interrupt context, so
+ * it must be in locked memory. Example:
+ *   def enigma_scrambler(key)
+ *     # Add one to both the scancode and ascii values.
+ *     return (((key >> 8) + 1) << 8) | ((key & 0xff) + 1)
+ *   end
+ *
+ *   ...
+ *
+ *     install_timer
+ *     LOCK_FUNCTION(:enigma_scrambler)
+ *     install_keyboard
+ *     keyboard_callback = self.method(:enigma_scrambler)
+ *
+ * Note that this callback will be ignored if you also set the unicode keyboard
+ * callback.
+ */
+VALUE a4r_API_keyboard_callback_set(VALUE self, VALUE proc)
+{
+  // TODO: Validate proc and maybe check for 0 in the keyboard_callback_method?
+  // TODO: hooked variable?
+  keyboard_callback_proc = proc;
+  if (proc == Qnil)
+    keyboard_callback = NULL;
+  else
+    keyboard_callback = keyboard_callback_method;
+  return proc;
+}
+
+/*
+ * call-seq:
+ *   keyboard_lowlevel_callback = proc
+ *
+ * If set, this function is called by the keyboard handler in response to every
+ * keyboard event, both presses (including keyboard repeat rate) and releases.
+ * It will be passed a raw keyboard scancode byte (scancodes are 7 bits long),
+ * with the top bit (8th bit) clear if the key has been pressed or set if it was
+ * released. This routine executes in an interrupt context, so it must be in
+ * locked memory. Example:
+ *
+ *   def keypress_watcher(scancode)
+ *     if (scancode & 0x80) != 0
+ *       key_up = 1
+ *     else
+ *       key_down = 1
+ *     end
+ *   end
+ *
+ *   ...
+ *
+ *     install_timer
+ *     LOCK_FUNCTION(silence_g_key)
+ *     LOCK_VARIABLE(key_down)
+ *     LOCK_VARIABLE(key_up)
+ *     install_keyboard
+ *     keyboard_lowlevel_callback = self.method(:keypress_watcher)
+ *     # Disable keyboard repeat to get typewriter effect.
+ *     set_keyboard_rate(0, 0)
+ *
+ *   ...
+ *
+ *     while (game_loop)
+ *       if (key_down == 1)
+ *          key_down = 0
+ *          # Play sample of typewriter key press.
+ *       end
+ *       if (key_up == 1)
+ *          key_up = 0;
+ *          # Play sample of typewriter key release.
+ *       end
+ *     end
+ */
+VALUE a4r_API_keyboard_lowlevel_callback_set(VALUE self, VALUE proc)
+{
+  // TODO: Validate proc and maybe check for 0 in the keyboard_lowlevel_callback_method?
+  // TODO: hooked variable?
+  keyboard_lowlevel_callback_proc = proc;
+  if (proc == Qnil)
+    keyboard_lowlevel_callback = NULL;
+  else
+    keyboard_lowlevel_callback = keyboard_lowlevel_callback_method;
+  return proc;
+}
+
+/*
+ * call-seq:
+ *   clear_keybuf -> nil
+ *
+ * Empties the keyboard buffer. Usually you want to use this in your program
+ * before reading keys to avoid previously buffered keys to be returned by calls
+ * to readkey or ureadkey.
+ */
+VALUE a4r_API_clear_keybuf(VALUE self)
+{
+  clear_keybuf();
+  return Qnil;
+}
+
+/******************************************************************************/
+// Predefined keyboard callback routines
+/*
+ * TODO: The keyboard callback routines are not working as expected.  I thought
+ * I might be able to fake things by setting a global variable to a proc, which
+ * then would get called by the below methods.  Unfortunately, even with no code
+ * in the proc, it crashes ruby.  I'm assuming that since these methods run
+ * in an interrupt context, there is a clash between the Ruby code and the
+ * lowlevel code.
+ */
+
+VALUE keyboard_callback_proc;
+VALUE keyboard_lowlevel_callback_proc;
+
+int keyboard_callback_method(int key)
+{
+  return FIX2INT(rb_funcall(keyboard_callback_proc, CALL_ID, 1, INT2FIX(key)));
+}
+END_OF_FUNCTION(keyboard_callback_method)
+
+void keyboard_lowlevel_callback_method(int scancode)
+{
+  rb_funcall(keyboard_lowlevel_callback_proc, CALL_ID, 1, INT2FIX(scancode));
+}
+END_OF_FUNCTION(keyboard_lowlevel_callback_method)
+