NAME
====
  vg_bitmap_overlap() - check whether two bitmaps overlap


SYNOPSIS
========
  int vg_bitmap_overlap(struct ovlap * ovl, const bitmap * bmp1, int x1start, int y1start, int x1end, int y1end, const bitmap * bmp2, int x2, int y2, int minpixel)


DESCRIPTION
===========
  This function checks whether two bitmaps overlap, where the first bitmap
  bmp1 is moving from (x1start,y1start) to (x1end,y1end),
  and the second bitmap bmp2 is at (x2,y2).

  Because a bitmap is always a rectangle, but need not be fully drawn out,
  it is not important whether the boundaries of the two bitmaps overlap,
  but only whether the drawn pixels of both bitmaps touch.
  E.g. a circle with a radius of 10 pixels needs at least a bitmap of (20,20).
  Two circle-bitmaps only overlap if the circles overlap, not if the bitmap
  boundaries overlap.
  So overlapping is true only, if at least one non-transparent pixel
  (not RGB_BLACK) of bmp1 touches a non-transparent pixel of bmp2.

  With parameter minpixel the number of overlapping pixels can be set:
  If it is greater than 0, the overlapping is true only,
  if at least minpixel non-transparent pixels overlap.
  If it is 0, no pixel checking is performed, only bitmap-boundary checking.

  As above mentioned, bmp1 is moving. This means, that the overlap checking
  is performed from bmp1's position (x1start,y1start) to (x1end,y1end).
  When an overlapping with at least minpixel is found, the moving is ended
  and return values are set into the passed struct ovlap ovl.
  This struct need not be initialized before and is changed only
  if an overlapping is found.
  ovl may be NULL, if return values are not needed.

  struct ovlap is defined as follows:

    struct ovlap {
      int hitside;          /* bitfield of VG_RIGHT,VG_LEFT,VG_TOP,VG_BOTTOM */
      int x_nohit,y_nohit;  /* last not overlapping position */
      int x_hit,y_hit;      /* first overlapping position */
      int step;             /* number of steps to overlapping */
    };

  The first position of bmp1 between (x1start,y1start)
  and (x1end,y1end) where the overlapping occurs, is saved
  in the elements x_hit and y_hit.
  The position before (which was the last without overlapping) is saved
  in the elements x_nohit and y_nohit.
  The number of steps bmp1 has taken to reach the overlapping is saved
  in the element step.
  If step is 0, x_nohit and y_nohit are both -1.
  In the element hitside is saved at which side bmp1 is hit by bmp2:
    VG_RIGHT:  if bmp1's right side is hit
    VG_LEFT:   if bmp1's left side is hit
    VG_TOP:    if bmp1's top side is hit
    VG_BOTTOM: if bmp1's bottom side is hit
  These values can be bitwise OR'd if a diagonal touch occurs,
    e.g. VG_RIGHT | VG_TOP,
  or if both bitmaps are at the same position, all 4 values are OR'd.
  The return value of the function is set to 1.

  E.g. a bitmap moving from (x1start=0,y1start=4) to (x1end=4,y1end=8)
  which overlaps with the other bitmap at (2,6), sets ovl as follows:

    hitside=VG_RIGHT|VG_BOTTOM;
    x_nohit=1; y_nohit=5;
    x_hit=2;   y_hit=6;
    step=2;

  If no overlapping occurs, the value 0 is returned and
  ovl is leaved untouched.

  Use this function e.g. for moving an object to check whether (and where)
  it eventually collides with another object.


RETURN VALUE
============
  If no overlapping occured, 0 is returned, else 1 is returned


SEE ALSO
========
  Index
  Understanding bitmaps
  vg_bitmap_createnew()
  vg_bitmap_createfromfile()
  vg_bitmap_createfromtext()
  vg_bitmap_duplicate()
  vg_bitmap_width()
  vg_bitmap_height()
  vg_bitmap_getpixel()
  vg_bitmap_clear()
  vg_bitmap_copyto()
  vg_bitmap_save()
  vg_bitmap_rotate()
  vg_bitmap_zoom()
  vg_bitmap_mirror()
  vg_bitmap_free()