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  DirectX  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 (sometimes 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 Allegro 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_DISPLAY_LOST and ALLEGRO_EVENT_DISPLAY_HALT_DRAWING and a should be restored
       when    you    get    the    ALLEGRO_EVENT_DISPLAY_FOUND     and     when     you     call
       al_acknowledge_drawing_resume(3alleg5) (after ALLEGRO_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 resources allocated for it.

SEE ALSO

       al_set_new_bitmap_format(3alleg5),                       al_set_new_bitmap_flags(3alleg5),
       al_clone_bitmap(3alleg5),                                   al_create_sub_bitmap(3alleg5),
       al_convert_memory_bitmaps(3alleg5), al_destroy_bitmap(3alleg5)