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
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
|
.TH "al_set_target_bitmap" "3" "" "Allegro reference manual" ""
.SH NAME
.PP
al_set_target_bitmap \- Allegro 5 API
.SH SYNOPSIS
.IP
.nf
\f[C]
#include\ <allegro5/allegro.h>
void\ al_set_target_bitmap(ALLEGRO_BITMAP\ *bitmap)
\f[]
.fi
.SH DESCRIPTION
.PP
This function selects the bitmap to which all subsequent drawing
operations in the calling thread will draw to.
To return to drawing to a display, set the backbuffer of the display as
the target bitmap, using al_get_backbuffer(3).
As a convenience, you may also use al_set_target_backbuffer(3).
.PP
Each allegro bitmap maintains two transformation matrices associated
with it for drawing onto the bitmap.
There is a view matrix and a projection matrix.
When you call al_set_target_bitmap, these will be made current for the
bitmap, affecting global OpenGL and DirectX states depending on the
driver in use.
.PP
Each video bitmap is tied to a display.
When a video bitmap is set to as the target bitmap, the display that the
bitmap belongs to is automatically made "current" for the calling thread
(if it is not current already).
Then drawing other bitmaps which are tied to the same display can be
hardware accelerated.
.PP
A single display cannot be current for multiple threads simultaneously.
If you need to release a display, so it is not current for the calling
thread, call \f[C]al_set_target_bitmap(NULL);\f[]
.PP
Setting a memory bitmap as the target bitmap will not change which
display is current for the calling thread.
.PP
On some platforms, Allegro automatically backs up the contents of video
bitmaps because they may be occasionally lost (see discussion in
al_create_bitmap(3)\[aq]s documentation).
If you\[aq]re completely recreating the bitmap contents often (e.g.
every frame) then you will get much better performance by creating the
target bitmap with ALLEGRO_NO_PRESERVE_TEXTURE flag.
.PP
OpenGL note:
.PP
Framebuffer objects (FBOs) allow OpenGL to directly draw to a bitmap,
which is very fast.
When using an OpenGL display, if all of the following conditions are met
an FBO will be created for use with the bitmap:
.IP \[bu] 2
The GL_EXT_framebuffer_object OpenGL extension is available.
.IP \[bu] 2
The bitmap is not a memory bitmap.
.IP \[bu] 2
The bitmap is not currently locked.
.PP
In Allegro 5.0.0, you had to be careful as an FBO would be kept around
until the bitmap is destroyed or you explicitly called
al_remove_opengl_fbo(3) on the bitmap, wasting resources.
In newer versions, FBOs will be freed automatically when the bitmap is
no longer the target bitmap, \f[I]unless\f[] you have called
al_get_opengl_fbo(3) to retrieve the FBO id.
.PP
In the following example, no FBO will be created:
.IP
.nf
\f[C]
lock\ =\ al_lock_bitmap(bitmap);
al_set_target_bitmap(bitmap);
al_put_pixel(x,\ y,\ color);
al_unlock_bitmap(bitmap);
\f[]
.fi
.PP
The above allows using al_put_pixel(3) on a locked bitmap without
creating an FBO.
.PP
In this example an FBO is created however:
.IP
.nf
\f[C]
al_set_target_bitmap(bitmap);
al_draw_line(x1,\ y1,\ x2,\ y2,\ color,\ 0);
\f[]
.fi
.PP
An OpenGL command will be used to directly draw the line into the
bitmap\[aq]s associated texture.
.SH SEE ALSO
.PP
al_get_target_bitmap(3), al_set_target_backbuffer(3)
|
