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.

       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)