I had a bit more time to work on the API. Here's the current incarnation of it.

At the bottom, there are some examples of tasks you can do using the configuration system.

What it doesn't cover:
- Blending (esp 8bpp color maps)
- the GUI

Main changes:
- More consistent API
- More flexible
- Palettes are associated to bitmaps

Thoughts? Comments? Flames?

I like it.
How will the set methods work? Will they set the values directly? Will they be set once a certain function is called?

If so, I'd like to ensure that there's a naming convention which makes it clear to the user which function commits something...

Here follow some totally unconnected comments.

• Nice work.

• Definitely blit. :-) Also very nice that the normal blit function actually draws the whole bitmap, since that is the usual case.

• Two comments about the blit-type functions: firstly, why source, dest ordering and not dest, source? Personally I prefer the latter (easier to remember), but I'll accept any logical argument for the former. And the flag parameter: is there no other way to achieve what you want? Flags are evil because add-on flags will conflict.

• Can we get a mailing list for v5 development? Allegro.cc is fine for short threads, but the interface is too cumbersome for long discussions and is painful for us poor modem users.

• al_set_bitmap_clip_region is very cumbersome for a potentially oft-used function. How about al_bitmap_clip()?

• al_draw_text() should still take a bg parameter. The reason for this is in the text renderers (currently I am writing an advanced renderer for v4, look out for it in conductors): drawing a bg with rectfill and then writing on it is potentially very slow compared to drawing fg/bg in one go. Maybe there should be a specific way of representing a transparent color? (see mail to conductors about using an array of char). Alternatively, add al_draw_text_solid().

Finally, my personal view about the config system. I agree with the API, but the usage is my concern. We should come up with rules for when things should be done through the config system and when they should be done through functions.

I think that global information which doesn't regularly change (this includes which graphics adapters you have, the CPU information, OS information, current color depth/screen resolution, etc) should be read from the config system.

Fast changing information, and anything which returns a pointer, should be implemented with a function (getting a pointer to the current screen, the equivalent to reading the key[] array in v4, etc.).

Changing things which won't have an immediate effect (eg. setting preferred drivers, telling packfiles to use bz2 compression, etc.) should go through the config system.

Changing things that will have an immediate effect, or anything using pointers (eg. setting the window size) should happen in a function. In your last example, imagine that it takes 0.5s to resize the window; you now have an unsightly delay in resizing along each axis.

Also, the config system encourages moving towards a state-based system, but we all know that this is generally a bad thing: it makes multithreading a problem. In fact, it makes multi-anything a problem :-( (By this I mean that performing an operation twice, but without the two instances interfering with each other, becomes a pain).

Having said this, I do like your example "Create a YUV 422 overlay": this shows where the config system would be most useful. The graphics driver doesn't have to know a thing about YUV 422, so it can just fail the request because it doesn't see enough information. But think about this in a multithreading context: two threads each trying to set up a display will totally break each other.

I think maybe you should do this instead:

- Create a YUV 422 overlay
    al_set_string ("gfx/my_new_display/color_space", "YUV422");
    al_set_int    ("gfx/my_new_display/color_depth", 16);
    al_set_boolean("gfx/my_new_display/overlay", TRUE);
    al_set_boolean("gfx/my_new_display/windowed", TRUE);

/* Also set all the other parms via the config system, because we may introduce new things in
   new versions of Allegro and using the config system waives the requirement that old drivers
   be updated to know about new code. */

    AL_BITMAP *screen = al_create_display_bitmap("my_new_display");

/* This call reads from the directory gfx/my_new_display/ to get its parms. */

This way, a thread simply needs a unique string ID rather than having to implement mutexes for each operation a thread might want to carry out using the config system.

Anyway, enough rambling for now. Please think about the mailing list.

Straight off the top of my head, I have a few changes I would like to see. Obviously shoot me down if these are stupid suggestions. What do people think about these :

/* Clipping */
int al_get_bitmap_num_clip_regions(AL_BITMAP *bitmap);
void al_set_bitmap_clip_region(AL_BITMAP *bitmap, int x, int y, int w, int h, int id);
void al_set_bitmap_clip_mode(AL_BITMAP *bitmap, int id, AL_BOOL mode);

It is assumed that num_clip_regions returns how many clip regions may be attached to a bitmap. This number is always positive, or it is 0 if there is no limit. People may then adjust the dimensions of any of the potential clip regions (id is either arbitrary with the user using whatever values they like, or else 0 <= id < number of clip regions) and enable them or disable them. When they are disabled, it is assumed that Allegro forgets their shape.

All elements of geometry that fall within any clip region are displayed. So the total clip region is the boolean OR of all regions.

Also, in addition to :

/* Updating the screen */
void al_show_display_bitmap(AL_BITMAP *display);
void al_flush(AL_BITMAP *display);

Just for future target proofing. That is, assuming the former is only for page flipping?

On the same topic, for similar future proofing, are you sure we can do without :

int al_unselect_read_bitmap_region(AL_BITMAP *bitmap);

Finally, are the Allegro team absolutely opposed to combining some of the al_create_*bitmap functions, except for sub? Imagine the benefits of this :

AL_BITMAP *al_create_display_bitmap(al_id_t card, int width, int height, al_id_t update_method);
AL_BITMAP *al_create_bitmap(int flags, AL_BITMAP *display, int width, int height);
AL_BITMAP *al_create_rle_bitmap(AL_BITMAP *memory);
AL_BITMAP *al_create_sub_bitmap(AL_BITMAP *parent, int x, int y, int w, int h);

Arguments to create_bitmap may be one of the obvious :

AL_VIDEO
AL_SYSTEM
AL_MEMORY

Or, to simplify things even further for users, could be one of these :

AL_MAXIMUM_VRAM_BLIT_SPEED
AL_MAXIMUM_READ_SPEED
AL_MAXIMUM_MEMORY_BLIT_SPEED
etc

With Allegro being a little intelligent about the matter. For example, the VRAM example might try to allocate a video bitmap if they are supported on this hardware and any memory is available, if that doesn't work out, it could head for AGP memory, then system memory (possibly in RLE form, first . . .). I think users would like this feature.

EDIT : in response to some more posts that have appeared just now.

I agree with dest, source, to be the same as memcpy, strcpy, etc.

Oh, one more thing, if those who wanted an events based input system have definitely been silenced, can there at least be the following additions to the traditional key array?

keychanged[] contains non-zero for any key that changed since either the last al_flush if that proposal is taken on board, or the last page flip or blit to the front buffer?

KEY_QUIT is a virtual key, which is considered pressed if the user uses some inherent quit request function available through their OS, such as clicking the [X] in Windows.

Hmm... DOS support has been discussed a lot. On the other hand, Mac support is quite preliminary. I guess the first near-stable Allegro 5 version will come in one year and a half, two years maybe. How many users are supporting MAC lately? I am afraid it doesn't get too much attention.

Let's please not degenerate into an OS support war ... whatever OS's are supported will be because someone took the time to develop for it. If you want support for an OS, help code it.

--

I like the looks of the new API. Anything that is consistent will plese me.

Typo here, though:

int al_get_text_wdith (const AL_FONT *f, const char *str);

Conversely, if people porting is to be encouraged, how about a document on how to write a new driver being a development priority? There used to be one, many years ago, but obviously it is irrelevant now.

Please remove as much macros as possible. Integer constants can be represented by anonymous enums if necessary.

RB: it doesn't really matter since v5 is such a drastic change from v4.

Rash: yes, macros are evil. If anybody disagrees, read the C++ FAQ (or failing that, the Allegro source code! damn 100-line macros...). Enums are generally much better because the compiler can use their information in a sensible manner (such as warning you when you forget to switch(){} on them).

I also vote for (dest, source). Looks pretty sweet so far.

The only thing I don't like is the fact that some functions(i.e. al_map_rgba() and co.) both return a colour and set a parameter for it... why would we need both? I can't think of a situation where you would need a parameter where you couldn't use a return value... and it seems to be cumbersome, at least to me.

maybe its also why fputc returns what you passed it?

Yeah, blit and blit alone. All the other bitmap drawing functions use (dest, source), and I still think it's more intuitive. Besides, who cares about consistency with Allegro 4 anyway ?