[AD] Proposal for new Allegro interface

[Laurence Withers <lwithers@xxxxxxxxxx>]

Hi everyone,

Here is my proposal for a new Allegro interface:

1/. All symbol names are prefixed like this:
  al_      global symbol
  _al_     `internal' global symbol
  AL_      structure or preprocessor define

    Feel free to work out something better than this, but it is what
    I vote for, and seems fairly neutral.

2/. We actually change the library code itself to use these symbols;
    this is to avoid namespace collisions with other libraries. 
    The new names will be declared in `allegro4.h' (or possibly
    another name; again, feel free to work out something better).

3/. We rework allegro.h so that it exactly emulates the current
    names and behaviour. This is to maintain backward compatibility.
    In order to do this, we use typedef statements:

typedef struct AL_BITMAP BITMAP;
et al.

    and the following constructs:

#ifdef AL_COMPILER_INLINE
static inline void clear(BITMAP* bmp)
{
    al_clear(bmp);
}
#endif
static void clear(BITMAP* bmp) NO_WARNING_WIDGETRY
{
    al_clear(bmp);
}

    where NO_WARNING_WIDGETRY could be a function attribute under gcc, 
    etc., and AL_COMPILER_INLINE is defined if the compiler supports
    inline functions. In fact, if all compilers used for Allegro
    support the `inline' keyword, we don't need the conditional.

    As to how this affects code generation (this is under gcc, I don't
    use any other compiler, but I believe we can expect similar 
    results):     (gcc 2.95.2)

    a/. In totally unoptimised compilation, inline functions aren't  
        supported, so an extra indirection is added. This consists of
        some stack operations and a jump.

    b/. With -O or -O2 (ie. some optimisation), the inline function
        call is completely non-existent; it is as if we called the
        function by its prefixed name.

    c/. With -O3 (which turns on -finline-functions, ie. gcc ignores
        the `inline' keyword and decides itself which functions
        should be inlined), both the inline and the static function
        calls are non-existent.

    I generated these results by using these two files:

default: test1.s test2.s test3.s test4.s

test1.s : test.c
	gcc -S $^ -o $@

test2.s : test.c
	gcc -O1 -S $^ -o $@

test3.s : test.c
	gcc -O2 -S $^ -o $@

test4.s : test.c
	gcc -O3 -S $^ -o $@

int other_func(int);

static inline int test_inline(int i)
{
    return other_func(i);
}

static int test_static(int i)
{
    return other_func(i);
}

void driver_inline(int i)
{
    test_inline(i);
}

void driver_static(int i)
{
    test_static(i);
}

void driver_direct(int i)
{
    other_func(i);
}

    Could Eric or Owen or somebody take a look at the assembly generated
    under MSVC and let me know if the same is true (or just mail it to
    me).

4/. We take the opportunity to change any recently introduced API 
    additions which seem broken (are there any?), and we also provide
    additional functions to fix a few things that have always been
    broken. The example that springs to mind is 6-bit palettes.

Here is my analysis of advantages/disadvantages:

Plus:

 - a nice, clean, non-polluting API. Coexistence with other libraries.
   (I don't feel that the argument `using two or more libraries is a
   very advanced features' justifies leaving this broken forever; it
   just requires a very advanced solution);

 - unless the programmer uses no optimisation, there is no effect
   on generated code or execution;

 - no preprocessor trickery to break things;

 - #include <allegro4.h> will get you the new API, and
   #include <allegro.h> will get you the old. No need for horrible
   #defines anywhere, and *all old code will continue to work as is*;

 - no compile-time options, so no need to have multiple Allegro .so 
   files for the same Allegro.

Minus:

 - somebody has to do all the work (I'll do it, though);

 - increases complexity slightly, both when maintaining code and
   when adding new stuff (because you need to think of two function
   names :-P ).

Please send your thoughts. If generally positive, and nobody raises any
unsolvable technical issues, I'll write a patch and submit it for
examination.

Bye for now,
-- 
Laurence Withers, lwithers@xxxxxxxxxx
                http://www.lwithers.demon.co.uk/

Attachment: signature.asc
Description: PGP signature