allegro4r 0.0.1-x86-mswin32-60

data/ext/a4r_API_timer_routines.c

@@ -0,0 +1,250 @@
+#include "allegro4r.h"
+
+/*
+ * call-seq:
+ *   install_timer -> int
+ *
+ * Installs the Allegro timer interrupt handler. You must do this before
+ * installing any user timer routines, and also before displaying a mouse
+ * pointer, playing FLI animations or MIDI music, and using any of the GUI
+ * routines.
+ *
+ * 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_timer(VALUE self)
+{
+  return INT2FIX(install_timer());
+}
+
+/*
+ * call-seq:
+ *   install_int(name, speed) -> int
+ *
+ * Installs a user timer handler, with the speed given as the number of
+ * milliseconds between ticks. This is the same thing as install_int_ex(name,
+ * MSEC_TO_TIMER(speed)). If you call this routine without having first
+ * installed the timer module, install_timer will be called automatically.
+ * Calling again this routine with the same timer handler as parameter allows
+ * you to adjust its speed.
+ *
+ * Return value: Returns zero on success, or a negative number if there is no
+ * room to add a new user timer.
+ *
+ * *** The Ruby method differs from the Allegro method. The Allegro method takes
+ * a function pointer as the first parameter, which it will use as the timer
+ * interrupt callback.  The Ruby method takes a name which will be used to
+ * identify a predefined counter routine which will be used as the interrupt
+ * callback. To get the value for that counter, call timer_counter_get with the
+ * name.
+ */
+VALUE a4r_API_install_int(VALUE self, VALUE name, VALUE speed)
+{
+  VALUE t_speed = LONG2NUM(MSEC_TO_TIMER(FIX2INT(speed)));
+  return a4r_API_install_int_ex(self, name, t_speed);
+}
+
+/*
+ * call-seq:
+ *   install_int_ex(name, speed) -> int
+ *
+ * Adds a function to the list of user timer handlers or, if it is already
+ * installed, retroactively adjusts its speed (i.e makes as though the speed
+ * change occurred precisely at the last tick). The speed is given in hardware
+ * clock ticks, of which there are 1193181 a second. You can convert from other
+ * time formats to hardware clock ticks with the macros:
+ *   SECS_TO_TIMER(secs)  - give the number of seconds between each tick
+ *   MSEC_TO_TIMER(msec)  - give the number of milliseconds between ticks
+ *   BPS_TO_TIMER(bps)    - give the number of ticks each second
+ *   BPM_TO_TIMER(bpm)    - give the number of ticks per minute
+ *
+ * There can only be sixteen timers in use at a time, and some other parts of
+ * Allegro (the GUI code, the mouse pointer display routines, rest, the FLI
+ * player, and the MIDI player) need to install handlers of their own, so you
+ * should avoid using too many at the same time. If you call this routine
+ * without having first installed the timer module, install_timer will be called
+ * automatically. 
+ *
+ * Return value: Returns zero on success, or a negative number if there is no
+ * room to add a new user timer.
+ *
+ * *** The Ruby method differs from the Allegro method. The Allegro method takes
+ * a function pointer as the first parameter, which it will use as the timer
+ * interrupt callback.  The Ruby method takes a name which will be used to
+ * identify a predefined counter routine which will be used as the interrupt
+ * callback. To get the value for that counter, call timer_counter_get with the
+ * name.
+ */
+VALUE a4r_API_install_int_ex(VALUE self, VALUE name, VALUE speed)
+{
+  VALUE i = find_timer_counter(name);
+  if (i == Qnil)
+  {
+    i = find_free_timer_counter();
+    rb_hash_aset(timer_counter_names, name, i);
+    timer_counters[FIX2INT(i)] = 0;
+  }
+
+  return INT2FIX(install_param_int_ex(&timer_counter_incr, (void *)&(timer_counters[FIX2INT(i)]), NUM2INT(speed)));
+}
+
+/*
+ * call-seq:
+ *   LOCK_VARIABLE(variable_name) -> nil
+ *
+ * Due to interrupts, you are required to lock all the memory used by your timer
+ * routines. See the description of install_int_ex for a more detailed
+ * explanation and usage example.
+ *
+ * *** The Ruby method differs from the Allegro method. Due to the use of
+ * predefined timer routines, LOCK_VARIABLE and LOCK_FUNCTION do nothing, and
+ * are here simply for API consistency. They will raise warnings if the Ruby
+ * script is run with -w.
+ */
+VALUE a4r_API_LOCK_VARIABLE(VALUE self, VALUE variable_name)
+{
+  rb_warning("Allegro4r::API::LOCK_VARIABLE does nothing.");
+  return Qnil;
+}
+
+/*
+ * call-seq:
+ *   LOCK_FUNCTION(function_name) -> nil
+ *
+ * See LOCK_VARIABLE.
+ */
+VALUE a4r_API_LOCK_FUNCTION(VALUE self, VALUE function_name)
+{
+  rb_warning("Allegro4r::API::LOCK_FUNCTION does nothing.");
+  return Qnil;
+}
+
+/*
+ * call-seq:
+ *   retrace_count -> int
+ *
+ * If the retrace simulator is installed, this count is incremented on each
+ * vertical retrace; otherwise, if the refresh rate is known, the count is
+ * incremented at the same rate (ignoring retraces); otherwise, it is
+ * incremented 70 times a second. This provides a way of controlling the speed
+ * of your program without installing user timer functions.
+ */
+VALUE a4r_API_retrace_count(VALUE self)
+{
+  // TODO: Convert to data struct or cached or hooked variable?
+  return INT2FIX(retrace_count);
+}
+
+/*
+ * call-seq:
+ *   rest(time) -> nil
+ *
+ * This function waits for the specified number of milliseconds.
+ *
+ * Passing 0 as parameter will not wait, but just yield. This can be useful in
+ * order to "play nice" with other processes. Other values will cause CPU time
+ * to be dropped on most platforms. This will look better to users, and also
+ * does things like saving battery power and making fans less noisy.
+ *
+ * Note that calling this inside your active game loop is a bad idea, as you
+ * never know when the OS will give you the CPU back, so you could end up
+ * missing the vertical retrace and skipping frames. On the other hand, on
+ * multitasking operating systems it is good form to give up the CPU for a while
+ * if you will not be using it.
+ */
+VALUE a4r_API_rest(VALUE self, VALUE time)
+{
+  rest(NUM2UINT(time));
+  return Qnil;
+}
+
+/*
+ * call-seq:
+ *   SECS_TO_TIMER(secs) -> num
+ *
+ * Give the number of seconds between each tick
+ */
+VALUE a4r_API_SECS_TO_TIMER(VALUE self, VALUE secs)
+{
+  return LONG2NUM(SECS_TO_TIMER(NUM2LONG(secs)));
+}
+
+/*
+ * call-seq:
+ *   MSEC_TO_TIMER(msec) -> num
+ *
+ * Give the number of milliseconds between ticks
+ */
+VALUE a4r_API_MSEC_TO_TIMER(VALUE self, VALUE msec)
+{
+  return LONG2NUM(MSEC_TO_TIMER(NUM2LONG(msec)));
+}
+
+/*
+ * call-seq:
+ *   BPS_TO_TIMER(bps) -> num
+ *
+ * Give the number of ticks each second
+ */
+VALUE a4r_API_BPS_TO_TIMER(VALUE self, VALUE bps)
+{
+  return LONG2NUM(BPS_TO_TIMER(NUM2LONG(bps)));
+}
+
+/*
+ * call-seq:
+ *   BPM_TO_TIMER(bpm) -> num
+ *
+ * Give the number of ticks per minute
+ */
+VALUE a4r_API_BPM_TO_TIMER(VALUE self, VALUE bpm)
+{
+  return LONG2NUM(BPM_TO_TIMER(NUM2LONG(bpm)));
+}
+
+/******************************************************************************/
+// Predefined timer counter routines
+
+VALUE timer_counter_names;
+volatile int timer_counters[MAX_TIMER_COUNTERS];
+
+void timer_counter_incr(void *param)
+{
+  *((int *)param) += 1;
+}
+END_OF_FUNCTION(timer_counter_incr)
+
+VALUE find_timer_counter(VALUE name)
+{
+  return rb_hash_aref(timer_counter_names, name);
+}
+
+VALUE find_free_timer_counter()
+{
+  int i;
+  ID f = rb_intern("has_value?");
+  for (i = 0; i < MAX_TIMER_COUNTERS; i++)
+    if (rb_funcall(timer_counter_names, f, 1, INT2FIX(i)) == Qfalse)
+      break;
+
+  if (i == MAX_TIMER_COUNTERS)
+    return Qnil;
+  return INT2FIX(i);
+}
+
+/*
+ * call-seq:
+ *   timer_counter_get(name) -> int
+ *
+ * Returns the value of the specified timer counter.
+ * 
+ * *** This is not an Allegro method. See the Ruby note under install_int_ex.
+ */
+VALUE a4r_API_timer_counter_get(VALUE self, VALUE name)
+{
+  VALUE i = find_timer_counter(name);
+  if (i == Qnil)
+    return i;
+  return INT2FIX(timer_counters[FIX2INT(i)]);
+}

data/ext/a4r_API_transparency_and_patterned_drawing.c

@@ -0,0 +1,87 @@
+#include "allegro4r.h"
+
+/*
+ * call-seq:
+ *   drawing_mode(mode, pattern, x_anchor, y_anchor) -> nil
+ *
+ * Sets the graphics drawing mode. This only affects the geometric routines like
+ * putpixel, lines, rectangles, circles, polygons, floodfill, etc, not the text
+ * output, blitting, or sprite drawing functions. The mode should be one of the
+ * following constants:
+ *   DRAW_MODE_SOLID               - the default, solid color drawing
+ *   DRAW_MODE_XOR                 - exclusive-or drawing
+ *   DRAW_MODE_COPY_PATTERN        - multicolored pattern fill
+ *   DRAW_MODE_SOLID_PATTERN       - single color pattern fill
+ *   DRAW_MODE_MASKED_PATTERN      - masked pattern fill
+ *   DRAW_MODE_TRANS               - translucent color blending
+ *
+ * In DRAW_MODE_SOLID, pixels of the bitmap being drawn onto are simply replaced
+ * by those produced by the drawing function.
+ *
+ * In DRAW_MODE_XOR, pixels are written to the bitmap with an exclusive-or
+ * operation rather than a simple copy, so drawing the same shape twice will
+ * erase it. Because it involves reading as well as writing the bitmap memory,
+ * xor drawing is a lot slower than the normal replace mode.
+ *
+ * With the patterned modes, you provide a pattern bitmap which is tiled across
+ * the surface of the shape. Allegro stores a pointer to this bitmap rather than
+ * copying it, so you must not destroy the bitmap while it is still selected as
+ * the pattern. The width and height of the pattern must be powers of two, but
+ * they can be different, eg. a 64x16 pattern is fine, but a 17x3 one is not.
+ * The pattern is tiled in a grid starting at point (x_anchor, y_anchor).
+ * Normally you should just pass zero for these values, which lets you draw
+ * several adjacent shapes and have the patterns meet up exactly along the
+ * shared edges. Zero alignment may look peculiar if you are moving a patterned
+ * shape around the screen, however, because the shape will move but the pattern
+ * alignment will not, so in some situations you may wish to alter the anchor
+ * position.
+ *
+ * When you select DRAW_MODE_COPY_PATTERN, pixels are simply copied from the
+ * pattern bitmap onto the destination bitmap. This allows the use of
+ * multicolored patterns, and means that the color you pass to the drawing
+ * routine is ignored. This is the fastest of the patterned modes.
+ *
+ * In DRAW_MODE_SOLID_PATTERN, each pixel in the pattern bitmap is compared with
+ * the mask color, which is zero in 256-color modes or bright pink for truecolor
+ * data (maximum red and blue, zero green). If the pattern pixel is solid, a
+ * pixel of the color you passed to the drawing routine is written to the
+ * destination bitmap, otherwise a zero is written. The pattern is thus treated
+ * as a monochrome bitmask, which lets you use the same pattern to draw
+ * different shapes in different colors, but prevents the use of multicolored
+ * patterns.
+ *
+ * DRAW_MODE_MASKED_PATTERN is almost the same as DRAW_MODE_SOLID_PATTERN, but
+ * the masked pixels are skipped rather than being written as zeros, so the
+ * background shows through the gaps.
+ *
+ * In DRAW_MODE_TRANS, the global color_map table or truecolor blender functions
+ * are used to overlay pixels on top of the existing image. This must only be
+ * used after you have set up the color mapping table (for 256 color modes) or
+ * blender functions (for truecolor modes). Because it involves reading as well
+ * as writing the bitmap memory, translucent drawing is very slow if you draw
+ * directly to video RAM, so wherever possible you should use a memory bitmap
+ * instead.
+ */
+VALUE a4r_API_drawing_mode(VALUE self, VALUE mode, VALUE pattern, VALUE x_anchor, VALUE y_anchor)
+{
+  BITMAP *bitmap;
+  if (pattern == Qnil)
+    bitmap = NULL;
+  else
+    Data_Get_Struct(pattern, BITMAP, bitmap);
+  drawing_mode(FIX2INT(mode), bitmap, FIX2INT(x_anchor), FIX2INT(y_anchor));
+  return Qnil;
+}
+
+/*
+ * call-seq:
+ *   solid_mode -> nil
+ *
+ * This is a shortcut for selecting solid drawing mode. It is equivalent to
+ * calling drawing_mode(DRAW_MODE_SOLID, nil, 0, 0).
+ */
+VALUE a4r_API_solid_mode(VALUE self)
+{
+  solid_mode();
+  return Qnil;
+}

data/ext/a4r_API_truecolor_pixel_formats.c

@@ -0,0 +1,44 @@
+#include "allegro4r.h"
+
+/*
+ * call-seq:
+ *   make_col(r, g, b) -> a_rgb
+ *
+ * Converts colors from a hardware independent format (red, green, and blue
+ * values ranging 0-255) to the pixel format required by the current video mode,
+ * calling the preceding 8, 15, 16, 24, or 32-bit makecol functions as
+ * appropriate. Example:
+ *   # Regardless of color depth, this will look green.
+ *   green_color = makecol(0, 255, 0)
+ *
+ * Return value: Returns the requested RGB triplet in the current color depth.
+ */
+VALUE a4r_API_makecol(VALUE self, VALUE r, VALUE g, VALUE b)
+{
+  return INT2FIX(makecol(FIX2INT(r), FIX2INT(g), FIX2INT(b)));
+}
+
+/*
+ * call-seq:
+ *   palette_color -> ary
+ *
+ * Table mapping palette index colors (0-255) into whatever pixel format is
+ * being used by the current display mode. In a 256-color mode this just maps
+ * onto the array index. In truecolor modes it looks up the specified entry in
+ * the current palette, and converts that RGB value into the appropriate packed
+ * pixel format. Example:
+ *   set_color_depth(32)
+ *   ...
+ *   set_palette(desktop_palette)
+ *   # Put a pixel with the color 2 (green) of the palette
+ *   putpixel(screen, 100, 100, palette_color[2])
+ */
+VALUE a4r_API_palette_color(VALUE self)
+{
+  // TODO: Cache the array, and only update if changed, or use hooked variable?
+  VALUE ary = rb_ary_new2(PAL_SIZE);
+  int x;
+  for (x = 0; x < PAL_SIZE; x++)
+    rb_ary_store(ary, x, INT2FIX(pallete_color[x]));
+  return ary;
+}

data/ext/a4r_API_unicode_routines.c

@@ -0,0 +1,53 @@
+#include "allegro4r.h"
+
+/*
+ * call-seq:
+ *   ustrzncpy(src, n) -> str
+ *
+ * This function is like ustrzcpy except that no more than 'n' characters from
+ * 'src' are copied into 'dest'. If 'src' is shorter than 'n' characters, null
+ * characters are appended to 'dest' as padding until 'n' characters have been
+ * written. In any case, 'dest' is guaranteed to be null-terminated.
+ *
+ * Note that, even for empty strings, your destination string must have at least
+ * enough bytes to store the terminating null character of the string, and your
+ * parameter 'size' must reflect this. Otherwise, the debug version of Allegro
+ * will abort at an assertion, and the release version of Allegro will overrun
+ * the destination buffer.
+ *
+ * Return value: The return value is the value of 'dest'.
+ *
+ * *** The Ruby method signature differs from the Allegro method signature. The
+ * Allegro signature takes a dest by reference, and a size, but the Ruby
+ * signature returns a string containing the dest.  The returned string will
+ * have null characters appended as per the description above.
+ */
+VALUE a4r_API_ustrzncpy(VALUE self, VALUE src, VALUE n)
+{
+  int size = FIX2INT(n) + 1;
+  char *dest = ALLOC_N(char, size);
+  ustrzncpy(dest, size, StringValuePtr(src), size);
+  VALUE s = rb_str_new(dest, size - 1);
+  free(dest);
+  return s;
+}
+
+/*
+ * call-seq:
+ *   usprintf(format) -> str
+ *
+ * This function writes formatted data into the output buffer. A NULL character
+ * is written to mark the end of the string. You should try to avoid this
+ * function because it is very easy to overflow the destination buffer. Use
+ * uszprintf instead.
+ *
+ * Return value: Returns the number of characters written, not including the
+ * terminating null character.
+ *
+ * *** The Ruby method differs from the Allegro method. The Allegro signature
+ * takes a dest but the Ruby signature returns a string containing the dest.
+ */
+VALUE a4r_API_usprintf(VALUE self, VALUE format)
+{
+  return format;
+}

data/ext/a4r_API_using_allegro.c

@@ -0,0 +1,98 @@
+#include "allegro4r.h"
+
+static VALUE a4r_at_exit()
+{
+  rb_funcall(rb_mKernel, rb_intern("at_exit"), 0);
+}
+
+/*
+ * call-seq:
+ *   allegro_init -> int
+ *
+ * Macro which initialises the Allegro library. This is the same thing as
+ * calling install_allegro(SYSTEM_AUTODETECT, &errno, atexit).
+ */
+VALUE a4r_API_allegro_init(VALUE self)
+{
+  int ret = allegro_init();
+  if (!ret)
+    rb_iterate(a4r_at_exit, 0, a4r_API_allegro_exit, self);
+  return INT2FIX(ret);
+}
+
+/*
+ * call-seq:
+ *   allegro_exit -> nil
+ *
+ * Closes down the Allegro system. This includes returning the system to text
+ * mode and removing whatever mouse, keyboard, and timer routines have been
+ * installed. You don't normally need to bother making an explicit call to this
+ * function, because allegro_init installs it as an atexit routine so it will be
+ * called automatically when your program exits.
+ *
+ * Note that after you call this function, other functions like destroy_bitmap
+ * will most likely crash. This is a problem for C++ global destructors, which
+ * usually get called after atexit, so don't put Allegro calls in them. You can
+ * write the destructor code in another method which you can manually call
+ * before your program exits, avoiding this problem.
+ */
+VALUE a4r_API_allegro_exit(VALUE self)
+{
+  allegro_exit();
+  return Qnil;
+}
+
+/*
+ * call-seq:
+ *   allegro_error -> str
+ *
+ * Text string used by set_gfx_mode, install_sound and other functions to report
+ * error messages. If they fail and you want to tell the user why, this is the
+ * place to look for a description of the problem. Example:
+ *   def abort_on_error(message)
+ *     set_gfx_mode(GFX_TEXT, 0, 0, 0, 0) unless screen.nil?
+ *
+ *     allegro_message("%s.\nLast Allegro error '%s'\n" %
+ *       [message, allegro_error])
+ *     exit -1
+ *   end
+ *   ...
+ *     if some_allegro_function == ERROR_CODE
+ *       abort_on_error("Error calling some function!")
+ *     end
+ */
+VALUE a4r_API_allegro_error(VALUE self)
+{
+  // TODO: Convert to data struct or cached or hooked variable?
+  return rb_str_new2(allegro_error);
+}
+
+/*
+ * call-seq:
+ *   allegro_message(text) -> nil
+ *
+ * Outputs a message, using a printf format string. Usually you want to use this
+ * to report messages to the user in an OS independant way when some Allegro
+ * subsystem cannot be initialised. But you must not use this function if you
+ * are in a graphic mode, only before calling set_gfx_mode, or after a
+ * set_gfx_mode(GFX_TEXT). Also, this function depends on a system driver being
+ * installed, which means that it won't display the message at all on some
+ * platforms if Allegro has not been initialised correctly.
+ *
+ * On platforms featuring a windowing system, it will bring up a blocking GUI
+ * message box. If there is no windowing system, it will try to print the string
+ * to a text console, attempting to work around codepage differences by reducing
+ * any accented characters to 7-bit ASCII approximations. Example:
+ *   exit 1 if allegro_init != 0
+ *
+ *   if init_my_data != 0
+ *     allegro_message("Sorry, missing game data!\n")
+ *     exit 2
+ *   end
+ */
+VALUE a4r_API_allegro_message(VALUE self, VALUE text)
+{
+  // TODO: Allow parameter possing a lo printf for direct API consistency or force string only?
+  allegro_message(StringValuePtr(text));
+  return Qnil;
+}