doc/blits.txt

   1 Blits
   2 -----
   3
   4 NOTE: You may want to see the link:coordinate_system.html[coordinate system] first.
   5
   6 Blit copies a rectangular area from one pixmap into the another one. Blits can
   7 do automatic pixel conversion i.e. swap R a B in blit from RGB888 to BGR888 or
   8 even convert RGB image into grayscale.
   9
  10 The conversion however may not be ideal as the pixel channel values are just
  11 divided/multiplied before they are written into the destination bitmap. For
  12 down-sampling (i.e. size or number of channels of destination bitmap is
  13 smaller) you should consider using the link:filters.html#Dithering[dithering
  14 filters] first to convert the source bitmap into destination format.
  15
  16 Also blits that do conversions are significantly slower than blits with equal
  17 pixel sizes. If you need to blit a pixmap several times consider converting it
  18 into destination pixel type to speed up the blitting.
  19
  20
  21 [source,c]
  22 --------------------------------------------------------------------------------
  23 #include <GP.h>
  24 /* or */
  25 #include <core/GP_Blit.h>
  26
  27 void GP_Blit(const GP_Context *src,
  28              GP_Coord x0, GP_Coord y0, GP_Size w0, GP_Size h0,
  29              GP_Context *dst, GP_Coord x1, GP_Coord y1);
  30
  31 void GP_BlitXYWH(const GP_Context *src,
  32                  GP_Coord x0, GP_Coord y0, GP_Size w0, GP_Size h0,
  33                  GP_Context *dst, GP_Coord x1, GP_Coord y1);
  34
  35 void GP_BlitXYXY(const GP_Context *src,
  36                  GP_Coord x0, GP_Coord y0, GP_Coord x1, GP_Coord y1,
  37                  GP_Context *dst, GP_Coord x2, GP_Coord y2);
  38 --------------------------------------------------------------------------------
  39
  40 Blit functions to copy rectangular area from source to destination.
  41
  42 As you may see the 'GP_Blit()' function is just alias for 'GP_BlitXYWH()'.
  43
  44 WARNING: For these functions the behavior is undefined when you pass
  45          coordinates or width or height outside of the source or destination
  46          pixmap. If you need safe variant that automatically clips the
  47          coordinates and rectangle to fit both the source and destination use
  48          the Clipped variants described bellow.
  49
  50
  51 [source,c]
  52 --------------------------------------------------------------------------------
  53 #include <GP.h>
  54 /* or */
  55 #include <core/GP_Blit.h>
  56
  57 void GP_BlitXYXY_Clipped(const GP_Context *src,
  58                          GP_Coord x0, GP_Coord y0, GP_Coord x1, GP_Coord y1,
  59                          GP_Context *dst, GP_Coord x2, GP_Coord y2);
  60
  61
  62 void GP_BlitXYWH_Clipped(const GP_Context *src,
  63                          GP_Coord x0, GP_Coord y0, GP_Size w0, GP_Size h0,
  64                          GP_Context *dst, GP_Coord x1, GP_Coord y1);
  65
  66 void GP_Blit_Clipped(const GP_Context *src,
  67                      GP_Coord x0, GP_Coord y0, GP_Size w0, GP_Size h0,
  68                      GP_Context *dst, GP_Coord x1, GP_Coord y1);
  69 --------------------------------------------------------------------------------
  70
  71 Blit functions to copy rectangular area from source to destination. Both
  72 source and destination coordinates and sizes are clipped to fit the pixmaps.
  73
  74 As you may see the 'GP_Blit_Clipped()' function is just alias for
  75 'GP_BlitXYWH_Clipped()'.