The Allegro Wiki is migrating to github at

Al create display bitmap

From Allegro Wiki
Jump to: navigation, search


al_create_display_bitmap - creates a display bitmap. A display bitmap is a bitmap that can be shown on screen. It represents a bitmap that is directly visible to the user (ie: what they see on their monitors).

C Specification

AL_DISPLAY *al_create_display_bitmap(al_id_t card, int width, int height, al_id_t format, al_id_t update_method)


card Type of display (see below)
width Width in pixels of the bitmap to create
height Height in pixels of the bitmap to create
format Color space and depth of the bitmap (see below)
update_method Style of buffering used for the bitmap (see below)

Types of Display

Card may be one of:

  • AL_GFX_FULL_SCREEN - Selects a full-screen display bitmap. The screen's resolution may be changed to accomodate the required display bitmap settings. Not all platforms support full screen display bitmaps. Typically, you can only have one display bitmap if you are using a full-screen mode. However, if the platform supports multiple monitors then multiple full-screen display bitmaps may be created, each on a different monitor.
  • AL_GFX_WINDOWED - Selects a windowed display bitmap. Not all platforms support windowed display bitmaps. For platforms that do support windowed bitmaps however, you can create multiple display bitmaps and Allegro will create and manage multiple windows.
  • AL_GFX_SAFE - Selects a display bitmap that is guaranteed to be creatable on the current platform. Color space and depth settings are ignored. You may get virtually any color depth and color space settings so your application should be able to work with all possible combinations. You may or may not get a full-screen mode. You can only create a single safe display bitmap; no other display bitmap can co-exist with a safe display bitmap.
  • AL_GFX_AUTODETECT - Allegro will autodetect whether the current platform supports windowed or full-screen modes, and will pick the mode that best matches the gfx configuration settings.

Color Space and Depth

Allegro supports several color spaces. The color space is specified by the following flags in the format parameter:

  • AL_RGB
  • AL_YUV

These flags select the color space but not the color depth. The depth is selected via one of the following flags, which are combined with a binary OR (|) with the previous ones:

  • AL_COLOR_8
  • AL_COLOR_8_8_I
  • AL_COLOR_5_5_5 (equivalent to AL_COLOR_15)
  • AL_COLOR_5_6_5 (equivalent to AL_COLOR_16)
  • AL_COLOR_8_8_8 (equivalent to AL_COLOR_24)
  • AL_COLOR_8_8_8_8 (equivalent to AL_COLOR_32)
  • AL_COLOR_10_10_10
  • AL_COLOR_10_10_10_2
  • AL_COLOR_16_16_16
  • AL_COLOR_16_16_16_16
  • AL_COLOR_32_32_32
  • AL_COLOR_32_32_32_32 (equivalent to AL_COLOR_128)

The color depth specification can be augmented by the following flags, which are combined with a binray OR (|) with the previous ones:


Note that not all combinations of formats and depths are valid.

If you don't specify the color space, then Allegro will default to AL_RGB if there are 3 components, AL_RGBA if there are 4 components and AL_PALETTE if there is only one component. If you don't specify the color depth, then Allegro will select the desktop color depth (if applicable) or some other sensible default depending on the platform.

Update Method

The update_method parameter must be one of the following:


Note that the update mode is only a suggestion. Individual drivers are free to pick the best matching mode they can get.

See the documentation for al_show_display_bitmap for the details on the display update methods.




If Allegro is unable to create the desired display bitmap, or if the specified display bitmap is unsupported on the current platform, then NULL is returned.


For setting an RGB 5.6.5 16-bpp mode, you'd use:

AL_BITMAP *screen = al_create_display_bitmap(AL_GFX_AUTO, w, h,
                     AL_COLOR_5_6_5, AL_GFX_UPDATE_AUTO);

Notice that we don't specify the color space so Allegro will select AL_RGB, since AL_COLOR_5_6_5 has 3 components.

See Also