  The GGI2D interface
  Thomas Tanner, tanner@gmx.de
  $Date: 1998/06/29 17:07:28 $

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

  1.  Introduction

  While the LibGGI is meant to be very low-level and near to the
  graphics board, libGGI2D's functionality satisfies the demands of user
  interfaces, window systems, non-3D games etc. It's also the base of
  libGPS, the GGI Display Postscript extension.


  2.  General

  2.1.  Start and Exit


  2.1.1.  int       ggi2dInit(void);

  Initializes the libGGI2D library.  This MUST be called at startup.


  2.1.2.  void      ggi2dExit(void);

  Deinitializes the libGGI2D library.  This MUST be called before exit.


  2.2.  Visual



  2.2.1.  void      ggi2dOpen(ggi_visual_t vis);

  Initialize a visual. This MUST be done before any drawing.  The
  default values of a visual are:

  o  arc mode: GGI_ARC_SECTOR

  o  poly mode: GGI_POLY_EVENODD

  o  line stipple: normal line

  o  antialiasing: no

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

  o  drawcolor: 0

  o  fillcolor: 0

  o  texture: none

  o  operator: GGI_SET

  o  alpha: GGI_MAX_ALPHA i.e 100%


  2.2.2.  void      ggi2dClose(ggi_visual_t vis);

  End drawing on the visual.



  2.2.3.  void      ggi2dReset(ggi_visual vis);

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



  3.  Manipulation of the graphics context

  3.1.  Clipping


  3.1.1.  void ggiSetClip(ggi_visual_t 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.


  3.1.2.  ggi_bool ggiPointVisible(ggi_visual_t vis, int x, int y);

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


  3.1.3.  ggi_bool ggiRectVisible(ggi_visual_t vis, int x1, int y1, int
  x2, int y2);

  Returns true if the rectangle ((x1,y1),(x2,y2)) is at least partially
  visible.


  3.2.  Drawing modes

  3.2.1.  void ggiSetArcMode(ggi_visual_t vis, ggi_arcmode mode);

  3.2.2.  ggi_arcmode ggiGetArcMode(ggi_visual_t vis);

  Set/Get the current arc drawing mode:

  o  GGI_ARC_SECTOR   draw a sector, start- and endpoint are connect
     with the middlepoint

  o  GGI_ARC_SEGMENT  draw a segment, start- and endpoint are connect


  3.2.3.  void ggiSetPolyMode(ggi_visual_t vis, ggi_polymode mode);

  3.2.4.  ggi_polymode ggiGetPolyMode(ggi_visual_t vis);

  Set/Get the current polygon filling mode:

  o  GGI_POLY_EVENODD  even odd rule

  o  GGI_POLY_WINDING  winding rule

  In general, the modes differ only in cases where a complex,
  overlapping polygon must be filled (for example, a five-sided polygon
  that forms a five-pointed star with a pentagon in the center).  In
  such cases, EVENODD mode fills every other enclosed region within the
  polygon (that is, the points of the star), but WINDING mode fills all
  regions (that is, the points and the pentagon).

  When the fill mode is EVENODD, libGGI2D fills the area between odd-
  numbered and even-numbered polygon sides on each scan line.  That is,
  libGGI2D fills the area between the first and second side, between the
  third and fourth side, and so on.

  When the fill mode is WINDING, libGGI2D fills any region that has a
  nonzero winding value. This value is defined as the number of times a
  pen used to draw the polygon would go around the region.  The
  direction of each edge of the polygon is important.


  3.2.5.  void      ggiSetLineDash(ggi_visual_t vis, uint dash[], uint
  size);

  3.2.6.  void      ggiGetLineDash(ggi_visual_t vis, uint dash[], uint
  *size);

  Set/Get the current line pattern.  A normal line will be drawn if size
  is 0.


  3.2.7.  void      ggiSetAppendMode(ggi_visual_t vis, ggi_bool append);

  3.2.8.  ggi_bool ggiGetAppendMode(ggi_visual_t vis);

  Set/Get the current append mode.


  3.2.9.  void ggiSetAntialias(ggi_visual_t vis, ggi_bool antialias);

  3.2.10.  ggi_bool ggiGetAntialias(ggi_visual_t vis);

  Set/Get the antialiasing mode.


  3.3.  Color and texture

  3.3.1.  void ggiSetDrawColor(ggi_visual_t vis, ggi_col color);

  3.3.2.  ggi_col ggiGetDrawColor(ggi_visual_t vis);

  Set/Get the current drawing color.


  3.3.3.  void ggiSetFillColor(ggi_visual_t vis, ggi_col color);

  3.3.4.  ggi_col ggiGetFillColor(ggi_visual_t vis);

  Set/Get the current filling color.


  3.3.5.  void ggiSetFillTexture(ggi_visual_t 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).


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

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





  3.4.  Drawing style

  3.4.1.  void ggiSetOperator(ggi_visual_t vis, ggi_operator operator);

  3.4.2.  ggi_operator ggiGetOperator(ggi_visual_t vis);

  Set/Get the current operator.  The following operators are defined:

  o  GGI_NOOP         dest = dest

  o  GGI_INVERT       dest =  dest

  o  GGI_SET          dest = src

  o  GGI_SET_INVERTED dest =  src

  o  GGI_AND          dest = (dest & src)

  o  GGI_NAND         dest =  (dest & src)

  o  GGI_AND_REVERSE  dest =  dest & src

  o  GGI_AND_INVERTED dest = dest &  src

  o  GGI_OR           dest = (dest | src)

  o  GGI_NOR          dest =  (dest | src)

  o  GGI_OR_REVERSE   dest =  dest & src

  o  GGI_OR_INVERTED  dest = dest &  src

  o  GGI_XOR          dest = (dest ^ src)

  o  GGI_EQUIV        dest =  (dest ^ src)

  o  GGI_ADD          dest = dest + src

  o  GGI_SUB          dest = dest - src

     GGI_NOOP disables drawing.


  3.4.3.  void ggiSetAlpha(ggi_visual_t vis, ggi_alpha alpha);

  3.4.4.  ggi_alpha ggiGetAlpha(ggi_visual_t vis);

  Set/Get the current alpha value.  The alpha value determines the
  transparency of a drawn pixel.  An alpha value of 0 disables drawing.


  4.  Drawing functions


  4.1.  Pixels

  4.1.1.  void      ggiPutPixel(ggi_visual_t vis, int x, int y,
  ggi_pixel color);

  4.1.2.  void      ggiDrawPixel(ggi_visual_t vis, int x, int y);

  Draw a pixel at (x,y).  Warning: libGGI's ggiPutPixel and ggiDrawPixel
  are overwritten!



  4.1.3.  void ggiDrawPixels(ggi_visual_t vis, ggi_coord coords[], uint
  count);

  Draw several pixels.


  4.2.  Lines

  4.2.1.  void      ggiScanLine(ggi_visual_t vis, int x1, int x2, int
  y);

  Fill a horizontal scanline between (x1,y) and (x2,y) with the current
  fillcolor/texture.


  4.2.2.  void      ggiScanLines(ggi_visual_t vis, int scanlines[], int
  starty, uint count);

  Fill several horizontal scanlines with the current fillcolor/texture.
  "scanlines" is an array of "count" start- and endpoints (x1,x2).  All
  scanlines from starty to starty+count will be filled.


  4.2.3.  void ggiHLine(ggi_visual_t vis, int x1, int x2, int y);

  Draw a horizontal line from (x1,y) to (x2,y).


  4.2.4.  void ggiVLine(ggi_visual_t vis, int x, int y1, int y2);

  Draw a vertical line from (x,y1) to (x,y2).


  4.2.5.  void ggiDrawRect(ggi_visual_t vis, int x1, int y1, int x2, int
  y2);

  4.2.6.  void ggiFillRect(ggi_visual_t vis, int x1, int y1, int x2, int
  y2);

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


  4.2.7.  void ggiLine(ggi_visual_t vis, int x1, int y1, int x2, int
  y2);

  4.2.8.  void ggiLinef(ggi_visual_t vis, ggi_float x1, ggi_float y1,
  ggi_float x2, ggi_float y2);

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


  4.2.9.  void ggiDrawLines(ggi_visual_t vis, ggi_line lines[], uint
  count);

  Draw several lines.


  4.3.  Circles and curves

  4.3.1.  void ggiDrawCircle(ggi_visual_t vis, int x, int y, uint r);

  4.3.2.  void ggiFillCircle(ggi_visual_t vis, int x, int y, uint r);

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


  4.3.3.  void ggiDrawEllipse(ggi_visual_t vis, int x, int y, uint rx,
  uint ry);

  4.3.4.  void ggiFillEllipse(ggi_visual_t vis, int x, int y, uint rx,
  uint ry);

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


  4.3.5.  void ggiDrawArc(ggi_visual_t 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 not GGI_FALSE the arc will be closed using the
  current arc drawing mode.


  4.3.6.  void ggiFillArc(ggi_visual_t 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) using the current arc drawing mode.


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

  Draw a bezier curve.


  4.4.  Polygons

  4.4.1.  void ggiTrapezoid(ggi_visual_t vis, int xl1, int xr1, int y1,
  int xl2, int xr2, int y2);

  Fill a trapezoid.


  4.4.2.  void ggiTriangle(ggi_visual_t vis, int x1, int y1, int x2, int
  y2, int x3, int y3);

  Fill a triangle.


  4.4.3.  void ggiDrawPoly(ggi_visual_t vis, ggi_coord coords[], uint
  count);

  4.4.4.  void ggiFillPoly(ggi_visual_t vis, ggi_coord coords[], uint
  count);

  Draw/Fill a polygon. The polygon may be self overlapping.


  4.4.5.  void ggiFillPolys(ggi_visual_t vis, ggi_coord coords[], uint
  counts[], uint count);

  Fill several polygons. The polygon may be overlapping.


  4.5.  Blitting functions





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

  4.5.2.  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.


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

  4.5.4.  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.


  4.5.5.  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);

  4.5.6.  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.
































