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
|
.TH al_hold_bitmap_drawing 3 "" "Allegro reference manual"
.SH NAME
.PP
al_hold_bitmap_drawing \- Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <allegro5/allegro.h>
void\ al_hold_bitmap_drawing(bool\ hold)
\f[]
.fi
.SH DESCRIPTION
.PP
Enables or disables deferred bitmap drawing.
This allows for efficient drawing of many bitmaps that share a parent
bitmap, such as sub\-bitmaps from a tilesheet or simply identical
bitmaps.
Drawing bitmaps that do not share a parent is less efficient, so it is
advisable to stagger bitmap drawing calls such that the parent bitmap is
the same for large number of those calls.
While deferred bitmap drawing is enabled, the only functions that can be
used are the bitmap drawing functions and font drawing functions.
Changing the state such as the blending modes will result in undefined
behaviour.
One exception to this rule are the transformations.
It is possible to set a new transformation while the drawing is held.
.PP
No drawing is guaranteed to take place until you disable the hold.
Thus, the idiom of this function\[aq]s usage is to enable the deferred
bitmap drawing, draw as many bitmaps as possible, taking care to stagger
bitmaps that share parent bitmaps, and then disable deferred drawing.
As mentioned above, this function also works with bitmap and truetype
fonts, so if multiple lines of text need to be drawn, this function can
speed things up.
.SH SEE ALSO
.PP
al_is_bitmap_drawing_held(3)
|
