libplot-dev 2.6-3 / usr / include / xmi.h

/* This is xmi.h, the public header file for the machine-independent libxmi
   rasterization library, which is based on source files in the X Window
   System distribution.  Written by Robert S. Maier.

   The eight painting functions in libxmi's core API, namely 

     the 5 drawing functions:
       miDrawPoints, miDrawLines, miDrawRectangles, miDrawArcs, miDrawArcs_r

     the 3 filling functions:     
       miFillPolygon, miFillRectangles, miFillArcs  

   are declared below.  The first argument of each of these is a pointer to
   a miPaintedSet.  Conceptually, a miPaintedSet is a set of points with
   integer coordinates, each of which is painted some color (a miPixel).
   The coordinates of the points are unconstrained, i.e., the core painting
   functions perform no clipping.

   Each of the core painting functions takes as second argument a pointer
   to a graphics context: a miGC.  A miGC is an opaque type that contains
   high-level drawing parameters that determine which points will be added
   to the miPaintedSet.  (For example, the line width, line style, and dash
   pattern, all of which are relevant to the drawing functions, though not
   to the filling functions.)  It also specifies the colors (miPixels) that
   will be used when painting the points.  The core painting functions use
   the Painter's Algorithm, so that if a point in an miPaintedSet is
   painted a second time, the new color will replace the old.

   (By default, the painting performed by the core painting functions,
   i.e. by both the drawing functions and the filling functions, is
   `solid', i.e., non-interpolated.  In `solid' painting, the color used is
   taken from the pixel array in the miGC.  Any miGC contains an array of
   pixel colors, of length n>=2.  Color #1 is the default color for
   painting, and colors 0,2,3,..,n-1 are used only by the drawing
   functions, when drawing in a dashed mode.  In normal (on/off) dashing,
   the colors of the `on' dashes will cycle through 1,2,..,n-1.  In
   so-called double dashing, the `off' dashes will be drawn too, in color #0.)

   After a miPaintedSet is built up by invoking one or more core painting
   functions, the next stage of the graphics pipeline is performed by
   calling miCopyPaintedSetToCanvas().  This transfers the pixels in the
   miPaintedSet onto a canvas structure called a miCanvas, which contains a
   bounded, fixed-size drawable.  In the transfer, more sophisticated
   algorithms than the Painter's Algorithm may be used.  Besides the
   drawable, a miCanvas may contain additional members, such as a stipple
   bitmap, a texture pixmap, and binary and ternary pixel-merging
   functions.  These will affect how the pixels from the miPaintedSet are
   combined with the ones that already exist on the drawable. */

#ifndef _XMI_H_
#define _XMI_H_ 1

/***********************************************************************/

/* Version of GNU libxmi which this header file accompanies.  This
   information is included beginning with version 1.2.

   The MI_LIBXMI_VER_STRING macro is compiled into the library, as
   `mi_libxmi_ver'.  The MI_LIBXMI_VER macro is not compiled into it.  Both
   are available to applications that include this header file. */

#define MI_LIBXMI_VER_STRING "1.3"
#define MI_LIBXMI_VER         130

extern const char mi_libxmi_ver[8]; /* need room for 99.99aa */

/**********************************************************************/

/* support C++ */
#ifdef ___BEGIN_DECLS
#undef ___BEGIN_DECLS
#endif
#ifdef ___END_DECLS
#undef ___END_DECLS
#endif
#ifdef __cplusplus
# define ___BEGIN_DECLS extern "C" {
# define ___END_DECLS }
#else
# define ___BEGIN_DECLS		/* empty */
# define ___END_DECLS		/* empty */
#endif
     
/**********************************************************************/

/* Structure that defines a point with integer coordinates. */
typedef struct
{
  int x, y;			/* integer coordinates, y goes downward */
} miPoint;

/* Definition of miPixel, the pixel value datatype.  By default, a miPixel
   is an unsigned int.  The libxmi installer may alter the definition by
   defining the symbol MI_PIXEL_TYPE at installation time.  The macro
   MI_SAME_PIXEL(), which tests for equality, may need to be redefined too
   (e.g., if MI_PIXEL_TYPE is a struct or a union). */
#ifdef MI_PIXEL_TYPE
typedef MI_PIXEL_TYPE miPixel;
#else
typedef unsigned int miPixel;
#endif
#ifndef MI_SAME_PIXEL
#define MI_SAME_PIXEL(pixel1,pixel2) \
  ((pixel1) == (pixel2))
#endif


/**********************************************************************/

/* A miPaintedSet is an opaque structure that contains a set of painted
   points, i.e., a set of points partitioned according to the pixel color
   used for painting.  When any public drawing function is invoked, a
   pointer to a miPaintedSet is passed as its first argument. */
typedef struct lib_miPaintedSet miPaintedSet;

/* Constructor and destructor for the miPaintedSet class. */
extern miPaintedSet * miNewPaintedSet (void);
extern void miDeletePaintedSet (miPaintedSet *paintedSet);

/* A function that clears any miPaintedSet (i.e. makes it the empty set). */
extern void miClearPaintedSet (miPaintedSet *paintedSet);

/**********************************************************************/

/* A miGC is an opaque structure that contains high-level drawing
   parameters.  When any public drawing function is invoked, a pointer to a
   miGC is passed as its second argument. */
typedef struct lib_miGC miGC;

/* Constructor, destructor, and copy constructor for the miGC class. */
extern miGC * miNewGC (int npixels, const miPixel *pixels); /* npixels >= 2 */
extern void miDeleteGC (miGC *pGC);
extern miGC * miCopyGC (const miGC *pGC);

/* Values for an miGC's miGCLineStyle attribute (default=MI_LINE_SOLID). */
enum { MI_LINE_SOLID, MI_LINE_ON_OFF_DASH, MI_LINE_DOUBLE_DASH };

/* Values for an miGC's miGCJoinStyle attribute (default=MI_JOIN_MITER). */
enum { MI_JOIN_MITER, MI_JOIN_ROUND, MI_JOIN_BEVEL, MI_JOIN_TRIANGULAR };

/* Values for an miGC's miGCCapStyle attribute (default=MI_CAP_BUTT).
   MI_CAP_NOT_LAST is the same as MI_CAP_BUTT except when drawing
   zero-width (Bresenham) polylines; it causes the final pixel not to be
   drawn.  A polyline drawn in this way is called `continuable'. */
enum { MI_CAP_NOT_LAST, MI_CAP_BUTT, MI_CAP_ROUND, MI_CAP_PROJECTING, MI_CAP_TRIANGULAR };

/* Values for an miGC's miGCFillRule attribute (default=MI_EVEN_ODD_RULE). */
enum { MI_EVEN_ODD_RULE, MI_WINDING_RULE };

/* Values for an miGC's miGCArcMode attribute (default=MI_ARC_PIE_SLICE). */
enum { MI_ARC_CHORD, MI_ARC_PIE_SLICE };

/* Possibilities for the `attribute' argument of miSetGCAttrib.  (All the
   preceding, plus MI_GC_LINE_WIDTH.) */
typedef enum { MI_GC_FILL_RULE, MI_GC_JOIN_STYLE, MI_GC_CAP_STYLE, MI_GC_LINE_STYLE, MI_GC_ARC_MODE, MI_GC_LINE_WIDTH } miGCAttribute;

/* A function that sets a single integer-valued miGC attribute.  `value'
   must be one of the preceding enum's, except when
   attribute=MI_GC_LINE_WIDTH, in which case value>=0 is required. */
extern void miSetGCAttrib (miGC *pGC, miGCAttribute attribute, int value);

/* A function that sets a list of integer-value miGC attributes. */
extern void miSetGCAttribs (miGC *pGC, int nattributes, const miGCAttribute *attributes, const int *values);

/* Functions that set miGC attributes that are not integer-valued.
   Note: currently, `offset' must be nonnegative. */
extern void miSetGCDashes (miGC *pGC, int ndashes, const unsigned int *dashes, int offset);
extern void miSetGCMiterLimit (miGC *pGC, double miter_limit);
extern void miSetGCPixels (miGC *pGC, int npixels, const miPixel *pixels); /* npixels >=2 */

/* Additional functions that set miGC attributes: in particular, functions
   that set the paint style that will be used.  Only in the case of `solid'
   painting (the default) is the above pixel array relevant. */
extern void miSetGCPaintSolid (void);
extern void miSetGCPaintInterpParallel (miPoint pts[2], miPixel pixels[2]);
extern void miSetGCPaintInterpTriangular (miPoint pts[3], miPixel pixels[3]);
extern void miSetGCPaintInterpElliptical (void);

/*********** DECLARATIONS OF PUBLIC DRAWING FUNCTIONS ******************/

/* The semantics of these drawing functions is similar to that of the
   corresponding X11 drawing functions.  Wide polylines (polylines with
   line width >= 1) are treated as polygons to be rendered by filling.
   Zero-width polylines are not invisible: instead, they are single-pixel
   polylines, specially rendered by the Bresenham midpoint line algorithm.

   Also, adjoining polygons (those with an edge in common) are drawn
   without gaps.  To arrange this, the `right' and `bottom' edges of any
   polygon are not drawn when the polygon is filled.  The filling of
   rectangles is similar.

   Wide arcs and polyarcs are drawn with a circular brush, of diameter
   equal to the line width.  Every brushed pixel is painted.  Zero-width
   arcs and polyarcs are not invisible: instead, they are single-pixel
   arcs, specially rendered by the Bresenham `midpoint arc' algorithm. */

/* For consistency, the first three arguments of each drawing function are
   (1) a pointer to a miPaintedSet, and (2) a pointer to an miGC. */

/* 1. Drawing functions for points, polylines, and polygons.

   The final three arguments of each are a `coordinate mode' (see below), a
   specified number of points, and an array that contains the points.
   miDrawPoints draws a cloud of points, miDrawLines draws a polyline, and
   miFillPolygon draws a filled polygon. */

/* Possible values for the `coordinate mode' argument (specifying whether
   the points in the points array, after the first point, are given in
   absolute or relative coordinates). */
typedef enum { MI_COORD_MODE_ORIGIN, MI_COORD_MODE_PREVIOUS } miCoordMode;

/* Possible values for the `shape' argument of miFillPolygon().  Two
   possibilities: (1) general (i.e., not necessarily convex, with
   self-intersections allowed), or (2) convex and not self-intersecting.
   Latter case can be drawn more rapidly. */
typedef enum { MI_SHAPE_GENERAL, MI_SHAPE_CONVEX } miPolygonShape;

___BEGIN_DECLS

extern void miDrawPoints (miPaintedSet *paintedSet, const miGC *pGC, miCoordMode mode, int npts, const miPoint *pPts);
extern void miDrawLines (miPaintedSet *paintedSet, const miGC *pGC, miCoordMode mode, int npts, const miPoint *pPts);
extern void miFillPolygon (miPaintedSet *paintedSet, const miGC *pGC, miPolygonShape shape, miCoordMode mode, int npts, const miPoint *pPts);

/* 2. Rectangle-related drawing functions.

   These draw and fill a specified number of rectangles, supplied as an
   array of miRectangles. */

/* Structure that defines a rectangle.  Upper left corner is [x,y] and
   lower right corner is [x+width,y+height]. */
typedef struct
{
  int x, y;			/* upper left corner */
  unsigned int width, height;	/* width >= 1 and height >= 1 */
} miRectangle;

extern void miDrawRectangles (miPaintedSet *paintedSet, const miGC *pGC, int nrects, const miRectangle *pRects);
extern void miFillRectangles (miPaintedSet *paintedSet, const miGC *pGC, int nrects, const miRectangle *pRects);

/* 3. Arc-related drawing functions.

   Each of these takes as argument a multi-arc, i.e. an array of elliptic
   arcs.  Here, an `elliptic arc' is a piece of an ellipse whose axes are
   aligned with the coordinate axes.  The arcs are not required to be
   contiguous.

   miDrawArcs draws a multi-arc.  If the arcs are contiguous, they will be
   joined as specified in the miGC.  Note that miDrawArcs is not reentrant,
   i.e., not thread-safe (for a thread-safe variant, see below).

   miFillArcs draws a sequence of filled arcs.  They are filled either as
   chords or as pie slices, as specified by the graphics context. */

/* Structure that defines an `arc' (i.e. a segment of an ellipse whose
   principal axes are aligned with the coordinate axes).  The upper left
   corner of the bounding box is [x,y], and the lower right corner is
   [x+width,y+height].  By convention, angle1 and angle2 are the starting
   polar angle and angle range that the arc would have if it were scaled
   into a circular arc. */
typedef struct
{
  int x, y;		/* upper left corner of ellipse's bounding box */
  unsigned int width, height;	/* dimensions; width, height >= 1 */
  int angle1, angle2;	/* starting angle and angle range, in 1/64 degrees */
} miArc;

extern void miDrawArcs (miPaintedSet *paintedSet, const miGC *pGC, int narcs, const miArc *parcs);
extern void miFillArcs (miPaintedSet *paintedSet, const miGC *pGC, int narcs, const miArc *parcs);

/* 4. A reentrant (thread-safe) arc-drawing function.  A special function
   is necessary because the normal arc-drawing function miDrawArcs
   maintains an internal, fixed-size cache of rasterized ellipses, one for
   each arc that is drawn.  The presence of this persistent data (internal
   to libxmi) prevents miDrawArcs from being reentrant.  miDrawArcs_r is a
   reentrant substitute.

   The caller of miDrawArcs_r must supply a pointer to an miEllipseCache
   object as the final argument.  A pointer to such an object, which is
   opaque, is returned by miNewEllipseCache.  After zero or more calls to
   miDrawArcs_r, the object may be deleted by calling
   miDeleteEllipseCache. */

typedef struct lib_miEllipseCache miEllipseCache;
extern miEllipseCache * miNewEllipseCache (void);
extern void miDeleteEllipseCache (miEllipseCache *ellipseCache);

extern void miDrawArcs_r (miPaintedSet *paintedSet, const miGC *pGC, int narcs, const miArc *parcs, miEllipseCache *ellipseCache);

___END_DECLS

/***************** LIBXMI's Canvas-Painting ***********************/

/* A miCanvas encapsulates (i) a drawable, which is a miCanvasPixmap, and
   (ii) parameters that specify how pixels should be painted.  By default,
   a miCanvasPixmap is a miPixmap, i.e., basically a 2-D array of miPixels
   (an array of pointers to rows of miPixels).  That is a low-level
   implementation decision that may easily be changed by the libxmi
   installer. */

/* Binary pixel-merging function type.  Such a function maps a source pixel
   and a destination pixel to a new, merged pixel. */
typedef miPixel (*miPixelMerge2) (miPixel source, miPixel destination);

/* Ternary pixel-merging function type.  Such a function maps a texture
   pixel, a source pixel, and a destination pixel, to a new, merged
   pixel. */
typedef miPixel (*miPixelMerge3) (miPixel texture, miPixel source, miPixel destination);

/* Definitions of miBitmap and miPixmap.  By convention, (0,0) is upper
   left hand corner. */
typedef struct
{
  int **bitmap;			/* each element is 0 or 1 */
  unsigned int width;
  unsigned int height;
}
miBitmap;

typedef struct
{
  miPixel **pixmap;		/* each element is a miPixel */
  unsigned int width;
  unsigned int height;
}
miPixmap;

/* Definition of miCanvasPixmap, the datatype of the drawable encapsulated
   within a miCanvas.  By default, a miCanvasPixmap is a miPixmap.  The
   libxmi installer may alter the definition by defining the symbol
   MI_CANVAS_DRAWABLE_TYPE at installation time. */
#ifdef MI_CANVAS_DRAWABLE_TYPE
typedef MI_CANVAS_DRAWABLE_TYPE miCanvasPixmap;
#else
typedef miPixmap miCanvasPixmap;
#endif

/* Definition of the miCanvas structure. */
typedef struct
{
  /* Drawable. */
  miCanvasPixmap *drawable;

  /* A stipple.  (Default is NULL, which means no stipping.  If non-NULL,
     the canvas will be tiled with the stipple, and painting will be
     allowed to take place only at points where the stipple is nonzero.) */
  miBitmap *stipple;
  miPoint stippleOrigin;   /* upper left corner of mask is mapped to this */

  /* A texture.  (Default is NULL, which means no texturing.  If non-NULL,
     the canvas will be tiled with the texture, and painting of a pixel at
     any point will be affected by the value of the texture pixel there.)  */
  miPixmap *texture;
  miPoint textureOrigin;   /* upper left corner of texture is mapped to this */

  /* User-specified binary pixel-merging function, if any.  (Default is
     NULL, which means the Painter's Algorithm is used: source pixel will
     replace destination pixel.) */
  miPixelMerge2 pixelMerge2;

  /* User-specified ternary pixel-merging function, if any.  Used when a
     texture has been specified.  (Default is NULL, which means the
     Painter's Algorithm is used: texture pixel will replace destination
     pixel, and source pixel will be ignored.) */
  miPixelMerge3 pixelMerge3;

} miCanvas;

/* The public function that merges pixels from a miPaintedSet onto a
   miCanvas.  `origin' is the point on the miCanvas to which the point
   (0,0) in the miPaintedSet is mapped.  (It could be called `offset'.) */
extern void miCopyPaintedSetToCanvas (const miPaintedSet *paintedSet, miCanvas *canvas, miPoint origin);

/* If MI_CANVAS_DRAWABLE_TYPE is defined by the libxmi installer (see
   above), then the accessor macros MI_GET_CANVAS_DRAWABLE_PIXEL() and
   MI_SET_CANVAS_DRAWABLE_PIXEL() will also need to be defined.  The
   default accessor macros simply access the 2-D miPixel array within a
   miPixmap.  MI_GET_CANVAS_DRAWABLE_BOUNDS() should be defined too. */
#ifndef MI_GET_CANVAS_DRAWABLE_PIXEL
#define MI_GET_CANVAS_DRAWABLE_PIXEL(pCanvas, x, y, pixel) \
    (pixel) = (pCanvas)->drawable->pixmap[(y)][(x)];
#endif
#ifndef MI_SET_CANVAS_DRAWABLE_PIXEL
#define MI_SET_CANVAS_DRAWABLE_PIXEL(pCanvas, x, y, pixel) \
    (pCanvas)->drawable->pixmap[(y)][(x)] = (pixel);
#endif
#ifndef MI_GET_CANVAS_DRAWABLE_BOUNDS
#define MI_GET_CANVAS_DRAWABLE_BOUNDS(pCanvas, xleft, ytop, xright, ybottom) \
    { (xleft) = 0; (ytop) = 0; \
      (xright) = (pCanvas)->drawable->width - 1; \
      (ybottom) = (pCanvas)->drawable->height - 1; \
    }
#endif

/* Functions that set data elements of a miCanvas. */
extern void miSetCanvasStipple (miCanvas *pCanvas, const miBitmap *pStipple, miPoint stippleOrigin);
extern void miSetCanvasTexture (miCanvas *pCanvas, const miPixmap *pTexture, miPoint textureOrigin);

/* Functions that set the binary and ternary pixel-merging functions to be
   used when pixels from a miPaintedSet are applied to a miCanvas.  The
   defaults are NULL; for the meaning of NULL, see above. */
extern void miSetPixelMerge2 (miCanvas *pCanvas, miPixelMerge2 pixelMerge2);
extern void miSetPixelMerge3 (miCanvas *pCanvas, miPixelMerge3 pixelMerge3);

/* The libxmi installer may request that the default algorithm used when
   applying pixels to a miPaintCanvas be something other than the Painter's
   Algorithm, by defining MI_DEFAULT_MERGE2_PIXEL at installation time. */
#ifndef MI_DEFAULT_MERGE2_PIXEL
/* use painter's algorithm */
#define MI_DEFAULT_MERGE2_PIXEL(new, source, dest) { (new) = (source); }
#endif

/* Likewise, the libxmi installer may request that the default algorithm
   used when applying pixels to a miPaintCanvas, when a texture pixel is
   available, be something other than the `replace canvas pixel by texture
   pixel' algorithm. */
#ifndef MI_DEFAULT_MERGE3_PIXEL
/* use painter's algorithm */
#define MI_DEFAULT_MERGE3_PIXEL(new, texture, source, dest) { (new) = (texture); }
#endif

#ifndef MI_CANVAS_DRAWABLE_TYPE
/* Constructor, destructor, and copy constructor for the miCanvas class.
   These are declared (and defined) only if the libxmi installer doesn't
   redefine the type of the drawable encapsulated within a miCanvas. */
extern miCanvas * miNewCanvas (unsigned int width, unsigned int height, miPixel initPixel);
extern void miDeleteCanvas (miCanvas *pCanvas);
extern miCanvas * miCopyCanvas (const miCanvas *pCanvas);
#endif /* not MI_CANVAS_DRAWABLE_TYPE */

/**********************************************************************/

#endif /* not _XMI_H_ */