1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
|
.TH "al_create_bitmap" "3" "" "Allegro reference manual" ""
.SH NAME
.PP
al_create_bitmap \- Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <allegro5/allegro.h>
ALLEGRO_BITMAP\ *al_create_bitmap(int\ w,\ int\ h)
\f[]
.fi
.SH DESCRIPTION
.PP
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.
.PP
Unless you set the ALLEGRO_MEMORY_BITMAP flag, the bitmap is created for
the current display.
Blitting to another display may be slow.
.PP
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.
.PP
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\[aq]t be an issue otherwise.
.PP
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(3).
.PP
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(3) (after
ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING event).
You can use those events to implement your own bitmap content
restoration mechanism if Allegro\[aq]s does not work well enough for you
(for example, you can reload them all from disk).
.PP
\f[I]Note\f[]: 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.
.PP
When you are done with using the bitmap you must call
al_destroy_bitmap(3) on it to free any resources allocated for it.
.SH SEE ALSO
.PP
al_set_new_bitmap_format(3), al_set_new_bitmap_flags(3),
al_clone_bitmap(3), al_create_sub_bitmap(3),
al_convert_memory_bitmaps(3), al_destroy_bitmap(3)
|
