4

Graphics

Donald L. Vossler

"Super TextPlot" is a machine language utility that lets you plot character images in any Atari graphics or text mode. The idea for the program was inspired by Charles Brannon's "TextPlot" utility (COMPUTE's First Book of Atari Graphics). Super TextPlot provides the following capabilities.

1. Plots the entire ATASCII character set, including upper/lowercase, graphics characters, special symbols, and the reverse video version of each of these characters in any graphics or text mode. Alternate character sets may be plotted by changing the CHBAS vector (location 756) to point to the alternate character set.

2. Allows the user to specify a string of characters to plot. The only length limitation for the string is that it must fit in the display area when it is plotted.

3. Allows the user to specify the starting position of the string to plot. This position can be any (X,Y) coordinate on the display.

4. Gives the user the option of overwriting the graphics already on the screen or of merging the plotted characters with the existing graphics.

5. Allows the user to select which color registers are to be used for the foreground and background of the characters plotted.

6. Allows the user to scale each character string independently in the horizontal and vertical directions by specifying the number of rows and columns for each character. The actual size of each character varies with the pixel size of the graphics mode selected. Many different-sized characters can be plotted on the same graphics screen.

7. Allows the user to select one of four angular orientations to plot each character string. The four available orientations are 90 degree increments from the horizontal.

All of these capabilities are available using one simple invocation of a machine language routine from the USR function in BASIC.

The fundamental trigonometric relationships used by Super TextPlot are illustrated in Figure 1. The angle THETA (θ) is measured from the horizontal + X axis to the baseline of the character string to be plotted; CHNUM is the index number of each character in the string; NROWS and NCOLS are the total number of rows and columns, respectively, to be plotted for each character; ROWand COL are the particular row and column of the pixel to be plotted; XS and YS are the coordinates of the lower-left corner of the first character to be plotted (before the string is rotated). Using these definitions, the appropriate formulas for the point to be plotted (XP,YP) are the following:

XP=XS+cos(θ)*(CHNUM*NCOLS-1-COL)-sin(θ)*(NROWS-1-ROW)
YP=YS-sin(θ)*(CHNUM*NCOLS-1-COL)-cos(θ)*(NROWS-1-ROW)

The derivation of these formulas is shown in Figure 2.

Figure 2. Derivation of Plotting Formulas

XP=XS+dX1-dX2
XP=XS+cos(THETA)*((CHNUM-1)*NCOLS+(NCOLS-1-COL))-sin(THETA)*(NROWS-1-ROW)
XP=XS+cos(THETA)*CHNUM*NCOLS-1-COL)-sin(THETA)*(NROWS-1-ROW)
YP=YS-dY1-dY2
YP=YS-sin(THETA)*((CHNUM-1)*NCOLS+(NCOLS-1-COL))-cos(THETA)*(NROWS-1-ROW)
YP=YS-sin(THETA)*(CHNUM*NCOLS-1-COL)-cos(THETA)*(NROWS-1-ROW)

With the appropriate formulas derived, the Super TextPlot routine was developed. The USR function is used to invoke the utility. The syntax for this function is:

A=USR(ADR(ASM$),ADR(S$),LEN(S$),XS,YS,ORIENT,NROWS,NCOLS,FCR,BCR,PRIOR)

The parameters specified above have the following meanings:

ADR(ASM$)		This parameter is the starting address of the Super TextPlot routine. Since the loader for the routine uses a character string (ASM$) to reserve space in memory for the routine, the starting address is merely the address of this string.
ADR(S$)		This parameter is the address of the string to be plotted. Usually it will be the value returned by the ADR function for the string since this is the first character in the string. However, any address is valid. For example, the address could point to a sub-string contained in a long string.
LEN(S$)		This parameter specifies how many characters are to be plotted. The LEN function provides the appropriate value if the entire string is to be plotted. Other values may be appropriate for plotting sub-strings. If this parameter is zero, nothing is plotted, and the USR function simply returns to the BASIC program.
XS,YS		These two parameters specify the (X,Y) coordinates of the starting position of the string to be plotted (lower-left comer of the first character). This point is also used as the pivot point when the string is rotated (see ORIENT parameter). (XS,YS) must define a point within the limits of the current graphics mode.
ORIENT		This parameter specifies the angular orientation of the character string to be plotted. The string is rotated counterclockwise from the horizontal + X axis about the point (XS,YS). The parameter ORIENT should be specified as an integer which is interpreted as follows: ORIENT =0,0 degree rotation =1,90 degree rotation =2,180 degree rotation =3,270 degree rotation The value of ORIENT is interpreted MOD(3) so that ORIENT=4 is the same as ORIENT=0, ORIENT=5 is the same as ORIENT=1, etc. The high byte of the two-byte integer passed by the USR function to the machine language routine is ignored. Figure 3 illustrates the orientation of strings plotted at each of the four orientations.
NROWS		The parameter specifies how many rows per character are to be plotted and therefore determines the height of each character. Normally, NROWS is greater than or equal to eight; however, positive values less than eight are valid and will result in characters plotted with "missing" rows. This may be useful for crowding strings into a limited space, or it may simply produce unreadable characters. If NROWS is zero, nothing is plotted, and the USR function returns to the BASIC program. The maximum acceptable value for NROWS is 255 (the high byte of the two-byte integer passed to the machine language routine by the USR function is ignored).
NCOLS		This parameter specifies how many columns per character are to be plotted and therefore determines the width of each character. The restrictions on the range of values for this parameter are the same as those specified for the NROWS parameter.
FCR		This parameter specifies the foreground color register to be used when plotting the string. This indirectly specifies the color of the characters plotted in the framework of the standard SETCOLOR-COLOR concept embodied in the Atari BASIC language. In text modes (GRAPHICS 0-2) this parameter should be specified as an ATASCII code. Using Super TextPlot in this manner allows block printing of character images which are typically used as headers to identify printed listings. For example, FCR=160 would use the reverse video space to plot large characters in GRAPHICS 0.
BCR		This parameter specifies the background color register for each character. The comments regarding the use of FCR in text modes also apply for this parameter. If the value of the parameter PRIOR (see below) is zero, then the BCR parameter has no effect on the characters plotted.
PRIOR		This parameter specifies the priority of the background of the character string plotted. If PRIOR is zero, the background of the characters is not plotted and existing graphics on the screen will not be disturbed. If PRIOR is a positive value, the color specified indirectly by BCR is plotted for the background (this color may be black).

The following items should be noted in relation to specifying these parameters:

1. The Super TextPlot routine does not check to make sure that points plotted to form a string fall within the bounds of the display area. The user must insure that all the points to be plotted will fall within the display limits. Plotting points which are out of range usually results in a system crash.
2. Reverse video characters may be plotted by two different methods:
   1. Specify reverse video characters in the string to be plotted; or
   2. Specify normal characters in the string and reverse the values for FCR and BCR.
3. If the parameters FCR and BCR are assigned the same value (and PRIOR is positive), the string will be plotted but will appear as contiguously colored blocks.
4. If an improper number of parameters is specified in the USR function statement, Super TextPlot will return to the BASIC program but take no other action.
5. The value A returned by the USR function has no significance.

One of the problems associated with writing utility routines in machine language is determining a safe range of memory locations which can be used to store the routine. This problem is complicated by various available memory configurations, memory used by custom display lists, player/missile graphics, and other machine language routines.

Super TextPlot solves all of these problems by providing the machine code in a relocatable format. All of the addresses in the DATA statements are relative addresses offset from the beginning of the routine. These addresses are flagged as minus numbers in the DATA statements. When the loader routine is invoked, it reserves a character string (ASM$) in which the machine code is stored. As each instruction code is loaded into this string, the addresses are modified to reflect the actual memory locations utilized.

Since Super TextPlot is a utility program, it can be treated as an extension to the BASIC programming language and therefore becomes one of the tools available to a programmer. Obvious examples for the use of this routine include labelling graphs and bar charts, adding text to graphic game displays, and developing colorful and attractive message displays. Super TextPlot can be an effective marketing/sales tool. A variety of textual messages can be displayed on a demonstration computer system in order to attract customers and provide information in an eye-catching format.

1000 REM 
1010 REM ------INITIALIZATION-------
1020 REM 
1030 DIM S$(40):DEG :? "LOADING ASSEMBLY CODE":? "45 SECOND DELAY ...":GOSUB 8000
1040 REM 
1050 REM ---------DEMO #1-----------
1060 REM 
1070 GRAPHICS 7+16
1080 S$="SUPER TEXTPLOT":XS=24:YS=24:ORIENT=0:NROWS=24:NCOLS=8:FCR=3:BCR=0:PRIOR=0:GOSUB 8000
1090 S$="FOR":XS=68:YS=44:ORIENT=0:NROWS=8:NCOLS=8:FCR=1:BCR=0:PRIOR=0:GOSUB 8000
1100 S$="ATARI":XS=0:YS=95:ORIENT=0:NROWS=32:NCOLS=32:FCR=2:BCR=0:PRIOR=0:GOSUB 800
1110 S$="COMPUTE!":NROWS=8:NCOLS=8:FCR=3:BCR=1:PRIOR=1
1120 XS=7:YS=64:ORIENT=1:PRIOR=1:GOSUB 8000
1130 XS=151:YS=2:ORIENT=3:GOSUB 8000
1140 GOSUB 7000
1150 REM 
1800 REM ---------DEMO #2-----------
1810 REM 
1820 GRAPHICS 7+16
1830 COLOR 3
1840 PLOT 34,2:DRAWTO 126,2:DRAWTO 126,94:DRAWTO 34,94:DRAWTO 34,2
1850 PLOT 51,19:DRAWTO 109,19:DRAWTO 109,77:DRAWTO 51,77:DRAWTO 51,19
1860 PLOT 60,28:DRAWTO 100,28:DRAWTO 100,68:DRAWTO 60,68:DRAWTO 60,28
1870 PLOT 34,2:DRAWTO 60,28
1880 PLOT 126,2:DRAWTO 100,28
1890 PLOT 126,94:DRAWTO 100,68
1900 PLOT 34,94:DRAWTO 60,68
1910 S$="ATARI":FCR=2:BCR=0:NROWS=8:NCOLS=8:PRIOR=0
1920 XS=60:YS=27:ORIENT=0:GOSUB 8000
1930 XS=101:YS=28:ORIENT=3:GOSUB 8000
1940 XS=98:YS=69:ORIENT=2:GOSUB 8000
1950 XS=58:YS=67:ORIENT=1:GOSUB 8000
1960 NROWS=16:NCOLS=11:FCR=1
1970 XS=53:YS=18:ORIENT=0:GOSUB 8000
1980 XS=110:YS=21:ORIENT=3:GOSUB 8000
1990 XS=107:YS=78:ORIENT=2:GOSUB 8000
2000 XS=50:YS=75:ORIENT=1:GOSUB 8000
2010 XS=61:YS=67:ORIENT=0:FCR=3:BCR=2:NROWS=39:NCOLS=39:PRIOR=1
2020 FOR I=1 TO 8
2030 S$="COMPUTE!":S$=S$(I,I):GOSUB 8000
2040 NEXT I
2050 GOSUB 7000
2060 GOTO 2060
7000 REM 
7010 REM ----COLOR FLASH ROUTINE----
7020 REM 
7030 FOR I=1 TO 50:FOR J=0 TO 2:SETCOLOR J,RND(0)*16,RND(0)*16:FOR W=1 TO 5:NEXT W:NEXT J:NEXT I:RETURN 
7997 REM 
7998 REM -- SUPER TEXTPLOT ROUTINE --
7999 REM 
8000 IF ASMLD=1 THEN A=USR(ADR(ASM$),ADR(S$),LEN(S$),XS,YS,ORIENT,NROWS,NCOLS,FCR,BCR,PRIOR):RETURN 
8010 ASMLD=1
8020 DIM ASM$(725)
8030 FOR I=ADR(ASM$) TO ADR(ASM$)+724
8040 READ A
8050 ON (SBN(A)+2) GOSUB 8080,8160,8220
8060 NEXT I
8070 GOTO 8000
8080 READ B
8090 ADDR=ABS(A)+256*ABS(B)+ADR(ASM$)
8100 ADDRHI=INT(ADDR/256)
8110 ADDRLO=ADDR-256*ADDRHI
8120 POKE I,ADDRLO
8130 POKE I+1,ADDRHI
8140 I=I+1
8150 RETURN 
8160 READ B
8170 IF B<0 THEN 8090
8180 POKE I,A
8190 POKE I+1,B
8200 I=I+1
8210 RETURN 
8220 POKE I,A
8230 RETURN 
8240 DATA 104,141,-255,0,10,170,240,8
8250 DATA 104,157,-255,0,202,76,-6,0
8260 DATA 173,-255,0,201,10,240,1,96
8270 DATA 173,-16,-1,208,1,96,173,-8
8280 DATA -1,208,1,96,173,-6,-1,208,1
8290 DATA 96,173,-10,-1,41,3,141,-10
8300 DATA -1,173,-18,-1,133,203,173
8310 DATA -19,-1,133,204,169,0,141
8320 DATA -17,-1,238,-17,-1,56,173
8330 DATA -16,-1,237,-17,-1,16,3,76
8340 DATA -254,0,32,-32,-1,173,-6,-1
8350 DATA 141,-7,-1,206,-7,-1,174,-7
8360 DATA -1,224,255,208,3,76,-251,0
8370 DATA 172,-6,-1,32,-138,-1,140,-3
8380 DATA -1,173,-6,-1,174,-17,-1,172
8390 DATA -7,-1,32,-195,-1,140,-20,-1
8400 DATA 142,-21,-1,169,255,141,-9
8410 DATA -1,238,-9,-1,174,-9,-1,236
8420 DATA -8,-1,208,3,76,-248,0,172
8430 DATA -8,-1,32,-138,-1,140,-5,-1
8440 DATA 172,-5,-1,177,205,172,-3,-1
8450 DATA 57,-24,-1,240,2,169,1,141
8460 DATA -1,-1,173,-135,-1,240,9,56
8470 DATA 169,1,237,-1,-1,141,-1,-1
8480 DATA 173,-1,-1,208,5,173,0,-1
8490 DATA 240,46,174,-2,-1,173,-1,-1
8500 DATA 240,3,174,-4,-1,142,-212,-2
8510 DATA 173,-8,-1,162,1,172,-9,-1
8520 DATA 32,-195,-1,140,-22,-1,142
8530 DATA -23,-1,32,-16,-2,173,-184
8540 DATA -2,174,-183,-2,172,-185,-2
8550 DATA 32,-187,-2,76,-134,0,76,-89
8560 DATA 0,76,-65,0,96,0,0,0,0,0,0,0
8570 DATA 0,0,0,0,0,0,0,0,0,0,0,0,0,0
8580 DATA 0,0,0,0,1,2,4,8,16,32,64
8590 DATA 128,169,0,141,-135,-1,172
8600 DATA -17,-1,136,177,203,141,-136
8610 DATA -1,16,13,169,1,141,-135,-1
8620 DATA 173,-136,-1,41,127,141,-136
8630 DATA -1,56,173,-136,-1,233,32,16
8640 DATA 12,24,173,-136,-1,105,64
8650 DATA 141,-137,-1,76,-107,-1,56
8660 DATA 173,-136,-1,233,96,16,12,56
8670 DATA 173,-136,-1,233,32,141,-137
8680 DATA -1,76,-107,-1,173,-136,-1
8690 DATA 141,-137,-1,169,0,133,206
8700 DATA 173,-137,-1,133,205,162,3
8710 DATA 24,38,205,38,206,202,208
8720 DATA 248,24,165,206,109,244,2
8730 DATA 133,206,96,0,0,0,142,-193
8740 DATA -1,140,-194,-1,142,-191,-1
8750 DATA 169,0,141,-192,-1,162,3,24
8760 DATA 46,-191,-1,46,-192,-1,202
8770 DATA 208,246,160,255,200,56,173
8780 DATA -191,-1,237,-194,-1,141
8790 DATA -191,-1,173,-192,-1,233,0
8800 DATA 141,-192,-1,16,235,142,-191
8810 DATA -1,96,0,0,0,0,141,-12,-2
8820 DATA 140,-13,-2,169,0,141,-14,-2
8830 DATA 141,-15,-2,24,173,-12,-2
8840 DATA 109,-14,-2,141,-14,-2,169,0
8850 DATA 109,-15,-2,141,-15,-2,202
8860 DATA 208,235,56,173,-14,-2,233,1
8870 DATA 141,-14,-2,173,-15,-2,233,0
8880 DATA 141,-15,-2,56,173,-14,-2
8890 DATA 237,-13,-2,141,-14,-2,168
8900 DATA 173,-15,-2,233,0,141,-15,-2
8910 DATA 170,96,0,0,0,0,174,-10,-1
8920 DATA 208,39,24,173,-14,-1,109
8930 DATA -20,-1,141,-183,-2,173,-15
8940 DATA -1,109,-21,-1,141,-184,-2
8950 DATA 56,173,-12,-1,237,-22,-1
8960 DATA 141,-185,-2,173,-13,-1,237
8970 DATA -23,-1,141,-186,-2,96,202
8980 DATA 208,39,56,173,-14,-1,237
8990 DATA -22,-1,141,-183,-2,173,-15
9000 DATA -1,237,-23,-1,141,-184,-2
9010 DATA 56,173,-12,-1,237,-20,-1
9020 DATA 141,-185,-2,173,-13,-1,237
9030 DATA -21,-1,141,-186,-2,96,202
9040 DATA 208,39,56,173,-14,-1,237
9050 DATA -20,-1,141,-183,-2,173,-15
9060 DATA -1,237,-21,-1,141,-184,-2
9070 DATA 24,173,-12,-1,109,-22,-1
9080 DATA 141,-185,-2,173,-13,-1,109
9090 DATA -23,-1,141,-186,-2,96,24
9100 DATA 173,-14,-1,109,-22,-1,141
9110 DATA -183,-2,173,-15,-1,109,-23
9120 DATA -1,141,-186,-2,24,173,-12
9130 DATA -1,109,-20,-1,141,-185,-2
9140 DATA 173,-13,-1,109,-21,-1,141
9150 DATA -186,-2,96,0,0,0,0,134,85
9160 DATA 133,86,132,84,162,96,169,11
9170 DATA 157,66,3,169,0,157,72,3,173
9180 DATA -212,-2,32,86,228,96,1

Listing. Super TextPlot Demonstration.
Download (Saved BASIC) / Download (Listed BASIC)