CLIP-GRAPHICS The Graphics Library for Clipper (tm) S87 and 5.0 by Maurice J. Halmos Version 2.1 March 1991 Serial #2000200 Copyright (c) VideoSoft/Video-Comp Electr. 1988, 1989, 1991 VideoSoft/Video-Comp CLIPGRAF Library 1 INTRODUCTION 1.1 Purpose & Registration The CLIPGRAF library is intended to be a supplement to your Clipper run time library. It contains a collection of graphic mode routines for doing all the low level and higher level graphic tasks, from determining the graphics adaptor, to animation. The library uses direct video rou- tines, for fast performance, hence, it will only work with IBM (tm) compat- ible desktop computers. The library functions have been tested in a number of 8088, 80286, and 80386 clones. It support CGA, EGA, Hercules, and VGA graphics adaptors. This is a shareware program. As such, it may be freely copied and distributed for evaluation. If you would like to use it, you must purchase a license. One license per user is required. The license will allow you to inhibit the copyright notice that you get when you initialize the CLIPGRAF library. Licenses cost $38. Include your name and address along with the ver- sion and serial number above. If you desire the actual disks, include an additional $10 for postage and handling. If you are registering from outside the US, you may send a check in US dollars from a bank that has a US representation, or you may send cash through registered mail. I am not yet able to accept credit cards, sorry. Make checks payable to Maurice J. Halmos. Send to: VideoSoft/Video-Comp Electr. Maurice J. Halmos 15000 Archwood St. Van Nuys, CA 91405 USA Send comments through written mail to the above address or use E-mail to my CompuServe address: 73307,3076 -1- VideoSoft/Video-Comp CLIPGRAF Library 1.2 Disclaimer The author claims no responsibility for any damages caused by the use or misuse of this library. This product is distributed "as is" with no warranty expressed or implied. The author will not be responsible for any losses incurred by the use of this product. The author reserves the right to make modifications at any time. Prices are subject to change without notice. Trademarks. Clipper is a registered trademark of Nantucket. CompuServe is a registered trademark of CompuServe Incorporated. IBM is a registered trademark of International Business Machines. Lotus is a registered trademark of Lotus Development Corporation. Microsoft is a registered trademark of Microsoft Corporation. Turbo C is a registered trademark of Borland International. PCPaintbrush is a registered trademark of Zsoft. -2- VideoSoft/Video-Comp CLIPGRAF Library 2 THE GRAPHICS LIBRARY 2.1 Usage Assuming that you have written a program, such as the sample program included in this package, CLIPDEMO, you must compile and link as follows (which is the usual way): (Compile the usual way,) c:\path1\clipper c:\path2\clipdemo you may use Microsoft Linker Version 5.01 or later or QuickC Linker version 4.06 or later - This is faster than Plink86 c:\path3\link /SE:256 clipdemo,clipdemo,, c:\path1\clipper c:\path1\clip- graf (the /SE switch allows to increase the number of segments used to 256) Turbo C Tlink - does not seem to work with vers. of CLIPGRAF later than 1.2 Clipper's plink86 - slowest c:\path3\plink86 FI clipdemo,LIB c:\path1\clipper, c:\path1\clipgraf or Clipper's new rtlink - same spped as Microsoft link c:\path3\rtlink FI clipdemo,LIB c:\path1\clipper, c:\path1\clipgraf If you use CLIPPER 5.0, make sure you use the appropriate library for version 5.0. There are some minor differences between the two libraries that may make your program hang if you mix them up. I changed the names of the libraries from CLIPGRAF to CGRAF21.lib for clipper S87 and C5GRAF.LIB for clipper 5.0. Hopefully this will help you keep them separated if you are using both version of clipper. -3- VideoSoft/Video-Comp CLIPGRAF Library 2.2 Running the Clipdemo The demonstration program along with this package must be compiled and linked as shown in the previous section. In order to run the program you just type its name, "clipdemo". The program will select the highest reso- lution graphics mode, that has more than 2 colors (i.e. for CGA it will choose 320x200 4 colors). You may override to different graphics mode by calling the program with a "number" parameter (i.e. "clipdemo 6") to try to force that mode. If your computer supports it, then that will be the active mode. See table in section 2.5.2 Notes on Initializing and Modes, for mode numbers. 2.3 What is in the New Version Version 1.1 added: The ability to save images to a CLIPPER variable. The ability to save images directly to disk (one pixel per byte) Mouse interface Version 1.2 added: HERCULES graphics support. The function g_getdot() to read a pixel from the screen. Version 1.2A added: Tried to fix a possible problem, when a filled rectangle was drawn out of the screen area. Version 1.2B added: Four new functions: g_xpos(), g_ypos(), g_col(), g_row(). These are the equivalent of CLIPPERS col() and row(). Changed mailing address. Version 2.0 added: The capability of reading and writing PCX type image files. The PCX format is supported by a number of drawing and painting pack- ages. Also added a slew of functions, that allow the programer to get more information about the video system and mode that the program is running under. For example: g_adapt() to find out the type of display, g_getcolor() to get current drawing color number, -4- VideoSoft/Video-Comp CLIPGRAF Library g_getlogy() to convert from physical coordinates to logical ones g_monitor() to find out the type of monitor being used g_pcx*() a number of functions to obtain information about a PCX file etc... Fixed problem with drawing filled rectangles out of the screen area, using physical or logical coordinates. Version 2.1 added: Split the library into two versions; one for the Summer 87 com- piler, and one for the version 5.0 compiler. In the version for the 5.0 compiler, I had to dissable the "fill" options with circles and pies. Fixed a problem with PCX information gathering functions, g_pcx_xsize, g_pcx_ysize, and g_pcx_planes. Their name has been changed to g_pcx_xs, g_pcx_ys, and g_pcx_pl. Added the function g_sdump() for a screen dump to a printer (due to popular demand). 2.4 Summary of functions The following list contains all the functions that may be used with the CLIPGRAF library. Some of the functions return values, while others only perform tasks. Function Name Purpose Returns g_adapt() Returns the type of video adapter used. g_arc(x1,y1,x2,y2,xb,yb, Draws an open elliptic Nothing xe,ye) arc g_clear(num) clears section of the Nothing screen g_close() return screen to start- Nothing ing or default mode g_cmax() Return the maximum number of text columns in the present video mode. -5- VideoSoft/Video-Comp CLIPGRAF Library g_col() Returns the text column position. g_disppcx(x,y,fname Displays a PCX file with Number of bytes [,n,n,n]) the upper left corner at read. (x,y). g_dot(x,y) sets pixel at x,y coor- Nothing dinates g_draw(x1,y1,IMAGE,action) Displays a rectangular Nothing screen image saved with g_imget(). g_ellip(fill,x1,y1,x2,y2) draw ellipse optionally Nothing filled g_fill(x,y,bcolor) Fill an area of the Nothing screen with the current color and fillmask g_getbkc() In text mode returns the current color from the palette number value. In graphics mode it returns zero. g_getcolor() Returns the current Color number. color number. g_getdot(x,y) Reads a pixel from the Integer repre- screen. senting the pixel color. g_getlstyle() Retrieves the 16 bit Integer mask. mask used to draw straight lines. g_getlogx(x) Convert from physical x logical x coordi- coordinate value to log- nate. ical one. g_getlogy(y) Convert from physical y logical y coordi- coordinate value to log- nate. ical one. g_getphx(x) Convert from logical x physical x coor- coordinate value to dinate. physical one. -6- VideoSoft/Video-Comp CLIPGRAF Library g_getphy(y) Convert from logical y physical y coor- coordinate value to dinate. physical one. g_gettxtclr() Returns the value of the Integer value of current text color. text color. g_imget(x1,y1,x2,y2) Saves rectangular image Up to 64K of in a CLIPPER variable. image data as To be used with TEXT. g_draw(). g_imload(x1,y1,"fname") Displays a rectangular Number of bytes screen image saved with read from disk. g_imsave(). g_imsave(x1,y1,x2,y2,"fname" Saves rectangular image Number of bytes ) to disk. written to disk. g_imsize(x1,y1,x2,y2) Calculates the size in Integer of image bytes of a rectangular size. image. g_init(num) Initializes the graphics False if it routines fails, True if successful g_lineto(x,y) Draw a line in the cur- Nothing rent color and style. g_mode() Returns the mode number g_monitor() Returns the monitor type being used. g_mouse(num) Sets mouse action Nothing g_moveto(x,y) Moves to x,y position Nothing g_msread(num) Reads mouse status Coordinates, but- tons pressed, and status. g_ncolors() Obtains the maxcolors Returns max. num- available in the present ber of colors mode. available. -7- VideoSoft/Video-Comp CLIPGRAF Library g_pcxinfo(fname) Read the PCX header Number of bytes about image information. read. g_pcx_xs() Returns image width in number of pixels. g_pcx_ys() Returns image height in number of lines. g_pcx_ver() Returns PCX version. g_pcx_pl() Returns the number of memory planes that make up the image. g_pcx_bpp() Returns the number of bits per pixel per plane. g_pie(fill,x1,y1,x2,y2, Draw a wedge cut from an Nothing xb,yb,xe,ye) ellipse g_rect(fill,x1,y1,x2,y2) Draw a rectangle Nothing g_reg(num) Register to CLIPGRAF Nothing library g_remapal(num,color) Remap one of the EGA or Nothing VGA colors. g_rmax() Return the maximum number of text rows in the present video mode. g_row() Returns the text row position. g_savpcx(x1,y1,x2,y2,fname) Saves the image bounded Number of bytes by (x1,y1) to (x2,y2) as written. a PCX file. g_say(row,col,text) Puts text at row,col Nothing g_setclipr(x1,y1,x2,y2) Set clipping region for Nothing graphics. g_selpalt(num) Selects CGA color pal- Previous palette ette number g_setapage(num) Select a video page for Previous page current output number. -8- VideoSoft/Video-Comp CLIPGRAF Library g_setbkc(num) Sets background color Nothing g_setclr(num) Sets the foreground Nothing color. g_setfmsk(byte,byte,byte, Sets the fill mask Nothing byte,byte,byte,byte,byte) g_setline(num) Sets line pattern. Nothing g_setorg(x,y) Changes the coordinate Nothing origin. g_settxtc(num) Set text color. Nothing g_setvpage(num) Select a video page for Previous page viewing number. g_sdump(printer, port, res, Will screen dump to the Error status. xm,ym,rv) printer of your choice. 0 is OK, 1 is error occurred. g_twindow(r1,r1,r2,c2) Defines a scrolling text True or False display window g_viewport(x1,y1,x2,y2) Sets up a rectangular True or False region for display g_vmemory() Returns the amount of video memory. g_wait() Waits for a character to The integer cor- be hit. responding to the character. g_wraptxt(flag) Allows text to wrap in Nothing text window. g_xmax() Maximum x pixels g_xpos() Returns the drawing x position. g_ymax() Maximum y pixels g_ypos() Returns the drawing y position. -9- VideoSoft/Video-Comp CLIPGRAF Library 2.5 Functions Description 2.5.1 Notes on Ellipse, Arc, and Pie The specification of the ellipse, arc, and the pie involves the con- cept of the "bounding rectangle," which is the smallest rectangle that completely encloses the figure being drawn. Since the arc and pie are both parts of the ellipse, in all cases you have to specify the bounding rectan- gle of an ellipse. Both the bounding rectangle and the basic rectangle are specified by the logical coordinates of their upper left hand and lower right corners. For the arc as well as the pie, the elliptic segment is drawn as follows. A (imaginary) line is drawn from the center of the ellipse (of which the arc or the pie is a part) to a point specified as the beginning point. The g_pie() and the g_arc() functions begin drawing the curved edge at the point where that line intersects the ellipse. The functions trace over the underlying ellipse, using the current color, in a counter- clockwise direction until reaching the point where an imaginary line drawn from the center to a specified end point cuts the ellipse. Curved lines are always drawn in a solid line style. Thus the ellipse and the pie can only have a solid boundary. They can however be filled in the interior with a user defined pattern. 2.5.2 Notes on Initializing and Modes You need to initialize the graphics driver to operate the graphics functions. The g_init() function does this, and sets up the screen to the highest mode supported by the hardware. You may override the mode selec- tion by including an argument to the function, i.e. g_init(mode_number). To use the HERCULES Graphics mode, you must run the utility HERC.COM before your program in order to set the video vectors. This utility is placed in the public domain by Microsoft and is included in this package. The following modes are supported: Mode # Mode Name 19 VGA 320x200 256 colors 18 VGA 640x480 16 colors 17 VGA 649x480 BW 2 colors 16 EGA 640x350 4 or 16 colors 15 EGA 640x350 BW 2 colors 14 EGA 640x200 16 colors 13 EGA 320x200 16 colors -10- VideoSoft/Video-Comp CLIPGRAF Library 8 Hercules BW 2 colors (Must run HERC.COM before) 7 MDA Text 80x25 BW 6 CGA 640x200 BW 2 colors 5 CGA 320x200 BW 4 grey 4 CGA 320x200 4 colors 3 CGA Text 80x25 16 or 8 colors -1 Default mode for the current hardware configuration. Is used to return to the initial mode, or just to ini- tialize the graphics routine without changing modes in order to read some of the hardware information. The first time you use g_init(), you will get a copyright message, further calls to g_init() (if you want to change the mode for instance) will not re-display this screen. To inhibit the original copyright screen you must use the function g_reg(reg_number), where reg_number is the registration number you get when you become a registered user. 2.5.3 Notes on Color The color number may vary according to the hardware used. The default colors in CGA text mode, EGA text and graphics, or the first 16 VGA text and graphics are list below. In some of the functions, such as remapping the palette, you must select a color value, which is a 3 byte number [blue, green, red], instead of a color number. With a VGA adaptor, you can select each color intensity to be any value between 0 to 63. If you choose a larger value, the func- tion will fail. From the table below, you can see that bright white is all colors at maximum intensity. The color value of bright white is then 63+63*256+63*(256^2) which is R+G+B. Color Palette Number Color Hexadecimal Color value 0 Black 0x000000 1 Blue 0x2a0000 2 Green 0x002a00 3 Cyan 0x2a2a00 4 Red 0x00002a 5 Magenta 0x2a002a 6 Brown 0x00152a 7 White 0x2a2a2a 8 Dark grey 0x151515 9 Light blue 0x3f1515 10 Light green 0x153f15 11 Light cyan 0x3f3f15 12 Light red 0x15153f -11- VideoSoft/Video-Comp CLIPGRAF Library 13 Light magenta 0x3f153f 14 Yellow 0x153f3f 15 Bright white 0x3f3f3f 2.5.4 Notes in Fill Pattern The fill pattern is specified by the argument in g_setfmsk(), which is made up of eight integers corresponding to eight bytes. Since each charac- ter has 8 bits, you can think of this array of bits as a model of an area on the screen, 8 pixels wide and 8 pixels tall, with the first byte representing the first row of the area. When filling an 8x8 area using the mask, those pixels that correspond to 0 bits are left untouched while the rest are filled with the current color. For areas larger than 8x8 pixels, the fill operation uses the mask on successive 8x8 blocks until the entire area is covered. Thus a solid fill is specified when all eight bytes contain the value FFh (255 decimal). This is the default value of the fill style in the graphics package. See demo program for further examples. 2.5.5 Notes on Raster Image Save and Load There are three basic ways of saving and loading images. 1. To and from a CLIPPER memory variable using the g_imget() and g_draw() function pairs, and g_imsize() to check for size, and 2. To and from a disk file using g_imsave() and g_imload(). 3. To and from disk using the PCX utilities. The image saved is of the same format as with the first method, except that it is compressed using an RLE technique. Real scanned photographs don't compress very much, but uniform color pictures (such as the ones created on a computer) may compress as much as 80%. Using the first method you must check to make sure you have enough RAM memory, and for the second method, enough disk space. Using the first method has the advantage of being able to "pop" the image on the screen rather quickly. You can also save the CLIPPER variable to disk. The drawback, is that you can only do this in 64K chunks. The disk method allows you to save a full high resolution screen to disk in one command, but is slower. The coding of the image is different for the two methods, and cannot be interchanged. The disk method uses one byte per pixel; for a high res VGA mode, this equals 640x480 = 307K bytes! Using this scheme, allows images saved in one mode to be showed in a different one (i.e. CGA to EGA or vice versa). -12- VideoSoft/Video-Comp CLIPGRAF Library Using the RAM memory method the minimum amount of bytes is used. For instance, one pixel in high res VGA or EGA (16 colors) requires only half a byte. Images may be switched from one mode to another, only if the pixels use the same number of bits. Otherwise, on gets garbage on the screen. The following table shows some of the full screen sizes in bytes: Mode Res. Colors Size 4 & 5 320x200 4 16,285 6 640x200 2 16,285 13 320x200 16 32,968 14 640x200 16 65,128 15 640x350 2 56,866 16 640x350 16 113,728 17 640x480 2 38,965 18 640x480 16 155,848 19 320x200 256 64,525 This table should give you an idea of the size of screen that can be saved to memory. Pixel action: OR, AND, RESET, SET XOR: When you use g_draw(), you can specify the pixel action. To put a pixel on the screen regardless of what is currently there, you should use SET. To make an image disappear you should XOR it with itself. 2.5.6 Notes on PCX Images Save and Load PCX Image file format was first developed by Zsoft, in the drawing package PC Paintbrush. This format has become popular, and is now sup- ported by a number of commercial drawing packages and also image capture software. The CLIPGRAF PCX functions open the doors to CLIPPER all the drawing and scanning software packages available. You will be able to read information about a PCX image file, display an image, and save an image. One possibility is to use a drawing or image scanning program to create an opening logo, save it with a PCX format, and then use it as the opening screen of your CLIPPER program. Another possibility is to include the images as part of a data base. Keep the image name in the regular field, and load it automatically when displaying the record. -13- VideoSoft/Video-Comp CLIPGRAF Library The image file is made up of three main parts: (1) The header made up of 128 bytes, (2) the image, and (3) an optional 256x3 byte array of the image color map. The image is compressed using an RLE method, where con- secutive repeating bytes are compressed as two, the repetition number and the data byte. Once decompressed, the image is in the native format of the particular video mode. For instance, lowres CGA is 1 plane, 2 consecutive bits per pixel, EGA and VGA are one consecutive bit per pixel, but 1 or 2 or 4 color planes, MCGA is one color plane, but 8 consecutive bits per pixel (256 colors). From the file header one may determined if a color palette map exists, and you may decide whether you want to remap the pal- ette or not. The remapping is most meaningful when working with a VGA or better type system, with EGA all you can do is rotate the existing 16 colors. When reading an unknown PCX file you have to determine which mode will display the image correctly, and also if that video mode is available in the current hardware. To determine the image natural video mode, you can read the image header to obtain the bits_per_pixel per plane using the function g_pcx_bpp(), and the number of planes using g_pcx_pl(). Then match the information to the following table: Mode Bits/pixel/plane # of planes CGA (4,5) 2 1 CGA (6) 1 1 Hercules 1 1 EGA/VGA (15-18) 1 1 to 4 MCGA (19) 8 1 For more detailed information, refer to any documentation on the graphics display for the IBM. If you are running with a VGA display, where most video modes are available, you have the option of letting the function g_disppcx() to auto- matically choose and switch to the video mode that it deems most adequate, without checking if that mode is available. This is done by including the flag argument as 1 (see function description). The default is not to switch automatically because in most uses, you would work with PCX files that you already know about, and you already have a combination of other graphics elements (all of which would get cleared and reset when you switch graphics modes). -14- VideoSoft/Video-Comp CLIPGRAF Library As with the g_draw() function, when you display a PCX image, you have the option to SET, AND, OR, XOR the pixels. SET will draw the image inde- pendent of background, and the other modes will perform and operation with the existing bits. For instance, if you want to erase an image, but not the changes done to it, repaint the original on top pf the modified one using the XOR option. If you don't include the ACTION parameter, the default is to use SET, which draws the image on top of any background pixels. When calling the PCX display function, you also have the option of letting the function to remap the whole palette (256 colors in MCGA), before displaying the image. This is also done by including a flag argu- ment (1 for remap, anything else no_remap). The default is no_remap because remapping will affect all your color scheme, and may change your colors to something not desirable (i.e. black on black). Finally, if you try to display a picture past the end of the screen (in the horizontal direction), the display function will crop the image in a very crude way. Without getting into details, this cropping does not work well with multiplane images but does make some interest effects. I strongly recommend that you experiment with different PCX images and the different options. I tried to include most of the useful functionality that a CLIPPER programmer might desire, and then some more. 2.5.7 Notes on Using the Mouse. The mouse interface is handled by a two function combination, g_mou- se() and g_msread(). The first function, g_mouse() causes an action, and the second function is used to read the status. This is done by reading the 4 registers (AX BX CX DX) using the appropriate argument 1 to 4. The following table shows the actions and results: g_mouse() g_msread() Return Value of Purpose num num g_msread(num) 0 1 1 Mouse installed Reset mouse and return 0 Mouse not installed status and number of but- tons 2 Number of buttons 1 Make mouse cursor visible 2 Hide mouse cursor 3 2 0 no button pressed Return button status and 1 left button pressed mouse position. 2 right button pressed 3 both buttons pressed 3 y coordinate -15- VideoSoft/Video-Comp CLIPGRAF Library 4 x coordinate The coordinates are in units of "mickeys". These are 0-639 across, and 0-ymax in the vertical, where ymax is the maximum number of pixels in the vertical. The mouse routines use the standard bios interrupt calls related to the mouse driver. I have found that the effects are not always as expected, and they may vary from one screen mode to another. You can test this with the clipdemo program accompanying this package. 2.5.8 Functions FUNCTION: g_adapt() Purpose: Returns the video adapter in use. Returns: the following numbers; 1-MDPA, 2-CGA, 4-EGA, 8-VGA, 10-MCGA, 20-Hercules. FUNCTION: g_arc(x1,y1,x2,y2,xb,yb,xe,ye) Purpose: Use g_arc to draw a segment of an ellipse using the current color. Arguments: x1,y1 Coordinates of upper left corner of bounding rectangle of the ellipse to which the arc belongs. x2,y2 Coordinates of lower right corner of bounding rectangle of the ellipse to which the arc belongs. xb,yb Arc begins at the point where a line drawn from the center of the bounding rectangle to (xb,yb) cuts the ellipse. xe,ye Arc ends at the point where a line drawn from the center of the bounding rectangle to (xe,ye) cuts the ellipse. FUNCTION: g_clear(num) Purpose: Clear an area of the screen and fill it with the current background color. -16- VideoSoft/Video-Comp CLIPGRAF Library Arguments: 0 Entire screen is cleared 1 Only current viewport is cleared 2 Only current text window is cleared FUNCTION: g_close() Purpose: Resets the screen to the mode it was before g_init() was invoked. FUNCTION: g_cmax() Purpose: To obtain the maximum number of columns in the current video mode. Returns: Integer corresponding to the number of columns. FUNCTION: g_col() Returns: Integer corresponding to the text column position. FUNCTION: g_disppcx(x,y,fname [,action,fm,fp]) Purpose: Display a PCX image file, with name "fname" with the upper left corner at the (x,y) real coordinates. Optional parame- ters are -fp- as 1 to remap the palette according to the image information, -fm- as 1 to determine and switch to the appropriate image mode, and -action- to determine the pixel operation to the background pixels. Arguments: x,y Coordinates of upper left corner of bounding rectangle of the image. fnamePCX file name such as "myfile.pcx" Optional Arguments: action Select pixel action, set, reset, and, or, xor. Default is set. The number values are 0 - for OR, 1 - for AND, 2 - for RESET, 3 - for SET, and 4 - for XOR. Reset will invert the pixel color. For instance, if you display a black and white picture, by using the RESET action you can display it as a negative. -17- VideoSoft/Video-Comp CLIPGRAF Library fm if 1 then function will automatically switch video mode before displaying the image. Default is 0. fp if 1 then the palette will be remapped. Default is 0. Returns: The number of bytes read. You may use this to catch errors. FUNCTION: g_dot(x,y) Purpose: Set a specific pixel to the current color Arguments: x,y is the current coordinate system FUNCTION: g_draw(x1,y1,IMAGE,action) Purpose: The function is used to draw a rectangular image, that was saved to a CLIPPER variable by g_imget(). Arguments: The rectangle coordinates, top left corner is (x1,y1), IMAGE is the CLIPPER text variable created with g_imget(), and action is a number that specifies the pixel action to be used. These may be, 0 - for OR, 1 - for AND, 2 - for RESET, 3 - for SET, and 4 - for XOR. FUNCTION: g_ellip(fill,x1,y1,x2,y2) Purpose: Draw a filled or bordered ellipse that you specify by the corners of the bounding rectangle. With CLIPPER 5.0, only the bordered figure will be drawn. Arguments: fill 0 do not fill, i.e. bordered only 1 fill with the current fillmask. With CLIPPER 5.0, this flag will be ignored. x1,y1 Coordinates of upper left corner of bounding rectangle of the ellipse to which the arc belongs. x2,y2 Coordinates of lower right corner of bounding rectangle of the ellipse to which the arc belongs. -18- VideoSoft/Video-Comp CLIPGRAF Library FUNCTION: g_fill(x,y,bcolor) Purpose: Fill an area of the screen with the current color using the current fillmask. Function is ignored with the CLIPPER 5.0 compiler. arguments: x,y position of starting point bcolor Color number of the boundary at which filling should stop FUNCTION: g_getbkc(num) Purpose: Returns the current text mode background color value. Returns: New palette number for the background color when in text mode. Otherwise it returns zero. FUNCTION: g_getcolor() Returns: The current drawing color palette number. FUNCTION: g_getdot(x,y) Returns: Returns the pixel at coordinate (x,y) color palette number. If the coordinate is outside the drawing area, then returns a -1. FUNCTION: g_getlstyle() Returns: Integer representing the 16 bit pattern of the current line style. FUNCTION: g_getlogx(x) Purpose: To obtain the logical or relative x coordinate value given physical x value. FUNCTION: g_getlogy(y) Purpose: To obtain the logical or relative y coordinate value given physical y value. FUNCTION: g_getphx(x) Purpose: To obtain the physical x coordinate given the logical or relative x coordinate. -19- VideoSoft/Video-Comp CLIPGRAF Library FUNCTION: g_getphy(y) Purpose: To obtain the physical y coordinate given the logical or relative y coordinate. FUNCTION: g_gettxtclr() Returns: The integer value of the current text color palette number FUNCTION: g_imget(x1,y1,x2,y2) Purpose: The function is used to save a rectangular screen image into a CLIPPER text variable. The CLIPPER variable may then be treated as any other. Arguments: The rectangle coordinates, top left corner is (x1,y1) and lower right corner (x2,y2). Returns: Character string up to 64K long. Size may be checked before operation, using g_imsize(). See "Notes on Raster Image Save and Load" section. FUNCTION: g_imload(x1,y1,"fname") Purpose: The function is used to load a rectangular screen image from disk. This image file must have been created with g_imsave(). Arguments: The rectangle coordinates top left corner is (x1,y1). "fname" is the file name to be used. Returns: Integer of the number of bytes loaded. If there was a problem opening file (i.e. not found), then it returns a -1. See "2.5.5" section. FUNCTION: g_imsave(x1,y1,x2,y2,"fname") Purpose: The function is used to save a rectangular screen image to disk. This image may be reloaded with g_imload(). Arguments: The rectangle coordinates, top left corner is (x1,y1) and lower right corner (x2,y2). "fname" is the file name to be used. If the file-name already exist, it is written over. -20- VideoSoft/Video-Comp CLIPGRAF Library Returns: Integer of the number of bytes written. See "2.5.5" section. FUNCTION: g_imsize(x1,y1,x2,y2) Purpose: The function is used to obtain the size of rectangular screen image. This is used to determine if there is enough RAM memory to hold the image. Arguments: The rectangle coordinates, top left corner is (x1,y1) and lower right corner (x2,y2). Returns: Integer value of the number of bytes, that would be require to hold the image. See "2.5.5" section. FUNCTION: g_init(num) Purpose: The g_init() function has two purposes: It sets which video mode to use for the graphics and gets the data for that mode and stores it to a data structure for program access. (i.e. g_mode(), g_xmax(), g_ymax(), g_ncolors()) Arguments: mode Optional mode number. If no argument is used, the highest possible one is selected. If mode number used is not supported by the hardware, then again the high- est possible one is selected. Returns: Logical TRUE if successful, FALSE is no mode was found. FUNCTION: g_lineto(x,y) Purpose: Draw a line from the current position to a new point using the current color and line style Arguments: x,y Coordinate point to which line is drawn FUNCTION: g_mode() Purpose: Retrieves the current video mode Returns: The mode number (see "Notes on Initializing and Modes" section) -21- VideoSoft/Video-Comp CLIPGRAF Library FUNCTION: g_monitor() Returns: Integer representing the monitor. The are; 1 for MONO, 2 for COLOR or enhanced in CGA mode, 4 for Enhanced color monitor, and 18 for analog monitor. FUNCTION: g_mouse(num) Purpose: Reset and activate mouse functions Parameters: Number specifying the mouse actions (see "Notes on Using the Mouse." section) Returns: Nothing FUNCTION: g_moveto(x,y) Purpose: Change the current position to a new point. Arguments: x,y Coordinate of new position. FUNCTION: g_msread(num) Purpose: Read the results of g_mouse(). This includes mouse status, position, and buttons pressed Parameters: Number specifying the mouse parameter to be read (see "2.5.7" section) Returns: Number corresponding to status, number of buttons, position. FUNCTION: g_ncolors() Purpose: Retrieves the maximum number of colors supported by the current video mode Returns: The color number (see "Notes on Color" section) FUNCTION: g_pcxinfo(fname) Purpose: To read the PCX file header and obtain the information that can be retrieve with the g_pcx_XXX() functions. Must use before the information retrieval functions. Argument: File name string. -22- VideoSoft/Video-Comp CLIPGRAF Library Returns: 0 if called in with error, -1 if unable to open file, or the number of bytes read (128). FUNCTION: g_pcx_xs() Returns: The pixel width of the file read by g_pcxinfo(), or of the image just displayed, or the image just saved. FUNCTION: g_pcx_ys() Returns: The pixel height of the file read by g_pcxinfo(), or of the image just displayed, or the image just saved. FUNCTION: g_pcx_ver() Returns: The PCX version number of the file read by g_pcxinfo(), or of the image just displayed, or the image just saved. The num- bers are as follows: 2 - old PCX no palette 3 - no palette info 4 - old Microsoft windows - no palette (new windows uses 3 or 5) 5 - with palette FUNCTION: g_pcx_pl() Returns: The number of image planes of the file read by g_pcxinfo(), or of the image just displayed, or the image just saved. See notes for explanation of planes. FUNCTION: g_pcx_bpp() Returns: The bits_per_pixel_per_plane of the file read by g_pcxin- fo(), or of the image just displayed, or the image just saved. See motes for more information. FUNCTION: g_pie(fill,x1,y1,x2,y2,xb,yb,xe,ye) Purpose: Draws a filled or bordered wedge whose boundary consists of a segment of an ellipse and lines joining the center of the ellipse to the beginning and end points of the segment. With CLIPPER 5.0, only the bordered figure will be drawn. Arguments: -23- VideoSoft/Video-Comp CLIPGRAF Library fill Number that indicates whether to fill (fill=1), or just draw a border (fill=0). With Clipper 5.0 this argument is ignored (but needed for compatibility with S87) and is taken as 0. x1,y1 Coordinates of upper left corner of bounding rectangle of the ellipse to which the pie belongs. x2,y2 Coordinates of lower right corner of bounding rectangle of the ellipse to which the pie belongs. xb,yb Pie begins at the point where a line drawn from the center of the bounding rectangle to (xb,yb) cuts the ellipse. xe,ye Pie ends at the point where a line drawn from the center of the bounding rectangle to (xe,ye) cuts the ellipse. FUNCTION: g_rect(fill,x1,y1,x2,y2) Purpose: Draw a filled or bordered rectangle that you specify by the corners. Arguments: fill 0 do not fill, i.e. bordered only 1 fill with the current fillmask. x1,y1 Coordinates of upper left corner. x2,y2 Coordinates of lower right corner. FUNCTION: g_reg(num) Purpose: To inhibit the copyright screen that is shown the first time that g_init() is used. Arguments: Registration number that is supplied when you register. FUNCTION: g_remapal(num,color) Purpose: Use in EGA or VGA environment to redefine how a specific value contained in a pixel is associated with a color displayed on the screen. Thus this function redefines a single color value in EGA or VGA palette. For example, since a color pixel value of -24- VideoSoft/Video-Comp CLIPGRAF Library 0 always signifies background, you can change the background color by redefining the color number 0. See notes on color values. Arguments: num, is the palette number or color number to change color, is the new color value. See notes for explanation about color values. Returns nothing. FUNCTION: g_rmax() Purpose: To obtain the maximum number of rows in the current video mode. Returns: Integer corresponding to the number of rows. FUNCTION: g_row() Returns: Integer corresponding to the text row position. FUNCTION: g_savpcx(x1,y1,x2,y2,"fname") Purpose: The function is used to save a rectangular screen image to disk using the PCX compression. Arguments: The rectangle coordinates, top left corner is (x1,y1) and lower right corner (x2,y2). "fname" is the file name to be used. If the file-name already exist, it is written over. Returns: Integer of the number of bytes written, or 0 if wrong arguments are used, or -1 if an error occurred opening the file. FUNCTION: g_say(row,col,text) Purpose: Puts text in the screen using the current text color. Similar to the "@row,col say 'TEXT'" command. Arguments: row,col is the text coordinates (i.e. 80x25) text is a string to be output. -25- VideoSoft/Video-Comp CLIPGRAF Library FUNCTION: g_sdump(printer, port, res,xm,ym,rv) Purpose: Starts a printer dump of the active CRT image. The screen dum routine can magnify but not improve the resolution of the CRT image. Arguments: Printer: enter a number in the range 0 to 5 where: 0 = Epson MX driver (use for all Epson MX emultors includ- ing Okidata, IBM Proprinter, IBM Graphics printer, Star, Gemini, etc.) 1 = Epson LQ driver (use with Epson 24 pin printers and emulators of the graphics protocol, including Star Gemini 24 pin printers and Panasonic 24 pin printers.) 2 = Toshiba P driver for Toshiba 24 pin printers. 3 = HP Laser Jet driver. Includes all Laser Jets and the HP Desk Jet. 4 = HP Think Jet driver. 5 = Epson FX driver. Port: 0 = LPT1, 1 = LPT2 res: each of the printer drivers supports different resolution print modes. Specify which print mode you wish to use according to the following table: EPSON MX, FX driver 0 = single density normal speed 1 = double density half speed 2 = double density normal speed 3 = quadruple density 4 to 7 = same as 0 to 3 but landscape mode. EPSON LQ driver 0 = single density normal speed 8 pin mode 1 = double density half speed 8 pin mode 2 = double density normal speed 8 pin mode 3 = quadruple density 8 pin mode 4 = standard density 24 pin mode -26- VideoSoft/Video-Comp CLIPGRAF Library 5 = double density 24 pin mode 6 = CRT III 24 pin mode 7 = triple density 24 pin mode 8 = hex density 24 pin mode Toshiba P driver 0 = 180x180 dot image transfer 1 = 180x360 dot image transfer HP Laser Jet driver 0 = 75 dots/inch 1 = 100 dots/inch 2 = 150 dots/inch 3 = 300 dots/inch HP Think Jet Driver 0 = 640 dots 1 = 1280 dots xm: Integer which holds the x multiplier for the dot width, must be >= 1. The CRT image is magnified in the horizon- tal dimension by the xm multiplier when output to the printer. ym: Integer which holds the y multiplier for the dot width, must be >= 1. The CRT image is magnified in the vertical dimension by the ym multiplier when output to the printer. rv: Reverse color. A 0 will cause all CRT colors > 0 to print out as a black dot on the printer. A 1 will create a reverse video white on black image where all CRT colors > 0 will print out as white on the printer and a CRT color 0 will print as black. RETURNS: 0 if everything went OK, 1 if an error occurred. Special Considerations: Because the two color scheme, graphs and charts will look good printed, however, a PCX image will prob- ably be all black or all white, unless only 2 colors are used 0 and another. Returns: -27- VideoSoft/Video-Comp CLIPGRAF Library FUNCTION: g_setclipr(x1,y1,x2,y2) Purpose: Define a rectangular region of the screen as the clipping region for graphics (i.e., any graphics falling outside this region will be cut off). Arguments: (x1,y1) is the upper left corner of clipping region in absolute or physical coordinates, and (x2,y2) is the lower right corner of the clipping region also in absolute coordinates. Returns nothing. FUNCTION: g_selpalt(num) Purpose: Use this function to activate one of up to four predefined palettes when using the CGA or the EGA in video mode 4 (320x200 4 color) or video mode 5 (320x200 4 grey). Arguments: num is palette number being selected. Returns: the previous palette number. FUNCTION: g_setapage(num) Purpose: Use this function in EGA or VGA graphics modes and in the text modes to select the current page or portion of display memory where graphics and text operations are performed. This function only works when the adapter has enough video memory to support multiple pages. Arguments: num is page number to be used for all further text and graphics operations. Returns: the previous active page number or a negative value if it fails. FUNCTION: g_setbkc(num) Purpose: Selects a new background color. In graphics mode the change is visible immediately. In text mode it is necessary to clear the screen to see the new background color. In text modes, the back- ground color specified by a number from the current palette. In EGA, for example, color number 4 in the default palette is red. -28- VideoSoft/Video-Comp CLIPGRAF Library Argument: In text mode, the new color palette number. In graphics mode, the new color value (see notes on color). Returns nothing. FUNCTION: g_setclr(num) Purpose: Selects a new color palette number to be used by all future calls to drawing functions. Until a color has been set, the drawing routines use the highest color number in the palette. Argument: New color value Returns nothing. FUNCTION: g_setfmsk(byte,byte,byte,byte,byte,byte,byte,byte) Purpose: Defines a new pattern that will be used as a fill in func- tions like g_rect(), g_pie(), and g_ellip(). Arguments: Eight integer from values 0 to 255 (see section Notes in Fill Pattern). FUNCTION: g_setline(num) Purpose: Selects a line pattern Argument: Number 0 to 15 where 0 is minimum number of dots to 15 a solid line. Numbers larger than 15 will generate a random pattern. FUNCTION: g_setorg(x,y) Purpose: Use to change the origin of the x,y coordinates. The default origin is the upper left corner of the screen. Usage of this function creates two sets of coordinates, the absolute or physical one which is the original default and remains unchanged, and the logical or relative one. Arguments: x,y coordinate for new origin. -29- VideoSoft/Video-Comp CLIPGRAF Library FUNCTION: g_settxtc(num) Purpose: Selects a new color to be used by all future text output using the g_say() function. The first 16 colors are use (0 to 15) and (16 to 31) produce the first fifteen colors but blinking. Argument: New color value 0 to 31. FUNCTION: g_setvpage(num) Purpose: Use this function in EGA or VGA graphics modes and in the text modes to select the current page or portion of display memory that is mapped to the screen. This function only works when the adapter has enough video memory to support multiple pages. Arguments: num is page number to be displayed. Returns: the previous visual page number or a negative value if it fails. FUNCTION: g_twindow(r1,c1,r2,c2) Purpose: Defines a window in terms of row and column coordinate for scrolled text output. You can define a new background color for text and clear the text window to give it a different background color from the rest. Similar windows for graphics functions can be defined with g_viewport(). Arguments: r1,c1 Upper left corner of text window in row and column coordinate. r2,c2 Lower right corner of text window in row and column coordinate. Returns: logical TRUE or FALSE FUNCTION: g_viewport(x1,y1,x2,y2) Purpose: Defines a window for graphics output, the coordinate origin is moved to the upper left corner of the viewport. Arguments: x1,y1 Upper left corner of graphics window x2,y2 Lower right corner of graphics window Returns: logical TRUE or FALSE -30- VideoSoft/Video-Comp CLIPGRAF Library FUNCTION: g_video memory() Purpose: To find out the amount of video memory. Returns: Integer with the amount of video memory in Kbytes. FUNCTION: g_wait() Purpose: To wait until a character has been typed. Similar to Clipper's wait command, but Clipper's command disrupts the graphics screen when in CGA mode. Returns: Integer number corresponding to the character pressed. FUNCTION: g_wraptxt(flag) Purpose: Allows text to wrap on text window. Arguments: flag is 0 -> do not wrap, 1 -> do wrap. FUNCTION: g_xmax() Purpose: To obtain the maximum number of horizontal pixels in the current video mode. Returns: Integer corresponding to the horizontal pixel number. FUNCTION: g_xpos() Returns: Integer corresponding to the drawing logical or relative x position. FUNCTION: g_ymax() Purpose: To obtain the maximum number of vertical pixels in the current video mode. Returns: Integer corresponding to the vertical pixel number. FUNCTION: g_ypos() Returns: Integer corresponding to the drawing logical or relative y position. -31- VideoSoft/Video-Comp CLIPGRAF Library 3 ORDER FORM TO: Maurice J. Halmos Video-Comp Electronics 15000 Archwood St. Van Nuys, CA 91405-4550 U.S.A. (818)988-9848 CompuServe #: 73307,3076 From: Full Name: ____________________________________ Company Name (if any): ____________________________________ Street Address: ____________________________________ City, Sate, Zip: ____________________________________ Country: ____________________________________ Phone(s): ____________________________________ CompuServe #: ____________________________________ Desired Registration & Disks: CLIPGRAF ver 2.1 Registration only: $38 x Qty____ = $_____ CLIPMATH ver 1.0 Registration only: $15 x Qty____ = $_____ ($10 only if with CLIPGRAF) CLIPGRAF & CLIPMATH Disk (1 for both) $10 $_____ (Postage & Handling) --------------------------- TOTAL Enclosed: $_____ When you register, I will send you your registration number to use in your program to inhibit the copyright notice. This will be a simple one sheet letter. If you require the disks sent to you, there is an additional $10 charge for postage, handling and material. -32- VideoSoft/Video-Comp CLIPGRAF Library Table of Contents 1 INTRODUCTION .................................................... 1 1.1 Purpose & Registration ..................................... 1 1.2 Disclaimer ................................................. 2 2 THE GRAPHICS LIBRARY ............................................ 3 2.1 Usage ...................................................... 3 2.2 Running the Clipdemo ....................................... 4 2.3 What is in the New Version ................................. 4 2.4 Summary of functions ....................................... 5 2.5 Functions Description ..................................... 10 2.5.1 Notes on Ellipse, Arc, and Pie ........................ 10 2.5.2 Notes on Initializing and Modes ....................... 10 2.5.3 Notes on Color ........................................ 11 2.5.4 Notes in Fill Pattern ................................. 12 2.5.5 Notes on Raster Image Save and Load ................... 12 2.5.6 Notes on PCX Images Save and Load ..................... 13 2.5.7 Notes on Using the Mouse. ............................. 15 2.5.8 Functions ............................................. 16 FUNCTION: g_adapt() ...................................... 16 FUNCTION: g_arc(x1,y1,x2,y2,xb,yb,xe,ye) ................. 16 FUNCTION: g_clear(num) ................................... 16 FUNCTION: g_close() ...................................... 17 FUNCTION: g_cmax() ....................................... 17 FUNCTION: g_col() ........................................ 17 FUNCTION: g_disppcx(x,y,fname [,action,fm,fp]) ........... 17 FUNCTION: g_dot(x,y) ..................................... 18 FUNCTION: g_draw(x1,y1,IMAGE,action) ..................... 18 FUNCTION: g_ellip(fill,x1,y1,x2,y2) ...................... 18 FUNCTION: g_fill(x,y,bcolor) ............................. 19 FUNCTION: g_getbkc(num) .................................. 19 FUNCTION: g_getcolor() ................................... 19 FUNCTION: g_getdot(x,y) .................................. 19 FUNCTION: g_getlstyle() .................................. 19 FUNCTION: g_getlogx(x) ................................... 19 FUNCTION: g_getlogy(y) ................................... 19 FUNCTION: g_getphx(x) .................................... 19 FUNCTION: g_getphy(y) .................................... 20 FUNCTION: g_gettxtclr() .................................. 20 FUNCTION: g_imget(x1,y1,x2,y2) ........................... 20 FUNCTION: g_imload(x1,y1,"fname") ........................ 20 FUNCTION: g_imsave(x1,y1,x2,y2,"fname") .................. 20 FUNCTION: g_imsize(x1,y1,x2,y2) .......................... 21 FUNCTION: g_init(num) .................................... 21 FUNCTION: g_lineto(x,y) .................................. 21 -ii- VideoSoft/Video-Comp CLIPGRAF Library FUNCTION: g_mode() ....................................... 21 FUNCTION: g_monitor() .................................... 22 FUNCTION: g_mouse(num) ................................... 22 FUNCTION: g_moveto(x,y) .................................. 22 FUNCTION: g_msread(num) .................................. 22 FUNCTION: g_ncolors() .................................... 22 FUNCTION: g_pcxinfo(fname) ............................... 22 FUNCTION: g_pcx_xs() ..................................... 23 FUNCTION: g_pcx_ys() ..................................... 23 FUNCTION: g_pcx_ver() .................................... 23 FUNCTION: g_pcx_pl() ..................................... 23 FUNCTION: g_pcx_bpp() .................................... 23 FUNCTION: g_pie(fill,x1,y1,x2,y2,xb,yb,xe,ye) ............ 23 FUNCTION: g_rect(fill,x1,y1,x2,y2) ....................... 24 FUNCTION: g_reg(num) ..................................... 24 FUNCTION: g_remapal(num,color) ........................... 24 FUNCTION: g_rmax() ....................................... 25 FUNCTION: g_row() ........................................ 25 FUNCTION: g_savpcx(x1,y1,x2,y2,"fname") .................. 25 FUNCTION: g_say(row,col,text) ............................ 25 FUNCTION: g_sdump(printer, port, res,xm,ym,rv) ........... 26 FUNCTION: g_setclipr(x1,y1,x2,y2) ........................ 28 FUNCTION: g_selpalt(num) ................................. 28 FUNCTION: g_setapage(num) ................................ 28 FUNCTION: g_setbkc(num) .................................. 28 FUNCTION: g_setclr(num) .................................. 29 FUNCTION: g_setfmsk(byte,byte,byte,byte,byte,byte,by- te,byte) .................................................. 29 FUNCTION: g_setline(num) ................................. 29 FUNCTION: g_setorg(x,y) .................................. 29 FUNCTION: g_settxtc(num) ................................. 30 FUNCTION: g_setvpage(num) ................................ 30 FUNCTION: g_twindow(r1,c1,r2,c2) ......................... 30 FUNCTION: g_viewport(x1,y1,x2,y2) ........................ 30 FUNCTION: g_video memory() .............................. 31 FUNCTION: g_wait() ....................................... 31 FUNCTION: g_wraptxt(flag) ................................ 31 FUNCTION: g_xmax() ....................................... 31 FUNCTION: g_xpos() ....................................... 31 FUNCTION: g_ymax() ....................................... 31 FUNCTION: g_ypos() ....................................... 31 3 ORDER FORM ...................................................... 32 -iii-