The Allegro Wiki is migrating to github at https://github.com/liballeg/allegro_wiki/wiki

NewAPI/AlternativeWindow

From Allegro Wiki
Jump to: navigation, search

Sample usage

<highlightSyntax language="c"> ALLEGRO_WINDOW *window = al_create_window(1024, 768, 0, 0, ALLEGRO_OPENGL); ALLEGRO_GRAPHICS *graphics = al_get_window_graphics(); ALLEGRO_BITMAP *bitmap = al_load_bitmap("example.bmp", al_get_format(graphics), ALLEGRO_SYNC_MEMORY_COPY); al_set_current_graphics(graphics); al_draw_bitmap(bitmap, x, y, 0); </highlightSyntax>

Events

An ALLEGRO_WINDOW will generate events if you call al_register_event_source on it. The events that it can generate are:

  • ALLEGRO_EVENT_WINDOW_EXPOSE - The window (or a portion thereof) has become visible. event->display.x/event->display.y will be the top left of the exposed area, and event->display.width/event->display.height will contain the width and height of the exposed area.
  • ALLEGRO_EVENT_WINDOW_RESIZE - The window has been resized. event->window.x/event->window.y will contain the top left position of the resized window, and event->display.width/event->display.height will contain the the new width and height of the window. In order for the window to actually be resized, you must call the acknowledge_resize method of the window.
  • ALLEGRO_EVENT_WINDOW_CLOSE - The close button of the window has been pressed.
  • ALLEGRO_EVENT_WINDOW_LOST - Devices can be lost with some drivers (just Direct3D?). This means that rendering is impossible. The device will be restored as soon as it is possible. The program should be able to ignore this event and continue rendering however it will have no effect.
  • ALLEGRO_EVENT_WINDOW_FOUND - Generated when a lost device is regained. Bitmaps created without the ALLEGRO_SYNC_MEMORY_COPY flag may lose their data when the device is lost, so they should be recreated when this event is received.


Structures

ALLEGRO_WINDOW

An ALLEGRO_WINDOW is a window on screen or a fullscreen "window".

AL_DISPLAY_MODE

<highlightSyntax language="c"> typedef struct AL_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 */

} AL_DISPLAY_MODE; </highlightSyntax>


Querying

al_get_num_display_modes

Get the number of available fullscreen display modes for the given set of display parameters. Using 0 for a parameter matches all possible values for that parameter.

  • format - The desired pixel format. See al_create_window for a list of valid pixel formats.
  • refresh_rate - The desired refresh rate. Only used for fullscreen modes.
  • flags - The desired flags. See al_create_window for a list of valid flags.

<highlightSyntax> int al_get_num_display_modes(int format, int refresh_rate, int flags); </highlightSyntax>


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 AL_DISPLAY_MODE structure. This function will return NULL on failure, and the mode parameter that was passed in on success. See AL_DISPLAY_MODE above. <highlightSyntax language="c"> AL_DISPLAY_MODE *al_get_display_mode(int index, AL_DISPLAY_MODE *mode); </highlightSyntax>


Creation/Destruction

al_create_window

Creates an ALLEGRO_WINDOW and makes it the current in the current thread.

  • width - The width of the window
  • height - The height of the window
  • format - The pixel format of the window. Valid values are:
    • ALLEGRO_PIXEL_FORMAT_ANY = 0,
    • ALLEGRO_PIXEL_FORMAT_ARGB_8888
    • ALLEGRO_PIXEL_FORMAT_RGBA_8888
    • ALLEGRO_PIXEL_FORMAT_ARGB_4444
    • ALLEGRO_PIXEL_FORMAT_RGB_888 /** 24 bit format **/
    • ALLEGRO_PIXEL_FORMAT_RGB_565
    • ALLEGRO_PIXEL_FORMAT_RGB_555
    • ALLEGRO_PIXEL_FORMAT_PALETTE_8
    • ALLEGRO_PIXEL_FORMAT_RGBA_5551
    • ALLEGRO_PIXEL_FORMAT_ARGB_1555
    • ALLEGRO_PIXEL_FORMAT_ABGR_8888
    • ALLEGRO_PIXEL_FORMAT_XBGR_8888 /** 32 bit size, 24 bits used **/
    • ALLEGRO_PIXEL_FORMAT_BGR_888 /** 24 bit format **/
    • ALLEGRO_PIXEL_FORMAT_BGR_565
    • ALLEGRO_PIXEL_FORMAT_BGR_555
    • ALLEGRO_PIXEL_FORMAT_RGBX_8888 /** 32 bit size, 24 bits used **/
    • ALLEGRO_PIXEL_FORMAT_XRGB_8888 /** 32 bit size, 24 bits used **/
  • refresh_rate - The refresh rate to use for the window. Only used for fullscreen windows.
  • flags - A bitmask of the flags to use to create the window. Valid flags are:
    • 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 1 buffer (front and back buffer are the same)

<highlightSyntax language="c"> ALLEGRO_WINDOW *al_create_window(int width, int height, int format, int refresh_rate, int flags); </highlightSyntax>


al_destroy_window

Destroy an ALLEGRO_WINDOW that was created with al_create_window.

  • window - The ALLEGRO_WINDOW to destroy.

<highlightSyntax language="c"> void al_destroy_window(ALLEGRO_WINDOW *window); </highlightSyntax>


Targets

al_set_current_window

Sets the current window for window operations for the current thread. <highlightSyntax language="c"> void al_set_current_window(ALLEGRO_WINDOW *window); </highlightSyntax>

al_get_current_window

Gets the current window for the current thread. <highlightSyntax language="c"> ALLEGRO_WINDOW *al_get_current_window(void); </highlightSyntax>


Buffers

al_get_backbuffer

Return a special bitmap representing the back-buffer of the current window. <highlightSyntax language="c"> ALLEGRO_BITMAP *al_get_backbuffer(void); </highlightSyntax>

al_get_frontbuffer

Return a special bitmap representing the front-buffer of the current window. This may not be supported by the driver; returns NULL in that case. <highlightSyntax language="c"> ALLEGRO_BITMAP *al_get_frontbuffer(void); </highlightSyntax>


Querying

al_get_window_width

Returns the width of the current window in pixels. <highlightSyntax language="c"> int al_get_window_width(void); </highlightSyntax>

al_get_window_height

Returns the height of the current window in pixels. <highlightSyntax language="c"> int al_get_window_height(void); </highlightSyntax>

al_get_window_format

Returns the pixel format of the current window's back buffer. <highlightSyntax language="c"> int al_get_window_format(void); </highlightSyntax>

al_get_window_refresh_rate

Returns the refresh rate of the current window if it is a fullscreen window, or 0 otherwise. <highlightSyntax language="c"> int al_get_window_refresh_rate(void); </highlightSyntax>

al_get_window_flags

Returns the flags that were used to create the current window. <highlightSyntax language="c"> int al_get_window_flags(void); </highlightSyntax>


Graphics

al_flip_window

Makes the backbuffer of the current window visible. <highlightSyntax language="c"> void al_flip_window(void); </highlightSyntax>

al_update_window_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. <highlightSyntax language="c"> bool al_update_window_region(int x, int y, int width, int height); </highlightSyntax>

al_acknowledge_resize

When the user receives a resize event from a resizable window, if they wish the window to be resized they must call this function to let the graphics driver know that it can now resize the window. <highlightSyntax language="c"> void al_acknowledge_resize(void); </highlightSyntax>

al_resize_window

Resize the current window. Returns false on error, true on success. This works on both fullscreen and windowed "windows", regardless of the ALLEGRO_RESIZABLE flag. <highlightSyntax language="c"> bool al_resize_window(int width, int height); </highlightSyntax>