Header Files There are two header files used by these programs. They are gr_lib.h and graph.h . The gr_lib.h file is used to compile the code for the graphics routines and the labels. The file graph.h is for use with user programs and defines the screen modes which are supported. It also contains an external declaration for two variables: X_mm and Y_mm. These are the screen sizes of your particular system. If the scaling routines are to work properly, these must be set to the particular hardware in use. For example: extern double X_mm = 220.0, Y_mm = 160.0; /* screen size in mm */ sets up the routines for a CRT with a graphics area 220 mm wide and 160 mm tall. To find the size of the graphics CRT on your system, run lb_demo and measure the size of the frame drawn by this program. Edit the graph.h file definitions for X_mm and Y_mm and substitute these numbers for the present values. Differences From the Hewlett-Packard Series 200/300 Workstation BASIC One of the major differences is the ability of the HP BASIC to default non-existant arguments for functions. For example, locate () requires all arguments to be present. The BASIC function LOCATE can have no arguments: it will draw a full screen cursor on the screen for you to digitize the missing coordinates. To do so in C would require access to the argument count when the function is called. While it is not impossible to access the argument count in a portable fashion, it is difficult to do so. The portable argument count mechanism is aimed at functions which behave like printf (), and is not targeted to functions whose behavior changes with different argument counts. It is also difficult to convince the compilers to accept function prototyping and yet permit varying argument counts without generating warnings. For these reasons, all functions must have a complete list of arguments, except for labelf () which functions perfectly with the portable argument count mechanisms. For the remaining functions which require all arguments, an optional argument may be set to zero. In this case, the default value is used. Functions which accept default values state this in the parameter list for the function. Supported Graphics Modes The following graphics modes are supported: CGA_320x200 1 /* BIOS CGA 320x200, 4 color */ CGA_640x200 2 /* BIOS CGA 640x200 BW */ ATT_640x400 3 /* AT&T 640x400 BW, tiny type */ EGA_320x200 4 /* IBM EGA low-res 320x200, 16 color */ EGA_640x200 5 /* IBM EGA med-res 640x200, 16 color */ EGA_640x350 6 /* IBM EGA high-res 640x350, 16 color */ VGA_640x480 7 /* IBM VGA high-res 640x480, 16 color */ VGA_320x200 8 /* IBM VGA lo-res 320x200, 256 color */ No provisions were made for the Hercules graphics controllers because no information was available on their programming when this code was written. Inclusion of these modes simply requires linking in the support libraries and setting a flag in the g_init () routine which would be read by the putdot () function in graphx.c This function would then alternatively use either the BIOS interface or the Hercules library when drawing. Function Summary clip ( Xmin, Xmax, Ymin, Ymax ) Parameter Minimum value Maximum value Default Units Xmin -1.7E+308 1.7E+308 none User Xmax -1.7E+308 1.7E+308 none User Ymin -1.7E+308 1.7E+308 none User Ymax -1.7E+308 1.7E+308 none User The function clip () defines a soft-clipping window within which to plot. The lower left corner of the window is defined by ( Xmin, Ymin ), and the upper right corner of the window is defined by ( Xmax, Ymax ). The default soft clip window is set by the locate () function. Calling locate () resets the soft clip window to the locate area. Note that this function is slightly different than the function as implimented in HP workstation BASIC. First, you must supply arguments to the clip () function: You can not omit the values and digitize the corners of the soft clip window. _________________________________________________________________ clip_off () This function turns off the soft clipping limits and sets the clipping window to the hard clip window ( either set by default or the limit () function ). _________________________________________________________________ clip_on () This function turns on the soft clipping limits if they were turned off by clip_off (). _________________________________________________________________ csize ( size, aspect_ratio, tilt_angle ) Parameter Minimum value Maximum value Default Units size 1.7E-308 1.7E+308 5 GDU's aspect_ratio 1.7E-308 1.7E+308 0.6 tilt_angle -1.7E+308 1.7E+308 none current angle units Default values for any argument are invoked by a zero (0) for that argument. This function controls the size, aspect ratio, and tilt angle of the characters drawn by labelf (). At initialization, the character size is set to 5 GDU's, at an aspect ratio of 0.6. There is no tilt. Note that, although the angle ranges cover the full range of type double, there is no point in using angles which exceed either +/- 360 degrees or +/- 2 * pi radians. A floating point math error will occur for any angle which resolves to n * 90 degrees or n * pi/2 radians for any odd values of n. _________________________________________________________________ deg (); This function sets the current angle unit to degrees. Affects: ldir (), pdir (), pivot (). _________________________________________________________________ draw ( X, Y ) Parameter Minimum value Maximum value Default Units X -1.7E-308 1.7E+308 none current Y -1.7E-308 1.7E+308 none current This function draws a line from the current position to (X, Y) using the current pen color and line type. If the pen is up, this function will lower the pen prior to drawing the line. The pen will remain down after the line is drawn. _________________________________________________________________ frame () Draw a frame around the current clipping window using the current pen color and line type. After the frame is complete, the pen is positioned to the lower left corner of the frame and the pen is raised. _________________________________________________________________ gclear () gclear () erases the data within the current clipping window. The areas outside of this boundary are not affected. Executing the clip_off () function will cause gclear () to clear the hard clip window. Note: This particular function is very (!!) slow on account of using the BIOS routines to place the pixels. This allows machine independence without significant software complexity and is very portable. If it is not important to clear only the clip window, execution of g_init () will clear the entire screen, but all windowing, scaling, pivoting, plotting directions, labeling information, and current position are lost. _________________________________________________________________ g_init () This function initializes the graphics function and sets the screen mode to graphics. This function must be called prior to issuing any call to any function in this library. g_init () sets the following parameters when called: pen 1 line type 1 csize 4 GDU's pdir 0 degrees mode degrees ldir 0 degrees lorg 1 hard clip full screen soft clip full screen pivot 0 degrees at origin (0,0) _________________________________________________________________ graphics_off () This function will exit from the graphics screen and return to the alpha screen. Unfortunately, unlike the Hewlett-Packard series 200/300 computers, the contents of the screen are erased by this transition. _________________________________________________________________ idraw ( Xinc, Yinc ) Parameter Minimum value Maximum value Default Units Xinc -1.7E-308 1.7E+308 none current Yinc -1.7E-308 1.7E+308 none current This function draws a line from the current position (Xp, Yp) to position (Xp + Xinc, Yp + Yinc) using the current pen color and line type. If the pen is up, this function will lower the pen prior to drawing the line. The position (Xp, Yp) is then updated to the new pen position. When the line is finished, the pen will remain down. _________________________________________________________________ imove ( Xinc, Yinc ) Parameter Minimum value Maximum value Default Units Xinc -1.7E-308 1.7E+308 none current Yinc -1.7E-308 1.7E+308 none current Function imove () incrementally moves from the current position (Xp, Yp) to position (Xp + Xinc, Yp + Yinc). If the pen was down, it is raised before moving. After moving, (Xp, Yp) will be updated to the new pen position. _________________________________________________________________ iplot ( Xinc, Yinc, penc ) Parameter Minimum value Maximum value Default Units Xinc -1.7E-308 1.7E+308 none current Yinc -1.7E-308 1.7E+308 none current penc -32768 32767 none N/A iplot () draws incrementally from the last position (Xp, Yp) to position (Xp + Xinc, Yp + Yinc). After moving the position (Xp, Yp) is updated to the new pen location. The pen control parameter (penc) is interpreted as follows: penc value Action + Even move and then raise pen - Even raise pen and then move + Odd move and then drop pen - Odd drop pen and then move iplot () is affected by pivot () and pdir (). _________________________________________________________________ labelf ( "format string" [, optional argument list] ); labelf () functions exactly as printf (). Imbedded carriage returns result in the line starting 1 line below the present line. Labels are positioned by the functions lorg () and ldir () and the size is governed by csize (). Care must be used when imbedding control characters. In general, no non-printing characters are counted when label positions are calculated, and imbedded backspace characters (\b) are ignored. A label may be drawn at any postion and angle using any size, aspect ratio, and origin using any pen color and line type. Note that only line type # 1 will result in smooth and continuous characters. See also lorg (), ldir (), and csize (). labelf () is not affected by pivot () and pdir () transformations. _________________________________________________________________ ldir ( angle ) ldir () sets the angle at which to draw labels. The specification of the angle may be in degrees or radians as set by the most recent deg () or rad () function call. Positive angle are measured counter-clockwise from the positive x-axis. _________________________________________________________________ limit ( Xmin, Xmax, Ymin, Ymax ) Parameter Minimum value Maximum value Default units Xmin -1.7E+308 1.7E+308 none mm's Xmax -1.7E+308 1.7E+308 none mm's Ymin -1.7E+308 1.7E+308 none mm's Ymax -1.7E+308 1.7E+308 none mm's The limit () function is used to re-define the hard clip boundaries of the screen. limit () clears any previous pivot () data and returns the pivot angle to 0 and the pivot point to the lower left corner (origin). These are the absolute plotting limits, and the pen can not be made to move outside of these limits under program control. limit () does not change scaling parameters to reflect the changed drawing area. One should set the hard clip limits using limit () and then define the scaling are (using locate () ) and then scale the are using either mscale (), show (), or scale (). _________________________________________________________________ line_type ( type_no, repeat ) Parameter Minimum value Maximum value Default Units type_no 1 10 none N/A repeat 0 1.7E+308 5 GDU's The default value for repeat length is invoked by a value of zero for this parameter. The line_type () function is used to select lines for differentiating between items in a drawing or graph. There are 10 line types described below. Although the original HP programs restricted line pattern repeats to integer multiples of 5 GDU's, no such restriction is present in this program. Line type description 1 Solid 2 Dot only at endpoint 3 Lightly dotted line 4 Densely dotted line 5 Broken line of one dash 6 Broken line of one dash and one dot 7 Broken line of one long dash and one short dash 8 Broken line of one dash and two dots 9 Solid line with 1 GDU ticks 10 Solid line with 2 GDU ticks For line types 9 and 10, the ticks are drawn vertically for lines within 45 degrees of the x-axis and horizontally for lines drawn above 45 degrees from the x-axis. Because the IBM PC and PC compatibles do not generally have square pixels (i.e. pixel aspect ratio and physical screen aspect ratio are not identical), the apparent angle at which the switch between vertical and horizontal ticks will not be 45 degrees. This occurs because the pixel drawing algorithm is based in pixels, and the calculation of the starting and ending points of lines is scaled so that the visual information is intuitively correct (i.e., a 45 deg. angle appears as a 45 degree angle on the screen). For example, assume a PC has a 1.38:1 physical aspect ratio. In the 640 x 200 drawing mode, the aspect ratio of the pixels is 3.20:1. Thus, the horizontal pixels are 2.33 times narrower than the vertical pixels are tall. The arctangent of 2.33 is 66.77 degrees. A line at 66.77 degrees (physically) will thus be at the pixel ratio of 1:1 or 45 degrees as far as the drawing algorithm is concerned. Lines above this angle will have horizontal ticks and lines below this angle will have vertical ticks. Line patterns are continuous from one line to the next. THus, if a move occurs after a particular line is drawn, the next line will start at the point in the pattern where the last line left stopped. To re-start the line drawing pattern, simply call the line_type () function again with the same parameters as used in the call which set the current pattern. _________________________________________________________________ locate ( Xmin, Xmax, Ymin, Ymax ) Parameter Minimum value Maximum value Default Units Xmin -1.7E+308 1.7E+308 none GDU Xmax -1.7E+308 1.7E+308 none GDU Ymin -1.7E+308 1.7E+308 none GDU Ymax -1.7E+308 1.7E+308 none GDU locate () is used to define the area to be scaled by scale (), mscale (), or show (). The parameters for the locate () function are always interpreted as GDU's from the lower left corner of the hard clip area (set by limit () ). The locate () function also defines the soft clip limits to be the same as the locate window. _________________________________________________________________ lorg ( origin_number ) Parameter Minimum value Maximum value Default Units origin_number 1 9 none Select an origin for use with labelf (). The following illustrates the origin locations: 3 6 9 +-----------------+-----------------+ | | | | | | | b | | | b | | | b 5 | 8 | 2 + b bbbb oo+oo x x+ | b b o | o x x | | b b o | o x x | | b b o | o x x | | bbbbb oo|oo x x| | | | +-----------------+-----------------+ 1 4 7 In summary, origins 1, 2, or 3 deliver left justified text. Origins 4, 5, or 6 center the text, and origins 8, 9, and 10 offer right justified text. Justification is performed relative to the current pen position. _________________________________________________________________ move ( X, Y ) Parameter Minimum value Maximum value Default Units X 1.7E+308 1.7E+308 none UDU's Y 1.7E+308 1.7E+308 none UDU's The move () function raises the pen and moves to the specified (X, Y) position. The pen remains up after a move. move () is affected by pivot () transformations. _________________________________________________________________ mscale ( Xmin, Ymin ) Parameter Minimum value Maximum value Default Units Xmin -1.7E+308 1.7E+308 none mm Ymin -1.7E+308 1.7E+308 none mm Scale the locate area in millimeters. The coordinate pair (Xmin, Ymin) defines the lower left corner of the locate area. For this function to work properly, it is necessary for the user to provide the correct graphics screen size in the graph.h header file. _________________________________________________________________ pen ( pen_number ) Parameter Minimum value Maximum value Default Units pen_number -32768 32767 none none This function is used to select the color of the pen for plotting. The default pen after g_init () is pen # 1. On the Hewlett-Packard systems, pen # 1 is white at power up. On the IBM compatible computers, it is not. Usually, the highest number pen is white. Pen numbers are limited to those defined for a particular mode. Pen numbers in excess of the maximum defined for a particular graphics mode are usually drawn in background color or not drawn at all. A negative pen value overwrites in background color (i.e., a line drawn with pen # 1 and overwritten with pen # -1 will be erased from the screen). Because of limitations in the PC graphics hardware, any negative pen number erases all pixel colors, not just the pixel colors for that pen. This is because the PC graphics adapters do not have a bitwise AND function built in. Instead, they have a bitwise XOR function. This will erase only pixels of the same color as are being drawn, but if no pixel is present in that color, it will draw one. This behaviour is highly undesireable, and for that reason, a negative pen number will erase all line colors by drawing in background color. _________________________________________________________________ penup () penup () lifts the pen from the plotting surface. On the CRT, this stops line drawing. The pen will remain up until pen control is changed by another statement. _________________________________________________________________ pdir ( angle ) Parameter Minimum value Maximum value Default Units angle -1.7E+308 1.7E+308 none degrees or radians pdir () specifies the angle at which the axes are rotated when drawing with incrimental or relative plotting functions iplot (), idraw (), imove (), rplot (), rdraw (), rmove (). Labels written with labelf () are not affected. The angular units may be specified either in degrees or radians. At g_init (), the units is degrees, but this may be changed at any time after g_init () by using either deg () to set degrees, or rad () to set radians. pdir () is affected by pivot (). _________________________________________________________________ pivot ( angle ) Parameter Minimum value Maximum value Default Units angle -1.7E+308 1.7E+308 none degrees or radians The pivot () function is used to rotate the coordinate axes by angle around the current (X, Y) location. This transformation applies to all drawn lines except axes (), grid (), and label (). The current units for angle are used. If pivot () is invoked a second time, it establishes a new pivot point using the original coordinate system. It does not pivot about the current position in the current coordinate system (which is pivoted). This means that the pivoting can be removed at any point on the plot by invoking pivot ( 0 ). _________________________________________________________________ plot ( X, Y, penc ) Parameter Minimum value Maximum value Default Units X -1.7E-308 1.7E+308 none current Y -1.7E-308 1.7E+308 none current penc -32768 32767 none N/A plot () draws from the last position (X, Y) to the specified position (X, Y). The type of line drawn is taken from the current line type. The pen control parameter (penc) is interpreted as follows: penc value Action + Even move and then raise pen - Even raise pen and then move + Odd move and then drop pen - Odd drop pen and then move plot () is affected by pivot (). _________________________________________________________________ rad () This function set the current angle units to radians. Affects: ldir (), pdir (), pivot (). _________________________________________________________________ ratio () The ratio function returns the aspect ratio of the hard clip area. This is normally the full graphics screen unless the size has been changed by using limit (). Because the pixels in IBM PC compatibles are not square ( that is, the number of pixels /cm in the x-direction is not the same as the number of pixels /cm in the y-direction), the number returned by this function may appear to be non-sensical. It is correct, but it reflects the aspect ratio if the pixels were square. This is one of several limitations of the program which are hardware related. _________________________________________________________________ rdraw ( Xr, Yr ) Parameter Minimum value Maximum value Default Units Xr -1.7E+308 1.7E+308 none current Yr -1.7E+308 1.7E+308 none current The rdraw () function draws using the last absolute position specified as the reference position (Xref, Yref). A reference position is the last position set by one of the following motion or plotting functions: move (), draw (), plot (), imove (), idraw (), iplot (), label (), axes (), frame (), or grid () . A line is drawn from the last position (X, Y) to the position (Xref + Xr, Yref + Yr). The type of line drawn is taken from the current line type. rdraw () is affected by pivot () and pdir (). _________________________________________________________________ rmove ( X, Y ) Parameter Minimum value Maximum value Default Units Xr -1.7E+308 1.7E+308 none current Yr -1.7E+308 1.7E+308 none current The rmove () function moves using the last absolute position specified as the reference position (Xref, Yref). A reference position is the last position set by one of the following motion or plotting functions: move (), draw (), plot (), imove (), idraw (), iplot (), label (), axes (), frame (), grid () . The pen is moved from the last position (X, Y) to the position (Xref + Xr, Yref + Yr). rmove () is affected by pivot () and pdir (). _________________________________________________________________ rplot ( X, Y, penc ) Parameter Minimum value Maximum value Default Units Xr -1.7E-308 1.7E+308 none current Yr -1.7E-308 1.7E+308 none current penc -32768 32767 none N/A The rplot () function draws using the last absolute position specified as the reference position (Xref, Yref). A reference position is the last position set by one of the following motion or plotting functions: move (), draw (), plot (), imove (), idraw (), iplot (), label (), axes (), frame (), grid () . A line is drawn from the last position (X, Y) to the position (Xref + Xr, Yref + Yr). The type of line drawn is taken from the current line type. The pen control parameter (penc) is interpreted as follows: penc value Action + Even move and then raise pen - Even raise pen and then move + Odd move and then drop pen - Odd drop pen and then move rplot () is affected by pivot () and pdir (). _________________________________________________________________ show ( Xmin, Xmax, Ymin, Ymax ) Parameter Minimum value Maximum value Default Units Xmin -1.7E+308 1.7E+308 none user Xmax -1.7E+308 1.7E+308 none user Ymin -1.7E+308 1.7E+308 none user Ymax -1.7E+308 1.7E+308 none user The show () function scales the locate area such that a physical representation of 1 unit along either the X- or Y-axis has the same physical size (i.e., square objects appear square ). _________________________________________________________________ setgu () This function changes the display units of the drawing from user defined units (UDU's) to graphics display units (GDU's). _________________________________________________________________ setuu () This function changes the display units of the drawing from graphics display units (GDU's) to user defined units (UDU's). The user units must have been previously defined using either scale (), show (), or mscale (). _________________________________________________________________ scale ( Xmin, Xmax, Ymin, Ymax ) Parameter Minimum value Maximum value Default Units Xmin -1.7E+308 1.7E+308 none user Xmax -1.7E+308 1.7E+308 none user Ymin -1.7E+308 1.7E+308 none user Ymax -1.7E+308 1.7E+308 none user The scale () function defines the minimum and maximum user units each axis of the area specified by locate (). _________________________________________________________________