Usage
=====

    test_driver [OPTIONS] config1.ini [TESTS ...] [config2.ini [TESTS...]] ...

where options are:

    -d, --delay
        delay between tests

    -s, --save
	save output images as <test name>.png

    -q, --quiet
	don't display graphical output

    -v, --verbose
        print extra output

    -v -v
        extra extra verbose

    --force-opengl
	select OpenGL driver

    --force-opengl-1.2
	restrict Allegro to OpenGL 1.2

    --force-opengl-2.0
	restrict Allegro to OpenGL 2.0

    --force-d3d
	select Direct3D driver

If the list of tests is omitted then every test in the config file will be run.
Otherwise each test named on the command line is run.  For convenience, you may
drop the "test " prefix on test names.

If a test name ends with an asterisk, then all tests which match that prefix
will be run, e.g.

    ./test_driver -d test_bitmaps.ini 'scaled rotate*'

Every test is run with both memory and video bitmaps.  The software rendered
result is checked against an expected hash code.  The hardware rendered result
is checked for similarity with the software result.


Config file format
==================

Each [test ...] section defines a single test, containing one or more
operations named by the keys op0, op1, ... opN.  The value of each op
key is a call to an Allegro function, or empty.  Each argument of the
call must be a literal of the correct type, or a variable name.

A variable name is just another key in the section, whose value is taken
as a _literal_ to be substituted in place of the variable.

A test may inherit the keys of another section using the 'extend' key.
Keys in the child section override keys in the parent.

The [bitmaps] section defines a list of bitmaps to load, relative to the
tests directory.  Each key name is then a valid bitmap literal.
The name 'target' refers to the default target bitmap.

ALLEGRO_COLOR literals may be written as #rrggbb, #rrggbbaa or a named
color (e.g. purple).

Integer, float and enumeration literals are written as per C.
(Note that "ALLEGRO_FLIP_HORIZONTAL|ALLEGRO_FLIP_VERTICAL" must be written
without whitespace, because we don't have a proper parser.)

String literals are not supported, but you can use a variable whose value
is treated as the string contents (no quotes).

Transformations are automatically created the first time they are mentioned,
and set to the identity matrix.

Each test section contains a key called 'hash', containing the hash code
of the expected output for that test.  When writing a test you should
check (visually) that the output looks correct, then add the hash code
computed hash code to the test section.

Some tests produce slightly different (but still acceptable) output depending
on the hardware, compiler or optimisation settings.  As an alternative to
'hash', which will only pass if the result is exactly the same, you can use
the 'sig' key.  This will perform a loose comparison on "signatures" which are
computed from the average intensity levels (greyscale) at 81 points on the
image.  Hopefully it is still strict enough to catch any major regressions.
You can supply both 'hash' and 'sig' keys.

Finally, 'hash=off' will disable hash checking entirely.  For example, TTF
rendering depends on the FreeType configuration, and the differences are big
enough to show up even in the thumbnails.

The hardware implementation is compared against the software implementation,
with some tolerance.  The tolerance is arbitrary but you can set it if
necessary with the 'tolerance' key. In case the HW results is supposed
to look different, a separate hash can be specifeid with 'hw_hash'
instead of the similarity comparison.
