1 /* This is xmi.h, the public header file for the machine-independent libxmi 2 rasterization library, which is based on source files in the X Window 3 System distribution. Written by Robert S. Maier. 4 5 The eight painting functions in libxmi's core API, namely 6 7 the 5 drawing functions: 8 miDrawPoints, miDrawLines, miDrawRectangles, miDrawArcs, miDrawArcs_r 9 10 the 3 filling functions: 11 miFillPolygon, miFillRectangles, miFillArcs 12 13 are declared below. The first argument of each of these is a pointer to 14 a miPaintedSet. Conceptually, a miPaintedSet is a set of points with 15 integer coordinates, each of which is painted some color (a miPixel). 16 The coordinates of the points are unconstrained, i.e., the core painting 17 functions perform no clipping. 18 19 Each of the core painting functions takes as second argument a pointer 20 to a graphics context: a miGC. A miGC is an opaque type that contains 21 high-level drawing parameters that determine which points will be added 22 to the miPaintedSet. (For example, the line width, line style, and dash 23 pattern, all of which are relevant to the drawing functions, though not 24 to the filling functions.) It also specifies the colors (miPixels) that 25 will be used when painting the points. The core painting functions use 26 the Painter's Algorithm, so that if a point in an miPaintedSet is 27 painted a second time, the new color will replace the old. 28 29 (By default, the painting performed by the core painting functions, 30 i.e. by both the drawing functions and the filling functions, is 31 `solid', i.e., non-interpolated. In `solid' painting, the color used is 32 taken from the pixel array in the miGC. Any miGC contains an array of 33 pixel colors, of length n>=2. Color #1 is the default color for 34 painting, and colors 0,2,3,..,n-1 are used only by the drawing 35 functions, when drawing in a dashed mode. In normal (on/off) dashing, 36 the colors of the `on' dashes will cycle through 1,2,..,n-1. In 37 so-called double dashing, the `off' dashes will be drawn too, in color #0.) 38 39 After a miPaintedSet is built up by invoking one or more core painting 40 functions, the next stage of the graphics pipeline is performed by 41 calling miCopyPaintedSetToCanvas(). This transfers the pixels in the 42 miPaintedSet onto a canvas structure called a miCanvas, which contains a 43 bounded, fixed-size drawable. In the transfer, more sophisticated 44 algorithms than the Painter's Algorithm may be used. Besides the 45 drawable, a miCanvas may contain additional members, such as a stipple 46 bitmap, a texture pixmap, and binary and ternary pixel-merging 47 functions. These will affect how the pixels from the miPaintedSet are 48 combined with the ones that already exist on the drawable. */ 49 50 #ifndef _XMI_H_ 51 #define _XMI_H_ 1 52 53 /***********************************************************************/ 54 55 /* Version of GNU libxmi which this header file accompanies. This 56 information is included beginning with version 1.2. 57 58 The MI_LIBXMI_VER_STRING macro is compiled into the library, as 59 `mi_libxmi_ver'. The MI_LIBXMI_VER macro is not compiled into it. Both 60 are available to applications that include this header file. */ 61 62 #define MI_LIBXMI_VER_STRING "1.3" 63 #define MI_LIBXMI_VER 130 64 65 extern const char mi_libxmi_ver[8]; /* need room for 99.99aa */ 66 67 /**********************************************************************/ 68 69 /* support C++ */ 70 #ifdef ___BEGIN_DECLS 71 #undef ___BEGIN_DECLS 72 #endif 73 #ifdef ___END_DECLS 74 #undef ___END_DECLS 75 #endif 76 #ifdef __cplusplus 77 # define ___BEGIN_DECLS extern "C" { 78 # define ___END_DECLS } 79 #else 80 # define ___BEGIN_DECLS /* empty */ 81 # define ___END_DECLS /* empty */ 82 #endif 83 84 /**********************************************************************/ 85 86 /* Structure that defines a point with integer coordinates. */ 87 typedef struct 88 { 89 int x, y; /* integer coordinates, y goes downward */ 90 } miPoint; 91 92 /* Definition of miPixel, the pixel value datatype. By default, a miPixel 93 is an unsigned int. The libxmi installer may alter the definition by 94 defining the symbol MI_PIXEL_TYPE at installation time. The macro 95 MI_SAME_PIXEL(), which tests for equality, may need to be redefined too 96 (e.g., if MI_PIXEL_TYPE is a struct or a union). */ 97 #ifdef MI_PIXEL_TYPE 98 typedef MI_PIXEL_TYPE miPixel; 99 #else 100 typedef unsigned int miPixel; 101 #endif 102 #ifndef MI_SAME_PIXEL 103 #define MI_SAME_PIXEL(pixel1,pixel2) \ 104 ((pixel1) == (pixel2)) 105 #endif 106 107 108 /**********************************************************************/ 109 110 /* A miPaintedSet is an opaque structure that contains a set of painted 111 points, i.e., a set of points partitioned according to the pixel color 112 used for painting. When any public drawing function is invoked, a 113 pointer to a miPaintedSet is passed as its first argument. */ 114 typedef struct lib_miPaintedSet miPaintedSet; 115 116 /* Constructor and destructor for the miPaintedSet class. */ 117 extern miPaintedSet * miNewPaintedSet (void); 118 extern void miDeletePaintedSet (miPaintedSet *paintedSet); 119 120 /* A function that clears any miPaintedSet (i.e. makes it the empty set). */ 121 extern void miClearPaintedSet (miPaintedSet *paintedSet); 122 123 /**********************************************************************/ 124 125 /* A miGC is an opaque structure that contains high-level drawing 126 parameters. When any public drawing function is invoked, a pointer to a 127 miGC is passed as its second argument. */ 128 typedef struct lib_miGC miGC; 129 130 /* Constructor, destructor, and copy constructor for the miGC class. */ 131 extern miGC * miNewGC (int npixels, const miPixel *pixels); /* npixels >= 2 */ 132 extern void miDeleteGC (miGC *pGC); 133 extern miGC * miCopyGC (const miGC *pGC); 134 135 /* Values for an miGC's miGCLineStyle attribute (default=MI_LINE_SOLID). */ 136 enum { MI_LINE_SOLID, MI_LINE_ON_OFF_DASH, MI_LINE_DOUBLE_DASH }; 137 138 /* Values for an miGC's miGCJoinStyle attribute (default=MI_JOIN_MITER). */ 139 enum { MI_JOIN_MITER, MI_JOIN_ROUND, MI_JOIN_BEVEL, MI_JOIN_TRIANGULAR }; 140 141 /* Values for an miGC's miGCCapStyle attribute (default=MI_CAP_BUTT). 142 MI_CAP_NOT_LAST is the same as MI_CAP_BUTT except when drawing 143 zero-width (Bresenham) polylines; it causes the final pixel not to be 144 drawn. A polyline drawn in this way is called `continuable'. */ 145 enum { MI_CAP_NOT_LAST, MI_CAP_BUTT, MI_CAP_ROUND, MI_CAP_PROJECTING, MI_CAP_TRIANGULAR }; 146 147 /* Values for an miGC's miGCFillRule attribute (default=MI_EVEN_ODD_RULE). */ 148 enum { MI_EVEN_ODD_RULE, MI_WINDING_RULE }; 149 150 /* Values for an miGC's miGCArcMode attribute (default=MI_ARC_PIE_SLICE). */ 151 enum { MI_ARC_CHORD, MI_ARC_PIE_SLICE }; 152 153 /* Possibilities for the `attribute' argument of miSetGCAttrib. (All the 154 preceding, plus MI_GC_LINE_WIDTH.) */ 155 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; 156 157 /* A function that sets a single integer-valued miGC attribute. `value' 158 must be one of the preceding enum's, except when 159 attribute=MI_GC_LINE_WIDTH, in which case value>=0 is required. */ 160 extern void miSetGCAttrib (miGC *pGC, miGCAttribute attribute, int value); 161 162 /* A function that sets a list of integer-value miGC attributes. */ 163 extern void miSetGCAttribs (miGC *pGC, int nattributes, const miGCAttribute *attributes, const int *values); 164 165 /* Functions that set miGC attributes that are not integer-valued. 166 Note: currently, `offset' must be nonnegative. */ 167 extern void miSetGCDashes (miGC *pGC, int ndashes, const unsigned int *dashes, int offset); 168 extern void miSetGCMiterLimit (miGC *pGC, double miter_limit); 169 extern void miSetGCPixels (miGC *pGC, int npixels, const miPixel *pixels); /* npixels >=2 */ 170 171 /* Additional functions that set miGC attributes: in particular, functions 172 that set the paint style that will be used. Only in the case of `solid' 173 painting (the default) is the above pixel array relevant. */ 174 extern void miSetGCPaintSolid (void); 175 extern void miSetGCPaintInterpParallel (miPoint pts[2], miPixel pixels[2]); 176 extern void miSetGCPaintInterpTriangular (miPoint pts[3], miPixel pixels[3]); 177 extern void miSetGCPaintInterpElliptical (void); 178 179 /*********** DECLARATIONS OF PUBLIC DRAWING FUNCTIONS ******************/ 180 181 /* The semantics of these drawing functions is similar to that of the 182 corresponding X11 drawing functions. Wide polylines (polylines with 183 line width >= 1) are treated as polygons to be rendered by filling. 184 Zero-width polylines are not invisible: instead, they are single-pixel 185 polylines, specially rendered by the Bresenham midpoint line algorithm. 186 187 Also, adjoining polygons (those with an edge in common) are drawn 188 without gaps. To arrange this, the `right' and `bottom' edges of any 189 polygon are not drawn when the polygon is filled. The filling of 190 rectangles is similar. 191 192 Wide arcs and polyarcs are drawn with a circular brush, of diameter 193 equal to the line width. Every brushed pixel is painted. Zero-width 194 arcs and polyarcs are not invisible: instead, they are single-pixel 195 arcs, specially rendered by the Bresenham `midpoint arc' algorithm. */ 196 197 /* For consistency, the first three arguments of each drawing function are 198 (1) a pointer to a miPaintedSet, and (2) a pointer to an miGC. */ 199 200 /* 1. Drawing functions for points, polylines, and polygons. 201 202 The final three arguments of each are a `coordinate mode' (see below), a 203 specified number of points, and an array that contains the points. 204 miDrawPoints draws a cloud of points, miDrawLines draws a polyline, and 205 miFillPolygon draws a filled polygon. */ 206 207 /* Possible values for the `coordinate mode' argument (specifying whether 208 the points in the points array, after the first point, are given in 209 absolute or relative coordinates). */ 210 typedef enum { MI_COORD_MODE_ORIGIN, MI_COORD_MODE_PREVIOUS } miCoordMode; 211 212 /* Possible values for the `shape' argument of miFillPolygon(). Two 213 possibilities: (1) general (i.e., not necessarily convex, with 214 self-intersections allowed), or (2) convex and not self-intersecting. 215 Latter case can be drawn more rapidly. */ 216 typedef enum { MI_SHAPE_GENERAL, MI_SHAPE_CONVEX } miPolygonShape; 217 218 ___BEGIN_DECLS 219 220 extern void miDrawPoints (miPaintedSet *paintedSet, const miGC *pGC, miCoordMode mode, int npts, const miPoint *pPts); 221 extern void miDrawLines (miPaintedSet *paintedSet, const miGC *pGC, miCoordMode mode, int npts, const miPoint *pPts); 222 extern void miFillPolygon (miPaintedSet *paintedSet, const miGC *pGC, miPolygonShape shape, miCoordMode mode, int npts, const miPoint *pPts); 223 224 /* 2. Rectangle-related drawing functions. 225 226 These draw and fill a specified number of rectangles, supplied as an 227 array of miRectangles. */ 228 229 /* Structure that defines a rectangle. Upper left corner is [x,y] and 230 lower right corner is [x+width,y+height]. */ 231 typedef struct 232 { 233 int x, y; /* upper left corner */ 234 unsigned int width, height; /* width >= 1 and height >= 1 */ 235 } miRectangle; 236 237 extern void miDrawRectangles (miPaintedSet *paintedSet, const miGC *pGC, int nrects, const miRectangle *pRects); 238 extern void miFillRectangles (miPaintedSet *paintedSet, const miGC *pGC, int nrects, const miRectangle *pRects); 239 240 /* 3. Arc-related drawing functions. 241 242 Each of these takes as argument a multi-arc, i.e. an array of elliptic 243 arcs. Here, an `elliptic arc' is a piece of an ellipse whose axes are 244 aligned with the coordinate axes. The arcs are not required to be 245 contiguous. 246 247 miDrawArcs draws a multi-arc. If the arcs are contiguous, they will be 248 joined as specified in the miGC. Note that miDrawArcs is not reentrant, 249 i.e., not thread-safe (for a thread-safe variant, see below). 250 251 miFillArcs draws a sequence of filled arcs. They are filled either as 252 chords or as pie slices, as specified by the graphics context. */ 253 254 /* Structure that defines an `arc' (i.e. a segment of an ellipse whose 255 principal axes are aligned with the coordinate axes). The upper left 256 corner of the bounding box is [x,y], and the lower right corner is 257 [x+width,y+height]. By convention, angle1 and angle2 are the starting 258 polar angle and angle range that the arc would have if it were scaled 259 into a circular arc. */ 260 typedef struct 261 { 262 int x, y; /* upper left corner of ellipse's bounding box */ 263 unsigned int width, height; /* dimensions; width, height >= 1 */ 264 int angle1, angle2; /* starting angle and angle range, in 1/64 degrees */ 265 } miArc; 266 267 extern void miDrawArcs (miPaintedSet *paintedSet, const miGC *pGC, int narcs, const miArc *parcs); 268 extern void miFillArcs (miPaintedSet *paintedSet, const miGC *pGC, int narcs, const miArc *parcs); 269 270 /* 4. A reentrant (thread-safe) arc-drawing function. A special function 271 is necessary because the normal arc-drawing function miDrawArcs 272 maintains an internal, fixed-size cache of rasterized ellipses, one for 273 each arc that is drawn. The presence of this persistent data (internal 274 to libxmi) prevents miDrawArcs from being reentrant. miDrawArcs_r is a 275 reentrant substitute. 276 277 The caller of miDrawArcs_r must supply a pointer to an miEllipseCache 278 object as the final argument. A pointer to such an object, which is 279 opaque, is returned by miNewEllipseCache. After zero or more calls to 280 miDrawArcs_r, the object may be deleted by calling 281 miDeleteEllipseCache. */ 282 283 typedef struct lib_miEllipseCache miEllipseCache; 284 extern miEllipseCache * miNewEllipseCache (void); 285 extern void miDeleteEllipseCache (miEllipseCache *ellipseCache); 286 287 extern void miDrawArcs_r (miPaintedSet *paintedSet, const miGC *pGC, int narcs, const miArc *parcs, miEllipseCache *ellipseCache); 288 289 ___END_DECLS 290 291 /***************** LIBXMI's Canvas-Painting ***********************/ 292 293 /* A miCanvas encapsulates (i) a drawable, which is a miCanvasPixmap, and 294 (ii) parameters that specify how pixels should be painted. By default, 295 a miCanvasPixmap is a miPixmap, i.e., basically a 2-D array of miPixels 296 (an array of pointers to rows of miPixels). That is a low-level 297 implementation decision that may easily be changed by the libxmi 298 installer. */ 299 300 /* Binary pixel-merging function type. Such a function maps a source pixel 301 and a destination pixel to a new, merged pixel. */ 302 typedef miPixel (*miPixelMerge2) (miPixel source, miPixel destination); 303 304 /* Ternary pixel-merging function type. Such a function maps a texture 305 pixel, a source pixel, and a destination pixel, to a new, merged 306 pixel. */ 307 typedef miPixel (*miPixelMerge3) (miPixel texture, miPixel source, miPixel destination); 308 309 /* Definitions of miBitmap and miPixmap. By convention, (0,0) is upper 310 left hand corner. */ 311 typedef struct 312 { 313 int **bitmap; /* each element is 0 or 1 */ 314 unsigned int width; 315 unsigned int height; 316 } 317 miBitmap; 318 319 typedef struct 320 { 321 miPixel **pixmap; /* each element is a miPixel */ 322 unsigned int width; 323 unsigned int height; 324 } 325 miPixmap; 326 327 /* Definition of miCanvasPixmap, the datatype of the drawable encapsulated 328 within a miCanvas. By default, a miCanvasPixmap is a miPixmap. The 329 libxmi installer may alter the definition by defining the symbol 330 MI_CANVAS_DRAWABLE_TYPE at installation time. */ 331 #ifdef MI_CANVAS_DRAWABLE_TYPE 332 typedef MI_CANVAS_DRAWABLE_TYPE miCanvasPixmap; 333 #else 334 typedef miPixmap miCanvasPixmap; 335 #endif 336 337 /* Definition of the miCanvas structure. */ 338 typedef struct 339 { 340 /* Drawable. */ 341 miCanvasPixmap *drawable; 342 343 /* A stipple. (Default is NULL, which means no stipping. If non-NULL, 344 the canvas will be tiled with the stipple, and painting will be 345 allowed to take place only at points where the stipple is nonzero.) */ 346 miBitmap *stipple; 347 miPoint stippleOrigin; /* upper left corner of mask is mapped to this */ 348 349 /* A texture. (Default is NULL, which means no texturing. If non-NULL, 350 the canvas will be tiled with the texture, and painting of a pixel at 351 any point will be affected by the value of the texture pixel there.) */ 352 miPixmap *texture; 353 miPoint textureOrigin; /* upper left corner of texture is mapped to this */ 354 355 /* User-specified binary pixel-merging function, if any. (Default is 356 NULL, which means the Painter's Algorithm is used: source pixel will 357 replace destination pixel.) */ 358 miPixelMerge2 pixelMerge2; 359 360 /* User-specified ternary pixel-merging function, if any. Used when a 361 texture has been specified. (Default is NULL, which means the 362 Painter's Algorithm is used: texture pixel will replace destination 363 pixel, and source pixel will be ignored.) */ 364 miPixelMerge3 pixelMerge3; 365 366 } miCanvas; 367 368 /* The public function that merges pixels from a miPaintedSet onto a 369 miCanvas. `origin' is the point on the miCanvas to which the point 370 (0,0) in the miPaintedSet is mapped. (It could be called `offset'.) */ 371 extern void miCopyPaintedSetToCanvas (const miPaintedSet *paintedSet, miCanvas *canvas, miPoint origin); 372 373 /* If MI_CANVAS_DRAWABLE_TYPE is defined by the libxmi installer (see 374 above), then the accessor macros MI_GET_CANVAS_DRAWABLE_PIXEL() and 375 MI_SET_CANVAS_DRAWABLE_PIXEL() will also need to be defined. The 376 default accessor macros simply access the 2-D miPixel array within a 377 miPixmap. MI_GET_CANVAS_DRAWABLE_BOUNDS() should be defined too. */ 378 #ifndef MI_GET_CANVAS_DRAWABLE_PIXEL 379 #define MI_GET_CANVAS_DRAWABLE_PIXEL(pCanvas, x, y, pixel) \ 380 (pixel) = (pCanvas)->drawable->pixmap[(y)][(x)]; 381 #endif 382 #ifndef MI_SET_CANVAS_DRAWABLE_PIXEL 383 #define MI_SET_CANVAS_DRAWABLE_PIXEL(pCanvas, x, y, pixel) \ 384 (pCanvas)->drawable->pixmap[(y)][(x)] = (pixel); 385 #endif 386 #ifndef MI_GET_CANVAS_DRAWABLE_BOUNDS 387 #define MI_GET_CANVAS_DRAWABLE_BOUNDS(pCanvas, xleft, ytop, xright, ybottom) \ 388 { (xleft) = 0; (ytop) = 0; \ 389 (xright) = (pCanvas)->drawable->width - 1; \ 390 (ybottom) = (pCanvas)->drawable->height - 1; \ 391 } 392 #endif 393 394 /* Functions that set data elements of a miCanvas. */ 395 extern void miSetCanvasStipple (miCanvas *pCanvas, const miBitmap *pStipple, miPoint stippleOrigin); 396 extern void miSetCanvasTexture (miCanvas *pCanvas, const miPixmap *pTexture, miPoint textureOrigin); 397 398 /* Functions that set the binary and ternary pixel-merging functions to be 399 used when pixels from a miPaintedSet are applied to a miCanvas. The 400 defaults are NULL; for the meaning of NULL, see above. */ 401 extern void miSetPixelMerge2 (miCanvas *pCanvas, miPixelMerge2 pixelMerge2); 402 extern void miSetPixelMerge3 (miCanvas *pCanvas, miPixelMerge3 pixelMerge3); 403 404 /* The libxmi installer may request that the default algorithm used when 405 applying pixels to a miPaintCanvas be something other than the Painter's 406 Algorithm, by defining MI_DEFAULT_MERGE2_PIXEL at installation time. */ 407 #ifndef MI_DEFAULT_MERGE2_PIXEL 408 /* use painter's algorithm */ 409 #define MI_DEFAULT_MERGE2_PIXEL(new, source, dest) { (new) = (source); } 410 #endif 411 412 /* Likewise, the libxmi installer may request that the default algorithm 413 used when applying pixels to a miPaintCanvas, when a texture pixel is 414 available, be something other than the `replace canvas pixel by texture 415 pixel' algorithm. */ 416 #ifndef MI_DEFAULT_MERGE3_PIXEL 417 /* use painter's algorithm */ 418 #define MI_DEFAULT_MERGE3_PIXEL(new, texture, source, dest) { (new) = (texture); } 419 #endif 420 421 #ifndef MI_CANVAS_DRAWABLE_TYPE 422 /* Constructor, destructor, and copy constructor for the miCanvas class. 423 These are declared (and defined) only if the libxmi installer doesn't 424 redefine the type of the drawable encapsulated within a miCanvas. */ 425 extern miCanvas * miNewCanvas (unsigned int width, unsigned int height, miPixel initPixel); 426 extern void miDeleteCanvas (miCanvas *pCanvas); 427 extern miCanvas * miCopyCanvas (const miCanvas *pCanvas); 428 #endif /* not MI_CANVAS_DRAWABLE_TYPE */ 429 430 /**********************************************************************/ 431 432 #endif /* not _XMI_H_ */ 433