# Display

## API: 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;

## API: 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;

## API: al_acknowledge_resize

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.

## API: al_clear

Clear a complete display, but confined by the clipping rectangle.

## API: al_create_display

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.

See Also: [al_set_new_display_format], [al_set_new_display_refresh_rate], 
	[al_set_new_display_flags]

## API: al_destroy_display

Destroy a display.

## API: al_flip_display

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.

## API: al_get_backbuffer

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

## API: al_get_current_display

Query for the current display in the calling thread.

## API: al_get_current_video_adapter

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

## API: al_get_display_flags

Gets the flags of the current display.

## API: al_get_display_format

Gets the pixel format of the current display.

## API: al_get_display_height

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

## API: al_get_display_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.

## API: al_get_display_refresh_rate

Gets the refresh rate of the current display.

## API: al_get_display_width

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

## API: al_get_frontbuffer

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.

## API: al_get_monitor_info

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

See Also: [ALLEGRO_MONITOR_INFO]

## API: al_get_new_display_flags

Gets the current flags used for newly created displays.

## API: al_get_new_display_format

Gets the current pixel format used for newly created displays.

## API: al_get_new_display_refresh_rate

Gets the current refresh rate used for newly created displays.

## API: al_get_new_window_position

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

See Also: [al_set_new_window_position]

## API: al_get_num_display_modes

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_format],
[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.

## API: al_get_num_video_adapters

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.

## API: al_get_window_position

Gets the position of a non-fullscreen display.

See Also: [al_set_window_position]

## API: al_inhibit_screensaver

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.

## API: al_resize_display

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.

## API: al_set_current_display

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

## API: al_set_current_video_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.

See Also: [al_get_num_video_adapters], [al_get_monitor_info]

## API: al_set_display_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?

## API: al_set_new_display_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_DOUBLEBUFFER - use double buffering

* ALLEGRO_PAGEFLIP - use page flipping

* ALLEGRO_SINGLEBUFFER - use only one buffer (front and back buffer are the
same) 

* 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.

0 can be used for default values. 

## API: al_set_new_display_format

Set the pixel format for al displays created after this call.

## API: al_set_new_display_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],
documented above.

See Also:
  [al_get_display_mode]

## API: al_set_new_window_position

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.

See Also: [al_set_new_window_position]

## API: al_set_window_position

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

See Also: [al_get_window_position]

## API: al_set_window_title

## API: al_toggle_window_frame

## API: al_update_display_region

Update the the front buffer from the backbuffer in the
specified region. This does not flip the whole buffer
and preserves the contents of the front buffer outside of
the given rectangle. This may not be supported by all drivers,
in which case it returns false.

