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  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       On some platforms, Allegro automatically backs up the contents of video
34       bitmaps  because  they  may  be  occasionally  lost  (see discussion in
35       al_create_bitmap(3)'s documentation).  If you're completely  recreating
36       the  bitmap  contents  often (e.g.  every frame) then you will get much
37       better performance by creating the target bitmap  with  ALLEGRO_NO_PRE‐
38       SERVE_TEXTURE flag.
39
40       OpenGL note:
41
42       Framebuffer  objects  (FBOs) allow OpenGL to directly draw to a bitmap,
43       which is very fast.  When using an OpenGL display, if all of  the  fol‐
44       lowing  conditions are met an FBO will be created for use with the bit‐
45       map:
46
47       · The GL_EXT_framebuffer_object OpenGL extension is available.
48
49       · The bitmap is not a memory bitmap.
50
51       · The bitmap is not currently locked.
52
53       In Allegro 5.0.0, you had to be careful as an FBO would be kept  around
54       until    the   bitmap   is   destroyed   or   you   explicitly   called
55       al_remove_opengl_fbo(3) on the bitmap,  wasting  resources.   In  newer
56       versions, FBOs will be freed automatically when the bitmap is no longer
57       the target bitmap,  unless  you  have  called  al_get_opengl_fbo(3)  to
58       retrieve the FBO id.
59
60       In the following example, no FBO will be created:
61
62              lock = al_lock_bitmap(bitmap);
63              al_set_target_bitmap(bitmap);
64              al_put_pixel(x, y, color);
65              al_unlock_bitmap(bitmap);
66
67       The  above allows using al_put_pixel(3) on a locked bitmap without cre‐
68       ating an FBO.
69
70       In this example an FBO is created however:
71
72              al_set_target_bitmap(bitmap);
73              al_draw_line(x1, y1, x2, y2, color, 0);
74
75       An OpenGL command will be used to directly draw the line into the  bit‐
76       map's associated texture.
77

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO