DragonFly On-Line Manual Pages

al_set_target_bitmap(3)                                al_set_target_bitmap(3)

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

       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:

       o The GL_EXT_framebuffer_object OpenGL extension is available.

       o The bitmap is not a memory bitmap.

       o 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(3) 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(3) 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(3) 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(3), al_set_target_backbuffer(3)

Allegro reference manual                               al_set_target_bitmap(3)