There are very few actual changes to the library code itself; only some
symbol declarations and definitions have been altered to include
AL_CONST. See below for a description of the AL_CONST preprocessor
define. In a few places, some string was changed that should not have
been - in these cases, the string is simply duplicated and then the
duplicate is erased on exiting the function.
In all, there were very few changes to the library code.
The AL_CONST preprocessor define
In order to support compilers which don't know about the `const'
keyword, or perhaps use a different keyword, the preprocessor symbol
AL_CONST is used wherever `const' would normally be used. Note that in
the documentation, I have used `const' for readability.
Allegro API changes
These are, generally speaking, totally transparent to the user. I did
not change the behaviour of any function; only its parameter types.
Basically, if you can pass it as
, then you can
pass it as
const type* ptr
without any problem whatsoever.
Note also that certain changes may remove warnings in your program as
static strings, etc, are now treated as `const' by Allegro functions.
There are a few places, described below, where there will be an effect
on existing code.
`const'-correctness is deemed important for two reasons. Firstly, it can
increase code readability and comprehension of Allegro functions (for
instance, you can see which parameters are altered and which are not).
Secondly, it ensures that the Allegro code is not changing data which it
should not be, and that client callback functions are not breaking
Allegro by changing data they should not be.
Callback functions and Pointers to Pointers
Certain callback functions now have a different type - they take `const'
pointers as opposed to non-`const' pointers. As far as I know, a
compiler will issue a warning about incompatible pointer types. You
should update your callback function to the new format (which will be
listed in the main Allegro documentation).
Also, when passing a pointer to a pointer to an Allegro function which
is declared as taking an
AL_CONST type** ptr
, you will need
to cast your pointer to be `const' if it is not already. For instance:
int some_allegro_function(AL_CONST char** p);
void my_func(char** x)
some_allegro_function((AL_CONST char**) x);
I realise that this is a change to the Allegro API, and that we are
supposed to avoid those at all costs, but this is essentially fixing a
bug in Allegro and changing behaviour. It also ensures that
client-supplied callback functions are functioning correctly, and not
altering data that they should not. Callback functions which do not
treat relevant parameters as `const' are, in a small (but potentially
signficant) way, broken.
Please note that for the Unicode function ugetx(), I have provided an
alternative version ugetxc(), which takes a `const char**' parameter as
opposed to a `char**' parameter. This is because it is valid to pass
either a `char**' or a `const char**', but unfortunately there is no way
to tell the compiler exactly what we mean.
Allegro represents both a screen bitmap and a memory bitmap by a single
object; a BITMAP. Unfortunately, these two things can be very different.
For instance, reading a pixel from a bitmap would not seem to change it,
but if it is a screen bitmap we are reading from, then it is possible
that some parameter of the video card is changed to select the correct
Therefore, a const BITMAP parameter does not make sense, and is not used
throughout the library. This is unfortunate, but I cannot see any way
Allegro `const'-correctness has been tested for quite enough time to say
that it is working OK. However, if you still find problems with a compiler,
please contact the Allegro mailing list; see `Contact info' in the Allegro
Email: lwithers AT lwithers.demon.co DOT uk.
Thanks for listening :-)