al_set_target_bitmap(3)

1al_set_target_bitmap(3)    Library Functions Manual    al_set_target_bitmap(3)
2
3
4

NAME

6       al_set_target_bitmap
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  video bitmap is tied to a display.  When a video bitmap is set to
21       as the target bitmap, the display that the bitmap belongs to  is  auto‐
22       matically  made  “current” for the calling thread (if it is not current
23       already).  Then drawing other bitmaps which are tied to the  same  dis‐
24       play can be hardware accelerated.
25
26       A single display cannot be current for multiple threads simultaneously.
27       If you need to release a display, so it is not current for the  calling
28       thread, call al_set_target_bitmap(NULL);
29
30       Setting a memory bitmap as the target bitmap will not change which dis‐
31       play is current for the calling thread.
32
33       OpenGL note:
34
35       Framebuffer objects (FBOs) allow OpenGL to directly draw to  a  bitmap,
36       which  is  very fast.  When using an OpenGL display, if all of the fol‐
37       lowing conditions are met an FBO will be created for use with the  bit‐
38       map:
39
40       · The GL_EXT_framebuffer_object OpenGL extension is available.
41
42       · The bitmap is not a memory bitmap.
43
44       · The bitmap is not currently locked.
45
46       In  Allegro 5.0.0, you had to be careful as an FBO would be kept around
47       until   the   bitmap   is   destroyed   or   you   explicitly    called
48       al_remove_opengl_fbo(3)  on  the  bitmap,  wasting resources.  In newer
49       versions, FBOs will be freed automatically when the bitmap is no longer
50       the  target  bitmap,  unless  you  have  called al_get_opengl_fbo(3) to
51       retrieve the FBO id.
52
53       In the following example, no FBO will be created:
54
55              lock = al_lock_bitmap(bitmap);
56              al_set_target_bitmap(bitmap);
57              al_put_pixel(x, y, color);
58              al_unlock_bitmap(bitmap);
59
60       The above allows using al_put_pixel(3) on a locked bitmap without  cre‐
61       ating an FBO.
62
63       In this example an FBO is created however:
64
65              al_set_target_bitmap(bitmap);
66              al_draw_line(x1, y1, x2, y2, color, 0);
67
68       An  OpenGL command will be used to directly draw the line into the bit‐
69       map's associated texture.
70

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO