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)