Re: [AD] Changes to aWiki

[Chris <chris.kcat@xxxxxxxxxx>]

If I may weigh in here..

Personally, I'd like to see an API that goes something like this:

----
AL_DISPLAY *display = al_create_display(w, h, bpp, flags);
/* This display is automatically selected for this thread (thread-local),
   and the first off-screen buffer in the buffer chain is selected for
   the rendering target */

al_line(0, 0, 100, 100, RED);

AL_BITMAP *bitmap = al_create_bitmap(w, h, bpp, flags);
/* Create an off-screen pixel-manipulation surface in RAM, VRAM, or
   where-ever (as the flags would hint) */

al_select_bitmap(bitmap);
/* overrides the rendering target; this is stored in the AL_DISPLAY
   struct, so it need not be global and you don't have to worry
   about threading (see below). Selecting NULL will cause Allegro to
   automatically draw to the next off-screen buffer in the buffer
   chain */

al_clear(al_get_mask_color(bitmap));
al_line(0, 100, 0, 100, BLUE);

al_unselect_bitmap();
/* deselects the current bitmap and selects the next off-screen
   buffer from the current chain to draw on (or the previously
   selected bitmap, if you want to hold a list) */

al_blit(bitmap, 0, 0, al_bitmap_width(bitmap), al_bitmap_height(bitmap),
                0, 0, al_bitmap_width(bitmap), al_bitmap_height(bitmap),
                AL_BMP_MASKED);
/* That looks ugly with all those parameters, IMO, but I'm hesitant to use
   an AL_RECT struct.. */

al_flip_display(display);
/* Shows the next page, and selects the next bitmap in the buffer chain
   for drawing if no user-specified bitmap is selected */
----

Now, the docs can be very explicit that you can't select the same 
display or bitmap from two different threads. Allegro could grab display- and 
buffer-specific mutex locks, so if you try the second selection attempt will 
block until the display/bitmap is deselected on the other thread.

As well, you could even add this:

----
AL_DISPLAY *sub_display = al_create_sub_display(display, x, y, w, h, flags);
/* Creates a sub-section of the display to make as a target for a secondary
   off-screen display chain. This could be an off-screen VRAM page that is
   hw-accel blitted on flip, an FBO, or perhaps an overlay. I've seen programs
   that can have an OpenGL sub-area within a larger normal window (and I've
   made programs that can have an overlay sub-area contained in main
   window). You would get something like that here. This can fail if no
   suitable methods are available. */
if(!sub_display)
   whoops();

al_select_display(sub_display);
/* All drawing now goes to the first off-screen page of the sub-display */

al_line(50, 0, 50, 100, GREEN);

al_flip_display(sub_display);
/* Shows the updated sub-display on the screen (*not* an off-screen buffer of
   the one-level-up display), at the previously specified coords. This is
   never a masked operation, so the whole area is overwritten. */

al_select_display(display);
/* Drawing target is now returned to the currently selected bitmap of the main
   display */
----

I realize it looks a bit complex, and I may be thinking too grand, but IMO it 
looks nice. The only "globals" here would be the the currently selected 
display. The display would hold the pointer(s) to the selected bitmap and 
buffer chain. As well, using methods available in MSVC/MinGW and recent 
versions of Unix/GCC, you can prevent any global symbols you want from being 
exported in a shared lib.