[AD] show_video_bitmap() documentation a bit misleading...

["Matt Witherspoon" <spoon@xxxxxxxxxx>]

Hello all. First time trying to submit a bug/error so bare with me and
hopefully this is to some value and I'm not messing up...

This problem caused me a tremendous headache on 4.0.2. As the documentation
for show_video_bitmap() states: "This function will wait for a vertical
retrace if the graphics card requires it, so you don't need to call vsync()
yourself." This is somewhat misleading as I'll explain..

The function show_video_bitmap is a function that seems to pretty much
directly correspond to a function in the Allegro graphics driver. So the
graphics driver is responsible for how this function behaves... and the
show_video_bitmap() in the DirectX driver tied to the vsync. However as I
found out on the SVGALIB driver, it does not support video bitmaps. Thus (I
assume or else it wouldn't work) Allegro provides a fallback emulation of
the function show_video_bitmap(). However, this fallback does not wait for
the vsync. Even though the SVGALIB driver has a vsync() function that works,
this fallback function does not make use of it. Therefore, we have a
complete difference on the speed a program runs based on the Allegro
graphics driver.

My program made use of show_video_bitmap() to ensure that the application
was running no faster than 60fps (due to 60Hz refresh). Upon moving the
application from DirectX (where it was running at the correct speed), to
SVGALIB, the application all of a sudden was obviously running excessively
fast. To fix the problem (after first believing the SVGALIB driver was at
fault) I inserted vsync() above the show_video_bitmap() function and
everything was the correct speed again. I found this quite contrary to the
"you don't need to call vsync() yourself" part of the documentation.

Am I interpreting the documentation wrong on this matter? Personally, I
would have expected the fallback show_video_bitmap to wait for vsync due to
what the documentation says... which makes me think either the fallback or
the documentation needs to be fixed or clarified.


Keep up the good work    --Matt Witherspoon