SFGL70 - Small Fast Graphics Library Last Revision: April 28, 1980 Additions for 4663 plotter June 1983 B. Z. Lederman CHAPTER 1 Introduction SFGL70 is a UTRC developed software library. This library is intended to provide graphics capability for the Tektronix 4010, 4006, and 4014 terminals. The library was designed to be small (under 2K words), while providing the user with essential graphic capabilities. Because the graphics package is a library, only those routines referenced by the users program will be linked as a part of the executable task image. Since the library has been created at UTRC, the systems programming group welcomes your comments regarding it's performance. Any suggestions as to how the SFGL70 can be improved are always welcome. If the content of any portion of this documentation package is not clear, please inform us. You can call us at: extension 7241. CHAPTER 2 Programming Considerations The Tektronix terminals have an absolute coordinate system ranging from 0-1023 on the X axis and from 0-780 on the Y axis. However, the coordinate system(window) established by GRID or WINDOW has a range from 0-920 on the X axis and from 0-735 on the Y axis. The window is shifted right 103 coordinates and up 45 coordinates to allow labels below and to the left of the window. Use with Plotter When plotting on full (C) size paper, the full window should be visible, as will be the case if the window is set with the locate buttons on both the lower left and upper right corners for any size paper. If, however, B or C size paper is used with the default page size, the full Y axis will not be available as the paper is not as high for it's width as a CRT screen. If the desired Y axis is N, set the YMAX for GRID or WINDOW to be N/0.875 to get the desired height. Note also that after a HOME, the pen will be above the top of the window. ASCII text may be displayed anywhere within the absolute coordinate system. However, if a text string is attempted to be displayed outside the range of the absolute coordinate system, the Tektronix termial hardware will insert a carriage return and line feed into the text string. ASCII characters are 14 coordinates in width and 22 coordinates in height. The coordinates reference the bottom left corner of each character. The operating mode of the Tektronix terminals may be either Alpha or Graphic. The SFGL70 routines will put the terminal in the correct mode before they attempt to do textural or graphic output. However, you must put the terminal in Alpha mode if you wish to do Fortran output after having just performed graphic output. We have designed the package for faster plot execution by reducing system I/O overhead. This is accomplished by buffering all graphic output. However, the graphic output buffer may be left partially full by any routine which returns to the calling program while still in Graphic mode. To ensure that all graphic output is physically sent to the terminal, the user must call any routine which returns the terminal to Alpha mode. Programming Considerations PAGE 2-2 Small Fast Graphics Library The Fortran program must not use a "stop" statement to exit. To ensure that all buffered graphic output is sent to the terminal correctly, the program should exit with a "call exit" statement. Any user linking assembly language routines to their program should note that the SFGL70 routines use local event flags 10 and 11. Terminals operating with the SFGL70 package must run at 9600 baud or slower. This speed dependency is due to the delays which must be generated as a result of terminal control functions such as hardcopy and erase. NOTE: for the 4663 plotter using x-on/x-off, there does not appear to be any speed restriction. Functions such as hardcopy and erase do not apply. If you are using the SFGL70 at a Tektronix 4014, you should set the character size to 74 characters per line and 35 lines per page. CHAPTER 3 Available Subroutines GRID - This routine establishes the limits of the user defined coordinate system. The range of the X and Y axis may be between + and - 1.7 * 10**38. This routine also displays an X and Y grid with labels. It establishes the screen's virtual window. Returns in Alpha Mode Calling Format: CALL GRID(LABELX,XMAX,XMIN,YGRDLO,LABELY,YMAX,YMIN,XGRDLO,MMFLG) Where: LABELX - is the ASCII label displayed below the X grid. XMAX - is the floating point maximum value of the X axis. It may be positive, negative, or zero. It may be less than XMIN. XMIN - is the floating point minimum value of the X axis. It may be positive, negative, or zero. It may be greater than XMAX. XGRDLO - is the floating point Y coordinate position of the X grid. If it is out of range, the X grid will appear at YMAX or YMIN depending on which limit it is closer to. LABELY - is the ASCII label displayed to the left of the Y grid. YMAX - is the floating point mayimum value of the Y axis. It may be positive, negative, or zero. It may be less than YMIN. YMIN - is the floating point minimum value of the Y axis. It may be positive, negative, or zero. It may be greater than YMAX. YGRDLO - is the floating point X coordinate position of the Y grid. If it is out of range, the Y grid will appear at XMAX or XMIN depending on which limit it is closer to. MMFLG - is a flag to specify whether the minimum and maximum values of each grid should be displayed. a MMFLG integer value of -1 will cause the grid's value not to be displayed. Available Subroutines PAGE 3-2 Small Fast Graphics Library ******************** WINDOW - This routine establishes the limits of the user defined coordinate system. The range of the X and Y axis may be between + and - 1.7 * 10**38. This routine also displays an X and Y grid with labels. It establishes the screen's virtual window. It calls GRID to perform those functions. However, unlike GRID, WINDOW will not perform correctly if a grid minimum is greater than the corresponding grid maximum. in addition, it computes an appropriate number of tics to display on the X and Y grid and the distance between those tics. This algorithm to automatically display tic marks with labels is a compromise between making your programming easier and keeping the library small. Returns in Alpha Mode Calling Format: CALL WINDOW(LABELX,XMAX,XMIN,YGRDLO,LABELY,YMAX,YMIN,XGRDLO,MMFLG) Where: LABELX - is the ASCII label displayed below the X grid. XMAX - is the floating point maximum value of the X axis. It may be positive, negative, or zero. It may be less than XMIN. XMIN - is the floating point minimum value of the X axis. It may be positive, negative, or zero. It may be greater than XMAX. XGRDLO - is the floating point Y coordinate position of the X grid. If it is out of range, the X grid will appear at YMAX or YMIN depending on which limit it is closer to. LABELY - is the ASCII label displayed to the left of the Y grid. YMAX - is the floating point mayimum value of the Y axis. It may be positive, negative, or zero. It may be less than YMIN. YMIN - is the floating point minimum value of the Y axis. It may be positive, negative, or zero. It may be greater than YMAX. YGRDLO - is the floating point X coordinate position of the Y grid. If it is out of range, the Y grid will appear at XMAX or XMIN depending on which limit it is closer to. MMFLG - is a flag to specify whether the minimum and maximum values of each grid should be displayed. A MMFLG integer value of -1 will cause the grid's value not to be displayed. ******************** Available Subroutines PAGE 3-3 Small Fast Graphics Library PLOT - Routine to plot a continuous or dashed curve(line), within the virtual window established by GRID. Returns in Graphic Mode Calling Format: CALL PLOT(NUMPTS,XARRAY,YARRAY) Where: NUMPTS - is the integer number of points to be connected to plot the curve(line). If less than zero every other point is connected. XARRAY - are the virtual floating point X coordinates. YARRAY - are the virtual floating point Y coordinates. ******************** PLOTC - The same as plot except the first point of the curve(line) is connected to the last point of the last call to plot or plotc. Returns in Graphic Mode ******************** POINT - Routine to display a point(s) within the virtual window established by grid. Returns in Graphic Mode Calling Format: CALL POINT(NUMPTS,XARRAY,YARRAY) Where: NUMPTS - is the integer number of points to be displayed XARRAY - are the virtual floating point X coordinates. YARRAY - are the virtual floating point Y coordinates. ******************** Available Subroutines PAGE 3-4 Small Fast Graphics Library POINTI - Routine to display a point(s) within the absolute window of the display. Returns in Graphic Mode Calling Format: CALL POINTI(NUMPTS,IXARRY,IYARRY) Where: NUMPTS - is the integer number of points to be displayed XARRAY - are the absolute integer X coordinates. YARRAY - are the absolute integer Y coordinates. ******************** TICWIN - Routine to display tic marks(crosses) within the complete virtual window established by GRID. The spacing between tics is in virtual coordinates. Returns in Graphic Mode Calling Format: CALL TICWIN(XSPACE,YSPACE) Where: XSPACE - is the virtual floating point number of X coordinates between tics. YSPACE - is the virtual floating point number of Y coordinates between tics. ******************** Available Subroutines PAGE 3-5 Small Fast Graphics Library TICGRD - Routine to display tic marks along the X and Y grid. The spacing between tics is in virtual coordinates, as established by GRID. Returns in Graphic Mode Calling Format: CALL TICGRD(XSPACE,YSPACE) Where: XSPACE - is the virtual floating point number of X coordinates between tics. YSPACE - is the virtual floating point number of Y coordinates between tics. ******************** HTEXT - Routine to display text horizontally, using the coordinate system (window) established by GRID. Returns in Alpha Mode Calling Format: CALL HTEXT(TEXT,XCOORD,YCOORD) Where: TEXT - is the ASCII string to be displayed XCOORD - is the virtual floating point X coordinate position to begin the text display. YCOORD - is the virtual floating point Y coordinate position to begin the text display. ******************* Available Subroutines PAGE 3-6 Small Fast Graphics Library VTEXT - Routine to display text vertically using the coordinate system (window) established by the call to GRID. Returns in Alpha Mode Calling Format: CALL VTEXT(TEXT,XCOORD,YCOORD) Where: TEXT - is the ASCII text to be displayed. XCOORD - is the virtual floating point X coordinate position to begin the text display. YCOORD - is the virtual floating point Y coordinate position to begin the text display. ******************** FLTXT - Routine to display a floating point number (in G17.6 Format) within the coordinate system(window) established by the call to GRID. Returns in Alpha Mode Calling Format: CALL FLTXT(FLTNUM,XCOORD,YCOORD) Where: FLTNUM - is the floating point number to be displated. XCOORD - is the virtual floating point X coordinate position to begin the display. YCOORD - is the virtual floating point Y coordinate position to begin the display. ******************** Available Subroutines PAGE 3-7 Small Fast Graphics Library PLTSYM - Routine to display any keyboard character(symbol) in the virtual window established by GRID. Returns in Alpha Mode Calling Format: CALL PLTSYM(NUMSYM,XARRAY,YARRAY,SYMBOL) Where: NUMSYM - is the number of times to display the symbol XARRAY - is the array(variable) containing the virtual floating point X coordinate position(s) to display the symbol YARRAY - is the array(variable) containing the virtual floating point Y coordinate position(s) to display the symbol SYMBOL - is the ASCII symbol(character) to be displayed ******************** HTEXTI - Routine to display text horizontally, using the display's absolute integer coordinate system. Returns in Alpha Mode Calling Format: CALL HTEXTI(TEXT,IXCORD,IYCORD) Where: TEXT - is the ASCII string to be displayed IXCORD - is the absolute integer X coordinate position to begin the text display. IYCORD - is the absolute integer Y coordinate position to begin the text display. ******************* Available Subroutines PAGE 3-8 Small Fast Graphics Library VTEXTI - Routine to display text vertically using absolute integer coordinate system. Returns in Alpha Mode Calling Format: CALL VTEXTI(TEXT,IXCORD,IYCORD) Where: TEXT - is the ASCII text to be displayed. IXCORD - is the absolute integer X coordinate position to begin the text display. IYCORD - is the absolute integer Y coordinate position to begin the text display. ******************** FLTXTI - Routine to display a floating point number (in G17.6 Format) within the absolute integer coordinate system. Returns in Alpha Mode Calling Format: CALL FLTXTI(FLTNUM,IXCORD,IYCORD) Where: FLTNUM - is the floating point number to be displated. IXCORD - is the absolute integer X coordinate position to begin the display. IYCORD - is the absolute integer Y coordinate position to begin the display. ******************** Available Subroutines PAGE 3-9 Small Fast Graphics Library SCURSR - Routine to activate the graphic cursor(cross-hair), allowing the user to position it. The cursor position is transmitted to to the computer when a keyboard character is struck. This character along with the cursor position is returned as arguments. NOTE: this has no relevance for the 4663 plotter. Returns in Alpha Mode Calling Format: CALL SCURSR(ICHAR,IX,IY) Where: ICHAR - is the keyboard character typed (right adjusted if not declared as a byte) IX - is the absolute integer X screen coordinate of the graphic cursor. IY - is the absolute integer Y screen coordinate of the graphic cursor. ******************** VCURSR - Routine to activate the graphic cursor(cross-hair), allowing the user to position it. The cursor position is transmitted to to the computer when a keyboard character is struck. This character along with the cursor position is returned as arguments. VCURSR transforms the returned coordinates into virtual floating point coordinates according to the window established by GRID. NOTE: this has no relevance for the 4663 plotter. Returns in Alpha Mode Calling Format: CALL VCURSR(ICHAR,X,Y) Where: ICHAR - is the keyboard character typed (right adjusted if not declared as a byte) X - is the virtual floating point X screen coordinate of the graphic cursor. Y - is the virtual floating point Y screen coordinate of the graphic cursor. ******************** Available Subroutines PAGE 3-10 Small Fast Graphics Library ERASE - Routine to erase the screen. Has no function for the 4663 plotter. Returns in Alpha Mode Calling Format: CALL ERASE ******************** COPY - Routine to make a hardcopy of the screen. Has no function for the 4663 plotter. Returns in Alpha Mode Calling Format: CALL COPY ******************* BELL - Routine to ring the terminal bell. Returns in Alpha Mode Calling Format: CALL BELL(N) Where: N - is the integer number of times to ring the bell. ******************* Available Subroutines PAGE 3-11 Small Fast Graphics Library BAUD - Routine to inform SFGL70 of the baud rate of the user's terminal. it is only needed if the routines copy, erase, or bell are used. The default baud rate is 9600. NOTE: this is not required for the 4663 plotter using x-on/x-off and through connected to a normal terminal. Returns in Previous Mode Calling Format: CALL BAUD(N) Where: N - is the integer baud rate of the terminal. ******************* MVCURI - Routine to move the cursor to the desired screen coordinates, using the absolute integer coordinates of the display. Returns in Alpha Mode Calling Format: CALL MVCURI(IX,IY) Where: IX - is the absolute integer X coordinate position to move the cursor to. IY - is the absolute integer Y coordinate position to move the cursor to. ******************* Available Subroutines PAGE 3-12 Small Fast Graphics Library MVCUR - Routine to move the cursor to the desired screen coordinates, using the virtual window established by GRID. Returns in Alpha Mode Calling Format: CALL MVCUR(X,Y) Where: X - is the virtual floating point coordinate position to move the cursor to. Y - is the virtual floating point Y coordinate position to move the cursor to. ******************* GTCURI - Routine to obtain the current cursor screen coordinates, using the absolute integer coordinates of the display. Returns in Alpha Mode Calling Format: CALL GTCURI(IX,IY) Where: IX - is the absolute integer X coordinate position of the cursor. IY - is the absolute integer Y coordinate position of the cursor. ******************* Available Subroutines PAGE 3-13 Small Fast Graphics Library GTCUR - Routine to obtain the current cursor screen coordinates, using the virtual window established by grid. Returns in Alpha Mode Calling Format: CALL GTCUR(X,Y) Where: X - is the virtual floating point coordinate position of the cursor. Y - is the virtual floating point Y coordinate position of the cursor. ******************* BACK - Routine to move the cursor back n spaces. Returns in Alpha Mode Calling Format: CALL BACK(N) Where: N - is the integer number of times to backspace. ******************* UP - Routine to move the cursor up n lines. Returns in Alpha Mode Calling Format: CALL UP(N) Where: N - is the integer number of lines to move the cursor up. ******************* Available Subroutines PAGE 3-14 Small Fast Graphics Library DOWN - Routine to move the cursor down n lines. Returns in Alpha Mode Calling Format: CALL DOWN(N) Where: N - is the integer number of lines to move the cursor down. ******************** HOME - Routine to move the cursor to the home position (top left corner of the screen). NOTE: when plotting on A or B size paper with default coordinates, home will be outside (above) the printing window by about 4 lines in the default character size. Returns in Alpha Mode Calling Format: CALL HOME ******************** ALPHA - Routine to return the terminal to Alpha mode. Returns in Alpha Mode Calling Format: CALL ALPHA ******************** Available Subroutines PAGE 3-15 Small Fast Graphics Library BLKBOX - Routine to inform the graphics package that the graphics terminal is on a shared line with the hardcopy device. NOTE: this does not apply to a 4663 plotter which is passing through to a normal terminal. In this case, the plotter must be set up to intercept commands, and should be turned on or off as required (see PLOTON, PLOTOF). Returns in Previous Mode Calling Format: CALL BLKBOX ******************** CHAPTER 4 ADDITIONS FOR PLOTTER The following additions are for the 4663 series plotter, although some are also relevant to 4014 type terminals. Unless otherwise specified, the commands are Type 1, the attention character is an Escape (octal 33), and the device address is "A". PLTRON - Turns on the plotter. This should be sent first to inform the plotter it is to respond to any commands which follow. Returns in default mode of plotter. Calling Format: CALL PLTRON ******************** PLTROF - Turns off the plotter, does a call to ALPHA, and so will flush the buffer. This should be the last command to the plotter. Returns in Alpha Mode Calling Format: CALL PLTROF ******************** Additions for plotter PAGE 4-2 PLTSET - Sends an attention (Escape) followed by a single byte. This is a Type 1 or Type 2 command depending upon the character sent, and may be used to change the line type, character size, etc. Once the character size or line type has been changed, it remains in that state for all subsequent commands until reset. Does not change mode. Calling Format: CALL PLTSET(byte) Where: byte - is the single byte to be sent. The following are valid for the 4663 plotter and 4014 terminal: 1. a - sets the line type to dots. 2. b - sets the line type to dash-dot. 3. c - sets the line type to short dashes. 4. d - sets the line type to long dashes. 5. e - sets the line type to solid (the default after a device reset). 6. 8 - sets the characters to the largest size (the default after reset). 7. 9 - sets the characters to size 2. 8. : - sets the characters to size 3. 9. ; - sets the characters to the smallest size. 10. Form-Feed (octal 14) resets graphic characteristics, sets the line type to solid, puts the pen at home (upper left corner). See PLTREG Other characters will be valid for the 4014 (such as write through or defocus) but not for the 4663. Other line types repeat those given above. ******************** Additions for plotter PAGE 4-3 PLTREA - Resets the Alpha characteristics (character size, font, slant, rotation). Returns in default Mode Calling Format: CALL PLTREA ******************** PLTREG - Resets Graphic characteristics (line type, carriage position). See Form-Feed under PLTSET. Calling Format: CALL PLTREG ******************** PLTRES - Resets Graphic and Alpha characteristics by calling PLTREG and PLTREA above. Calling Format: CALL PLTRES ******************** PLTLOD - Moves the pens to load point. As this is the upper right corner which is usually outside the window, the locate buttons will light. This does not generate a pause, and any commands which follow will be executed, so if a pen change is desired, the program must prompt the user. The command is useful immediatly prior to PLTROF to move the pens away from the paper. Calling Format: CALL PLTLOD ******************** Additions for plotter PAGE 4-4 PLTPEN - Selects a pen for subsequent use. Calling Format: CALL PLTPEN(n) Where: n - is the pen number. The command does a modulo 4 reduction of this parameter, so that only numbers 0, 1, 2, or 3 result (even if a letter or non-integer number is used). 1 and 2 select the respective pens, 3 causes no change. 0 selects the cross hairs, but the next command requiring something to be drawn will result in the previous pen being re-selected. ******************** Index PAGE 4-5 Small Fast Graphics Library ALPHA . . . . . . . . . . . . . . . . 3-14 BACK . . . . . . . . . . . . . . . . . 3-13 BAUD . . . . . . . . . . . . . . . . . 3-10 BELL . . . . . . . . . . . . . . . . . 3-10 BLKBOX . . . . . . . . . . . . . . . . 3-14 COPY . . . . . . . . . . . . . . . . . 3-10 DOWN . . . . . . . . . . . . . . . . . 3-13 ERASE . . . . . . . . . . . . . . . . 3-9 FLTXT . . . . . . . . . . . . . . . . 3-6 FLTXTI . . . . . . . . . . . . . . . . 3-8 GRID . . . . . . . . . . . . . . . . . 3-1 GTCUR . . . . . . . . . . . . . . . . 3-12 GTCURI . . . . . . . . . . . . . . . . 3-12 HOME . . . . . . . . . . . . . . . . . 3-14 HTEXT . . . . . . . . . . . . . . . . 3-5 HTEXTI . . . . . . . . . . . . . . . . 3-7 MVCUR . . . . . . . . . . . . . . . . 3-11 MVCURI . . . . . . . . . . . . . . . . 3-11 PLOT . . . . . . . . . . . . . . . . . 3-3 PLOTC . . . . . . . . . . . . . . . . 3-3 PLTLOD . . . . . . . . . . . . . . . . 4-3 PLTPEN . . . . . . . . . . . . . . . . 4-4 PLTREA . . . . . . . . . . . . . . . . 4-3 PLTREG . . . . . . . . . . . . . . . . 4-3 PLTRES . . . . . . . . . . . . . . . . 4-3 PLTROF . . . . . . . . . . . . . . . . 4-1 PLTRON . . . . . . . . . . . . . . . . 4-1 PLTSET . . . . . . . . . . . . . . . . 4-2 PLTSYM . . . . . . . . . . . . . . . . 3-6 POINT . . . . . . . . . . . . . . . . 3-3 POINTI . . . . . . . . . . . . . . . . 3-4 SCURSR . . . . . . . . . . . . . . . . 3-8 TICGRD . . . . . . . . . . . . . . . . 3-4 TICWIN . . . . . . . . . . . . . . . . 3-4 UP . . . . . . . . . . . . . . . . . . 3-13 VCURSR . . . . . . . . . . . . . . . . 3-9 VTEXT . . . . . . . . . . . . . . . . 3-6 VTEXTI . . . . . . . . . . . . . . . . 3-7 WINDOW . . . . . . . . . . . . . . . . 3-2