[AD] Windowed mode in X version

[Michael Bukin <M.A.Bukin@xxxxxxxxxx>]

In this message I will describe how windowed mode is organized in X
version of Allegro.  I may forgot something in the process, and if
something is not clear, then ask specific questions.

Initialization of system driver:

1. make window with default size (it can be used for getting mouse and
keyboard input), and install input callback.

input callback is called by timer.  It reads events from X-server,
converts them to format suitable for Allegro and calls hooks in
keyboard and mouse drivers.

Graphics initialization:

1. Resize window to the requested screen size.

2. Create XImage (this is a client side image where data is local to
client, unlike Window and Pixmap (drawables), which are server side
objects with data local to X-server) with the size of requested
virtual screen.  It will try to create shared XImage first (data is
directly accessible by both client program and X-server), but will use
normal XImage overwise.

3. Test that XImage data can be accessed directly as stream of bytes,
i.e. I know the layout of pixels in XImage and can place them there by
dereferencing some pointers.  If layout is known, it is called "fast",
otherwise it is called "slow".

4. Determine format of X windows pixels.  It can be used as "truecolor",
when some parts of pixel are used for red, green and blue components,
or as "palette", where X windows pixel value is determined by lookup
table (index for lookup table is RRRRGGGGBBBB).  Lookup tables and
possibly X windows colormaps are initialized.

5. If XImage can be accessed directly and it has the same pixel format
as Allegro in requested color depth, then setup line pointers to the
XImage data, overwise allocate memory for virtual screen data and
setup screen->line pointers to this memory.  When screen->line points
to XImage, this situation is called "matching", overwise it is called
"not matching".

5. In "not matching" mode decide how to update XImage data from
Allegro screen data (because they are different surfaces).  There can
be 3 fast truecolor modes (8, 16, 32), 3 fast palette modes (8, 16,
32) and 2 slow modes for XImage (truecolor and palette), and 5 Allegro
modes (8, 15, 16, 24, 32), i.e. total of 8*5 different update
functions.  They use lookup tables for converting pixels from Allegro
format to XImage format.  Slow modes use XPutPixel and fast modes use
pointer dereferencing to put pixels into XImage.

6. Determine which bank switching routines to use.  Bank switch
routines should always update window, but may not need to update
XImage when in "matching" mode.  But look for _in_gfx_call flag below.

7. Create a bitmap with _make_bitmap and fixup bitmap and gfx_driver
fields. (**)

8. Store original vtable and replace vtable with special one
(src/x/xvtable.c).  Routines in this vtable set _in_gfx_call flag and
call corresponding function from original vtable, then clear
_in_gfx_call flag and update part of the window which was changed.
When _in_gfx_call flag is set, bank switch routines don't update
XImage and window, because it will be updated explicitly in graphics
primitive.

9. Return pointer to bitmap.

Notes: Allegro functions and structures are avoided everywhere,
e.g. driver keeps its own copy of line pointers to screen data,
copying from Allegro screen to XImage (with pixel format similar to
Allegro, but different color depth) is not done with blit, but uses
its own function.  This should help in case someone wants to remove
specific color depths or do something else, which might limit
available Allegro functions in resulting library.


** I think passing virtual resolution to _make_bitmap and initializing
bitmap and gfx_driver fields there might reduce amount of fixup work
in graphics drivers.

-- 
Michael Bukin