# Allegro Legacy

Port your Allegro 4 programs to modern systems using Allegro 5.

## Introduction

Allegro Legacy is a library that you can use in place of Allegro 4 to compile
your programs and run them on modern systems. It utilizes Allegro 5 to access
the system hardware, so it should theoretically run anywhere Allegro 5 can run.

## Features

* Full Allegro 4 API compatibility
* Additional functions to take advantage of Allegro 5 features

## How to Use

You will need to have Allegro 5 installed before you can build Allegro Legacy.
Your Allegro 5 build needs to have the audio add-on enabled. Once you have that
set up, you need to use CMake to generate the build scripts for your
development environment.

To build Allegro Legacy, you create a build directory somewhere and navigate to
it in the terminal. Then you type:

    cmake <path_to_allegro_legacy_source>
    make
    make install

Once you have Allegro Legacy installed, you can build your Allegro 4 program as
you normally would.

## API

Allegro Legacy exposes the entire Allegro 4 API and adds a few functions to
make it easier to upgrade your old projects. Below are all the additional
variables and functions that Allegro Legacy exposes:

* `ALLEGRO_LEGACY`  
  Defined so you can detect from your code whether or not it is being built
  with Allegro Legacy.
* `void all_disable_threaded_display(void)`  
  Disable the emulated display. Must be called before `set_gfx_mode()`. If you
  do this, you will need to add your own code to get graphics to render to the
  display.
* `ALLEGRO_DISPLAY * all_get_display(void)`  
  Get a pointer to the Allegro 5 display that is being used by Allegro Legacy.
  This variable is initialized during a call to `set_gfx_mode()`.
* `ALLEGRO_BITMAP * all_get_a5_bitmap(BITMAP * bp)`  
  Get an Allegro 5 `ALLEGRO_BITMAP * ` from an Allegro 4 `BITMAP *`.
* `void all_render_a5_bitmap(BITMAP * bp, ALLEGRO_BITMAP * a5bp)`  
  Render the Allegro 4 `BITMAP *` to the Allegro 5 `ALLEGRO_BITMAP *`.
* `void all_render_screen(void)`  
  Render the contents of `screen` to the display.
* `void all_set_display_transform(ALLEGRO_TRANSFORM * transform)`  
  Apply the transformation `transform` when rendering `screen` to the internal
  Allegro 5 display. Must be called after `set_gfx_mode()` for it to take
  effect. If you set the `ALLEGRO_FULLSCREEN_WINDOW` flag before setting the
  graphics mode, you can use this to inform Allegro Legacy how you want to scale
  `screen` to fill the display. Set the `ALLEGRO_MIN_LINEAR` and/or
  `ALLEGRO_MAG_LINEAR` new bitmap flags before calling `set_gfx_mode()` to
  enable bilinear filtering.
* `bool all_adjust_int(void * proc, double speed)`  
  Adjust the speed of the underlying timer associated with `proc`. This makes
  it possible to take advantage of Allegro 5's more precise timer routines
  without requiring you to write a whole new timing loop. For example:

      intall_int_ex(increment_tick, BPS_TO_TIMER(60));
      #ifdef ALLEGRO_LEGACY
        all_adjust_int(increment_tick, 1.0 / 60.0);
      #endif

* `bool all_wait_for_int(void * proc)`  
  Idle until the underlying timer associated with `proc` ticks. This makes it
  much easier to reduce CPU usage for Allegro 4 style timing loops since we can
  just add a call to this function to the top of the loop. For example:

      while(ticks > 0)
      {
        /* sleep until timer ticks */
        #ifdef ALLEGRO_LEGACY
          all_wait_for_int(increment_tick);
        #endif
        process_logic();
        ticks--;
        /* or yield when not using Allegro Legacy */
        #ifndef ALLEGRO_LEGACY
          yield_timeslice();
        #endif
      }

## Advanced Usage

Once you have your program up and running with Allegro Legacy, you may wish to
upgrade some aspects of it to take advantage of some of the enhancements that
Allegro 5 offers. Allegro Legacy lets you use both the Allegro 4 and Allegro 5
APIs at the same time.

One thing you may want to do is replace your old timing loops with Allegro 5
loops. This will allow your program to only use the amount of CPU time it
needs.

You can optimize your rendering if you are using a separate buffer instead of
rendering directly to `screen` using the following code:

    a5_backbuffer = al_get_backbuffer(all_get_display());
    all_render_a5_bitmap(a4_buffer, a5_backbuffer);
    al_flip_display();

## Compatibility Notes

Allegro Legacy does not support hacked graphics modes such as that used by the
ex12bit example. After looking into ex12bit not working, I decided the hacked
mode it uses is not officially part of the Allegro 4 API. The additional code to
support that specific mode could be added, but there may be other possible
hacked modes. There's no clean way to add support for these types of hacks.

## License

Allegro Legacy is licensed under the gift-ware license (see a4_readme.txt for
details). This means it can be used in any way that Allegro 4 can be used.
