[AD] Docs and set_gfx_mode

[Christer Sandberg <christer.sandberg@xxxxxxxxxx>]

I'm trying to understand the function set_gfx_mode by reading the docs
(version 4.0.3), and I can't get everything completely clear.

When testing set_gfx_mode, it seems that the semantics might be
something like:
- In case the 'card' (card?) parameter is GFX_AUTODETECT_FULLSCREEN it
will, if possible, switch to a resolution as given by the parameters w
and h. It can only succeed if the graphics card of the system where the
program is executing, have the capability to set the requested
resolution. Even if the card has the capability to set the requested
resolution, set_gfx_mode can still fail if the driver that Allegro
choses does not support it.
- In case the 'card' parameter is GFX_AUTODETECT_WINDOWED it will, if
possible, create a window. The size of the drawing area in that window
will be as specified by the w and h parameter.
It seems that on my Linux systems arbitrary window sizes can be set
(only memory limitations). Does that apply also for other platforms,
or are there some stricter limitations?

If I have made correct observations of the behavior (as described
above), then neither of the below statements are correct (copied from
the docs):
"Switches into graphics mode"
"The w and h parameters specify what screen resolution you want"

The meaning of GFX_AUTODETECT is not explained, and it's not very clear
from the name what behavior that should be expected (e.g. will it try
both windowed and full screen mode?, in which order?, what does it
actually autodetect?). 

Maybe the description of the GFX_AUTODETECT_FULLSCREEN and
GFX_AUTODETECT_WINDOWED should be explained here (under st_gfx_mode)
rather than under the platform specifics (leaving the exceptions
concerning DOS and Linux Console to the platform specifics)? The reasons
why I think that would be better are two:
- They are refered here and have almost the same meaning on all
platforms
- Avoiding to encurage people to dig into platform specifics at the very
beginning.

I can't find any info about which colour depth that is used by default
(if set_color_depth is not called).

Also, I can't get the meaning of "colour depth" in windowed mode, when
reading the docs. Experimenting at bit, it seems that the graphics card
keeps its current settings when changing the colour depth.

The use of virtual screens is maybe simple, but I don't understand it
(using the docs as the source). Reading the examples ex3buf and exflip
raises the idea that a virtual screen needs to be set up if one want to
create video bitmaps. Is that so? If so, I think it would be nice with
some hints about it under 'set_gfx_mode' item in the docs. Also the
description of the usage (scrolling/page flipping) could be improved by
just mention the functions split_modex_screen and scroll_screen. Are
there any differences in windowed and full screen modes concerning
virtual screens? What is the precise meaning of setting one of the
parameters v_w or v_h to 0? At least the size of the screen mode?, the
largest possible? or something else? If "largest possible", then, what
does it mean when both are set to 0?

Sorry if I have I have missed something. In case I have, I would be
happy to get pointers to the right information sources. 

Please note that I am not in emergent need of the actual knowledge. I
rather want to know where to get the information the day I need it. One
of the reasons is that I am teaching a course where Allegro is suggested
as the platform for the game programming project. One of the first
things for a student to look up in the docs is probably 'set_gfx_mode'.

-- 
Christer Sandberg <csg01@xxxxxxxxxx>