1al_create_bitmap(3) al_create_bitmap(3)
2
6 al_create_bitmap - Allegro 5 API
7
9 #include <allegro5/allegro.h>
10 ALLEGRO_BITMAP *al_create_bitmap(int w, int h)
12
14 Creates a new bitmap using the bitmap format and flags for the current
15 thread. Blitting between bitmaps of differing formats, or blitting be‐
16 tween memory bitmaps and display bitmaps may be slow.
17 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 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 re‐
28 turned 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 There is an experimental switch to turns this padding off by editing
31 the system configuration (see min_bitmap_size key in al_get_system_con‐
32 fig(3)).
33 Some platforms do not directly support display bitmaps whose dimensions
35 are not powers of two. Allegro handles this by creating a larger bit‐
36 map that has dimensions that are powers of two and then returning a
37 section of that bitmap with the dimensions you requested. This can be
38 relevant if you plan to use this bitmap with the primitives addon but
39 shouldn’t be an issue otherwise.
40 If you create a bitmap without ALLEGRO_MEMORY_BITMAP set but there is
42 no current display, a temporary memory bitmap will be created instead.
43 You can later convert all such bitmap to video bitmap and assign to a
44 display by calling al_convert_memory_bitmaps(3).
45 On some platforms the contents of video bitmaps may be lost when your
47 application loses focus. Allegro has an internal mechanism to restore
48 the contents of these video bitmaps, but it is not foolproof (sometimes
49 bitmap contents can get lost permanently) and has performance implica‐
50 tions. If you are using a bitmap as an intermediate buffer this mecha‐
51 nism may be wasteful. In this case, if you do not want Allegro to man‐
52 age the bitmap contents for you, you can disable this mechanism by cre‐
53 ating the bitmap with the ALLEGRO_NO_PRESERVE_TEXTURE flag. The bitmap
54 contents are lost when you get the ALLEGRO_EVENT_DISPLAY_LOST and ALLE‐
55 GRO_EVENT_DISPLAY_HALT_DRAWING and a should be restored when you get
56 the ALLEGRO_EVENT_DISPLAY_FOUND and when you call al_acknowledge_draw‐
57 ing_resume(3) (after ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING event). You
58 can use those events to implement your own bitmap content restoration
59 mechanism if Allegro’s does not work well enough for you (for example,
60 you can reload them all from disk).
61 Note: The contents of a newly created bitmap are undefined - you need
63 to clear the bitmap or make sure all pixels get overwritten before
64 drawing it.
65 When you are done with using the bitmap you must call al_destroy_bit‐
67 map(3) on it to free any resources allocated for it.
68
70 al_set_new_bitmap_format(3), al_set_new_bitmap_flags(3), al_clone_bit‐
71 map(3), al_create_sub_bitmap(3), al_convert_memory_bitmaps(3), al_de‐
72 stroy_bitmap(3)
73Allegro reference manual al_create_bitmap(3)