Another part

* Pattern filled graphics primitives

The library also supports a pattern filled version of the basic filled primitives described above. These functions have similar parameter passing conventions as the basic ones with one difference: instead of the color value a pointer to an union of type 'GrPattern' has to be passed to them. The 'GrPattern' union can contain either a bitmap or a pixmap fill pattern. The first integer slot in the union determines which type it is. Bitmap fill patterns are rectangular arrays of bits, each set bit representing the foreground color of the fill operation, and each zero bit representing the background. Both the foreground and background colors can be combined with any of the supported logical operations. Bitmap fill patterns have one restriction: their width must be eight pixels. Pixmap fill patterns are very similar to contexts. The relevant structure declarations (from "grx20.h"):

/* * BITMAP: a mode independent way to specify a fill pattern of two * colors. It is always 8 pixels wide (1 byte per scan line), its * height is user-defined. SET THE TYPE FLAG TO ZERO!!! */ typedef struct _GR_bitmap { int bmp_ispixmap; /* type flag for pattern union */ int bmp_height; /* bitmap height */ char *bmp_data; /* pointer to the bit pattern */ GrColor bmp_fgcolor; /* foreground color for fill */ GrColor bmp_bgcolor; /* background color for fill */ int bmp_memflags; /* set if dynamically allocated */ } GrBitmap;

/* * PIXMAP: a fill pattern stored in a layout identical to the video RAM * for filling using 'bitblt'-s. It is mode dependent, typically one * of the library functions is used to build it. KEEP THE TYPE FLAG * NONZERO!!! */ typedef struct _GR_pixmap { int pxp_ispixmap; /* type flag for pattern union */ int pxp_width; /* pixmap width (in pixels) */ int pxp_height; /* pixmap height (in pixels) */ GrColor pxp_oper; /* bitblt mode (SET, OR, XOR, AND, IMAGE) */ struct _GR_frame pxp_source; /* source context for fill */ } GrPixmap;

/* * Fill pattern union -- can either be a bitmap or a pixmap */ typedef union _GR_pattern { int gp_ispixmap; /* nonzero for pixmaps */ GrBitmap gp_bitmap; /* fill bitmap */ GrPixmap gp_pixmap; /* fill pixmap */ } GrPattern;

This define group (from "grx20.h") help to acces the 'GrPattern0 menbers:

#define gp_bmp_data gp_bitmap.bmp_data #define gp_bmp_height gp_bitmap.bmp_height #define gp_bmp_fgcolor gp_bitmap.bmp_fgcolor #define gp_bmp_bgcolor gp_bitmap.bmp_bgcolor

#define gp_pxp_width gp_pixmap.pxp_width #define gp_pxp_height gp_pixmap.pxp_height #define gp_pxp_oper gp_pixmap.pxp_oper #define gp_pxp_source gp_pixmap.pxp_source

Bitmap patterns can be easily built from initialized character arrays and static structures by the C compiler, thus no special support is included in the library for creating them. The only action required from the application program might be changing the foreground and background colors as needed. Pixmap patterns are more difficult to build as they replicate the layout of the video memory which changes for different video modes. For this reason the library provides three functions to create pixmap patterns in a mode-independent way:

GrPattern *GrBuildPixmap(char *pixels,int w,int h,GrColorTableP colors); GrPattern *GrBuildPixmapFromBits(char *bits,int w,int h, GrColor fgc,GrColor bgc); GrPattern *GrConvertToPixmap(GrContext *src);

'GrBuildPixmap' build a pixmap from a two dimensional ('w' by 'h') array of characters. The elements in this array are used as indices into the color table specified with the argument 'colors'. (This means that pixmaps created this way can use at most 256 colors.) The color table pointer:

typedef GrColor *GrColorTableP;

should point to an array of integers with the first element being the number of colors in the table and the color values themselves starting with the second element. NOTE: any color modifiers (GrXOR, GrOR, GrAND) OR-ed to the elements of the color table are ignored.

The 'GrBuildPixmapFromBits' function builds a pixmap fill pattern from bitmap data. It is useful if the width of the bitmap pattern is not eight as such bitmap patterns can not be used to build a 'GrBitmap' structure.

The 'GrConvertToPixmap' function converts a graphics context to a pixmap fill pattern. It is useful when the pattern can be created with graphics drawing operations. NOTE: the pixmap pattern and the original context share the drawing RAM, thus if the context is redrawn the fill pattern changes as well. Fill patterns which were built by library routines can be destroyed when no longer needed (i.e. the space occupied by them can be freed) by calling:

void GrDestroyPattern(GrPattern *p);

NOTE: when pixmap fill patterns converted from contexts are destroyed, the drawing RAM is not freed. It is freed when the original context is destroyed. Fill patterns built by the application have to be destroyed by the application as well (if this is needed).

The list of supported pattern filled graphics primitives is shown below. These functions are very similar to their solid filled counterparts, only their last argument is different:

void GrPatternFilledPlot(int x,int y,GrPattern *p); void GrPatternFilledLine(int x1,int y1,int x2,int y2,GrPattern *p); void GrPatternFilledBox(int x1,int y1,int x2,int y2,GrPattern *p); void GrPatternFilledCircle(int xc,int yc,int r,GrPattern *p); void GrPatternFilledEllipse(int xc,int yc,int xa,int ya,GrPattern *p); void GrPatternFilledCircleArc(int xc,int yc,int r,int start,int end, int style,GrPattern *p); void GrPatternFilledEllipseArc(int xc,int yc,int xa,int ya,int start,int end, int style,GrPattern *p); void GrPatternFilledConvexPolygon(int numpts,int points[][2],GrPattern *p); void GrPatternFilledPolygon(int numpts,int points[][2],GrPattern *p); void GrPatternFloodFill(int x, int y, GrColor border, GrPattern *p);

Strictly speaking the plot and line functions in the above group are not filled, but they have been included here for convenience.

* Patterned line drawing

The custom line drawing functions introduced above also have a version when the drawn sections can be filled with a (pixmap or bitmap) fill pattern. To achieve this these functions must be passed both a custom line drawing option ('GrLineOption' structure) and a fill pattern ('GrPattern' union). These two have been combined into the 'GrLinePattern' structure:

typedef struct { GrPattern *lnp_pattern; /* fill pattern */ GrLineOption *lnp_option; /* width + dash pattern */ } GrLinePattern;

All patterned line drawing functions take a pointer to this structure as their last argument. The list of available functions:

void GrPatternedLine(int x1,int y1,int x2,int y2,GrLinePattern *lp); void GrPatternedBox(int x1,int y1,int x2,int y2,GrLinePattern *lp); void GrPatternedCircle(int xc,int yc,int r,GrLinePattern *lp); void GrPatternedEllipse(int xc,int yc,int xa,int ya,GrLinePattern *lp); void GrPatternedCircleArc(int xc,int yc,int r,int start,int end, int style,GrLinePattern *lp); void GrPatternedEllipseArc(int xc,int yc,int xa,int ya,int start,int end, int style,GrLinePattern *lp); void GrPatternedPolyLine(int numpts,int points[][2],GrLinePattern *lp); void GrPatternedPolygon(int numpts,int points[][2],GrLinePattern *lp);