NAME

       al_hold_bitmap_drawing - Allegro 5 API

SYNOPSIS

              #include <allegro5/allegro.h>

              void al_hold_bitmap_drawing(bool hold)

DESCRIPTION

       Enables  or  disables  deferred bitmap drawing.  This allows for efficient drawing of many
       bitmaps that share a parent bitmap,  such  as  sub-bitmaps  from  a  tilesheet  or  simply
       identical bitmaps.  Drawing bitmaps that do not share a parent is less efficient, so it is
       advisable to stagger bitmap drawing calls such that the parent  bitmap  is  the  same  for
       large number of those calls.  While deferred bitmap drawing is enabled, the only functions
       that can be used are the bitmap drawing functions and font  drawing  functions.   Changing
       the state such as the blending modes will result in undefined behaviour.  One exception to
       this  rule  are  the  non-projection  transformations.   It  is  possible  to  set  a  new
       transformation while the drawing is held.

       No  drawing  is  guaranteed  to take place until you disable the hold.  Thus, the idiom of
       this function's usage is to enable the deferred bitmap drawing, draw as  many  bitmaps  as
       possible,  taking  care  to  stagger  bitmaps  that share parent bitmaps, and then disable
       deferred drawing.  As mentioned above, this function also works with bitmap  and  truetype
       fonts, so if multiple lines of text need to be drawn, this function can speed things up.

SEE ALSO

       al_is_bitmap_drawing_held(3alleg5)