<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: Graphics modes
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="Graphics modes">Graphics modes</a></h1>
<ul>
<li><a href="#destroy_gfx_mode_list">destroy_gfx_mode_list</a> — Frees the list created by get_gfx_mode_list().
<li><a href="#enable_triple_buffer">enable_triple_buffer</a> — Enables triple buffering.
<li><a href="#get_color_depth">get_color_depth</a> — Returns the current pixel color depth.
<li><a href="#get_display_switch_mode">get_display_switch_mode</a> — Returns the current display switching mode.
<li><a href="#get_gfx_mode">get_gfx_mode</a> — Returns the id of the current graphics driver.
<li><a href="#get_gfx_mode_list">get_gfx_mode_list</a> — Obtains a list of available video modes.
<li><a href="#get_gfx_mode_type">get_gfx_mode_type</a> — Retrieves type information for a specific graphics card.
<li><a href="#get_refresh_rate">get_refresh_rate</a> — Returns the current refresh rate.
<li><a href="#gfx_capabilities">gfx_capabilities</a> — Bitfield describing video hardware capabilities.
<li><a href="#is_windowed_mode">is_windowed_mode</a> — Tells if you are running in windowed mode.
<li><a href="#poll_scroll">poll_scroll</a> — Checks the status of a scroll request with triple buffering.
<li><a href="#remove_display_switch_callback">remove_display_switch_callback</a> — Removes a switching notification callback.
<li><a href="#request_refresh_rate">request_refresh_rate</a> — Requests a specific refresh rate during graphic mode switch.
<li><a href="#request_scroll">request_scroll</a> — Queues a hardware scroll request with triple buffering.
<li><a href="#request_video_bitmap">request_video_bitmap</a> — Triple buffering page flip request.
<li><a href="#scroll_screen">scroll_screen</a> — Requests a hardware scroll request.
<li><a href="#set_color_depth">set_color_depth</a> — Sets the global pixel color depth.
<li><a href="#set_display_switch_callback">set_display_switch_callback</a> — Installs a switching notification callback.
<li><a href="#set_display_switch_mode">set_display_switch_mode</a> — Tells Allegro how the program handles background switching.
<li><a href="#set_gfx_mode">set_gfx_mode</a> — Sets a graphic video mode.
<li><a href="#show_video_bitmap">show_video_bitmap</a> — Flips the hardware screen to use the specified page.
<li><a href="#vsync">vsync</a> — Waits for a vertical retrace to begin.
</ul>
<p>
Graphics modes are the common denominator for most Allegro programs. While it
is possible to write platform specific programs using Allegro which don't set
a graphic mode through the routines provided in this chapter, these are not
very common.
<p>
The first thing to note is that due to the wide range of supported platforms,
a graphic mode is the only way to safely communicate with the user. When
Allegro was a DOS only library (versions 3.x and previous), it was frequent
for programmers to use functions from the C standard library to communicate
with the user, like calling printf() before setting a graphic mode or maybe
scanf() to read the user's input. However, what would happen for such a game
running under Windows where there is no default console output or it may be
hidden from the user? Even if the game compiled successfully, it would be
unplayable, especially if there was vital information for the user in those
text only messages.
<p>
Allegro provides the allegro_message() function to deal with this problem,
but this is not a very user friendly method of communicating with the user
and its main purpose is displaying small error like messages when no graphic
mode is available. Therefore, the first thing your Allegro program should do
is set a graphic mode, and from there on, use Allegro's text output routines
to display messages to the user, just like <tt>`allegro/examples/exhello.c'</tt> does.
<p>
Setting a graphic mode involves deciding how to allocate the memory of the
video card for your program. On some platforms this means creating a virtual
screen bigger than the physical resolution to do hardware scrolling or page
flipping. Virtual screens can cause a lot of confusion, but they are really
quite simple. Warning: patronising explanation coming up, so you may wish to
skip the rest of this paragraph. Think of video memory as a rectangular piece
of paper which is being viewed through a small hole (your monitor) in a bit of
cardboard. Since the paper is bigger than the hole you can only see part of it
at any one time, but by sliding the cardboard around you can alter which
portion of the image is visible. You could just leave the hole in one position
and ignore the parts of video memory that aren't visible, but you can get all
sorts of useful effects by sliding the screen window around, or by drawing
images in a hidden part of video memory and then flipping across to display
them.
<p>
For example, you could select a 640x480 mode in which the monitor acts as a
window onto a 1024x1024 virtual screen, and then move the visible screen
around in this larger area (hardware scrolling). Initially, with the visible
screen positioned at the top left corner of video memory, this setup would
look like:
<blockquote class="text"><pre>
(0,0)------------(640,0)----(1024,0)
| | |
| visible screen | |
| | |
(0,480)----------(640,480) |
| |
| the rest of video memory |
| |
(0,1024)--------------------(1024,1024)
</pre></blockquote>
With a virtual screen bigger than the visible screen you can perform smooth
CPU inexpensive scrolling: you draw your graphics once, and then only tell
the video card to show a different portion of the screen. However, virtual
screens are not supported on all platforms, and on some they might be
emulated through software, losing any performance. On top of that, many video
cards only allow horizontal scrolling in steps of 32 bytes. This is not a
problem if your game runs in 24 or 32 bit, but it tends to mean jerky
scrolling for other color depths.
<p>
The other reason you could use virtual screens for is page flipping. This
means showing one portion of the virtual screen while your program draws to
the hidden one. When you finish, you show the part you have been drawing to
and repeat the process with the area now hidden. The result is a perfectly
smooth screen update without flickering or other graphical artifacts.
<p>
Scrolling manually to one part of the video memory is one non portable way to
accomplish this. The portable way is to use functions like
create_system_bitmap(), create_video_bitmap(), show_video_bitmap(), etc. These
functions divide the memory of the video card in areas and switch between
them, a feature supported on all platforms and video cards (given that they
have enough memory for the screen resolutions you asked for).
<p>
The last thing you need to know about setting a graphic mode are drivers.
Each platform has a number of graphic drivers which support a different range
of hardware or behave in different ways. To avoid cluttering your own code
with #ifdefs and dealing with drivers added after you release your program,
Allegro provides several so called magic drivers. These magic drivers don't
really exists, they wrap around a specific kind of functionality.
<p>
The magic drivers you can use are:
<ul><li>
GFX_AUTODETECT:<br>
Allegro will try to set the specified resolution with the current color
depth in fullscreen mode. Failing that, it will try to repeat the same
operation in windowed mode. If the call to set_gfx_mode() succeeds, you
are guaranteed to have set the specified resolution in the current color
depth, but you don't know if the program is running fullscreen or
windowed.
<li>
GFX_AUTODETECT_FULLSCREEN:<br>
Allegro will try to set the specified resolution with the current color
depth in fullscreen mode. If that is not possible, set_gfx_mode() will
fail.
<li>
GFX_AUTODETECT_WINDOWED:<br>
Allegro will try to set the specified resolution with the current color
depth in a windowed mode. If that is not possible, set_gfx_mode() will
fail. When it comes to windowed modes, the `specified resolution' actually
means the graphic area your program can draw on, without including window
decorations (if any). Note that in windowed modes running with a color
depth other than the desktop may result in non optimal performance due to
internal color conversions in the graphic driver. Use
desktop_color_depth() to your advantage in these situations.
<li>
GFX_SAFE:<br>
Using this driver Allegro guarantees that a graphic mode will always be
set correctly. It will try to select the resolution that you request, and
if that fails, it will fall back upon whatever mode is known to be
reliable on the current platform (this is 320x200 VGA mode under DOS, a
640x480 resolution under Windows, the actual framebuffer's resolution
under Linux if it's supported, etc). If it absolutely cannot set any
graphics mode at all, it will return negative as usual, meaning that
there's no possible video output on the machine, and that you should abort
your program immediately, possibly after notifying this to the user with
allegro_message.
This fake driver is useful for situations where you just want to get into
some kind of workable display mode, and can't be bothered with trying
multiple different resolutions and doing all the error checking yourself.
Note however, that after a successful call to set_gfx_mode with this
driver, you cannot make any assumptions about the width, height or color
depth of the screen: your code will have to deal with this little detail.
<li>
GFX_TEXT:<br>
Closes any previously opened graphics mode, making you unable to use the
global variable <tt>`screen'</tt>, and in those environments that have text modes,
sets one previously used or the closest match to that (usually 80x25).
With this driver the size parameters of set_gfx_mode don't mean anything,
so you can leave them all to zero or any other number you prefer.
</ul>
<p><br>
<div class="al-api"><b>void <a name="set_color_depth">set_color_depth</a>(int depth);</b></div><br>
Sets the pixel format to be used by subsequent calls to set_gfx_mode()
and create_bitmap(). Valid depths are 8 (the default), 15, 16, 24, and 32
bits. Example:
<blockquote class="code"><pre>
<a href="#set_color_depth" class="autotype" title="Sets the global pixel color depth.">set_color_depth</a>(32);
if (<a href="#set_gfx_mode" class="autotype" title="Sets a graphic video mode.">set_gfx_mode</a>(GFX_AUTODETECT, 640, 480, 0, 0) != 0) {
abort_on_error("Couldn't set a 32 bit color resolution");
}
</pre></blockquote>
Note that the screen color depth won't change until the next successful
call to set_gfx_mode().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_color_depth" title="Returns the current pixel color depth.">get_color_depth</a>,
<a class="xref" href="#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="alleg010.html#set_color_conversion" title="Tells Allegro how to convert images during loading time.">set_color_conversion</a>,
<a class="xref" href="alleg012.html#makecol" title="Converts an RGB value into the current pixel format.">makecol</a>,
<a class="xref" href="alleg012.html#getr" title="Extract a color component from the current pixel format.">getr</a>,
<a class="xref" href="alleg000.html#desktop_color_depth" title="Finds out the desktop color depth.">desktop_color_depth</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b>int <a name="get_color_depth">get_color_depth</a>(void);</b></div><br>
Returns the current pixel format. This can be very useful to know in order
to write generic functions which select a different code path internally
depending on the color depth being used.
<p>
Note that the function returns whatever value you may have set previously
with set_color_depth(), which can be different from the current color
depth of the screen global variable. If you really need to know the color
depth of the screen, use bitmap_color_depth().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_color_depth" title="Sets the global pixel color depth.">set_color_depth</a>,
<a class="xref" href="alleg009.html#bitmap_color_depth" title="Returns the color depth of the specified bitmap.">bitmap_color_depth</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exrgbhsv" title="RGB <-> HSV color space conversions.">exrgbhsv</a>.</blockquote>
<div class="al-api"><b>void <a name="request_refresh_rate">request_refresh_rate</a>(int rate);</b></div><br>
Requests that the next call to set_gfx_mode() try to use the specified
refresh rate, if possible. Not all drivers are able to control this at
all, and even when they can, not all rates will be possible on all
hardware, so the actual settings may differ from what you requested.
After you call set_gfx_mode(), you can use get_refresh_rate() to find out
what was actually selected. At the moment only the DOS VESA 3.0, X DGA 2.0
and some Windows DirectX drivers support this function. The speed is
specified in Hz, eg. 60, 70. To return to the normal default selection,
pass a rate value of zero. Example:
<blockquote class="code"><pre>
<a href="#request_refresh_rate" class="autotype" title="Requests a specific refresh rate during graphic mode switch.">request_refresh_rate</a>(60);
if (<a href="#set_gfx_mode" class="autotype" title="Sets a graphic video mode.">set_gfx_mode</a>(GFX_AUTODETECT, 640, 480, 0, 0) != 0)
abort_on_error("Couldn't set graphic mode!");
if (<a href="#get_refresh_rate" class="autotype" title="Returns the current refresh rate.">get_refresh_rate</a>() != 60)
abort_on_error("Couldn't set refresh rate to 60Hz!");</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="#get_refresh_rate" title="Returns the current refresh rate.">get_refresh_rate</a>.</blockquote>
<div class="al-api"><b>int <a name="get_refresh_rate">get_refresh_rate</a>(void);</b></div><br>
Returns the current refresh rate, if known (not all drivers are able to
report this information). Returns zero if the actual rate is unknown.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#request_refresh_rate" title="Requests a specific refresh rate during graphic mode switch.">request_refresh_rate</a>.</blockquote>
<div class="al-api"><b><a class="autotype" href="alleg001.html#GFX_MODE_LIST" title="Stores an array of GFX_MODE structures.">GFX_MODE_LIST</a> *<a name="get_gfx_mode_list">get_gfx_mode_list</a>(int card);</b></div><br>
Attempts to create a list of all the supported video modes for a certain
graphics driver, made up from the GFX_MODE_LIST structure, which has the
following definition:
<blockquote class="code"><pre>
typedef struct <a href="alleg001.html#GFX_MODE_LIST" class="autotype" title="Stores an array of GFX_MODE structures.">GFX_MODE_LIST</a>
{
int num_modes;
<a href="alleg001.html#GFX_MODE" class="autotype" title="Stores video mode information.">GFX_MODE</a> *mode;
} <a href="alleg001.html#GFX_MODE_LIST" class="autotype" title="Stores an array of GFX_MODE structures.">GFX_MODE_LIST</a>;
</pre></blockquote>
The mode entry points to the actual list of video modes.
<blockquote class="code"><pre>
typedef struct <a href="alleg001.html#GFX_MODE" class="autotype" title="Stores video mode information.">GFX_MODE</a>
{
int width, height, bpp;
} <a href="alleg001.html#GFX_MODE" class="autotype" title="Stores video mode information.">GFX_MODE</a>;
</pre></blockquote>
This list of video modes is terminated with an { 0, 0, 0 } entry.
<p>
Note that the card parameter must refer to a _real_ driver. This function
fails if you pass GFX_SAFE, GFX_AUTODETECT, or any other "magic" driver.
<p><b>Return value:</b>
Returns a pointer to a list structure of the type GFX_MODE_LIST or NULL
if the request could not be satisfied.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#destroy_gfx_mode_list" title="Frees the list created by get_gfx_mode_list().">destroy_gfx_mode_list</a>,
<a class="xref" href="#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="#set_color_depth" title="Sets the global pixel color depth.">set_color_depth</a>.</blockquote>
<div class="al-api"><b>void <a name="destroy_gfx_mode_list">destroy_gfx_mode_list</a>(<a class="autotype" href="alleg001.html#GFX_MODE_LIST" title="Stores an array of GFX_MODE structures.">GFX_MODE_LIST</a> *mode_list);</b></div><br>
Removes the mode list created by get_gfx_mode_list() from memory. Use this
once you are done with the generated mode list to avoid memory leaks in
your program.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#get_gfx_mode_list" title="Obtains a list of available video modes.">get_gfx_mode_list</a>,
<a class="xref" href="#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="#set_color_depth" title="Sets the global pixel color depth.">set_color_depth</a>.</blockquote>
<div class="al-api"><b>int <a name="set_gfx_mode">set_gfx_mode</a>(int card, int w, int h, int v_w, int v_h);</b></div><br>
Switches into graphics mode. The card parameter should usually be one of
the Allegro magic drivers (read introduction of chapter "Graphics modes")
or see the platform specific documentation for a list of the available
drivers. The w and h parameters specify what screen resolution you want.
The color depth of the graphic mode has to be specified before calling
this function with set_color_depth().
<p>
The v_w and v_h parameters specify the minimum virtual screen size, in
case you need a large virtual screen for hardware scrolling or page
flipping. You should set them to zero if you don't care about the virtual
screen size.
<p>
When you call set_gfx_mode(), the v_w and v_h parameters represent the
minimum size of virtual screen that is acceptable for your program. The
range of possible sizes is usually very restricted, and Allegro may
end up creating a virtual screen much larger than the one you request.
Allowed sizes are driver dependent and some drivers do not allow virtual
screens that are larger than the visible screen at all: don't assume
that whatever you pass will always work.
<p>
In mode-X the virtual width can be any multiple of eight greater than or
equal to the physical screen width, and the virtual height will be set
accordingly (the VGA has 256k of vram, so the virtual height will be
256*1024/virtual_width).
<p>
Currently, using a big virtual screen for page flipping is considered bad
practice. There are platforms which don't support virtual screens bigger
than the physical screen but can create different video pages to flip back
and forth. This means that, if you want page flipping and aren't going to
use hardware scrolling, you should call set_gfx_mode() with (0,0) as the
virtual screen size and later create the different video pages with
create_video_bitmap(). Otherwise your program will be limited to the
platforms supporting hardware scrolling.
<p>
After you select a graphics mode, the physical and virtual screen sizes
can be checked with the macros SCREEN_W, SCREEN_H, VIRTUAL_W, and
VIRTUAL_H.
<p><b>Return value:</b>
Returns zero on success. On failure returns a negative number and stores a
description of the problem in allegro_error.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_color_depth" title="Sets the global pixel color depth.">set_color_depth</a>,
<a class="xref" href="#request_refresh_rate" title="Requests a specific refresh rate during graphic mode switch.">request_refresh_rate</a>,
<a class="xref" href="alleg009.html#screen" title="Global pointer to the screen hardware video memory.">screen</a>,
<a class="xref" href="#gfx_capabilities" title="Bitfield describing video hardware capabilities.">gfx_capabilities</a>,
<a class="xref" href="alleg000.html#allegro_error" title="Stores the last Allegro error message.">allegro_error</a>,
<a class="xref" href="alleg003.html#Standard config variables" title="">Standard config variables</a>,
<a class="xref" href="alleg036.html#GFX_*/DOS" title="Supported DOS graphic drivers.">GFX_*/DOS</a>,
<a class="xref" href="alleg037.html#GFX_*/Windows" title="Supported Windows graphic drivers.">GFX_*/Windows</a>,
<a class="xref" href="alleg038.html#GFX_*/X" title="Supported X graphic drivers.">GFX_*/X</a>,
<a class="xref" href="alleg038.html#GFX_*/Linux" title="Supported Linux console graphic drivers.">GFX_*/Linux</a>,
<a class="xref" href="alleg039.html#GFX_*/BeOS" title="Supported BeOS graphic drivers.">GFX_*/BeOS</a>,
<a class="xref" href="alleg041.html#GFX_*/MacOSX" title="Supported MacOSX graphic drivers.">GFX_*/MacOSX</a>,
<a class="xref" href="alleg009.html#create_video_bitmap" title="Creates a video memory bitmap.">create_video_bitmap</a>,
<a class="xref" href="alleg000.html#get_desktop_resolution" title="Finds out the desktop resolution.">get_desktop_resolution</a>,
<a class="xref" href="alleg009.html#SCREEN_W" title="Global define to obtain the size of the screen.">SCREEN_W</a>,
<a class="xref" href="alleg009.html#SCREEN_H" title="Global define to obtain the size of the screen.">SCREEN_H</a>,
<a class="xref" href="alleg009.html#VIRTUAL_W" title="Global define to obtain the virtual size of the screen.">VIRTUAL_W</a>,
<a class="xref" href="alleg009.html#VIRTUAL_H" title="Global define to obtain the virtual size of the screen.">VIRTUAL_H</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<div class="al-api"><b>int <a name="set_display_switch_mode">set_display_switch_mode</a>(int mode);</b></div><br>
Sets how the program should handle being switched into the background,
if the user tabs away from it. Not all of the possible modes will be
supported by every graphics driver on every platform. The available modes
are:
<ul><li>
SWITCH_NONE<br>
Disables switching. This is the default in single-tasking systems like
DOS. It may be supported on other platforms, but you should use it
with caution, because your users won't be impressed if they want to
switch away from your program, but you don't let them!
<li>
SWITCH_PAUSE<br>
Pauses the program whenever it is in the background. Execution will be
resumed as soon as the user switches back to it. This is the default
in most fullscreen multitasking environments, for example the Linux
console, but not under Windows.
<li>
SWITCH_AMNESIA<br>
Like SWITCH_PAUSE, but this mode doesn't bother to remember the
contents of video memory, so the screen, and any video bitmaps that
you have created, will be erased after the user switches away and then
back to your program. This is not a terribly useful mode to have, but
it is the default for the fullscreen drivers under Windows because
DirectDraw is too dumb to implement anything better.
<li>
SWITCH_BACKGROUND<br>
The program will carry on running in the background, with the screen
bitmap temporarily being pointed at a memory buffer for the fullscreen
drivers. You must take special care when using this mode, because bad
things will happen if the screen bitmap gets changed around when your
program isn't expecting it (see below).
<li>
SWITCH_BACKAMNESIA<br>
Like SWITCH_BACKGROUND, but this mode doesn't bother to remember the
contents of video memory (see SWITCH_AMNESIA). It is again the only
mode supported by the fullscreen drivers under Windows that lets the
program keep running in the background.
</ul>
Note that you should be very careful when you are using graphics routines
in the switching context: you must always call acquire_screen() before the
start of any drawing code onto the screen and not release it until you are
completely finished, because the automatic locking mechanism may not be
good enough to work when the program runs in the background or has just
been raised in the foreground.
<p><b>Return value:</b>
Returns zero on success, invalidating at the same time all callbacks
previously registered with set_display_switch_callback(). Returns -1 if
the requested mode is not currently possible.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_display_switch_callback" title="Installs a switching notification callback.">set_display_switch_callback</a>,
<a class="xref" href="#get_display_switch_mode" title="Returns the current display switching mode.">get_display_switch_mode</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exmidi" title="Playing MIDI music.">exmidi</a>,
<a class="eref" href="alleg045.html#exswitch" title="Controlling the console switch mode for background running.">exswitch</a>.</blockquote>
<div class="al-api"><b>int <a name="set_display_switch_callback">set_display_switch_callback</a>(int dir, void (*cb)());</b></div><br>
Installs a notification callback for the switching mode that was
previously selected by calling set_display_switch_mode(). The direction
parameter can either be SWITCH_IN or SWITCH_OUT, depending whether you
want to be notified about switches away from your program or back to your
program. You can sometimes install callbacks for both directions at the
same time, but not every platform supports this. You can install several
switch callbacks, but no more than eight on any platform.
<p><b>Return value:</b>
Returns zero on success, decreasing the number of empty callback slots by
one. Returns -1 if the request is impossible for the current platform or
you have reached the maximum number of allowed callbacks.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#remove_display_switch_callback" title="Removes a switching notification callback.">remove_display_switch_callback</a>,
<a class="xref" href="#set_display_switch_mode" title="Tells Allegro how the program handles background switching.">set_display_switch_mode</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exswitch" title="Controlling the console switch mode for background running.">exswitch</a>.</blockquote>
<div class="al-api"><b>void <a name="remove_display_switch_callback">remove_display_switch_callback</a>(void (*cb)());</b></div><br>
Removes a notification callback that was previously installed by calling
set_display_switch_callback(). All the callbacks will automatically be
removed when you call set_display_switch_mode(). You can safely call this
function even if the callback you want to remove is not installed.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_display_switch_callback" title="Installs a switching notification callback.">set_display_switch_callback</a>.</blockquote>
<div class="al-api"><b>int <a name="get_display_switch_mode">get_display_switch_mode</a>();</b></div><br>
Returns the current display switching mode, in the same format passed to
set_display_switch_mode().
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_display_switch_mode" title="Tells Allegro how the program handles background switching.">set_display_switch_mode</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exswitch" title="Controlling the console switch mode for background running.">exswitch</a>.</blockquote>
<div class="al-api"><b>int <a name="is_windowed_mode">is_windowed_mode</a>(void);</b></div><br>
This function can be used to detect whether or not set_gfx_mode() selected
a windowed mode. Example:
<blockquote class="code"><pre>
if (<a href="#set_gfx_mode" class="autotype" title="Sets a graphic video mode.">set_gfx_mode</a>(GFX_AUTODETECT, 640, 480, 0, 0) != 0)
abort_on_error("Couldn't set graphic mode!");
if (<a href="#is_windowed_mode" class="autotype" title="Tells if you are running in windowed mode.">is_windowed_mode</a>()) {
/* Windowed mode stuff. */
} else {
/* Fullscreen mode stuff. */
}</pre></blockquote>
<p><b>Return value:</b>
Returns true if the current graphics mode is a windowed mode, or zero if
it is a fullscreen mode. You should not call this function if you are not
in graphics mode.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>.</blockquote>
<div class="al-api"><b>int <a name="get_gfx_mode_type">get_gfx_mode_type</a>(int graphics_card);</b></div><br>
This function lets you determine the types of operating modes that a
specific graphics card driver operates in. It will tell you whether it is
a windowed, fullscreen, definitely windowed or fullscreen, and/or a magic
driver.
<p>
The value returned is a bitfield consisting of these fields:<br>
<b>GFX_TYPE_UNKNOWN</b><br>
<b>GFX_TYPE_WINDOWED</b><br>
<b>GFX_TYPE_FULLSCREEN</b><br>
<b>GFX_TYPE_DEFINITE</b><br>
<b>GFX_TYPE_MAGIC</b><br>
<br>
<p>
The return value will only be equivalent to GFX_TYPE_UNKNOWN when it is
a driver unrecognized on that platform, or it is a bogus value. Test for
the other types by using a bitwise AND. If the driver is windowed or
fullscreen, it will also have the definite flag set.
For example,
<blockquote class="code"><pre>
int gfx_type = <a href="#get_gfx_mode_type" class="autotype" title="Retrieves type information for a specific graphics card.">get_gfx_mode_type</a>(GFX_AUTODETECT_WINDOWED);
</pre></blockquote>
gfx_type would have the GFX_TYPE_WINDOWED, GFX_TYPE_DEFINITE, and
GFX_TYPE_MAGIC flags set.
<p>
Allegro needs to be initialized first.
<p>
Example:
<blockquote class="code"><pre>
/* Accept the use of only windowed drivers in our selection dialog */
int accept_windowed(int card , int w , int h , int color_depth)
{
if (<a href="#get_gfx_mode_type" class="autotype" title="Retrieves type information for a specific graphics card.">get_gfx_mode_type</a>(card) & GFX_TYPE_WINDOWED)
return 0;
return 1;
}
/* In main: */
<a href="alleg035.html#gfx_mode_select_filter" class="autotype" title="Even more extended version of the graphics mode selection dialog.">gfx_mode_select_filter</a>(&card, &w, &h, &color_depth, accept_windowed);
</pre></blockquote>
<p><b>Return value:</b>
Returns a bitfield describing the graphics mode type.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg035.html#gfx_mode_select_filter" title="Even more extended version of the graphics mode selection dialog.">gfx_mode_select_filter</a>,
<a class="xref" href="#get_gfx_mode" title="Returns the id of the current graphics driver.">get_gfx_mode</a>,
<a class="xref" href="#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="#is_windowed_mode" title="Tells if you are running in windowed mode.">is_windowed_mode</a>.</blockquote>
<div class="al-api"><b>int <a name="get_gfx_mode">get_gfx_mode</a>();</b></div><br>
This function will let you determine which graphics driver is currently
set by allegro. If no graphics driver is set, it will return GFX_NONE.
<p><b>Return value:</b>
<p>
Returns the id of the current graphics driver if there is one, or GFX_NONE
if none is set.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="#is_windowed_mode" title="Tells if you are running in windowed mode.">is_windowed_mode</a>.</blockquote>
<div class="al-api"><b>extern int <a name="gfx_capabilities">gfx_capabilities</a>;</b></div><br>
Bitfield describing the capabilities of the current graphics driver and
video hardware. This may contain combination any of the flags:
<p>
<b>GFX_CAN_SCROLL:</b><br>
Indicates that the scroll_screen() function may be used with this
driver.
<p>
<b>GFX_CAN_TRIPLE_BUFFER:</b><br>
Indicates that the request_scroll() and poll_scroll() functions may be
used with this driver. If this flag is not set, it is possible that
the enable_triple_buffer() function may be able to activate it.
<p>
<b>GFX_HW_CURSOR:</b><br>
Indicates that a hardware mouse cursor is in use. When this flag is
set, it is safe to draw onto the screen without hiding the mouse
pointer first. Note that not every cursor graphic can be implemented
in hardware: in particular VBE/AF only supports 2-color images up to
32x32 in size, where the second color is an exact inverse of the
first. This means that Allegro may need to switch between hardware and
software cursors at any point during the execution of your program, so
you should not assume that this flag will remain constant for long
periods of time. It only tells you whether a hardware cursor is in use
at the current time, and may change whenever you hide/redisplay the
pointer.
<p>
<b>GFX_SYSTEM_CURSOR</b><br>
Indicates that the mouse cursor is the default system cursor, not
Allegro's custom cursor.
<p>
<b>GFX_HW_HLINE:</b><br>
Indicates that the normal opaque version of the hline() function is
implemented using a hardware accelerator. This will improve the
performance not only of hline() itself, but also of many other
functions that use it as a workhorse, for example circlefill(),
triangle(), and floodfill().
<p>
<b>GFX_HW_HLINE_XOR:</b><br>
Indicates that the XOR version of the hline() function, and any other
functions that use it as a workhorse, are implemented using a hardware
accelerator.
<p>
<b>GFX_HW_HLINE_SOLID_PATTERN:</b><br>
Indicates that the solid and masked pattern modes of the hline()
function, and any other functions that use it as a workhorse, are
implemented using a hardware accelerator (see note below).
<p>
<b>GFX_HW_HLINE_COPY_PATTERN:</b><br>
Indicates that the copy pattern mode of the hline() function, and any
other functions that use it as a workhorse, are implemented using a
hardware accelerator (see note below).
<p>
<b>GFX_HW_FILL:</b><br>
Indicates that the opaque version of the rectfill() function, the
clear_bitmap() routine, and clear_to_color(), are implemented using a
hardware accelerator.
<p>
<b>GFX_HW_FILL_XOR:</b><br>
Indicates that the XOR version of the rectfill() function is
implemented using a hardware accelerator.
<p>
<b>GFX_HW_FILL_SOLID_PATTERN:</b><br>
Indicates that the solid and masked pattern modes of the rectfill()
function are implemented using a hardware accelerator (see note below).
<p>
<b>GFX_HW_FILL_COPY_PATTERN:</b><br>
Indicates that the copy pattern mode of the rectfill() function is
implemented using a hardware accelerator (see note below).
<p>
<b>GFX_HW_LINE:</b><br>
Indicates that the opaque mode line() and vline() functions are
implemented using a hardware accelerator.
<p>
<b>GFX_HW_LINE_XOR:</b><br>
Indicates that the XOR version of the line() and vline() functions are
implemented using a hardware accelerator.
<p>
<b>GFX_HW_TRIANGLE:</b><br>
Indicates that the opaque mode triangle() function is implemented
using a hardware accelerator.
<p>
<b>GFX_HW_TRIANGLE_XOR:</b><br>
Indicates that the XOR version of the triangle() function is
implemented using a hardware accelerator.
<p>
<b>GFX_HW_GLYPH:</b><br>
Indicates that monochrome character expansion (for text drawing) is
implemented using a hardware accelerator.
<p>
<b>GFX_HW_VRAM_BLIT:</b><br>
Indicates that blitting from one part of the screen to another is
implemented using a hardware accelerator. If this flag is set,
blitting within the video memory will almost certainly be the fastest
possible way to display an image, so it may be worth storing some of
your more frequently used graphics in an offscreen portion of the
video memory.
<p>
<b>GFX_HW_VRAM_BLIT_MASKED:</b><br>
Indicates that the masked_blit() routine is capable of a hardware
accelerated copy from one part of video memory to another, and that
draw_sprite() will use a hardware copy when given a sub-bitmap of the
screen or a video memory bitmap as the source image. If this flag is
set, copying within the video memory will almost certainly be the
fastest possible way to display an image, so it may be worth storing
some of your more frequently used sprites in an offscreen portion of
the video memory.
<p>
Warning: if this flag is not set, masked_blit() and draw_sprite() will
not work correctly when used with a video memory source image! You
must only try to use these functions to copy within the video memory
if they are supported in hardware.
<p>
<b>GFX_HW_MEM_BLIT:</b><br>
Indicates that blitting from a memory bitmap onto the screen is being
accelerated in hardware.
<p>
<b>GFX_HW_MEM_BLIT_MASKED:</b><br>
Indicates that the masked_blit() and draw_sprite() functions are being
accelerated in hardware when the source image is a memory bitmap and
the destination is the physical screen.
<p>
<b>GFX_HW_SYS_TO_VRAM_BLIT:</b><br>
Indicates that blitting from a system bitmap onto the screen is being
accelerated in hardware. Note that some acceleration may be present
even if this flag is not set, because system bitmaps can benefit from
normal memory to screen blitting as well. This flag will only be set
if system bitmaps have further acceleration above and beyond what is
provided by GFX_HW_MEM_BLIT.
<p>
<b>GFX_HW_SYS_TO_VRAM_BLIT_MASKED:</b><br>
Indicates that the masked_blit() and draw_sprite() functions are being
accelerated in hardware when the source image is a system bitmap and
the destination is the physical screen. Note that some acceleration
may be present even if this flag is not set, because system bitmaps
can benefit from normal memory to screen blitting as well. This flag
will only be set if system bitmaps have further acceleration above and
beyond what is provided by GFX_HW_MEM_BLIT_MASKED.
<p>
<b>GFX_HW_VRAM_STRETCH_BLIT:</b><br>
Indicates that stretched blitting of video bitmaps onto the screen is
implemented using hardware acceleration.
<p>
<b>GFX_HW_SYS_STRETCH_BLIT:</b><br>
Indicates that stretched blitting of system bitmaps onto the screen is
implemented using hardware acceleration.
<p>
<b>GFX_HW_VRAM_STRETCH_BLIT_MASKED:</b><br>
Indicates that masked stretched blitting (including stretch_sprite) of
video bitmaps onto the screen is implemented using hardware acceleration.
NOTE: some display drivers may show artifacts when this function is used.
If the image does not look correct try updating your video drivers.
<p>
<b>GFX_HW_SYS_STRETCH_BLIT_MASKED:</b><br>
Indicates that masked stretched blitting (including stretch_sprite) of
system bitmaps onto the screen is implemented using hardware acceleration.
NOTE: some display drivers may show artefact's when this function is used.
If the image does not look correct try updating your video drivers.
<p>
Note: even if the capabilities information says that patterned drawing is
supported by the hardware, it will not be possible for every size of
pattern. VBE/AF only supports patterns up to 8x8 in size, so Allegro will
fall back on the original non-accelerated drawing routines whenever you
use a pattern larger than this.
<p>
Note2: these hardware acceleration features will only take effect when
you are drawing directly onto the screen bitmap, a video memory bitmap,
or a sub-bitmap thereof. Accelerated hardware is most useful in a page
flipping or triple buffering setup, and is unlikely to make any
difference to the classic "draw onto a memory bitmap, then blit to the
screen" system.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg009.html#screen" title="Global pointer to the screen hardware video memory.">screen</a>,
<a class="xref" href="alleg009.html#create_video_bitmap" title="Creates a video memory bitmap.">create_video_bitmap</a>,
<a class="xref" href="#scroll_screen" title="Requests a hardware scroll request.">scroll_screen</a>,
<a class="xref" href="#request_scroll" title="Queues a hardware scroll request with triple buffering.">request_scroll</a>,
<a class="xref" href="alleg004.html#show_mouse" title="Tells Allegro to display a mouse pointer on the screen.">show_mouse</a>,
<a class="xref" href="#enable_triple_buffer" title="Enables triple buffering.">enable_triple_buffer</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#ex3buf" title="Mode-X triple buffering and retrace interrupt simulation.">ex3buf</a>,
<a class="eref" href="alleg045.html#exaccel" title="Using offscreen video memory to store source graphics for VBE/AF.">exaccel</a>,
<a class="eref" href="alleg045.html#exsyscur" title="Hardware accelerated mouse cursors.">exsyscur</a>,
<a class="eref" href="alleg045.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>.</blockquote>
<div class="al-api"><b>int <a name="enable_triple_buffer">enable_triple_buffer</a>();</b></div><br>
If the GFX_CAN_TRIPLE_BUFFER bit of the gfx_capabilities field is not
set, you can attempt to enable it by calling this function. In particular
if you are running in mode-X in a clean DOS environment, this routine
will enable the timer retrace simulator, which will activate the triple
buffering functions.
<p><b>Return value:</b>
Returns zero if triple buffering is enabled, -1 otherwise.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#gfx_capabilities" title="Bitfield describing video hardware capabilities.">gfx_capabilities</a>,
<a class="xref" href="#request_scroll" title="Queues a hardware scroll request with triple buffering.">request_scroll</a>,
<a class="xref" href="#request_video_bitmap" title="Triple buffering page flip request.">request_video_bitmap</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#ex3buf" title="Mode-X triple buffering and retrace interrupt simulation.">ex3buf</a>,
<a class="eref" href="alleg045.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>.</blockquote>
<div class="al-api"><b>int <a name="scroll_screen">scroll_screen</a>(int x, int y);</b></div><br>
Attempts to scroll the hardware screen to display a different part of the
virtual screen (initially it will be positioned at 0, 0, which is the top
left corner). You can use this to move the screen display around in a
large virtual screen space, or to page flip back and forth between two
non-overlapping areas of the virtual screen. Note that to draw outside the
original position in the screen bitmap you will have to alter the clipping
rectangle with set_clip_rect().
<p>
Mode-X scrolling is reliable and will work on any card, other drivers may
not work or not work reliably. See the platform-specific section of the docs
for more information.
<p>
Allegro will handle any necessary vertical retrace synchronisation when
scrolling the screen, so you don't need to call vsync() before it. This
means that scroll_screen() has the same time delay effects as vsync().
<p><b>Return value:</b>
Returns zero on success. Returns non-zero if the graphics driver can't
handle hardware scrolling or the virtual screen is not large enough.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#set_gfx_mode" title="Sets a graphic video mode.">set_gfx_mode</a>,
<a class="xref" href="#show_video_bitmap" title="Flips the hardware screen to use the specified page.">show_video_bitmap</a>,
<a class="xref" href="#request_scroll" title="Queues a hardware scroll request with triple buffering.">request_scroll</a>,
<a class="xref" href="#request_video_bitmap" title="Triple buffering page flip request.">request_video_bitmap</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exscroll" title="Mode-X hardware scrolling and split screens.">exscroll</a>.</blockquote>
<div class="al-api"><b>int <a name="request_scroll">request_scroll</a>(int x, int y);</b></div><br>
This function is used for triple buffering. It requests a hardware scroll
to the specified position, but returns immediately rather than waiting
for a retrace. The scroll will then take place during the next vertical
retrace, but you can carry on running other code in the meantime and use
the poll_scroll() routine to detect when the flip has actually taken
place.
<p>
Triple buffering is only possible with certain drivers: you can look at the
GFX_CAN_TRIPLE_BUFFER bit in the gfx_capabilities flag to see if it will
work with the current driver.
<p><b>Return value:</b>
This function returns zero on success, non-zero otherwise.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#poll_scroll" title="Checks the status of a scroll request with triple buffering.">poll_scroll</a>,
<a class="xref" href="#request_video_bitmap" title="Triple buffering page flip request.">request_video_bitmap</a>,
<a class="xref" href="#gfx_capabilities" title="Bitfield describing video hardware capabilities.">gfx_capabilities</a>,
<a class="xref" href="#scroll_screen" title="Requests a hardware scroll request.">scroll_screen</a>.</blockquote>
<div class="al-api"><b>int <a name="poll_scroll">poll_scroll</a>();</b></div><br>
This function is used for triple buffering. It checks the status of a
hardware scroll previously initiated by the request_scroll() routine.
<p><b>Return value:</b>
Returns non-zero if it is still waiting to take place, and zero if the
requested scroll has already happened.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#request_scroll" title="Queues a hardware scroll request with triple buffering.">request_scroll</a>,
<a class="xref" href="#request_video_bitmap" title="Triple buffering page flip request.">request_video_bitmap</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#ex3buf" title="Mode-X triple buffering and retrace interrupt simulation.">ex3buf</a>,
<a class="eref" href="alleg045.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>.</blockquote>
<div class="al-api"><b>int <a name="show_video_bitmap">show_video_bitmap</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bitmap);</b></div><br>
Attempts to page flip the hardware screen to display the specified video
bitmap object, which must be the same size as the physical screen, and
should have been obtained by calling the create_video_bitmap() function.
<p>
Allegro will handle any necessary vertical retrace synchronisation when
page flipping, so you don't need to call vsync() before it. This means
that show_video_bitmap() has the same time delay effects as vsync() by
default. This can be adjusted with the "disable_vsync" config key in the
[graphics] section of allegro.cfg. Example:
<blockquote class="code"><pre>
int current_page;
<a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *video_page[2];
...
/* Create pages for page flipping */
video_page[0] = <a href="alleg009.html#create_video_bitmap" class="autotype" title="Creates a video memory bitmap.">create_video_bitmap</a>(<a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a>, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>);
video_page[1] = <a href="alleg009.html#create_video_bitmap" class="autotype" title="Creates a video memory bitmap.">create_video_bitmap</a>(<a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a>, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>);
current_page = 0;
...
/* draw the <a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a> and flip pages */
draw_screen(video_page[current_page]);
<a href="#show_video_bitmap" class="autotype" title="Flips the hardware screen to use the specified page.">show_video_bitmap</a>(video_page[current_page]);
current_page = (current_page+1)%2;
...</pre></blockquote>
<p><b>Return value:</b>
Returns zero on success and non-zero on failure.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#scroll_screen" title="Requests a hardware scroll request.">scroll_screen</a>,
<a class="xref" href="alleg009.html#create_video_bitmap" title="Creates a video memory bitmap.">create_video_bitmap</a>,
<a class="xref" href="alleg003.html#Standard config variables" title="">Standard config variables</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#exaccel" title="Using offscreen video memory to store source graphics for VBE/AF.">exaccel</a>,
<a class="eref" href="alleg045.html#exflip" title="Comparison of double buffering and page flipping.">exflip</a>,
<a class="eref" href="alleg045.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>.</blockquote>
<div class="al-api"><b>int <a name="request_video_bitmap">request_video_bitmap</a>(<a class="autotype" href="alleg001.html#BITMAP" title="Stores the contents of a bitmap.">BITMAP</a> *bitmap);</b></div><br>
This function is used for triple buffering. It requests a page flip to
display the specified video bitmap object, but returns immediately rather
than waiting for a retrace. The flip will then take place during the next
vertical retrace, but you can carry on running other code in the meantime
and use the poll_scroll() routine to detect when the flip has actually
taken place. Triple buffering is only possible on certain hardware: see
the comments about request_scroll(). Example:
<blockquote class="code"><pre>
int current_page;
<a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *video_page[3];
...
/* Create pages for page flipping */
video_page[0] = <a href="alleg009.html#create_video_bitmap" class="autotype" title="Creates a video memory bitmap.">create_video_bitmap</a>(<a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a>, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>);
video_page[1] = <a href="alleg009.html#create_video_bitmap" class="autotype" title="Creates a video memory bitmap.">create_video_bitmap</a>(<a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a>, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>);
video_page[2] = <a href="alleg009.html#create_video_bitmap" class="autotype" title="Creates a video memory bitmap.">create_video_bitmap</a>(<a href="alleg009.html#SCREEN_W" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_W</a>, <a href="alleg009.html#SCREEN_H" class="autotype" title="Global define to obtain the size of the screen.">SCREEN_H</a>);
current_page = 0;
...
/* draw the <a href="alleg009.html#screen" class="autotype" title="Global pointer to the screen hardware video memory.">screen</a> and flip pages */
draw_screen(video_page[current_page]);
do {
} while (<a href="#poll_scroll" class="autotype" title="Checks the status of a scroll request with triple buffering.">poll_scroll</a>());
<a href="#request_video_bitmap" class="autotype" title="Triple buffering page flip request.">request_video_bitmap</a>(video_page[current_page]);
current_page = (current_page+1)%3;
...</pre></blockquote>
<p><b>Return value:</b>
Returns zero on success and non-zero on failure.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#poll_scroll" title="Checks the status of a scroll request with triple buffering.">poll_scroll</a>,
<a class="xref" href="#request_scroll" title="Queues a hardware scroll request with triple buffering.">request_scroll</a>,
<a class="xref" href="#gfx_capabilities" title="Bitfield describing video hardware capabilities.">gfx_capabilities</a>,
<a class="xref" href="alleg009.html#create_video_bitmap" title="Creates a video memory bitmap.">create_video_bitmap</a>,
<a class="xref" href="#scroll_screen" title="Requests a hardware scroll request.">scroll_screen</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#ex3buf" title="Mode-X triple buffering and retrace interrupt simulation.">ex3buf</a>,
<a class="eref" href="alleg045.html#exupdate" title="Supporting different screen update methods in a single program.">exupdate</a>.</blockquote>
<div class="al-api"><b>void <a name="vsync">vsync</a>();</b></div><br>
Waits for a vertical retrace to begin. The retrace happens when the
electron beam in your monitor has reached the bottom of the screen and is
moving back to the top ready for another scan. During this short period
the graphics card isn't sending any data to the monitor, so you can do
things to it that aren't possible at other times, such as altering the
palette without causing flickering (snow). Allegro will automatically
wait for a retrace before altering the palette or doing any hardware
scrolling, though, so you don't normally need to bother with this
function.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="alleg011.html#set_palette" title="Sets the entire palette of 256 colors.">set_palette</a>,
<a class="xref" href="#scroll_screen" title="Requests a hardware scroll request.">scroll_screen</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg045.html#Available Allegro examples" title="">Available Allegro examples</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>
</body>
</html>
distrib
>
Arklinux
>
devel
>
x86_64
>
media
>
main
>
by-pkgid
>
c13bc007afe382f898b3b1cfcaf62e82
>
files
>
781
