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 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.

       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)