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 be‐
16       tween 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  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
34       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
41       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
46       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
62       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
66       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

SEE ALSO

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)
73
74
75
76Allegro reference manual                                   al_create_bitmap(3)
Impressum