The Allegro Wiki is migrating to github at

Unix architecture

From Allegro Wiki
Jump to: navigation, search

Architecture of the Unix port

TODO: X11 driver, DGA2 driver, SVGAlib video driver, VGA video driver, console input drivers


Under Unix, some parts of the library are kept as modules. The reason for modules are binary distributions. You can distribute an Allegro library without additional dependencies, and only the modules will have additional dependencies. For example, only the aRts module depends on aRts, but the main Allegro library does not. This way you can use the binary Allegro distribution without requiring aRts.

When testing code that is compiled to modules, be extra careful to not use old modules while testing. Allegro will pick them up from the install path, even if you compile static programs.

Unsharable code

Under Unix, some parts of the library are put into a statically linked library called liballeg_unsharable instead of the usual shared library. Sam Hocevar explained on [AD] on 2004-08-05 that liballeg_unsharable was needed to "provide assembly functions that are not position independent code (PIC). When building a Unix shared object (library), one needs to use the -fPIC flag to create position independent code, or the library will not be properly loaded in a shared address space. PIC code stores a special pointer in a reserved register (EBX on x86), which means that the compiled code cannot use EBX and will run at a slight performance loss. Since the asm code in alleg_unsharable does not reserve EBX, it is built as a static library instead of a shared one.

However, on x86 library code need not be compiled with -fPIC because the architecture allows linking non-PIC code with PIC code in the same object. And we do not provide assembly routines on platforms that do not allow this linking (such as Alpha, IA64, HPPA)."

So liballeg_unsharable may be removed soon, although something like it may need to be reintroduced in future (for non-x86 platforms).

X11 drivers

The X11 drivers aren't in a very clean shape, but this is changing. X11 itself was changing a lot historically, what worked with one server or one window manager wouldn't work with others. At all times a lot of hacks were necessary in any X11 program to work correctly. For example, just the task of switching to fullscreen, and capturing mouse and keyboard. Things get even worse with all the extensions, notably DGA2. (The messy DGA1 related stuff already was thrown out.)

The single drivers, like video, keyboard, mouse, weren't fully split up in the beginning - and there is one big file xwin.c which contains a lot of stuff. But things are improving. The main code of the X11 port is in src/x. Important files are also include/platform/aintunix.h and include/xalleg.h.


In X11, there are normally 3 threads running. The main thread, the background thread, and the timer thread. There's also a version not using threads, but this is ignored in the following.

The main thread is where all the user code runs. It starts at the main function, and then just executes whatever the user wrote.

The background thread is sort of between the main thread and X11. For example, it will update the key[] array, or will propagate updates to the screen to X11. The background thread periodically calls _xwin_handle_input in src/x/xwin.c. This uses XNextEvent to retrieve the next event.


Whenever _xwin_handle_input encounters a keyboard event, it will pass it on to the keyboard driver, in src/x/xkeyboard.c.

When available, the unicode representation will be looked up for a keypress event using XIM, else only Latin1 characters can be reported. These characters are returned by readkey/ureadkey.

The key[] array is updated by mapping any X11 key to one of Allegro's KEY_* constants. The mapping uses some heuristics to map keys as good as possible, e.g. the key producing an "a" will be mapped to KEY_A. Keys for which this doesn't work are randomly distributed. There is no positional mapping. A section [xkeyboard] in the config file can be used to override the automatic mapping, and map any X11 keycode to a specific Allegro keycode.


TODO: Internal double buffer, direct updating with X11 commands, XSync() called from background that...