Display

Display creation
Display operations
Fullscreen display modes
Monitors

Display creation

ALLEGRO_DISPLAY

typedef struct ALLEGRO_DISPLAY ALLEGRO_DISPLAY;

An opaque type representing an open display or window.

al_create_display

ALLEGRO_DISPLAY *al_create_display(int w, int h)

Create a display, or window, with the specified dimensions. The parameters of the display are determined by the last calls to al_set_new_display_*. Default parameters are used if none are set explicitly. Creating a new display will automatically make it the active one, with the backbuffer selected for drawing.

Returns NULL on error.

al_destroy_display

void al_destroy_display(ALLEGRO_DISPLAY *display)

Destroy a display.

al_get_num_display_formats

int al_get_num_display_formats(void)

Returns the number of available display formats.

Note that on some platforms this may return 0 unless there is a current display already. In that case, first create a small window using Allegro's standard settings to query the available formats and create your actual display later.

In pseudo-code:

display = al_create_display();
n = al_get_num_display_formats();
for (i = 0; i < n; i++) {
   /* Use al_get_display_format_option to inspect each available
    * format and select the one you want.
    */
}
al_destroy_display(display); 

/* Now create the real display. */
al_set_new_display_format(i);
real_display = al_create_display();

al_get_display_format_option

int al_get_display_format_option(int i, int option)

Queries information about one of the available display formats. The parameter must be between 0 and al_get_num_display_formats - 1. The same options as with al_set_new_display_option are supported.

al_set_new_display_format

void al_set_new_display_format(int i)

Sets one of the available display formats. The index must be between 0 and al_get_num_display_formats - 1. Calling this functions is equivalent to calling al_set_new_display_option with all of the available display format options.

al_get_new_display_flags

int al_get_new_display_flags(void)

Gets the current flags used for newly created displays.

al_get_new_display_refresh_rate

int al_get_new_display_refresh_rate(void)

Gets the current refresh rate used for newly created displays.

al_get_new_window_position

void al_get_new_window_position(int *x, int *y)

Gets the position where newly created non-fullscreen displays will be placed.

al_set_new_display_option

void al_set_new_display_option(int option, int value, int importance)

Sets an extra display option. Allegro itself will not care about those options itself, but you may want to specify them, for example if you want to use multisampling.

The 'importance' parameter can be either:

ALLEGRO_REQUIRE - The display will not be created if the setting can not be met.
ALLEGRO_SUGGEST - If the setting is not available, the display will be created anyway. FIXME: We need a way to query the settings back from a created display.
ALLEGRO_DONTCARE - If you added a display option with one of the above two settings before, it will be removed again. Else this does nothing.

The supported options are:

ALLEGRO_RED_SIZE
ALLEGRO_GREEN_SIZE
ALLEGRO_BLUE_SIZE
ALLEGRO_ALPHA_SIZE
ALLEGRO_COLOR_SIZE
ALLEGRO_RED_SHIFT
ALLEGRO_GREEN_SHIFT
ALLEGRO_BLUE_SHIFT
ALLEGRO_ALPHA_SHIFT: These settings can be used to specify the pixel layout the display should use.
ALLEGRO_ACC_RED_SIZE
ALLEGRO_ACC_GREEN_SIZE
ALLEGRO_ACC_BLUE_SIZE
ALLEGRO_ACC_ALPHA_SIZE: This and the preceding three settings can be used to define the required accumulation buffer size.
ALLEGRO_STEREO: Whether the display is a stereo display.
ALLEGRO_AUX_BUFFERS: Number of auxiliary buffers the display should have.
ALLEGRO_DEPTH_SIZE: How many depth buffer (z-buffer) bits to use.
ALLEGRO_STENCIL_SIZE: How many bits to use for the stencil buffer.
ALLEGRO_SAMPLE_BUFFERS: Whether to use multisampling (1) or not (0).
ALLEGRO_SAMPLES: If the above is 1, the number of samples to use per pixel. Else 0.
ALLEGRO_RENDER_METHOD: 0 if hardware acceleration is not used with this display.
ALLEGRO_FLOAT_COLOR: Whether to use floating point color components.
ALLEGRO_FLOAT_DEPTH: Whether to use a floating point depth buffer.
ALLEGRO_SINGLE_BUFFER: Whether the display uses a single buffer (1) or another update method (0).
ALLEGRO_SWAP_METHOD: If the above is 0, this is set to 1 to indicate the display is using a copying method to make the next buffer in the flip chain available, or to 2 to indicate a flipping or other method.
ALLEGRO_COMPATIBLE_DISPLAY: Indicates if Allegro's graphics functions can use this display. If you request a display not useable by Allegro, you can still use for example OpenGL to draw graphics.
ALLEGRO_UPDATE_DISPLAY_REGION: Set to 1 if the current display is capable of updating just a region, and 0 if calling al_update_display_region is equivalent to al_flip_display.
ALLEGRO_VSYNC: Set to 1 to tell the driver to wait for vsync in al_flip_display, or to 2 to force vsync off.

FIXME: document them all in detail

al_get_new_display_option

int al_get_new_display_option(int option, int *importance)

Retrieve an extra display setting which was previously set with al_set_new_display_option.

al_reset_new_display_options

void al_reset_new_display_options(void)

This undoes any previous calls to al_set_new_display_option.

al_set_new_display_flags

void al_set_new_display_flags(int flags)

Sets various flags for display creation. flags is a bitfield containing any reasonable combination of the following:

ALLEGRO_WINDOWED - prefer a windowed mode
ALLEGRO_FULLSCREEN - prefer a fullscreen mode
ALLEGRO_RESIZABLE - the display is resizable (only applicable if combined with ALLEGRO_WINDOWED)
ALLEGRO_OPENGL - require the driver to provide an initialized opengl context after returning successfully
ALLEGRO_DIRECT3D - require the driver to do rendering with Direct3D and provide a Direct3D device
ALLEGRO_NOFRAME - Try to create a window without a frame (i.e. no border or titlebar). This usualy does nothing for fullscreen modes, and even in windowed moded it depends on the underlying platform whether it is supported or not.
ALLEGRO_GENERATE_EXPOSE_EVENTS - Let the display generate expose events.

0 can be used for default values.

al_set_new_display_refresh_rate

void al_set_new_display_refresh_rate(int refresh_rate)

Sets the refresh rate to use for newly created displays. If the refresh rate is not available, al_create_display will fail. A list of modes with refresh rates can be found with al_get_num_display_modes and al_get_display_mode.

al_set_new_window_position

void al_set_new_window_position(int x, int y)

Sets where the top left pixel of the client area of newly created windows (non-fullscreen) will be on screen. Negative values allowed on some multihead systems.

Display operations

al_acknowledge_resize

bool al_acknowledge_resize(ALLEGRO_DISPLAY *display)

When the user receives a resize event from a resizable display, if they wish the display to be resized they must call this function to let the graphics driver know that it can now resize the display. Returns true on success.

Adjusts the clipping rectangle to the full size of the backbuffer.

al_flip_display

void al_flip_display(void)

Copies or updates the front and back buffers so that what has been drawn previously on the currently selected display becomes visible on screen. Pointers to the special back and front buffer bitmaps remain valid and retain their semantics as back and front buffers respectively, although their contents may have changed.

Several display options change how this function behaves:

With ALLEGRO_SINGLE_BUFFER, no flipping is done. You still have to call this function to display graphics, depending on how the used graphics system works.

The ALLEGRO_SWAP_METHOD option may have additional information about what kind of operation is used internally to flip the front and back buffers.

If ALLEGRO_VSYNC is 1, this function will force waiting for vsync. If ALLEGRO_VSYNC is 2, this function will not wait for vsync. With many drivers the vsync behavior is controlled by the user and not the application, and ALLEGRO_VSYNC will not be set; in this case al_flip_display will wait for vsync depending on the settings set in the system's graphics preferences.

al_get_backbuffer

ALLEGRO_BITMAP *al_get_backbuffer(void)

Return a special bitmap representing the back-buffer of the current display.

al_get_current_display

ALLEGRO_DISPLAY *al_get_current_display(void)

Query for the current display in the calling thread. Returns NULL if there is none.

al_get_display_flags

int al_get_display_flags(void)

Gets the flags of the current display.

al_get_display_format

int al_get_display_format(void)

Gets the pixel format of the current display.

al_get_display_height

int al_get_display_height(void)

Gets the height of the current display. This is like SCREEN_H in Allegro 4.x.

al_get_display_refresh_rate

int al_get_display_refresh_rate(void)

Gets the refresh rate of the current display.

al_get_display_width

int al_get_display_width(void)

Gets the width of the current display. This is like SCREEN_W in Allegro 4.x.

al_get_frontbuffer

ALLEGRO_BITMAP *al_get_frontbuffer(void)

Return a special bitmap representing the front-buffer of the current display. This may not be supported by the driver; returns NULL in that case.

al_get_window_position

void al_get_window_position(ALLEGRO_DISPLAY *display, int *x, int *y)

Gets the position of a non-fullscreen display.

al_inhibit_screensaver

bool al_inhibit_screensaver(bool inhibit)

This function allows the user to stop the system screensaver from starting up if true is passed, or resets the system back to the default state (the state at program start) if false is passed. It returns true if the state was set successfully, otherwise false.

al_resize_display

bool al_resize_display(int width, int height)

Resize the current display. Returns true on success, or false on error. This works on both fullscreen and windowed displays, regardless of the ALLEGRO_RESIZABLE flag.

Adjusts the clipping rectangle to the full size of the backbuffer.

al_set_current_display

bool al_set_current_display(ALLEGRO_DISPLAY *display)

Change the current display for the calling thread. Also sets the target bitmap to the display's backbuffer.

A display may not be "current" for multiple threads simultaneously. To stop a display being current for the calling thread, call al_set_current_display(NULL). Then the display may be made current by another thread.

Returns true on success.

al_set_display_icon

void al_set_display_icon(ALLEGRO_BITMAP *icon)

Changes the icon associated with the current display (window).

Note: If the underlying OS can not use an icon with the size of the provided bitmap, it will be scaled.

TODO: Describe best practice for the size? TODO: Allow providing multiple icons in differet sizes?

al_get_display_option

int al_get_display_option(int option)

Return an extra display setting of the current display.

al_set_window_position

void al_set_window_position(ALLEGRO_DISPLAY *display, int x, int y)

Sets the position on screen of a non-fullscreen display.

al_set_window_title

void al_set_window_title(AL_CONST char *title)

Set the title on a display.

al_toggle_window_frame

void al_toggle_window_frame(ALLEGRO_DISPLAY *display, bool onoff)

Enable or disable the decorations around a windowed display.

al_update_display_region

void al_update_display_region(int x, int y, int width, int height)

Does the same as al_flip_display, but tries to update only the specified region. With many drivers this is not possible, but for some it can improve performance.

The ALLEGRO_UPDATE_DISPLAY_REGION option (see al_get_display_option) will specify the behavior of this function in the current display.

al_wait_for_vsync

bool al_wait_for_vsync(void)

Wait for the beginning of a vertical retrace. Some driver/card/monitor combinations may not be capable of this.

Note how al_flip_display usually already waits for the vertical retrace, so unless you are doing something special, there is no reason to call this function.

Returns false if not possible, true if successful.

al_get_display_event_source

ALLEGRO_EVENT_SOURCE *al_get_display_event_source(ALLEGRO_DISPLAY *display)

Retrieve the associated event source.

Fullscreen display modes

ALLEGRO_DISPLAY_MODE

typedef struct ALLEGRO_DISPLAY_MODE

Used for display mode queries. Contains information about a supported fullscreen display mode.

typedef struct ALLEGRO_DISPLAY_MODE {
   int width;          // Screen width
   int height;         // Screen height
   int format;         // The pixel format of the mode
   int refresh_rate;   // The refresh rate of the mode
} ALLEGRO_DISPLAY_MODE;

al_get_display_mode

ALLEGRO_DISPLAY_MODE *al_get_display_mode(int index, ALLEGRO_DISPLAY_MODE *mode)

Retrieves a display mode. Display parameters should not be changed between a call of al_get_num_display_modes and al_get_display_mode. index must be between 0 and the number returned from al_get_num_display_modes-1. mode must be an allocated ALLEGRO_DISPLAY_MODE structure. This function will return NULL on failure, and the mode parameter that was passed in on success.

al_get_num_display_modes

int al_get_num_display_modes(void)

Get the number of available fullscreen display modes for the current set of display parameters. This will use the values set with al_set_new_display_refresh_rate, and al_set_new_display_flags to find the number of modes that match. Settings the new display parameters to zero will give a list of all modes for the default driver.

Monitors

ALLEGRO_MONITOR_INFO

typedef struct ALLEGRO_MONITOR_INFO

Describes a monitors size and position relative to other monitors. x1, y1 will be 0, 0 on the primary display. Other monitors can have negative values if they are to the left or above the primary display.

typedef struct ALLEGRO_MONITOR_INFO
{
   int x1;
   int y1;
   int x2;
   int y2;
} ALLEGRO_MONITOR_INFO;

al_get_current_video_adapter

int al_get_current_video_adapter(void)

Gets the video adapter index where new displays will be created.

al_set_current_video_adapter

void al_set_current_video_adapter(int adapter)

Sets the adapter to use for newly created displays. The adapter has a monitor attached to it. Information about the monitor can be gotten using al_get_num_video_adapters and al_get_monitor_info.

al_get_monitor_info

void al_get_monitor_info(int adapter, ALLEGRO_MONITOR_INFO *info)

Get information about a monitor's position on the desktop. adapter is a number from 0 to al_get_num_video_adapters()-1.

al_get_num_video_adapters

int al_get_num_video_adapters(void)

Get the number of video "adapters" attached to the computer. Each video card attached to the computer counts as one or more adapters. An adapter is thus really a video port that can have a monitor connected to it.