The GGI2D interface
  Thomas Tanner, tanner@gmx.de
  $Date: 1998/02/17 10:53:35 $

  This document describes the LibGGI2D, the extension library to LibGGI
  providing common 2D graphics primitives.

  1.  Introduction

  This is (as of 22-Jan-98) an API proposal! This is not implemented
  yet!


  While the LibGGI is meant to be very low-level and near to the
  graphics board, this library contains more



  2.  Functions to manipulate the current graphics context

  2.1.  General


  The default values of an visual are:

  o  arc mode: GGI_ARC_PIE

  o  poly mode: GGI_POLY_ALTERNATE

  o  line stipple: normal line

  o  antialiasing: no

  o  clipping rectangle:((0,0),(width,height))

  o  drawcolor: white

  o  fillcolor: black

  o  texture: none

  o  operator: GGI_SET

  o  alpha: 100%



  2.1.1.  void ggiResetVisual(ggi_dc dc);

  Reset the visual to the default values (as listed above).


  2.2.  Clipping

  2.2.1.  void ggiSetClip(ggi_visual vis, int x1, int y1, int x2, int
  y2);

  Set the clipping rectangle to the intersection of ((x1,y1),(x2,y2))
  and the current clipping rectangle.  A pixel (x,y) lies inside the
  clipping rectangle if (x >= x1 && y >= y2 && x < x2 && y < y2).
  ggiSetClip(dc, x, y, x, y) disables all drawing.





  2.2.2.  void ggiResetClip(ggi_visual vis);

  Reset the clipping rectangle to default values.


  2.2.3.  ggi_bool ggiPointVisible(ggi_visual vis, int x, int y);

  Returns true if the point (x,y) lies inside the clipping rectangle.


  2.2.4.  ggi_bool ggiRectVisible(ggi_visual vis, int x1, int y1, int
  x2, int y2);

  Returns true if the rectangle ((x1,y1),(x2,y2)) intersects the
  clipping rectangle.

  2.3.  Drawing modes

  2.3.1.  void ggiSetArcMode(ggi_visual vis, ggi_arcmode mode);

  2.3.2.  ggi_arcmode ggiGetArcMode(ggi_visual vis);

  Set/Get the current arc mode:

   typedef enum {
   GGI_ARC_PIE,
   GGI_ARC_CHORD
   } ggi_arcmode;




  2.3.3.  void ggiSetPolyMode(ggi_visual vis, ggi_polymode mode);

  2.3.4.  ggi_polymode ggiGetPolyMode(ggi_visual vis);

  Set/Get the current polygon mode:

   typedef enum {
   GGI_POLY_ALTERNATE,
   /* alternate rule */
   GGI_POLY_WINDING
   /* winding rule */
   } ggi_polymode;




  2.3.5.  void ggiSetLineStipple(ggi_visual vis, uint stipple, uint
  count);

  2.3.6.  void ggiGetLineStipple(ggi_visual vis, uint *stipple, uint
  *count);

  Set/Get the current line stipple.

  2.3.7.  void ggiSetAntialias(ggi_visual vis, ggi_bool antialias);

  2.3.8.  ggi_bool ggiGetAntialias(ggi_visual vis);

  Set/Get the antialiasing mode.

  2.4.  Color and texture



  2.4.1.  void ggiSetDrawColor(ggi_visual vis, ggi_col color);

  2.4.2.  ggi_col ggiGetDrawColor(ggi_visual vis);

  Set/Get the current drawing color.


  2.4.3.  void ggiSetFillColor(ggi_visual vis, ggi_col color);

  2.4.4.  ggi_col ggiGetFillColor(ggi_visual vis);

  Set/Get the current filling color.


  2.4.5.  void ggiSetFillTexture(ggi_visual vis, int refx, int refy,
  ggi_visual texture);

  Set the texture and the reference point (refx,refy).  The color of a
  drawn pixel at (x,y) is now the texel at (abs(refx-x) mod
  texture.width, abs(refy-y) mod texture.height).


  2.4.6.  ggi_visual ggiGetFillTexture(ggi_visual vis, int *refx, int
  *refy);

  Get the current texture and reference point.  Returns NULL and (0,0)
  if no texture is set.

  2.5.  Drawing style

  2.5.1.  void ggiSetOperator(ggi_visual vis, ggi_operator operator);

  2.5.2.  ggi_operator ggiGetOperator(ggi_visual vis);

  Set/Get the current operator.

   typedef enum {
   GGI_NOOP, /* dest = dest */
   GGI_INVERT, /* dest = ~dest */
   GGI_SET, /* dest = src */
   GGI_SET_INVERTED, /* dest = ~src */
   GGI_AND, /* dest = (dest & src) */
   GGI_NAND, /* dest = ~(dest & src) */
   GGI_AND_REVERSE, /* dest = ~dest & src */
   GGI_AND_INVERTED, /* dest = dest & ~src */
   GGI_OR, /* dest = (dest | src) */
   GGI_NOR, /* dest = ~(dest | src) */
   GGI_OR_REVERSE, /* dest = ~dest & src */
   GGI_OR_INVERTED, /* dest = dest & ~src */
   GGI_XOR, /* dest = (dest ^ src) */
   GGI_EQUIV, /* dest = ~(dest ^ src) */
   GGI_ADD, /* dest = dest + src */
   GGI_SUB /* dest = dest - src */
   } ggi_operator;





  2.5.3.  void ggiSetAlpha(ggi_visual vis, ggi_alpha alpha);

  2.5.4.  ggi_alpha ggiGetAlpha(ggi_visual vis);

  Set/Get the current alpha value.


  3.  Drawing functions


  3.1.  Pixels

  3.1.1.  void ggiGetPixel(ggi_visual vis, int x, int y, ggi_col *color)

  Get the color of the pixel at (x,y).  Returns 0 if the point lies
  outside the clipping rectangle.


  3.1.2.  void ggiPutPixel(ggi_visual vis, int x, int y, ggi_col color);

  3.1.3.  void ggiPutPixelA(ggi_visual vis, int x, int y, ggi_col color,
  ggi_alpha alpha);

  3.1.4.  void ggiDrawPixel(ggi_visual vis, int x, int y);

  3.1.5.  void ggiDrawPixelA(ggi_visual vis, int x, int y, ggi_alpha
  alpha);

  Draw a pixel at (x,y).


  3.1.6.  void ggiDrawPixels(ggi_visual vis, ggi_coord coords[], uint
  count);

  Draw several pixels.

  3.2.  Lines

  3.2.1.  void ggiHLine(ggi_visual vis, int x1, int x2, int y);

  Draw a horizontal line from (x1,y) to (x2,y).  Note: This line is not
  stippled!


  3.2.2.  void ggiVLine(ggi_visual vis, int x, int y1, int y2);

  Draw a vertical line from (x,y1) to (x,y2).  Note: This line is not
  stippled!


  3.2.3.  void ggiDrawRect(ggi_visual vis, int x1, int y1, int x2, int
  y2);

  3.2.4.  void ggiFillRect(ggi_visual vis, int x1, int y1, int x2, int
  y2);

  Draw/Fill the rectangle ((x1,y1),(x2,y2)).


  3.2.5.  void ggiLine(ggi_visual vis, int x1, int y1, int x2, int y2);

  3.2.6.  void ggiLinef(ggi_visual vis, ggi_float x1, ggi_float y1,
  ggi_float x2, ggi_float y2);

  Draw a line from (x1,y1) to (x2,y2).


  3.2.7.  void ggiDrawLines(ggi_visual vis, ggi_line lines[], uint
  count);

  Draw several lines.


  3.3.  Circles and curves

  3.3.1.  void ggiDrawCircle(ggi_visual vis, int x, int y, uint r);

  3.3.2.  void ggiFillCircle(ggi_visual vis, int x, int y, uint r);


  Draw/Fill a circle with radius r around (x,y).


  3.3.3.  void ggiDrawEllipse(ggi_visual vis, int x, int y, uint rx,
  uint ry);

  3.3.4.  void ggiFillEllipse(ggi_visual vis, int x, int y, uint rx,
  uint ry);


  Draw/Fill an ellipse with radius (rx,ry) around (x,y).


  3.3.5.  void ggiDrawArc(ggi_visual vis, int x, int y, uint rx, uint
  ry, ggi_float start, ggi_float end, ggi_bool close);


  Draw an arc with radius (rx,ry) around (x,y) between "start" and "end"
  (degree).  If close is GGI_TRUE, the arc will be closed (using
  arcmode).


  3.3.6.  void ggiFillArc(ggi_visual vis, int x, int y, uint rx, uint
  ry, ggi_float start, ggi_float end);


  Fill an arc with radius (rx,ry) around (x,y) between "start" and "end"
  (degree).


  3.3.7.  void ggiBezier(ggi_visual vis, int x1, int y1, int x2, int y2,
  int x3, int y3, int x4, int y4);


  Draw a bezier curve.


  3.4.  Polygons

  3.4.1.  void ggiTrapezoid(ggi_visual vis, int xl1, int xr1, int y1,
  int xl2, int xr2, int y2);


  Fill a trapezoid.


  3.4.2.  void ggiTriangle(ggi_visual vis, int x1, int y1, int x2, int
  y2, int x3, int y3);


  Fill a triangle.


  3.4.3.  void ggiDrawPoly(ggi_visual vis, ggi_coord coords[], uint
  count);




  3.4.4.  void ggiFillPoly(ggi_visual vis, ggi_coord coords[], uint
  count);


  Draw/Fill a polygon.


  3.4.5.  void ggiFillPolys(ggi_visual vis, ggi_coord coords[], uint
  counts[], uint count);


  Fill several (overlapping) polygons.


  3.5.  Scrolling/Blitting functions



  3.5.1.  void ggiScroll( ggi_visual vis, int dx, int dy, int sx, int
  sy, int width, int height);


  Copy the rectangular area ((sx,sy),(sx+width,sy+height)) to (dx,dy).

  3.5.2.  void ggiBlit(ggi_visual vis, int dx, int dy, ggi_visual src,
  int sx, int sy, int width, int height);

  3.5.3.  void ggiStretchBlit(ggi_visual dest, int dx, int dy, int
  dwidth, int dheight, ggi_visual src, int sx, int sy, int swidth, int
  sheight);


  Copy the rectangular area ((sx,sy),(sx+width,sy+height)) from "src" to
  (dx,dy).  ggiStretchBlit() can scale the image.

  3.5.4.  void ggiBlitTrans(ggi_visual dest, int dx, int dy, ggi_visual
  src, int sx, int sy, int width, int height, ggi_col transcol);

  3.5.5.  void ggiStretchBlitTrans(ggi_visual dest, int dx, int dy, int
  dwidth, int dheight,ggi_visual src, int sx, int sy, int swidth, int
  sheight,ggi_col transcol);


  Copy the rectangular area ((sx,sy),(sx+width,sy+height)) from "src" to
  (dx,dy). Pixels with color "transcol" are not drawn.
  ggiStretchBlitTrans() can scale the image.


  3.5.6.  void ggiBlitOp(ggi_visual dest, int dx, int dy, ggi_visual
  src1, ggi_visual src2, int sx, int sy, int width, int height,
  ggi_operator op);

  3.5.7.  void ggiStretchBlitOp(ggi_visual dest, int dx, int dy, int
  dwidth, int dheight, ggi_visual src1, ggi_visual src2, int sx, int sy,
  int swidth, int sheight, ggi_operator op);


  Apply the operator "op" to all pixels of the rectangular areas
  ((sx,sy),(sx+width,sy+height)) of "src1" and "src2" and draw them only
  if the result is not 0.  ggiStretchBlitOp() can scale the image.