NAME

       al_set_target_bitmap - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro.h>

              void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)

DESCRIPTION

       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(3alleg5).  As a convenience, you may also
       use al_set_target_backbuffer(3alleg5).

       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.

       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.

       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
       al_set_target_bitmap(NULL);

       Setting a memory bitmap as the target bitmap will not change which display is current  for
       the calling thread.

       On  some  platforms,  Allegro automatically backs up the contents of video bitmaps because
       they  may  be   occasionally   lost   (see   discussion   in   al_create_bitmap(3alleg5)'s
       documentation).   If  you'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.

       OpenGL note:

       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:

       • The GL_EXT_framebuffer_object OpenGL extension is available.

       • The bitmap is not a memory bitmap.

       • The bitmap is not currently locked.

       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(3alleg5) on  the  bitmap,  wasting
       resources.   In  newer  versions,  FBOs  will be freed automatically when the bitmap is no
       longer the target bitmap, unless you have called  al_get_opengl_fbo(3alleg5)  to  retrieve
       the FBO id.

       In the following example, no FBO will be created:

              lock = al_lock_bitmap(bitmap);
              al_set_target_bitmap(bitmap);
              al_put_pixel(x, y, color);
              al_unlock_bitmap(bitmap);

       The above allows using al_put_pixel(3alleg5) on a locked bitmap without creating an FBO.

       In this example an FBO is created however:

              al_set_target_bitmap(bitmap);
              al_draw_line(x1, y1, x2, y2, color, 0);

       An  OpenGL  command  will  be  used to directly draw the line into the bitmap's associated
       texture.

SEE ALSO

       al_get_target_bitmap(3alleg5), al_set_target_backbuffer(3alleg5)