Spectrum Tool Kit

Spectrum Tool Kit





Bobby Rao offers some handy hints to


would-be machine-code users. Here are


some useful off-the-peg routines.





Here are about 20 machine-code graphics routines, any com-


bination of which may be used in your programs to enhance


the screen displays, or to give them that extra touch of


elegance that comes only from the use of machine code. Also


included are renumber and memory-left routines which may be


used to aid your programming.


No understanding of machine code is necessary to use the


routines - just a good working knowledge of the Spectrum


and its manual. Machine code is the computer's first lan-


guage - it only speaks Basic out of courtesy to humans -


and its use results in greater speed, flexibility and more


economical use of memory than does the use of Basic.


To get the machine code into the computer a hex loader


must be used - see program 1. Type this in and save it.


Machine code can either be stored above RAMTOP or in a REM


statement at the beginning of a program. I prefer the


latter method, for each different routine may be stored in


a REM statement with a different line number and then


merged into a program as required. However, if you wish to


use the first method then change line 5 as shown under-


neath the program listing. [I.e., "change line 5 to read


5 CLEAR x: LET a=x where x is the address they need to move


RAMTOP to". Note that this is wrong, though: it should read


"CLEAR x-1", unless you like confusing the GO SUB stack.]


Here is an examnple of how you go about loading in the


memory-left routine, see figure 1. [Or rather, listing 1;


it's on the TZX as "memoryleft".] First load in the hex


loader and type in a REM statement as line 1. This REM


statement should consist of 14 full stops because the


memory-left routine is 14 bytes - characters - long. If you


are using the RAMTOP method then you will not need to do


this - just CLEAR yourself enough memory space above


RAMTOP. Now carefully type in the DATA line in figure 1 and


after checking this line run the program. Listing it will


show that line 1 is now a meaningless jumble - if you have


a line 1, that is - but do not worry, for this is supposed


to happen. Also it is likely that listing the program when


the REM line is in this state will cause the computer to


stop with an error report. To avoid this and view the rest


of the program you must always used LIST -line number of


first line after the REM line- so that the Spectrum does


not try to list the unlistable REM line.


Now the routine is ready to be saved. Erase all of the


hex loader except the REM line - do not use NEW whatever


you do - and save this with a filename like "Mem Left".


Now NEW the computer and reload the hex loader. Repeat the


above process for the rest of the routines, but make sure


you never use the same REM line number for two different


routines because this will cause trouble when you come to


merging routines together. [Which would a good trick,


seeing that REM must be the first line of the program and


the first line of the loader is line 5...]


RAMTOP-method users may save their routines by using the


SAVE filename CODE method detailed in the manual on pages


143 and 180.


[ And now the method for TZX-users, which is even simpler.


Load the program called "Hexloader", then merge the


required routine (e.g., "memoryleft"). Note that a. the


mergeable routines have their required REM statements


already added; b. each of these has a different line


number; c. to accomodate this, the hexloader starts at


line 1000 instead of at 5. Note also that you will get the


error "E Out of DATA, 1010:2"; this is normal and would


also have occurred, albeit at line 10 instead, had you


typed in the listings yourself.


And if you want it even easier: at the end of the TZX,


you will find pre-REMmed versions of all routines, with


all the other lines removed. Just merge them into your


program and you're ready to go. They're the ones with the


capitals in the names (e.g., "ScrInvert", where the


version for the loader would be "scrinvert".]


Once the tedious task of typing in and saving the rou-


tines has been accomplished [you're welcome] you are ready


to use these routines. If you wish to use some of the rou-


tines in one of your programs then start that program at,


for example, line 100, leaving the earlier line numbers


free for the machine-code REM lines. After typing in the


program, merge in the routines you require. To run machine


code rather than Basic the USR function must be used.


The argument of this function is the address of the first


byte of the machine-code routine you want to run, and this


may be found, if you are using the REM method, by using


program 2 [on the TZX as "linefinder"]. On running this


program - whilst the machine-code routines are in the


computer - line numbers and the start addresses of the


routines in those lines are printed until the computer


finds a non-REM line, when it will stop. Note these start


addresses down, or better still, define variables equal to


these values by placing a lot of LET statements somewhere


in your program, for example:


LET inv=23760


Now just typing PRINT inv will tell you the address of the


first byte of the invert-screen routine.


RAMTOP method users will not need to use program 2


because they will already know the addresses of their rou-


tines or they would not have been able to get them above


RAMTOP in the first place.


To use the routines use the command RANDOMIZE 0*USR X,


where X is the address of the routine you are using. The


result of the USR function is multiplied by 0 to keep RND


truly random, that is, it acts like a RANDOMIZE 0 command.





Below there is a description of all the routines and how


to use them. In these descriptions the variable X stands


for the address of the first byte of the routine in ques-


tion. All numbers are in decimal and unless otherwise


stated all the screen routines operate on all 24 lines of


the screen.


When you are told to poke something somewhere the pokes


must be done before you use the routines and they may be


entered as a series of direct commands before you run the


program or they may be built into the program.





Memory Left: running this, listing 1 ["memoryleft"],


using PRINT USR X will tell you the exact number of free


bytes of memory you have left.


Hi-Res Up Scroll: this, listing 2 ["hiscrup"], routine


scrolls the screen up by one hi-res pixel, replacing the


bottom line of pixels with blanks.


Hi-Res Down Scroll: as in listing 2, but this - listing 3


["hiscrdown"] - scrolls down, blanking the top line of


pixels.


Hi-Res Left Scroll: this scrolls the screen left one


pixel, replacing the rightmost column of pixels with


blanks. See listing 4 ["hiscrleft"].


Hi-Res Right Scroll: as in listing 4, but listing 5


["hiscrright"] scrolls right, blanking the leftmost column


of pixels.


One Character Left Scroll: the listing 6 ["chscrleft"]


routine scrolls the screen left one character, replacing


the rightmost column with either blanks - for this effect


POKE X+16,54 - or the previous leftmost column, a wrap-


around effect - for this POKE X+16,119.


One Character Right Scroll: the listing 7 ["chscrright"]


routine scrolls right. POKE X+16,54 causes the leftmost


column to be blanked and POKE X+16,119 replaces this


column with the previous rightmost column.


These last two routines are adjustable in which part of


the screen they scroll, but you only have five options. The


table below tells you how to adjust the routines. The first


column tells you which part of the screen is to be


scrolled. The next two columns tell you what to poke in X+1


and in X+4 respectively for the left scroll routine. The


last two columns tell you what to poke in X+1 and X+4


respectively for the right scroll routine.


Top one-third 64 64 64 71


Middle one-third 64 72 64 69


Bottom one-third 64 80 64 87


Top two-thirds 128 64 128 79


Bottom two-thirds 128 72 128 87


[ Whole screen 192 64 192 87 - these were not


given in the article, being the default setting when you


poke nothing at all, but they're useful to know if you want


to restore them after using the others.]


Invert Screen: the listing 8 ["scrinvert"] inverts the


actual pixels on the screen, that is, all pixels on are


turned off and all pixels off are turned on, and so it is


different from the INVERSE function on the Spectrum which


only inverts the INK and PAPER colours - which this routine


does not alter.


Screen Fill: this routine, listing 9 ["scrfill"], fills


in a box of height a, width b, and a top left-hand corner


at point c,d - where c and d are co-ordinates used by the


PRINT AT system - with any character of your choice.


POKE X+1,character code POKE X+3,a


POKE X+4,c POKE X+6,b POKE x+7,d


So if a=22, b=32, c=0 and d=0 then the normal 22-line


screen is filled. You must have printed something somewhere


before using this routine or it will not work properly.


Also note that you cannot print on line 24 with this


routine.


Ink Change: this - see listing 10 ["chngink"] - changes


the ink colour of the screen without altering anything


else. Poke X+1, the number of the colour you want to change


the ink to.


Paper Change: as listing 10 but changes the paper colour.


Poke X+1, the number of the colour you want to change the


paper to. See listing 11 ["chngpaper"].


Flash On/Off: this routine, listing 12 ["chngflash"],


sets the whole screen flashing - for this POKE X+9,254 - or


returns the screen to normal non-flashing mode - for this


POKE X+9,190.


Bright On/Off: the routine shown in listing 13


["chngbright"] makes the whole screen bright - POKE X+9,246


- or returns it to normal brightness - POKE X+9,182.


Attr Fill: the fourteenth listing ["attrfill"] changes


the attributes for a box height a, width b and of top left-


hand corner at point c,d wheew c and d are co-ordinates


used by the PRINT AT system to denote a point on the


screen.


POKE X+3,d POKE X+4,c POKE X+6,b


POKE X+7,a


POKE X+1, the value you want to change the attributes to.


This value may be calculated thus: first assume that the


new ATTR value is Y and initially Y=0. If flash is on add


128 to Y, if off add 0. If bright is on add 64 to Y, if off


add 0. Add eight times the number of the paper colour to Y.


Add the number of the ink colour to Y.


This means that an attribute of flashing, bright yelllow


ink on blue paper would be 128+64+(1x8)+6=206.


With this routine you can change the attributes of the


whole 24-line screen.


Attr Up Scroll: this routine, listing 15 ["atscrup"],


allows you to scroll up the attributes for a box height a,


width b, and top left-hand corner at point c,d. The bottom


line of the box is replaced with an attribute of value Y -


see Attr Fill for how to calculate Y.


POKE X+1,y POKE X+3,d POKE X+4,c


POKE X+6,b POKE X+7,a


Attr Down Scroll: listing 16 ["atscrdown"] scrolls down


replacing the top line of the box with the new attribute.


The pokes are the same as for the previous routine.


Attr Left Scroll: as listing 16 but scrolls left re-


placing the rightmost column of the box with either a new


attribute - for this POKE X+36,0 - with what was previously


in the leftmost column of the box - for this POKE X+36,26.


This last effect, wrap-around, allows this routine to be


used fully with the one character left scroll routine given


above. See listing 17 ["atscrleft"].


Attr Right Scroll: the routine shown in listing 18


["atscrright"] scrolls right, replacint the leftmost column


of the box with either a new attribute - for this POKE


X+43,0 - or with what was previously in the rightmost


column of the box - for this POKE X+43,26. This last effect


allows this routine to be used fully with the one charac-


ter right scroll given previously.





The next three routines allow you to store screens cur-


rently being displayed in spare memory and then recall them


on to the display, either making them swap memory position


with the screen currently being displayed, or overprinting


them on to the current display. To store screens you must


firstly CLEAR some memory space so you can store the


screens there. Each screen - with attributes - is 6,912


bytes long, so this much space is required for each screen.


The memory location of RAMTOP - the last byte of the


computer's memory - can be found by using PRINT PEEK 23730+


256*PEEK 23731. If this number is W then W-Q*6912 - where Q


is the number of screens to be stored - will tell you the


address to CLEAR RAMTOP to - see manual page 168. You must


have cleared this space or the routines will not function


correctly.


If you only have 16K of memory then space exists for


storing only one screen so CLEAR 25685 is all you need to


use. In order that the routines know where in the memory a


screen is to be fetched from or sent to you must do the


following for all the routines:


POKE X+1,W-256*INT(W/256)


POKE X+2,INT(W/256)


If you have 48K and you wish to store more than one screen


then it might be advisable to leave a gap of a few bytes in


between screens so as to lower the risk of one screen


running over on to another by accident.


If you are using the RAMTOP method for storing the


machine-code routines then be extra careful, or you will


end up ruining the routines and crashing the computer. Make


sure you take into account the length of the routines when


deciding where you CLEAR RAMTOP to.


Store Screen: This replaces the current display with one


already in the memory. See listing 19 ["scrstore"].


Swap Screens: This routine swaps the current display with


one higher up in the memory so that the screen that was


being displayed is stored in the memory and the screen that


was in the memory is now displayed. See listing 20.


["scrswap". The listings for this and the next routine were


printed the other way 'round in the magazine. The order on


the TZX is the one in this text.]


Overprint Screens: This overprints a screen from higher


up in the memory onto the current display. The old display


is lost in its original form - it is not stored anywhere by


this routine before it is altered - but the screen used to


PRINT OVER the old display still remains intact higher up


in the memory. [Note that this, and the reversible nature


of OVER, means that you can get the original screen back by


calling the routine a second time.] The attributes are not


changed by this routine so after the routine has been used


the attributes being displayed are those of the old


display. See listing 21 ["scrover"].





Renumber: this routine, listing 22 ["renumber"...],


instantly renumbers all the line numbers of your program


starting the first line at a specified value and increasing


this value by a specified amount as it renumbers the rest


of the lines. Note that this does not change the GO TOs and


GO SUBs so you will have to alter these manually. If the


first line is renumbered L and the value by which L is in-


creased is M then


POKE X+5,M-256*INT(M/256)


POKE X+6,INT(M/256)


POKE X+8,L-256*INT(L/256)


POKE X+9,INT(L/256)


For fun you might try renumbering all lines 0 or try using


a starting value greater than 9999.





The uses of these routines are many and varied, limited


only by the imagination of the user. For example, the left


and right scrolls with wrap-around may be used to create a


constantly moving background for a space game. Any of the


scrolling routines may be used to clear all or part of the


screen in a novel way.


The ink and paper changing routines may be used to create


a surprise effect by first drawing a picture on the screen


using the same ink and paper colour and then altering


either so that the picture appears instantly. Animated


cartoon effects are possible using the screen swapping


routines and stunning explosion effects may be simulated by


using the Invert Screen routine repeatedly - in a loop. The


list is endless and these are just a few broad guidelines


that you can experiment with and doubtless improve on.





Just as a bit of fun try the following POKE next time you


have a program in your Spectrum: POKE 23606,8. This makes


the computer speak Russian - nearly. POKE 23606,0 restores


normality. [No, I have no idea what this has to do with the


rest of the article, either.]