Forem: amuletofyendor

Optical Illusion tutorial with the Commodore 64 and DurexForth

amuletofyendor — Wed, 25 Jan 2023 02:31:50 +0000

Hello again. Start here if you don't know what DurexForth is, or perhaps even what a Commodore 64 is.

Let's expand on my previous post with something a bit more fun than yet-another-fizzbuzz.

In this post, we'll implement the "stepping feet" illusion. Here's an example:

Let's think about how to implement this. We'll need the black and white vertical bars, and a way to quickly switch them off to show a plain gray background (thus revealing the illusion). Commodore 64 character graphics seem just about ideal for this.

The coloured "feet" can be hardware sprites moving across this background. Two big rectangles must be just about the simplest sprites we could imagine!

But first, the alternating bars. I want to implement the colours in colour memory, and then just fill the screen with "reversed" spaces to display the coloured bars. That way I can turn off the bars by simply filling the screen with "non-reversed" spaces (which are invisible), leaving the alternating colours intact in the colour memory but allowing the background "screen colour" to show through. I'll make this gray just like in the example.

Let's begin by starting up the DurexForth 'v' editor, and entering some useful constants.

$0400 constant SCREENMEM
$d800 constant COLORMEM
53281 constant SCREENCOLOR
32 constant SPACE-CHAR
160 constant REVERSE-CHAR
12 constant GRAY2

Notice how easily numbers can be entered in either hexadecimal or decimal. You can also enter numbers as binary by prefixing with '%', e.g. %10000011.

Now I'll make a helper word (i.e. a function) to fill the screen with a given character. Although DurexForth is much faster than Basic, using a loop to fill in the screen memory is still noticeably slower than if you were to do it in assembly. Fortunately, there is a better way. Let's take a look at the fill word from the DurexForth manual:

fill ( addr len char — )
Fill range [addr, len + addr) with char.

Note the stack comment, ( addr len char — ). This indicates what values the word will expect to take off the stack (before the dash), and what values it may leave on the stack (after the dash). So, the fill word will consume three parameters from the stack and add nothing back onto the stack. It's good practice to leave comments like this on your own words too, as it helps you to prevent stack overflow or underflow, which will crash your program.

So, using this word to fill the first 100 characters of screen memory with the 'A' character would look like this:

$0400 100 1 fill

where $0400 is the start address of the fill operation, 100 is the number of bytes to fill, and 1 is the byte you want to fill that memory area with (i.e. the character code for the letter 'A').

We want to fill screen memory, so the first two parameters will always be $0400 and 1000. Here's how the helper word looks:

: fillscreen ( char -- )
 SCREENMEM 1000 rot fill ;

first, take a look at the stack comment. This word expects the character code to already be on the stack. Then the word itself will push the SCREENMEM constant onto the stack ($0400), followed by size in bytes of screen memory (1000).

The stack will now contain char addr len. Referring back to the documentation for fill we see that it requires those values in this order: addr len char.

Now let's take a look at the documentation for the built-in stack-manipulation word, rot:

rot ( a b c — b c a )
Rotate the third item to the top.

Substitute a b c for char addr len, and you can see this will give us just what we need. There are many such stack-manipulation words for getting parameters into the required order.

Now we have our fillscreen helper word which we can use to fill the screen with any character we give it. For example, using our predefined character constants:

REVERSE-CHAR fillscreen  \ show the black and white bars
SPACE-CHAR fillscreen    \ hide them again

Next, we'll implement the colours. We can put this into a setup word, as once we've defined these colours, we don't need to touch them again. Also, as this is a one-off setup routine, I don't mind using a slightly slow loop construct.

: coloursetup
GRAY2 SCREENCOLOR c!
1000 0 do
 i 1 and COLORMEM i + c!
loop ;

The snippet i 1 and will give us a zero for even-numbered iterations, and a one for odd-numbered iterations. Fortuitously, these are the colour codes for black and white respectively. c! simply stores a byte at an address. It's POKE with a less silly name.

Let's add a couple of words to test what we have so far:

: mainloop
 REVERSE-CHAR fillscreen
 key drop
 SPACE-CHAR fillscreen
 key drop
recurse ;

: main
 screen-setup
 mainloop ;

The key word gets one character from input and leaves it on the stack. We don't want to use that character for anything, we only want to check if a key has been pressed, so we can discard that value from the stack with the drop word.

Let's try it out. If you're in the 'v' editor, hit F7 to compile and return to the immediate prompt, and then run the main word. Tapping a key will toggle the black and white bars on or off. Hit RESTORE to exit the program ("Page up" on my Vice key mapping... YMMV).

Now let's move on to the sprites. First, let's add some more useful constants to the top of the program:

53280 constant VIC
14 constant SPRITEPTR
4 constant BLUE
7 constant YELLOW

Note that it is common in BASIC to store a base address for the VIC-II registers as V=53280, and then reference the various registers by their offset, e.g. POKE V+21, 3. While I am going to do the same in my program, I'm using the name VIC, so as not to collide with the command to open the 'v' text editor. Despite my convention of using ALL CAPS for constant names, these names are case insensitive so naming this constant 'V' would be a problem.

Here's the wall of POKEs required to initialise the two sprites:

: init-sprites
 SPRITEPTR 2040 c! \ sprite 0
 SPRITEPTR 2041 c! \ sprite 1
 SPRITEPTR 64 * 64 $ff fill \ data
 YELLOW VIC 39 + c!
 BLUE VIC 40 + c!
 \ sprite x expand
 3 VIC 29 + c!
 \ sprite initial position
 50 VIC c!       \ sprite 0 xpos
 100 VIC 1 + c!  \ sprite 0 ypos
 50 VIC 2 + c!   \ sprite 1 xpos
 180 VIC 3 + c!  \ sprite 1 ypos
;

: show-sprites
 3 VIC 21 + c! ;

: hide-sprites
 0 VIC 21 + c! ;

This is straightforward sprite boilerplate. As I mentioned, I'm just poking values into various VIC registers to initialise the sprites, their size, their colour and their positions. I use the fill word again to initialise the sprite data because we just want to turn on every pixel... i.e. a plain rectangle of pixels. There a many resources online which explain the various registers and how to set up your sprites. Here's a pretty good example.

At this point I want to add a value to track whether the black and white bars are currently hidden. This can go near the top of the program with the constants:

0 value hidebars

The syntax for using a value is nice and simple. hidebars will push the current value of hidebars to the stack, and val to hidebars will set hidebars with a new value. In our case we want to toggle the value between true and false, so we'll use hidebars invert to hidebars.

Now all that is left is to modify our main and mainloop words to incorporate the sprites.

: mainloop
 begin
 [ VIC inc, VIC 2 + inc, ]
 100 0 do
  key? if
   key drop
   hidebars invert to hidebars
   hidebars if
    SPACE-CHAR fillscreen
   else
    RVS-CHAR fillscreen
   then
  then
 loop
 again ;

: main
 screen-setup
 init-sprites
 RVS-CHAR fillscreen
 show-sprites
 mainloop ;

Notice that I've used some inline assembly to increment the x-position of the two sprites. This is a rare case where I feel assembly code provides nicer syntax.

The alternative in forth would be:

VIC dup c@ 1+ swap c!
VIC 2 + dup c@ 1+ swap c!

Another change is that I'm now using key? to check whether there is a character available for key. This prevents the program from waiting for input when there is none, which would pause the animation.

Let's take a look at the end result:

Here's the full program:

$0400 constant SCREENMEM
$d800 constant COLORMEM
53281 constant SCREENCOLOR
32 constant SPACE-CHAR
160 constant RVS-CHAR
12 constant GRAY2
53248 constant VIC
14 constant SPRITEPTR
6 constant BLUE
7 constant YELLOW
0 value hidebars

: screen-setup  ( -- )
 GRAY2 SCREENCOLOR c!
 1000 0 do
  i 1 and COLORMEM i + c!
 loop ;

: fillscreen ( char -- )
SCREENMEM 1000 rot fill ;

: init-sprites
 SPRITEPTR 2040 c! \ sprite 0
 SPRITEPTR 2041 c! \ sprite 1
 SPRITEPTR 64 * 64 $ff fill \ data
 YELLOW VIC 39 + c!
 BLUE VIC 40 + c!
 \ sprite x expand
 3 VIC 29 + c!
 \ sprite initial position
 50 VIC c!       \ sprite 0 xpos
 100 VIC 1 + c!  \ sprite 0 ypos
 50 VIC 2 + c!   \ sprite 1 xpos
 180 VIC 3 + c!  \ sprite 1 ypos
;

: show-sprites
 3 VIC 21 + c! ;

: hide-sprites
 0 VIC 21 + c! ;

: mainloop
 begin
 [ VIC inc, VIC 2 + inc, ]
 100 0 do
  key? if
   key drop
   hidebars invert to hidebars
   hidebars if
    SPACE-CHAR fillscreen
   else
    RVS-CHAR fillscreen
   then
  then
 loop
 again ;

: main
 screen-setup
 init-sprites
 RVS-CHAR fillscreen
 show-sprites
 mainloop ;

A Brief Introduction to DurexForth for the Commodore 64

amuletofyendor — Mon, 09 Jan 2023 11:51:10 +0000

Forth is pretty great. In an alternate timeline, the C64 might have had Forth loaded into ROM instead of BASIC (indeed, some other 8-bit computers of the era did just that).

My goal is to keep this post brief and informative, so in that spirit, let's get a few things out of the way.

Why would I want to use Forth instead of Basic?

It's much faster
It allows structured programming (essentially, this means subroutines with parameters and return values)
It's extendable
It's as high level as you want (build as many new capabilities into the language as you want), or as low level (drop into assembly code whenever you need to go even faster).
You might discover you love it
You might even find it's still a handy language for programming small microcontrollers, or deep space exploration probes
Some people even prefer it as a scripting language over the likes of Lua or Python
Because just try to do this in Basic:

What does it look like?

To the uninitiated, perhaps a little odd. Let's take as an example the famous FizzBuzz program. So you'll have a point of reference, I'll first show the algorithm in both a modern c-like language and in Commodore Basic 2.0.

In a modern language, it would perhaps look like this

public static void Main()
{
    for (int i=1; i<=100; i++) {
        if (i%3==0 && i%5==0) {
            Console.WriteLine("fizzbuzz");
        } else if (i%3==0) {
            Console.WriteLine("fizz");
        }  else if (i%5==0) {
            Console.WriteLine("buzz");
        } else {
            Console.WriteLine(i);
        }
    }
}

In Commodore Basic 2.0 (the Commodore 64's "built-in" language), it could look like this

10 I=0
20 I=I+1 : IF I > 100 THEN END
30 IF INT(I/3)=I/3 AND INT(I/5)=I/5 THEN PRINT "FIZZBUZZ"
35 GOTO 20
40 IF INT(I/3)=I/3 THEN PRINT "FIZZ"
45 GOTO 20
50 IF INT(I/5)=I/5 THEN PRINT "BUZZ"
55 GOTO 20
60 PRINT I
65 GOTO 20

A couple of things to note here. First, there is no modulo operator in Basic 2.0, so I'm performing an inline test to check whether a number divides evenly by either 3 or 5.

If we wanted to factor out the modulo operation (sort of), we could do this:

10 DEF FN D3(X) = INT(I/3)=I/3
20 DEF FN D5(X) = INT(I/5)=I/5

Note, however, that only one parameter is allowed, so we couldn't do something like DEF FN DIVIDESBY(I,D) = INT(I/D)=I/D. Additionally, variable names in Basic only regard the first two characters as significant, which is why I've gone for D3 and D5 over the more descriptive names DIVIDES_BY_3 and DIVIDES_BY_5.

Secondly, I'd like to point out that there is no IF, ELSE IF, ELSE structure in basic, forcing the programmer to implement the desired behaviour with the dreaded GOTO statement.

Finally, let's take a look at some Forth

: fizzbuzz
  101 1 do
    i 3 mod 0= i 5 mod 0= and if
      ." fizzbuzz" cr
    else i 3 mod 0= if
      ." fizz" cr
    else i 5 mod 0= if
      ." buzz" cr
    else i . cr
    then then then
  loop ;

Here's a quick guide to all the moving parts:

: fizzbuzz
...
;

Here we are compiling a new word into Forth, fizzbuzz. "Word" is just Forth-speak for a subroutine. You make a program by extending Forth with your own words. In fact there are two "core" words hidden in that snippet, : to define a word and enter the so-called compilation state, and ; to end the current definition.

101 1 do
...
loop

First, we push two values to the parameter stack, 101 and 1. The stack is a first-in last-out data structure which is key to how Forth programs work. It acts as a sort of universal mechanism for passing parameters and returning results.

Now we call the core word do. This consumes the parameters that were placed on the stack and sets up some loop controls variables (on another stack... the return stack. but that's not important right now -- forget I mentioned it).

As you can probably guess, loop is a word marking the end of the loop. In addition to do ... loop, Forth supports begin ... again for endless loops and both begin ... until and begin ... while ... repeat.

i 3 mod 0=

This places two parameters on the stack, i and 3 and calls the mod word, which is a proper built-in modulo operation. mod consumes the two parameters from the stack, and replaces them with the result of the modulo operation.

But what is i? It's a little bit magic, but not really. i is a word that copies the current iteration value from the return stack to the top of the parameter stack. So for the first iteration we'll have 1 3 mod 0=, the next iteration we'll have 2 3 mod 0= and so on.

Next, 0= checks whether the value at the top of the stack is zero, replacing it on the stack with a boolean result. The actual boolean will be represented by either 0 (false) or -1 (true), just like in Basic.

By the way, why 0 and -1 and not 0 and 1? Because the byte representation of -1 is 11111111, which is about as "true" as you can get, and 0 is 00000000, which is pretty darn false. Actually, the stack holds 16-bit numbers, but I digress further from this digression.

Now take a look at this snippet and try to imagine what's happening to the parameter stack at each step:

i 3 mod 0= i 5 mod 0= and

Let's step through it. For the purposes of this demonstration, we'll assume i to be 10

executing...	leaves this on the stack...	note
`i`	`10`	push a value to the stack
`3`	`10 3`	...and another.
`mod`	`1`	the result of 10 % 3
`0=`	`0`	...is not equal to zero.
`i`	`0 10`	our previous result is safe on the stack.
`5`	`0 10 5`
`mod`	`0 0`
`0=`	`0 -1`	we have "false, true" on the stack
`and`	`0`	false and true = false. 10 is not a "fizzbuzz" number

If you're familiar with Reverse Polish Notation, you'll probably see what's going on here. If not, you'll need to familiarise yourself with the concept before you can have much fun with Forth, as it goes hand-in-glove with stack-based programming.

... if ... else ... then

Well we know what this is, but in the spirit of RPN, things are a little backwards.

Let's fill in the gaps:

[predicate] if [true part] else [false part] then

Note the idiomatic role of the word "then". In Basic, you'd read it as "if this predicate is true, then do this". In some languages, e.g. Visual Basic, you'd close it out with "End If".

In Forth, then marks the end of the conditional structure, much like an "end if". So I imagine it means something more like "here's a predicate, if it's true I'll do some stuff here, then I'll carry on and do this other stuff I was going to do anyway."

The three then's near the end of the program make a lot more sense when you think of them as three "end-ifs" at the end of some nested if statements, or even three closing curly brackets if that's more your style.

The final piece of the puzzle is some console IO:

." fizzbuzz" cr

." fizzbuzz" prints some text to the screen, equivalent to PRINT "fizzbuzz";. Note, ." is it's own core word, so the space between that and the text to print is required.

cr is another core word which prints a carriage return, so ." fizzbuzz" cr is simply equivalent to PRINT "fizzbuzz"

This code does not affect the stack in any way.

Finally, the last piece of the puzzle:

i . cr

i pushes the value of i to the top of the stack, then . prints the top item on the stack to the screen (removing it from the stack in the process), and cr as mentioned will print a carriage return.

And that's the end of this gentle introduction. I'll most probably do a few more posts showing some fun stuff that can be done on the Commodore 64 in particular. For now, I didn't want to assume too much prior knowledge. Hopefully you, the reader, now have a feel for what Forth is, and what it looks like. Next time we can really take it for a spin.

Some links for the curious:

DurexForth's Operators Manual
Jeff from Hey Birt! Installs DurexForth
Robin from 8-Bit Show and Tell explores 64Forth, an older version of Forth for the C64

Forem: amuletofyendor

Optical Illusion tutorial with the Commodore 64 and DurexForth

A Brief Introduction to DurexForth for the Commodore 64

What is a Commodore 64?

What is Forth?

What is DurexForth?

Why would I want to use Forth instead of Basic?

What does it look like?