         ______   ___    ___
        /\  _  \ /\_ \  /\_ \
        \ \ \L\ \\//\ \ \//\ \      __     __   _ __   ___
         \ \  __ \ \ \ \  \ \ \   /'__`\ /'_ `\/\`'__\/ __`\
          \ \ \/\ \ \_\ \_ \_\ \_/\  __//\ \L\ \ \ \//\ \L\ \
           \ \_\ \_\/\____\/\____\ \____\ \____ \ \_\\ \____/
            \/_/\/_/\/____/\/____/\/____/\/___L\ \/_/ \/___/
                                           /\____/
                                           \_/__/

                    API compatibility information.

             See readme.txt for a more general overview.

# Introduction

Once Allegro 4.0 is released, we plan to maintain Application Programming Interface compatibility for the rest of the 4.x series. For example, that means you will be able to compile your program written for version 4.0 with version 4.0.23 or version 4.2.1 of the library. However, in order to fix some inconsistencies of the 4.0 API, we may make exceptions to the rule and break strict API compatibility in a few cases. But this is guaranteed to never happen in a series for which major and minor version numbers are fixed; in other words, two versions that differ from each other only by the revision (3rd) number will be strictly API compatible.

# Changes between 4.0.x and 4.1.x series

- The 'aspect' parameter of get_camera_matrix() and get_camera_matrix_f() strictly conforms to the documentation; in particular, setting it to 1 instructs the functions to do no scaling. This was not the case before, because the functions multiplied this aspect ratio by 4/3.
- Menus created from a DIALOG array (by using d_menu_proc for the proc pointer) now correctly use the w and h fields as a minimum for their inclusive dimensions (in the same way as all other GUI elements). Before, they would draw the border outside of this dimension (1 pixel overdraw with other GUI elements), and also add an additional 'shadow' to the right and the bottom (2 pixels overdraw with other GUI elements).
- The 'retrace_count' variable and the 'retrace_proc' callback function take into account the refresh rate (if it is known) when the retrace simulator is not installed. This was not the case before, except under Windows.
- The default value for the mouse configuration variable 'emulate_three' has been changed to 'no' in all cases (even if you have a 2-button mouse).
- The COLORCONV_KEEP_TRANS flag strictly conforms to the documentation now. This was not the case before, because it was ignored when loading bitmaps from datafiles. fixup_datafile() was modified to preserve transparency when this flag is set, which was not guaranteed before in rare cases.
- create_sub_bitmap() is now less tolerant about receiving bad arguments. For example, it used to compensate for negative values for the origin and return NULL if the parent bitmap was NULL. These cases are now ASSERTed in the debug version, but unchecked in the release version.
- install_allegro() and allegro_init() now return an error code if unable to initialise a system driver. Previously they would have aborted the program in such cases. Consequently you should check their return values.
- The preprocessor symbol USE_CONSOLE is deprecated. Define instead the symbol ALLEGRO_USE_CONSOLE prior to including Allegro headers in order to set up Allegro for building a console application.
- The constructors of the fix class from integer and floating point values are now explicit.
- All BeOS gfx driver IDs and constants have been replaced by more meaningful ones. You may have to modify your allegro.cfg to reflect the change, or update and recompile your programs if you used BeOS specific gfx drivers.
- The behaviour of the GFX_SAFE driver has changed: it doesn't try to first set up GFX_AUTODETECTed drivers anymore and is now guaranteed to be a windowed driver when the platform has got a windowing system.
- A datafile object returned by load_datafile_object() used not to contain the properties attached to the object. This has been fixed.