1al_create_bitmap(3)                                        al_create_bitmap(3)
2
3
4

NAME

6       al_create_bitmap - Allegro 5 API
7

SYNOPSIS

9              #include <allegro5/allegro.h>
10
11              ALLEGRO_BITMAP *al_create_bitmap(int w, int h)
12

DESCRIPTION

14       Creates  a new bitmap using the bitmap format and flags for the current
15       thread.  Blitting between bitmaps of  differing  formats,  or  blitting
16       between memory bitmaps and display bitmaps may be slow.
17
18       Unless  you  set  the ALLEGRO_MEMORY_BITMAP flag, the bitmap is created
19       for the current display.  Blitting to another display may be slow.
20
21       If a display bitmap is created, there may be limitations on the allowed
22       dimensions.  For example a DirectX or OpenGL backend usually has a max‐
23       imum allowed texture size - so if bitmap creation fails for very  large
24       dimensions,  you  may want to re-try with a smaller bitmap.  Some plat‐
25       forms also dictate a minimum texture size, which  is  relevant  if  you
26       plan  to use this bitmap with the primitives addon.  If you try to cre‐
27       ate a bitmap smaller than  this,  this  call  will  not  fail  but  the
28       returned  bitmap  will be a section of a larger bitmap with the minimum
29       size.  The minimum size that will work on all platforms is 32 by 32.
30
31       Some platforms do not directly support display bitmaps whose dimensions
32       are  not powers of two.  Allegro handles this by creating a larger bit‐
33       map that has dimensions that are powers of two  and  then  returning  a
34       section  of that bitmap with the dimensions you requested.  This can be
35       relevant if you plan to use this bitmap with the primitives  addon  but
36       shouldn't be an issue otherwise.
37
38       If  you  create a bitmap without ALLEGRO_MEMORY_BITMAP set but there is
39       no current display, a temporary memory bitmap will be created  instead.
40       You  can  later convert all such bitmap to video bitmap and assign to a
41       display by calling al_convert_memory_bitmaps(3).
42
43       On some platforms the contents of video bitmaps may be lost  when  your
44       application  loses focus.  Allegro has an internal mechanism to restore
45       the contents of these video bitmaps, but it is not foolproof (sometimes
46       bitmap  contents can get lost permanently) and has performance implica‐
47       tions.  If you are using a bitmap as an intermediate buffer this mecha‐
48       nism may be wasteful.  In this case, if you do not want Allegro to man‐
49       age the bitmap contents for you, you can disable this mechanism by cre‐
50       ating the bitmap with the ALLEGRO_NO_PRESERVE_TEXTURE flag.  The bitmap
51       contents are lost when you get the ALLEGRO_EVENT_DISPLAY_LOST and ALLE‐
52       GRO_EVENT_DISPLAY_HALT_DRAWING  and  a  should be restored when you get
53       the ALLEGRO_EVENT_DISPLAY_FOUND and when you call  al_acknowledge_draw‐
54       ing_resume(3)  (after ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING event).  You
55       can use those events to implement your own bitmap  content  restoration
56       mechanism  if Allegro's does not work well enough for you (for example,
57       you can reload them all from disk).
58
59       Note: The contents of a newly created bitmap are undefined -  you  need
60       to  clear  the  bitmap  or  make sure all pixels get overwritten before
61       drawing it.
62
63       When you are done with using the bitmap you must  call  al_destroy_bit‐
64       map(3) on it to free any resources allocated for it.
65

SEE ALSO

67       al_set_new_bitmap_format(3),  al_set_new_bitmap_flags(3), al_clone_bit‐
68       map(3),     al_create_sub_bitmap(3),      al_convert_memory_bitmaps(3),
69       al_destroy_bitmap(3)
70
71
72
73Allegro reference manual                                   al_create_bitmap(3)
Impressum