Hi, attached the part 3, any comments?
* Graphics primitives
The screen, the current context or the current clip box can be cleared (i.e. set to a desired background color) by using one of the following three functions:
void GrClearScreen(GrColor bg); void GrClearContext(GrColor bg); void GrClearClipBox(GrColor bg);
Thanks to the special 'GrColor' definition, you can do more than simple clear with this functions, by example with:
GrClearScreen( GrWhite()|GrXOR );
the graphics screen is negativized, do it again and the screen is restored.
The following line drawing graphics primitives are supported by the library:
void GrPlot(int x,int y,GrColor c); void GrLine(int x1,int y1,int x2,int y2,GrColor c); void GrHLine(int x1,int x2,int y,GrColor c); void GrVLine(int x,int y1,int y2,GrColor c); void GrBox(int x1,int y1,int x2,int y2,GrColor c); void GrCircle(int xc,int yc,int r,GrColor c); void GrEllipse(int xc,int yc,int xa,int ya,GrColor c); void GrCircleArc(int xc,int yc,int r,int start,int end,int style,GrColor c); void GrEllipseArc(int xc,int yc,int xa,int ya, int start,int end,int style,GrColor c); void GrPolyLine(int numpts,int points[][2],GrColor c); void GrPolygon(int numpts,int points[][2],GrColor c);
All primitives operate on the current graphics context. The last argument of these functions is always the color to use for the drawing. The 'HLine' and 'VLine' primitives are for drawing horizontal and vertical lines. They have been included in the library because they are more efficient than the general line drawing provided by 'GrLine'. The ellipse primitives can only draw ellipses with their major axis parallel with either the X or Y coordinate axis. They take the half X and Y axis length in the 'xa' and 'ya' arguments. The arc (circle and ellipse) drawing functions take the start and end angles in tenths of degrees (i.e. meaningful range: 0 ... 3600). The angles are interpreted counter-clockwise starting from the positive X axis. The style argument can be one of this defines from "grx20.h":
#define GR_ARC_STYLE_OPEN 0 #define GR_ARC_STYLE_CLOSE1 1 #define GR_ARC_STYLE_CLOSE2 2
'GR_ARC_STYLE_OPEN' draws only the arc, 'GR_ARC_STYLE_CLOSE1' closes the arc with a line between his start and end point, 'GR_ARC_STYLE_CLOSE1' draws the typical cake slice. This routine:
void GrLastArcCoords(int *xs,int *ys,int *xe,int *ye,int *xc,int *yc);
can be used to retrieve the start, end, and center points used by the last arc drawing functions.
The polyline and polygon primitives take the address of an n by 2 coordinate array. The X values should be stored in the elements with 0 second index, and the Y values in the elements with a second index value of 1. Coordinate arrays passed to the polygon primitive can either contain or omit the closing edge of the polygon -- the primitive will append it to the list if it is missing.
Because calculating the arc points it's a very time consuming operation, there are two functions to pre-calculate the points, that can be used next with polyline and polygon primitives:
int GrGenerateEllipse(int xc,int yc,int xa,int ya, int points[GR_MAX_ELLIPSE_POINTS][2]); int GrGenerateEllipseArc(int xc,int yc,int xa,int ya,int start,int end, int points[GR_MAX_ELLIPSE_POINTS][2]);
The following filled primitives are available:
void GrFilledBox(int x1,int y1,int x2,int y2,GrColor c); void GrFramedBox(int x1,int y1,int x2,int y2,int wdt,GrFBoxColors *c); void GrFilledCircle(int xc,int yc,int r,GrColor c); void GrFilledEllipse(int xc,int yc,int xa,int ya,GrColor c); void GrFilledCircleArc(int xc,int yc,int r, int start,int end,int style,GrColor c); void GrFilledEllipseArc(int xc,int yc,int xa,int ya, int start,int end,int style,GrColor c); void GrFilledPolygon(int numpts,int points[][2],GrColor c); void GrFilledConvexPolygon(int numpts,int points[][2],GrColor c);
Similarly to the line drawing, all of the above primitives operate on the current graphics context. The 'GrFramedBox' primitive can be used to draw motif-like shaded boxes and "ordinary" framed boxes as well. The 'x1' through 'y2' coordinates specify the interior of the box, the border is outside this area, 'wdt' pixels wide. The primitive uses five different colors for the interior and four borders of the box which are specified in the 'GrFBoxColors' structure:
typedef struct { GrColor fbx_intcolor; GrColor fbx_topcolor; GrColor fbx_rightcolor; GrColor fbx_bottomcolor; GrColor fbx_leftcolor; } GrFBoxColors;
The 'GrFilledConvexPolygon' primitive can be used to fill convex polygons. It can also be used to fill some concave polygons whose boundaries do not intersect any horizontal scan line more than twice. All other concave polygons have to be filled with the (somewhat less efficient) 'GrFilledPolygon' primitive. This primitive can also be used to fill several disjoint nonoverlapping polygons in a single operation.
The function:
void GrFloodFill(int x, int y, GrColor border, GrColor c);
flood-fills the area bounded by the color 'border' using 'x','y' like the starting point.
The current color value of any pixel in the current context can be obtained with:
GrColor GrPixel(int x,int y);
and:
GrColor GrPixelC(GrContext *c,int x,int y);
do the same for any context.
Rectangular areas can be transferred within a context or between contexts by calling:
void GrBitBlt(GrContext *dest,int x,int y,GrContext *source, int x1,int y1,int x2,int y2,GrColor op);
'x','y' is the position in the destination context, and 'x1','y1','x2',y2' the area from the source context to be transfered. The 'op' argument should be one of supported color write modes (GrWRITE, GrXOR, GrOR, GrAND, GrIMAGE), it will control how the pixels from the source context are combined with the pixels in the destination context (the GrIMAGE op must be ored with the color value to be handled as transparent). If either the source or the destination context argument is the NULL pointer then the current context is used for that argument.
* Non-clipping graphics primitives (not recomended to use!)
There is a non-clipping version of some of the elementary primitives. These are somewhat more efficient than the regular versions. These are to be used only in situations when it is absolutely certain that no drawing will be performed beyond the boundaries of the current context. Otherwise the program will almost certainly crash! The reason for including these functions is that they are somewhat more efficient than the regular, clipping versions. ALSO NOTE: These function do not check for conflicts with the mouse cursor. (See the explanation about the mouse cursor handling later in this document.) The list of the supported non-clipping primitives:
void GrPlotNC(int x,int y,GrColor c); void GrLineNC(int x1,int y1,int x2,int y2,GrColor c); void GrHLineNC(int x1,int x2,int y,GrColor c); void GrVLineNC(int x,int y1,int y2,GrColor c); void GrBoxNC(int x1,int y1,int x2,int y2,GrColor c); void GrFilledBoxNC(int x1,int y1,int x2,int y2,GrColor c); void GrFramedBoxNC(int x1,int y1,int x2,int y2,int wdt,GrFBoxColors *c); void GrBitBltNC(GrContext *dst,int x,int y,GrContext *src, int x1,int y1,int x2,int y2,GrColor op); GrColor GrPixelNC(int x,int y); GrColor GrPixelCNC(GrContext *c,int x,int y);
* Customized line drawing
The basic line drawing graphics primitives described previously always draw continuous lines which are one pixel wide. There is another group of line drawing functions which can be used to draw wide and/or patterned lines. These functions have similar parameter passing conventions as the basic ones with one difference: instead of the color value a pointer to a structure of type 'GrLineOption' has to be passed to them. The definition of the 'GrLineOption' structure:
typedef struct { GrColor lno_color; /* color used to draw line */ int lno_width; /* width of the line */ int lno_pattlen; /* length of the dash pattern */ unsigned char *lno_dashpat; /* draw/nodraw pattern */ } GrLineOption;
The 'lno_pattlen' structure element should be equal to the number of alternating draw -- no draw section length values in the array pointed to by the 'lno_dashpat' element. The dash pattern array is assumed to begin with a drawn section. If the pattern length is equal to zero a continuous line is drawn.
Example, a white line 3 bits wide and pattern 6 bits draw, 6 bits nodraw:
unsigned char mydash[2] = { 0xFC,0x00 }; GrLineOption mylineop; ... mylineop.lno_color = GrWhite(); mylineop.lno_width = 3; mylineop.lno_pattlen = 12; mylineop.lno_dashpat = mydash;
The available custom line drawing primitives:
void GrCustomLine(int x1,int y1,int x2,int y2,GrLineOption *o); void GrCustomBox(int x1,int y1,int x2,int y2,GrLineOption *o); void GrCustomCircle(int xc,int yc,int r,GrLineOption *o); void GrCustomEllipse(int xc,int yc,int xa,int ya,GrLineOption *o); void GrCustomCircleArc(int xc,int yc,int r, int start,int end,int style,GrLineOption *o); void GrCustomEllipseArc(int xc,int yc,int xa,int ya, int start,int end,int style,GrLineOption *o); void GrCustomPolyLine(int numpts,int points[][2],GrLineOption *o); void GrCustomPolygon(int numpts,int points[][2],GrLineOption *o);