al_set_target_bitmap(3)

1al_set_target_bitmap(3)                                al_set_target_bitmap(3)
2
3
4

NAME

6       al_set_target_bitmap - Allegro 5 API
7

SYNOPSIS

9              #include <allegro5/allegro.h>
10
11              void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)
12

DESCRIPTION

14       This function selects the bitmap to which all subsequent drawing opera‐
15       tions in the calling thread will draw to.  To return to  drawing  to  a
16       display,  set the backbuffer of the display as the target bitmap, using
17       al_get_backbuffer(3).  As a convenience, you may also  use  al_set_tar‐
18       get_backbuffer(3).
19
20       Each  allegro  bitmap  maintains two transformation matrices associated
21       with it for drawing onto the bitmap.  There is a view matrix and a pro‐
22       jection matrix.  When you call al_set_target_bitmap, these will be made
23       current for the bitmap, affecting global OpenGL and DirectX states  de‐
24       pending on the driver in use.
25
26       Each  video bitmap is tied to a display.  When a video bitmap is set to
27       as the target bitmap, the display that the bitmap belongs to  is  auto‐
28       matically  made  “current” for the calling thread (if it is not current
29       already).  Then drawing other bitmaps which are tied to the  same  dis‐
30       play can be hardware accelerated.
31
32       A single display cannot be current for multiple threads simultaneously.
33       If you need to release a display, so it is not current for the  calling
34       thread, call al_set_target_bitmap(NULL);
35
36       Setting a memory bitmap as the target bitmap will not change which dis‐
37       play is current for the calling thread.
38
39       On some platforms, Allegro automatically backs up the contents of video
40       bitmaps  because  they  may  be  occasionally  lost  (see discussion in
41       al_create_bitmap(3)’s documentation).  If you’re completely  recreating
42       the  bitmap  contents  often (e.g.  every frame) then you will get much
43       better performance by creating the target bitmap  with  ALLEGRO_NO_PRE‐
44       SERVE_TEXTURE flag.
45
46       OpenGL note:
47
48       Framebuffer  objects  (FBOs) allow OpenGL to directly draw to a bitmap,
49       which is very fast.  When using an OpenGL display, if all of  the  fol‐
50       lowing  conditions are met an FBO will be created for use with the bit‐
51       map:
52
53       • The GL_EXT_framebuffer_object OpenGL extension is available.
54
55       • The bitmap is not a memory bitmap.
56
57       • The bitmap is not currently locked.
58
59       In Allegro 5.0.0, you had to be careful as an FBO would be kept  around
60       until   the  bitmap  is  destroyed  or  you  explicitly  called  al_re‐
61       move_opengl_fbo(3) on the bitmap, wasting  resources.   In  newer  ver‐
62       sions,  FBOs  will  be freed automatically when the bitmap is no longer
63       the target bitmap, unless you have called al_get_opengl_fbo(3)  to  re‐
64       trieve the FBO id.
65
66       In the following example, no FBO will be created:
67
68              lock = al_lock_bitmap(bitmap);
69              al_set_target_bitmap(bitmap);
70              al_put_pixel(x, y, color);
71              al_unlock_bitmap(bitmap);
72
73       The  above allows using al_put_pixel(3) on a locked bitmap without cre‐
74       ating an FBO.
75
76       In this example an FBO is created however:
77
78              al_set_target_bitmap(bitmap);
79              al_draw_line(x1, y1, x2, y2, color, 0);
80
81       An OpenGL command will be used to directly draw the line into the  bit‐
82       map’s associated texture.
83

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO