Blits
-----

NOTE: You may want to see the link:coordinate_system.html[coordinate system] first.

Blit copies a rectangular area from one pixmap to another. Blits can
do automatic pixel conversion i.e. swap R a B in blit from RGB888 to BGR888 or
even convert RGB image into grayscale.

The conversion however may not be ideal as the pixel channel values are just
divided/multiplied before they are written into the destination bitmap. For
down-sampling (i.e. size or number of channels of destination bitmap is
smaller) you should consider using the link:filters.html#Dithering[dithering
filters] first to convert the source bitmap into destination format.

Also blits that do conversions are significantly slower than blits with equal
pixel sizes. If you need to blit a pixmap several times consider converting it
into destination pixel type to speed up the blitting.


[source,c]
--------------------------------------------------------------------------------
#include <gfxprim.h>
/* or */
#include <core/gp_blit.h>

void gp_blit(const gp_pixmap *src,
             gp_coord x0, gp_coord y0, gp_size w0, gp_size h0,
             gp_pixmap *dst, gp_coord x1, gp_coord y1);

void gp_blit_xywh(const gp_pixmap *src,
                  gp_coord x0, gp_coord y0, gp_size w0, gp_size h0,
                  gp_pixmap *dst, gp_coord x1, gp_coord y1);

void gp_blit_xyxy(const gp_pixmap *src,
                  gp_coord x0, gp_coord y0, gp_coord x1, gp_coord y1,
                  gp_pixmap *dst, gp_coord x2, gp_coord y2);
--------------------------------------------------------------------------------

Blit functions to copy rectangular area from source to destination.

As you may see the 'gp_blit()' function is just alias for 'gp_blit_xywh()'.

WARNING: For these functions the behavior is undefined when you pass
         coordinates or width or height outside of the source or destination
	 pixmap. If you need safe variant that automatically clips the
	 coordinates and rectangle to fit both the source and destination use
	 the clipped variants described below.


[source,c]
--------------------------------------------------------------------------------
#include <gfxprim.h>
/* or */
#include <core/gp_blit.h>

void gp_blit_xyxy_clipped(const gp_pixmap *src,
                          gp_coord x0, gp_coord y0, gp_coord x1, gp_coord y1,
                          gp_pixmap *dst, gp_coord x2, gp_coord y2);


void gp_blit_xywh_clipped(const gp_pixmap *src,
                          gp_coord x0, gp_coord y0, gp_size w0, gp_size h0,
                          gp_pixmap *dst, gp_coord x1, gp_coord y1);

void gp_blit_clipped(const gp_pixmap *src,
                     gp_coord x0, gp_coord y0, gp_size w0, gp_size h0,
                     gp_pixmap *dst, gp_coord x1, gp_coord y1);
--------------------------------------------------------------------------------

Blit functions to copy rectangular area from source to destination. Both
source and destination coordinates and sizes are clipped to fit the pixmaps.

As you may see the 'gp_blit_clipped()' function is just alias for
'gp_blit_xywh_clipped()'.
