There are three versions of the Allegro library: the normal optimised code,
one with extra debugging support, and a profiling version. See the platform
specific readme files for information about how to install and link with
these alternative libs. Although you will obviously want to use the
optimised library for the final version of your program, it can be very
useful to link with the debug lib while you are working on it, because this
will make debugging much easier, and includes assert tests that will help to
locate errors in your code at an earlier stage. Allegro also contains some
debugging helper functions:
Debugging helper macro. Normally compiles away to nothing, but if you
defined the preprocessor symbol DEBUGMODE before including Allegro headers,
it will check the supplied condition and call al_assert() if it fails,
whose default action is to stop the program and report the assert. You can
use this macro even when Allegro has not been initialised. Example:
#define DEBUGMODE
#include
...
void my_blitter(BITMAP *source, int flags)
{
int some_variables;
ASSERT(source != NULL);
ASSERT(flags & GAME_RUNNING);
...
}
See also:
al_assert,
TRACE,
register_assert_handler.
Examples using this:
expackf.
void TRACE(char *msg, ...);
Debugging helper macro. Normally compiles away to nothing, but if you
defined the preprocessor symbol DEBUGMODE before including Allegro headers,
it passes the supplied message given in ASCII format to al_trace().
Example:
#define DEBUGMODE
#include
...
void my_blitter(BITMAP *source, int flags)
{
static int count_call = 0;
TRACE("my_blitter() called %d times.\n", count_call++);
...
}
See also:
al_trace,
ASSERT,
register_trace_handler.
Supplies a custom handler function for dealing with assert failures. Your
callback will be passed a formatted error message in ASCII, and should
return non-zero if it has processed the error, or zero to continue with
the default actions. You could use this to ignore assert failures, or to
display the error messages on a graphics mode screen without aborting the
program. You can call this function even when Allegro has not been
initialised. Example:
int show_but_continue(const char *text)
{
alert("Uh oh...", "Fasten your seat belts.", text,
"&Go on!", NULL, 'g', 0);
return 1;
}
...
register_assert(show_but_continue);
ASSERT(0); /* This won't crash the program now. */
See also:
al_assert,
ASSERT,
register_trace_handler.
Supplies a custom handler function for dealing with trace output. Your
callback will be passed a formatted error message in ASCII, and should
return non-zero if it has processed the message, or zero to continue with
the default actions. You could use this to ignore trace output, or to
display the messages on a second monochrome monitor, etc. You can call
this function even when Allegro has not been initialised. Example:
int network_broadcaster(const char *text)
{
int f;
for (int f = 0; f < connected_clients; f++)
send_msg_to_client(client[f], text);
return 0; /* Let normal tracing occur. */
}
...
register_trace_handler(network_broadcaster);
TRACE("Networked tracing activated\n");
See also:
al_trace,
TRACE,
register_assert_handler.
Raises an assert for an error at the specified file and line number. The
file parameter is always given in ASCII format. By default, this will call
the system driver's assert handler. If there is none, the error will be
sent to stderr and the program will abort. However, if the environment
variable ALLEGRO_ASSERT is set, this function writes a message into the
file specified by the environment variable and program execution will
continue. If none of this behaviours is wanted, you can override them with
a custom assert handler.
You will usually want to use the ASSERT() macro instead of calling this
function directly.
See also:
ASSERT,
al_trace,
register_assert_handler.
Outputs a debugging trace message, using a printf() format string given
in ASCII. If you have installed a custom trace handler it uses that, or
if the environment variable ALLEGRO_TRACE is set it writes into the file
specified by the environment, otherwise it writes the message to
"allegro.log" in the current directory. You will usually want to use the
TRACE() macro instead of calling this function directly.
See also:
TRACE,
al_assert,
register_trace_handler.