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)

Allegro reference manual                                                           al_set_target_bitmap(3alleg5)