@html_text_substitution=readme.txt|<a href="readme.html">readme.txt</a>
@external-css=allegro.css
@document_title=Allegro `const'-correctness
<center><h1><b>
Allegro `const'-correctness
</b></h1></center>
<hr>
<i>
This is a short document about the introduction of `const'-correctness
to Allegro. It details what changes have occurred to internal library
code, the API changes (mainly transparent) and what you will need to do
to adapt code to compile without warnings (again, mainly nothing).
</i>


@!text
@heading
Contents

@shortcontents


@text

@heading
Library changes

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.



@heading
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.



@heading
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 <code>type* ptr</code>, then you can
pass it as <code>const type* ptr</code> 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.



@heading
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 <code>AL_CONST type** ptr</code>, you will need
to cast your pointer to be `const' if it is not already. For instance:
<codeblock>
   int some_allegro_function(AL_CONST char** p);
   
   void my_func(char** x)
   {
       some_allegro_function((AL_CONST char**) x);
   }
<endblock>
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.



@heading
BITMAP objects

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
line, etc.

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
around it.



@heading
Finally...

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
documentation (readme.txt).

Email: <email>lwithers@lwithers.demon.co.uk</a>.

Thanks for listening :-)