Because I wanted less latency between user input and displayed changes, I am using ALLEGRO_SINGLE_BUFFER asa new display option.
On one computer, it worked great (an old intel video card) but on another (an old nvidia card - both in Linux) my program did not work smoothly because al_flip_display() was not waiting for vsync, and my fps was going at over 2000, and this was causing mouse movement events to be delayed/lost.
Upon further investigation, I found that ALLEGRO_VSYNC,1,ALLEGRO_REQUIRE would fail, however if I used _SUGGEST then it would run, but without vsync holdoff.
OK - so my video card driver doesn't support vsync waiting for al_flip_display().
So then I tried al_wait_for_vsync() just before al_flip_display() then my program runs nice again.
So I guess my suggested improvements to the documentation would be along these lines:
Some video card drivers will not allow you to set ALLEGRO_VSYNC as a new display option, in which case al_flip_display() will not wait for vsync but run as fast as your computer can, which can cause lost/delayed allegro events and cpu hogging..
At current time of this posting, there does not seem to be a way to determine cause of display creation failure, and no way to determine whether the request for ALLEGRO_VSYNC was honored. At some point al_get_display_option(display,ALLEGRO_VSYNC) may be able to be called after the display is created to see if the request was honored.
So at present there are two approaches: One is to just set ALLEGRO_VSYNC to 2 (disabled) and always call al_wait_for_vsync() before al_flip_display(). The other method is to attempt to create the display with ALLEGRO_VSYNC,1,ALLEGRO_REQUIRE, and if that fails, then try again with ALLEGRO_VSYNC,2,ALLEGRO_REQUIRE(vsync holdoff disabled) -- and if it succeeds the second time, then your program knows that it needs to call al_wait_for_vsync() before al_flip_display().