Edit
I traded out is_a_real_mode for is_a_magic_mode, to be more consistent in usage among the set of functions. Source code and demonstration program updated as well.

I've created some helper functions that I think would be useful to add to the Allegro library version 4.3.11 for future use in Allegro 4.4. They let you determine whether a certain graphics card driver is windowed, fullscreen, definitely windowed or fullscreen, or whether it is a magic driver like GFX_AUTODETECT*, GFX_SAFE, and GFX_TEXT. There is also a function to determine the current graphics driver, which is useful for when you set a magic mode that can set several different drivers.

Here are the function declarations that would be added to allegro\gfx.h :

//
AL_FUNC(int , is_a_windowed_mode   , (const int graphics_card));
AL_FUNC(int , is_a_fullscreen_mode , (const int graphics_card));
AL_FUNC(int , is_a_definite_mode   , (const int graphics_card));
AL_FUNC(int , is_a_magic_mode      , (const int graphics_card));
AL_FUNC(int , current_gfx_mode     , ());
//

The first four functions allow the programmer to determine which drivers and modes they want to allow the users of their program to select during run time. In Windows, they can use the is_a_windowed_mode function to filter out any window sizes that are not smaller than the desktop to prevent a failure to set a driver. The is_a_definite_mode function can be used to prevent a user from trying to set GFX_AUTODETECT or GFX_SAFE, neither of which guarantee to be windowed or fullscreen only.

The current_gfx_mode function will let a programmer determine which of several possible graphics mode drivers has been set, especially in the case of using GFX_AUTODETECT* and GFX_SAFE modes.

Here's the code for all 5 functions that would be added to src\graphics.c :

Naming conventions -

So, I have a couple questions :

1. Is the is_a_*_mode naming convention acceptable, or would people like to see something else?

If the current is_windowed_mode() function is renamed to in_windowed_mode(), then these functions could use a is_*_mode() naming convention, and I think in_windowed_mode would be a more appropriate name for it's purpose, since it checks the current graphics mode, and not an arbitrary one.

2. Do you see any improvements that could be made to the functions, or do you see any problems with them as they are?

Here is a zip file of the source code, and a zip file of a statically linked win32 executable of an example program that demonstrates the use of the functions to filter graphics modes used by the gfx_mode_select_filter function.

The program depends on Allegro 4.3.11+ for some fixes made to the gfx_mode_select* functions since 4.2 came out. Any revision more recent than August '08 should suffice. The program itself contains directions how to use it on screen.

I'll write up accompanying documentation for the manual tomorrow, and if everything's acceptable, I'll submit a patch for everything to [AD] for review.

Edit
Anyone have any constructive comments to make, or any preferences on the names of the functions before I submit them to [AD]?

That would actually be a different set of functions though, because for these functions you can pass any graphics card that is recognized on your platform as the parameter, as opposed to finding out whether the currently set mode is one of those types. The second behaviour could be easily implemented using these functions though :

//
   int mode_set = current_gfx_mode();
   if (is_a_windowed_mode(mode_set))   {/* .... */}
   if (is_a_fullscreen_mode(mode_set)) {/* .... */}
//

However, the first four functions are generally more useful before you set a new graphics mode, and for customizing the allowable types of graphics modes that you wish to allow your program user to set. Also, the is_windowed_mode function already exists to test the current mode's type. If it were renamed to in_windowed_mode, then I could use the is_*_mode naming convention instead of the is_a_*_mode naming convention, but it seems fine to me either way.

Edit
After some suggestions by Peter, I combined the is_a_*_mode functions into a single get_gfx_mode_type function, and renamed current_gfx_mode to get_gfx_mode.

Here's the updated header addition :

//

/// Bitfield for relaying graphics driver type information
#define GFX_TYPE_UNKNOWN     0
#define GFX_TYPE_WINDOWED    1
#define GFX_TYPE_FULLSCREEN  2
#define GFX_TYPE_DEFINITE    4
#define GFX_TYPE_MAGIC       8

AL_FUNC(int , get_gfx_mode_type , (const int graphics_card));
AL_FUNC(int , get_gfx_mode      , ());

//

Reworked source code :

Updated source code of example using the functions.
Static win32 4.3.11+ binary of the example program.

Thanks. It hasn't been accepted yet though, I'm just posting the latest incarnation for comments, suggestions, or for others to use if they like.