.........1.........2.........3.........4.........5.........6.........7.........8

LIGHT SCREEN DESIGNER
ZX Computing, June 1986
Part 13 of 13

Now that the machine code is complete, Toni Baker gives you the full
details of how to use Light Screen Designer.


This article comprises an overall view of the Light Screen Designer
program which has been serialised in ZX Computing. It is intended as
(a) an overview, and (b) a guide as to how the program may be extended
or improved by you, the user.


Getting started

[C000 = 49152; DB00 = 56064; EA16 = 59926; 59926 - 56064 + 1 = 3863]

The program should be SAVEd as CODE, occupying addresses DB00 to EA17
[The last byte used is EA16. JimG] . To load the program you should
type CLEAR 49151, followed by LOAD "LSD" CODE (or equivalent
microdrive or whatever version). A Basic program of your own may be
loaded or typed in either before or after this. Once the program is in
memory it may be activated either from a Basic program, or by the user
as a direct command. The instruction needed to activate it is
RANDOMIZE USR 56789. (The number 56789 was specially chosen so as to
be easy to remember). Having done this the message "Light Screen
Designer" will appear at the bottom of the screen. You must now press
the SPACE key once and you're away. (In this program, SPACE is used as
an ESCAPE key - in this instance we are "escaping" from the opening
message).


Cursor movement

The program uses three cursors, two of which are on screen at all
times. The cursors are printed as small crosswires, and each pixel of
these crosswires is XORed with whatever is on the screen. This means
that whenever two cursors fall directly on top of each other, both
will become invisible. This may happen the first time you activate the
program when two cursors will be initialised at the top left hand
corner of the screen. Keys 5, 6, 7 and 8 are single-step cursor keys,
and these will move the main cursor one pixel at a time in any
direction, without altering the contents of the screen. If these keys
are pressed together with CAPS SHIFT then continuous cursor movement
is provided. On a Spectrum+ or a Spectrum 128 the built-in cursor keys
will also give continuous cursor movement.

Once you've practiced moving the MAIN cursor around the screen try
pressing "A". At first, both cursors will appear to vanish, but if you
play with the cursor controls a little more you'll see that what has
happened is that the second cursor (the ORIGIN cursor, as we shall
call it) has simply been moved to the position of the MAIN cursor. By
this method you can move both the MAIN cursor and the ORIGIN cursor to
any position on the screen.


Lines, rectangles and triangles

Try this: put a good distance between the two cursors and then press
"W". You'll find a line should be drawn between the two points. Also,
the cursors will appear to vanish because the ORIGIN cursor will have
moved to the end of the line (on top of the MAIN cursor). This means
that you can draw a continuous sequence of straight lines. Now - move
the cursors apart again and press "J". You should find a rectangle
drawn, with the two cursors at opposite corners. Now we shall learn to
use the third cursor, called the MARKER cursor. Move the MAIN cursor
anywhere you like and press "S" - a third cursor will have appeared at
the main cursor position. Move the cursor again and press "A" to move
the ORIGIN cursor. Finally move the cursor for the last time so that
the three cursors form a triangle. Press "K", and a triangle should
appear between the three points.

As you will have gathered from the above description, general
operation of the program consists solely of moving cursors around the
screen and pressing buttons, and each button has a different effect.
At present there is no menu provided with the program, so it's best to
provide yourself with a keyboard diagram such as that in Figure 1
[PART13.GIF]. If you own an old Spectrum (ie. not a Spectrum+ or a
Spectrum 128) then you can actually cut holes in your diagram and lay
it over the keyboard so that you can see at a glance what you're
doing. Alternatively, if you wish to add a menu to the program,
instructions to do so are included later in this article.

Users of the Spectrum+ and Spectrum 128 should note that both symbol
shift keys will operate the BRIGHT function, and that caps shift keys
are not needed in the present version (except to produce capital
letters when using text) since the built-in cursor keys make it
unnecessary ever to use CAPS SHIFT 5, 6, 7 and 8.


The UNDO procedure

This is perhaps the most important of all the procedures. Located on
key "0", the procedure will undo the last command performed - which
means that if you make a mistake you can rub it out.

We've seen some of the controlling procedures already - cursor
movement, along with MOVE and MARK ("A" and "S" respectively). There
is a third controlling procedure on "D" - CANCEL MARK, which removes
the marker cursor from the screen. STORE and RECALL ("3" and "4") may
be used to store and recall the position of the MAIN cursor. Very
simply, there are ten memories numbered zero to nine. To store the
position of the main cursor in memory seven, just press STORE ("3")
and then "7". Similarly, to move the main cursor to the position
stored in memory two press RECALL ("4") and then "2". It is also
possible to temporarily store the whole screen! To do so press STORE
("3") and then ENTER. Conversely, to restore a stored screen press
RECALL ("4") and then ENTER. Note that whilst a screen is stored in
this manner UNDO will not work. To clear the screen memory you should
press CLEAR MEM ("I") which will enable UNDO to work again as normal.
Finally, one last controlling procedure is ESCAPE (SPACE). This
procedure will ask you whether or not you wish to return to BASIC. You
may then press "Y" (to return to BASIC), or "N" (to continue with
Light Screen Designer). As always, you may alternatively press ESCAPE
("SPACE") which in this case has the same effect as "N".


CLS and colours

Light Screen Designer will always print things in the current ink
colour, with the current paper colour as background. It has therefore
been made very simple to change these colours. Simply press PAPER
("C") followed by "6" for PAPER YELLOW; INK ("X") followed by "9" for
INK CONTRAST; OVER ("N") followed by "1" for OVER ON; BRIGHT ("Symbol
Shift") followed by "8" for BRIGHT TRANSPARENT, and so on. CLS is on
key "9". All of the colour controls except BRIGHT (INK/PAPER/FLASH/
OVER/INVERSE) are in the same position that you would normally expect
to find them on the Spectrum keyboard. BRIGHT is now on the Symbol
Shift key, with BORDER taking its place on key "B". As always - if you
start a procedure, and then decide you want to abandon it you can
press ESCAPE which will return you to Light Screen Designer.

To copy a screen onto the ZX Printer you should press key "Z" (COPY).
You will then be asked to press either "Y" or "N". Pressing "Y" will
copy the screen as required - this is identical to the COPY routine in
BASIC. At present there is no built-in facility for loading or saving
screens, but this is nonetheless extremely simple to do. To save press
ESCAPE followed by "Y" (to return to BASIC) then type SAVE "FILENAME"
SCREEN$. If you then wish to continue drawing the screen you should
type RANDOMIZE USR 56789. Similarly, to load, simply return to BASIC,
use LOAD "FILENAME" SCREEN$ to load the picture in the normal way, and
then use RANDOMIZE USR 56789 to continue Light Screen Designer.


Geometry

The geometry procedures of Light Screen Designer are very good indeed.
PLOT to plot a single point; LINE to draw a line; and TRIANGLE and
RECTANGLE are self explanatory. There are three procedures for drawing
an ARC - in each case an anti- clockwise arc will be drawn from the
ORIGIN cursor to the MAIN cursor. ARC (THROUGH) will draw an arc
through the marker cursor (if this is possible), ARC (USING) will draw
an arc using the marker cursor as the centre of the circle of which
the arc forms a part (again if this is possible), and ARC (RAD)
requires the user to input the number of radians required for the arc.
This latter variation is the closest to BASIC. PARALLELOGRAM will draw
a parallelogram using three points given as three of the corners (the
fourth corner will be worked out for you, positioned diagonally
opposite the MARKER cursor). QUARTER ELLIPSE will draw a quarter
ellipse anti-clockwise from the ORIGIN cursor to the MAIN cursor - the
two ends of such an ellipse will always slope horizontally and
vertically. ELLIPSE will draw a complete ellipse at any angle. Simply
position the ORIGIN cursor and the MAIN cursor at either end of the
major axis, and the MARKER cursor somewhere along the intended curve.
An ellipse will be drawn passing through all three points. Finally
there are two procedures for drawing a circle: CIRCLE (THROUGH) will
draw a circle passing through all three points, and CIRCLE (CENTRE)
will draw a circle passing through the MAIN cursor, using the ORIGIN
cursor as its centre.


Colouring in

PAINT and FILL are both designed for colouring in existing outlines.
FILL is intended for black and white pictures (or at least simple
ones) and will INK every pixel within the outline in the current ink
colour. Pictures coloured in this way will copy perfectly well on the
ZX Printer using COPY. PAINT is intended for more complicated colour
pictures, and will intelligently decide for itself whether to PAPER or
to INK any given pixel, so that two adjacent outlines may both be
coloured in different colours. PAINT will not always use the current
ink colour, but will ask you which colour you wish to use.


Miscellaneous

CURSOR TYPE (key "O") toggles the cursor image between small
crosswires (this is most usual) and a small dot. HIDE ("ENTER')
toggles whichever cursor you've chosen between visible and invisible.
Finally USR (key "L") requires you to input a four digit hexadecimal
address. A machine code subroutine at that address will be called.
This last feature means of course that Light Screen Designer can be
made to do anything whatsoever, and can integrate with other machine
code programs.


Text

To type text on the screen from Light Screen Designer it is necessary
to enter text mode, which is done by first of all moving the cursor to
wherever [text] is required, and then pressing key "P" (TEXT). Text
does not have to be printed exactly on a character square, but may
overlap as many squares as are required. The text may be printed in
italics if desired. Once you are in text mode sym-shift-Q will switch
italics off, sym-shift-W will switch half-slope italics on, and
sym-shift-E will switch on full-slope italics.

Additional functions are available on the editing keys: TRUE VIDEO (or
caps-shift-3) will toggle between seven and eight pixel wide
characters; INV VIDEO (or caps-shift-4) will toggle between bold type
and ordinary type; GRAPH (or caps-shift-9) will enter or leave
graphics mode, enabling you to enter graphic symbols or UDGs as text;
EXTEND MODE (or both shifts together) will enable you to change the
size of printed text - simply press EXTEND MODE (or both shifts
together) followed by the cursor keys in any order, followed by ESCAPE
("SPACE"). BREAK (or caps-shift-space), or ENTER, will enable you to
exit text mode. All of the symbols may be printed. Symbol-shift-I will
produce the copyright symbol; if you own a Spectrum+ or a Spectrum 128
then ".", ",", ";" and """ are available on separate keys; all
remaining symbols may be obtained by holding down symbol-shift and
pressing the key on (or under or over) which is printed the desired
symbol. It is never necessary to enter E-mode. To leave text mode and
return to Light Screen Designer proper you should press either BREAK
or ENTER.


Extending and improving Light Screen Designer

The "core" of the Light Screen Designer program is the main loop which
occupies addresses DE17 to DE9D. This piece of program makes reference
to a table called NULL_TABLE which occupies addresses DEAD to DEBD.
Slotted neatly between these two is the ESCAPE routine (DE9E to DEAC).
The present purpose of the NULL_TABLE is to list the key codes of
those procedures for which it is not necessary to copy the screen into
the back up screen area SCR2 (C000 to DAFF).

To extend the program an extensive reorganization of memory would be
required. Very simply, the first three bytes of the main loop (at
DE17) should be replaced by a single machine code JP instruction. The
ESCAPE routine should be moved from DE9E down to DE1A. To do this the
ESCAPE entry in the command addresses table must be changed, so the
two bytes DB82/DB83 must contain the new address of DE1A). Once you
have done this the addresses between DE27 and DEBD will all be free,
and you can then use them for whatever you like. New code should be
added at the end of the program - addresses EA17 to FFFF are at
present unused, so there's lots of room. The first new piece of code
should be a new version of the main loop - you can make this as close
to the original as you like, or you can make it drastically different.
One obvious improvement you can make is to implement a potential
thirty-nine new procedures, all on CAPS-SHIFTed keys. You can
initially make the new procedures the same as the old ones, simply by
directing control to precisely the same addresses, and then change
them as you add new procedures one at a time. A menu would be a good
procedure to add - you could put it on CAPS SHIFT 1 (this is
equivalent to the EDIT key on the Spectrum+ and Spectrum 128).
Pressing ESCAPE would escape from the menu and take you back to Light
Screen Designer proper (the original screen will have been preserved
in SCR2), or pressing ENTER would continue the menu, giving the
additional procedures available on shift.

The main loop itself could be drastically changed too. Potentially you
could make the cursor move at variable speed (slow at first, then
speeding up) - you could add a PENUP / PENDOWN feature so that the
cursor draws as it moves - you could use the bottom two lines of the
screen to display information about the exact coordinates of the three
cursors at all times - and so on. The possibilities are endless.

Well, this brings me to the end of the series. Good programming
everyone, and I hope this series has been informative. I'll be back
with a new series soon. Bye till then, and may the force be with you.


-----------------------------------------------------------------------------
LIGHT SCREEN DESIGNER FROM A
MACHINE CODEIST'S POINT OF VIEW

The memory layout of Light Screen Designer is as follows:

C000 to DAFF: SCR2	Back up copy of screen.
DB00 to DB03: ORIGIN_2	Back up copy of origin cursor position.
DB04 to DB07: MARKER_2	Back up copy of marker cursor position.
DB08 to DB0B: CURSOR_2	Back up copy of main cursor position.
DB0C to DB0F: ORIGIN	Origin cursor position.
DB10 to DB13: MARKER	Marker cursor position.
DB1A to DB17: CURSOR	Main cursor position.
DB18 to DB3F: MEMORY	Ten 4-byte memories capable of storing
			cursor position.
DB40 to DB41: JFLAGS	Two bytes of flags.
DB42 to DB8F: CMD_ADDRS	Table of addresses for main procedures.
DB90 to DB9F: INP_TABLE	Table of acceptable inputs for use with
			message printing.
DBA0 to DCB4: MES_TABLE	Messages which may appear at bottom
			of screen.
DCB5 to DDDA:		Subroutines associated with cursor
			drawing and message printing.
DDD5 to DE16: START	Initialisation (Note: 56789d = DDD5h).
DE17 to DE9D: MAIN_LOOP	Main structure of program.
DE9E to ....		Main procedures.


Any improvements or alterations made to Light Screen Designer will
almost certainly involve changing the main loop at address DE17, so I
will describe how to do this later on [see "Extending and improving
Light Screen Designer" above. JimG]. First though, let's look at some
of the individual subroutines which may be used with your own
programs; either in conjunction with the Designer, or by taking out
such subroutines and using them separately.

E0C9 - LINE_LENGTH
[There is no subroutine called LINE_LENGTH. The routine at E0C9 is called]
[CIRCLE_ARGS, which seems to do what is described here.                  ]
Calculate the distance, L, from (M0,M1) to (M4,M5). Memories M0 to M3
are corrupted. Three additional entries are left on the calculator
stack: In order: M1, M0, L.

E106 - MATRIX
[MATRIX is actually at E0DA.]
Given p,q on [the] calculator stack, solve the simultaneous equations:
	M0*x + M1*y = p
	M2*x + M3*y = q
On exit M4 will contain p, and M5 will contain q. The calculator stack
will contain, in order: x, y. Note that if the equations are
unsolvable then a triple-return [Eh?] will be performed.

E168 - INPUT_ITEM:
Will INPUT an Item and leave that item on the calculator stack. The
subroutine requires the existence of a "prompt" string which must end
in "ENTER" (in fact with INPUT NUMBER and INPUT LINE the prompt string
may consist of "ENTER" only, but with INPUT STRING it should at least
contain two quote marks followed by "ENTER"). On entry A must contain
20 (input string), 60 (input number), or A0 (input line). C must
contain the number of characters in the prompt string, B must contain
the position within the prompt string of the flashing I or C cursor,
and HL must point to the "ENTER" character at the end of the prompt.

E265 - ANGLE:
Calculates the angle, A, subtended at (M2,M3), by the line (M2,M3) to
(M4,M5), and the horizontal (positive x axis). On exit A is left on
the calculator stack.

E3OD - T_CHR:
Wait until a key is pressed, then return all symbols without the
necessity of enter[ing] E-mode.

E64A - CURVE:
Draw a curve - any curve whatsoever - on the screen. On entry BC must
contain the number of line segments needed to draw this curve, and HL
must contain the address of a subroutine which when called will leave
the coordinates (X,Y) of the next point on the curve at the top of the
calculator stack. Note that such a subroutine is likely to use the
calculator memories, and that some of these may need to be initialised
first.
-----------------------------------------------------------------------------
