1blit(3)                         Allegro manual                         blit(3)
2
3
4

NAME

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

SYNOPSIS

10       #include <allegro.h>
11
12
13       void blit(BITMAP *source, BITMAP *dest, int source_x, int source_y, int
14       dest_x, int dest_y, int width, int height);
15

DESCRIPTION

17       Copies  a rectangular area of the source bitmap to the destination bit‐
18       map.  The source_x and source_y parameters are the top left  corner  of
19       the  area to copy from the source bitmap, and dest_x and dest_y are the
20       corresponding position in the destination bitmap. This routine respects
21       the destination clipping rectangle, and it will also clip if you try to
22       blit from areas outside the source bitmap. Example:
23
24          BITMAP *bmp;
25          ...
26          /* Blit src on the screen. */
27          blit(bmp, screen, 0, 0, 0, 0, bmp->w, bmp->h);
28
29          /* Now copy a chunk to a corner, slightly outside. /*
30          blit(screen, screen, 100, 100, -10, -10, 25, 30);
31
32       You can blit between any parts of any two bitmaps, even if the two mem‐
33       ory areas overlap (ie. source and dest are the same, or one is sub-bit‐
34       map of the other). You should be aware, however, that  a  lot  of  SVGA
35       cards  don't  provide  separate  read and write banks, which means that
36       blitting from one part of the screen to another requires the use  of  a
37       temporary  bitmap in memory, and is therefore extremely slow. As a gen‐
38       eral rule you should avoid blitting from the screen onto itself in SVGA
39       modes.
40
41       In  mode-X,  on the other hand, blitting from one part of the screen to
42       another can be significantly faster than blitting from memory onto  the
43       screen,  as  long  as  the source and destination are correctly aligned
44       with each other. Copying between overlapping screen rectangles is slow,
45       but  if the areas don't overlap, and if they have the same plane align‐
46       ment (ie.  (source_x%4) == (dest_x%4)), the VGA latch registers can  be
47       used for a very fast data transfer. To take advantage of this, in mode-
48       X it is often worth storing tile graphics in a  hidden  area  of  video
49       memory  (using  a  large  virtual screen), and blitting them from there
50       onto the visible part of the screen.
51
52       If the GFX_HW_VRAM_BLIT bit in the gfx_capabilities flag  is  set,  the
53       current driver supports hardware accelerated blits from one part of the
54       screen onto another. This is extremely fast, so when this flag  is  set
55       it  may  be worth storing some of your more frequently used graphics in
56       an offscreen portion of the video memory.
57
58       Unlike most of the graphics routines, blit() allows the source and des‐
59       tination  bitmaps to be of different color depths, so it can be used to
60       convert images from one pixel format to  another.  In  this  case,  the
61       behavior  is affected by the COLORCONV_KEEP_TRANS and COLORCONV_DITHER*
62       flags of the current color conversion mode: see  set_color_conversion()
63       for more information.
64
65

SEE ALSO

67       masked_blit(3),  stretch_blit(3),  draw_sprite(3), gfx_capabilities(3),
68       set_color_conversion(3)
69
70
71
72Allegro                          version 4.4.3                         blit(3)
Impressum