allegro4r 0.0.1-x86-mswin32-60

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)));
+}