NAME

       al_create_bitmap - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro.h>

              ALLEGRO_BITMAP *al_create_bitmap(int w, int h)

DESCRIPTION

       Creates  a new bitmap using the bitmap format and flags for the current thread.  Blitting between bitmaps
       of differing formats, or blitting between memory bitmaps and display bitmaps may be slow.

       Unless you set the ALLEGRO_MEMORY_BITMAP flag, the bitmap is created for the current  display.   Blitting
       to another display may be slow.

       If a display bitmap is created, there may be limitations on the allowed dimensions.  For example a Direc‐
       tX  or  OpenGL  backend usually has a maximum allowed texture size - so if bitmap creation fails for very
       large dimensions, you may want to re-try with a smaller bitmap.  Some platforms also  dictate  a  minimum
       texture  size, which is relevant if you plan to use this bitmap with the primitives addon.  If you try to
       create a bitmap smaller than this, this call will not fail but the returned bitmap will be a section of a
       larger bitmap with the minimum size.  The minimum size that will work on  all  platforms  is  32  by  32.
       There  is  an  experimental  switch  to  turns  this padding off by editing the system configuration (see
       min_bitmap_size key in al_get_system_config(3alleg5)).

       Some platforms do not directly support display bitmaps whose dimensions are not powers of  two.   Allegro
       handles  this by creating a larger bitmap that has dimensions that are powers of two and then returning a
       section of that bitmap with the dimensions you requested.  This can be relevant if you plan to  use  this
       bitmap with the primitives addon but shouldn’t be an issue otherwise.

       If  you  create  a  bitmap without ALLEGRO_MEMORY_BITMAP set but there is no current display, a temporary
       memory bitmap will be created instead.  You can later convert all such bitmap to video bitmap and  assign
       to a display by calling al_convert_memory_bitmaps(3alleg5).

       On  some  platforms the contents of video bitmaps may be lost when your application loses focus.  Allegro
       has an internal mechanism to restore the contents of these video bitmaps, but it is not foolproof  (some‐
       times  bitmap  contents  can  get lost permanently) and has performance implications.  If you are using a
       bitmap as an intermediate buffer this mechanism may be wasteful.  In this case, if you do not want  Alle‐
       gro to manage the bitmap contents for you, you can disable this mechanism by creating the bitmap with the
       ALLEGRO_NO_PRESERVE_TEXTURE  flag.   The  bitmap  contents  are  lost when you get the ALLEGRO_EVENT_DIS‐
       PLAY_LOST and ALLEGRO_EVENT_DISPLAY_HALT_DRAWING and  a  should  be  restored  when  you  get  the  ALLE‐
       GRO_EVENT_DISPLAY_FOUND   and   when   you   call   al_acknowledge_drawing_resume(3alleg5)  (after  ALLE‐
       GRO_EVENT_DISPLAY_RESUME_DRAWING event).  You can use those events to implement your own  bitmap  content
       restoration  mechanism  if  Allegro’s does not work well enough for you (for example, you can reload them
       all from disk).

       Note: The contents of a newly created bitmap are undefined - you need to clear the bitmap  or  make  sure
       all pixels get overwritten before drawing it.

       When  you  are  done with using the bitmap you must call al_destroy_bitmap(3alleg5) on it to free any re‐
       sources allocated for it.

SEE ALSO

       al_set_new_bitmap_format(3alleg5),  al_set_new_bitmap_flags(3alleg5),  al_clone_bitmap(3alleg5),  al_cre‐
       ate_sub_bitmap(3alleg5), al_convert_memory_bitmaps(3alleg5), al_destroy_bitmap(3alleg5)

Allegro reference manual                                                               al_create_bitmap(3alleg5)