NAME

       blit - Copies a rectangular area from one bitmap to another. Allegro game programming library.

SYNOPSIS

       #include <allegro.h>

       void  blit(BITMAP  *source,  BITMAP *dest, int source_x, int source_y, int dest_x, int dest_y, int width,
       int height);

DESCRIPTION

       Copies a rectangular area of the source bitmap to the destination  bitmap.   The  source_x  and  source_y
       parameters  are the top left corner of the area to copy from the source bitmap, and dest_x and dest_y are
       the corresponding position in the destination bitmap. This  routine  respects  the  destination  clipping
       rectangle, and it will also clip if you try to blit from areas outside the source bitmap. Example:

          BITMAP *bmp;
          ...
          /* Blit src on the screen. */
          blit(bmp, screen, 0, 0, 0, 0, bmp->w, bmp->h);

          /* Now copy a chunk to a corner, slightly outside. /*
          blit(screen, screen, 100, 100, -10, -10, 25, 30);

       You  can  blit between any parts of any two bitmaps, even if the two memory areas overlap (ie. source and
       dest are the same, or one is sub-bitmap of the other). You should be aware, however, that a lot  of  SVGA
       cards  don't provide separate read and write banks, which means that blitting from one part of the screen
       to another requires the use of a temporary bitmap in memory,  and  is  therefore  extremely  slow.  As  a
       general rule you should avoid blitting from the screen onto itself in SVGA modes.

       In mode-X, on the other hand, blitting from one part of the screen to another can be significantly faster
       than  blitting  from  memory onto the screen, as long as the source and destination are correctly aligned
       with each other. Copying between overlapping screen rectangles is slow, but if the areas  don't  overlap,
       and  if they have the same plane alignment (ie.  (source_x%4) == (dest_x%4)), the VGA latch registers can
       be used for a very fast data transfer. To take advantage of this, in mode-X it  is  often  worth  storing
       tile  graphics  in  a  hidden area of video memory (using a large virtual screen), and blitting them from
       there onto the visible part of the screen.

       If the GFX_HW_VRAM_BLIT bit in the gfx_capabilities flag is set, the  current  driver  supports  hardware
       accelerated  blits from one part of the screen onto another. This is extremely fast, so when this flag is
       set it may be worth storing some of your more frequently used graphics in an  offscreen  portion  of  the
       video memory.

       Unlike most of the graphics routines, blit() allows the source and destination bitmaps to be of different
       color  depths,  so  it  can be used to convert images from one pixel format to another. In this case, the
       behavior is affected by the  COLORCONV_KEEP_TRANS  and  COLORCONV_DITHER*  flags  of  the  current  color
       conversion mode: see set_color_conversion() for more information.

SEE ALSO

       masked_blit(3alleg4),     stretch_blit(3alleg4),     draw_sprite(3alleg4),     gfx_capabilities(3alleg4),
       set_color_conversion(3alleg4)

Allegro                                           version 4.4.3                                    blit(3alleg4)