There's a lot to explain in Revs, and some of it is pretty challenging stuff. Before getting stuck in, it's probably wise to take a brief look at some of the terminology I've used in this commentary.
Let's start with some general terms.
- Given a number X, ~X is the number with all the bits inverted.
- Given a number A, |A| is the absolute of that number - i.e. the number with no sign, or just the magnitude of the number.
- Given a multi-byte number, (S R) say, the absolute would be written |S R| (see below for more on multi-byte numbers and terminology).
- Coordinates are shown as (x, y), both on the screen and in the outside world, so the centre of the radar is at screen coordinate (140, 207), while the origin for the outside world, which is not far from Acornsville, is at (0, 0, 0).
- Vectors and matrices are enclosed in square brackets, like this:
[ 1 0 0 ] [ x ] [ 0 1 0 ] or [ y ] [ 0 0 -1 ] [ z ]We might sometimes write a column vector as (x y z) instead, just to save space, but it means the same thing as the vertical version. And as vectors and coordinates are often interchangeable, we might also talk about the vector (x, y, z); it's all the same thing under the hood, anyway.
We also need some terminology for multi-byte numbers, but that needs its own section.
Revs uses standard 6502 integers, both signed and unsigned, so for the most part the normal arithmetic instructions work as expected, and two's complement applies. There are some exceptions to this, in the variables (sinYawAngleHi sinYawAngleLo), (cosYawAngleHi cosYawAngleLo), (steeringHi steeringLo) and carSteering. In carSteering, bit 7 is the sign bit, bit 6 is a status bit and the magnitude is in bits 0 to 5, while in the others bit 0 is the sign bit and bits 1 to 15 store the magnitude. This is explained whenever it appears in the source code.
For multi-byte numbers, however, Revs doesn't tend to use the little-endian approach of the standard 6502 instruction set (i.e. where numbers are stored sequentially in memory with the least significant byte first). Instead, Revs stores the individual bytes of its multi-byte variables in totally separate locations, almost never sequentially. This means that we don't have to worry about whether numbers are big-endian or litle-endian, because there is no beginning or end when the bytes aren't together in memory.
It does make it challenging to talk about such disparate variables, though, so let's agree on some terminology to make it easier to talk about multi-byte numbers and how they are stored in memory.
If we have three bytes called xTop, xHi and xLo, which between them contain a 24-bit number with the highest byte in xTop and the lowest in xLo, then we can refer to their 24-bit number like this:
(xTop xHi xLo)
In this terminology, the most significant byte is always written first, irrespective of how the bytes are stored in memory. So, we can talk about 16-bit numbers made up of registers:
So here X is the high byte and Y the low byte. Or here's a 24-bit number made up of a mix of registers and memory locations:
(A S S+1)
Again, the most significant byte is on the left, so that's the accumulator A, then the next most significant is in memory location S, and the least significant byte is in S+1.
Or we can even talk about numbers made up of registers, memory locations and constants, like this 24-bit number:
(A P 0)
or this constant, which stores 590 in a 32-bit number:
Just remember that in every case, the high byte is on the left, and the low byte is on the right. It might help to think of the digits listed in the brackets as being written down in the same order that we would write them down as humans. The point of this terminology is to make it easier for people to read, after all.