(back to project page)

# Atari Math Box

The 1.5MHz 6502 CPU used in Battlezone, Red Baron, and Tempest wasn't fast enough to perform the arithmetic required for a 3D game at a reasonable frame rate. To make the game possible, Atari engineers devised the "math box", a board with a 16-bit ALU constructed from four 4-bit AMD 2901 microprocessors.

The best description of what the math box provides is the MAME source code, which simulates the features without emulating the hardware and ROM. Some more human-readable explanations of the feature set can be found on the Retrocomputing Q&A site, but to really understand what it does you also need to see how it's used by a game. The math box is not a collection of general-purpose math functions, but rather an implementation of features required specifically for 3D games.

If you want to see a first-person tank game implemented in 6502 assembly without additional hardware, see the Stellar 7 disassembly.

### Background: Fixed-Point Math

(This is intended as a quick introduction for anyone not familiar.)

Performing arithmetic with floating-point numbers is too slow for use in a game on 8-bit hardware. Some games used 8.8 fixed-point numbers, where a 16-bit value has the integer part in the high byte and the fractional part in the low byte. While addition and subtraction work the same as they do for 16-bit integers, multiplication and division require minor adjustments.

Suppose we want to compute 9.5 x 3.75 = 35.625. In 8.8 fixed-point the inputs would be represented as \$0980 and \$03c0. Multiplying them together yields the 32-bit value \$0023a000. To get the result we want, we need to shift it 8 bits to the right, to get the 16-bit value \$23a0 (\$23=35, \$a0=160, 160/256=0.625, so it all checks out). Fixed-point arithmetic code will either right-shift to adjust the magnitude, or will construct its loops in a way that leaves the result properly positioned.

Division has complimentary behavior: the dividend must be shifted to the left before the operation is performed. To compute 9.5 / 3.75, we divide the 32-bit value \$00098000 by \$03c0 to get \$0288 (2.53125).

If the inputs have placed the fixed point differently, e.g. we're multiplying by an 8.0 integer or a 0.16 fraction, the size of the pre- or post-shift must be adjusted accordingly.

Signed values require additional consideration. Suppose you multiply the 8.0 value 7 (\$07) by the 0.8 fractional value 0.5 (\$80). You multiply them to get the 8.8 value \$0380, then shift right 8x to keep the integer part (\$03). All good. If you instead have a signed 0.8 value, it could be +0.5 (\$40) or -0.5 (\$c0). Multiplication works by sign-extending the fractional part before performing the multiplication (or by working with absolute values and tracking the sign). In this case we'd multiply \$07 by \$ffc0, yielding \$fe40, which we would shift right 7x to get the integer (\$fd = -3). We right-shift one fewer time because the sign bit doesn't count as a fractional bit. It's more accurate to describe a signed 8-bit fraction as a 1.7 value.

### Battlezone's 3D Coordinate System

Objects in three-dimensional space have a position and an orientation. 3D rendering involves moving things around in 3D space and then projecting the result onto a 2D surface (the screen).

Jed Margolin's "Unit Vector Math for 3D Graphics" describes a left-handed coordinate system in which +X points into the monitor, +Y to the right, and +Z up. The game itself does seem to use a left-handed system, but rotated 90 degrees: when the player is facing angle 0, moving forward increases Y. Turning slightly left increases the angle, and moving forward begins to increase X as well.

The Battlezone sources apply the coordinate system inconsistently. For example, the logo that slides off into the distance is in three parts, "Ba", "ttle", and "Zone". "Ba" is above and to the left of the center point and tilted into the screen, so all values should be +X/-Y/+Z, but if you look at the vertex list you'll note that all of its coordinates are positive. It's necessary to flip the object coordinates to make it come out right. (The vertex transformation code appears to do this.)

For the sake of sanity it's useful to apply a more common set of labels to the various axes: +X to the right, +Y up, +Z into the monitor. The trouble with doing so is that, as the viewer sees it, +X is to the left. Except, as it turns out, it isn't: the vertex transformation code negates the screen X coordinate, essentially mirror-imaging the screen. So +X is to the right where it should be when most of the math is being performed, but ends up on the left at the end. Which works right for some things, but reverses the direction of rotation.

The labeling used in the disassembly was chosen because it makes the math in the game work with the fewest mental remappings: +X to the left, +Y up, +Z into the monitor. When facing angle 0 you're looking toward +Z; increasing the angle rotates counter-clockwise toward +X. It looks like this: Happily, the 2D coordinate system used for the monitor is conventional Cartesian: center at (0,0), +X/+Y to the right and up.

### API Overview

A simple way to think about the math box is as an opaque device with 32 8-bit inputs and three 8-bit outputs. When the 6502 writes a value to one of the inputs, the math box takes the byte of data and executes a function. Some of the functions simply save the data, some perform complex operations. All functions write a 16-bit value to the output, setting and clearing a "device busy" flag so the 6502 can tell when the computation has finished.

The 6502 does not need to wait for the "busy" flag to clear after every operation. (I don't know the details here. The MAME mathbox.cpp implementation always executes "instantly".) In some cases the Battlezone code simply delays for a few cycles before reading the results.

The device has sixteen 16-bit "registers" that retain state between calls, as well as a bit of temporary storage for computation. These are not literally CPU registers, but since we're treating the device as opaque it's okay to think of them that way. For convenience we will refer to them in hex notation, as R0 through RF. The values in the first 12 can be set directly. The last four are only used internally.

## Details

### Function Summary

Each function is listed with its index, the address label used in the disassembly, and a brief description of the function it performs.

Index Label Function (approximate)
\$00 MB_SET_R0L Set R0 low; result=R0
\$01 MB_SET_R0H Set R0 high; result=R0
\$02 MB_SET_R1L Set R1 low; result=R1
\$03 MB_SET_R1H Set R1 high; result=R1
\$04 MB_SET_R2L Set R2 low; result=R2
\$05 MB_SET_R2H Set R2 high; result=R2
\$06 MB_SET_R3L Set R3 low; result=R3
\$07 MB_SET_R3H Set R3 high; result=R3
\$08 MB_SET_R4L Set R4 low; result=R4
\$09 MB_SET_R4H Set R4 high; result=R4
\$0a MB_SET_R5L Set R5 low; result=R5
\$0b MB_ROT_Z Set R5 high;
R4 = R4 - R2
R5 = R5 - R3
result = (R0 * R4) - (R1 * R5)
\$0c MB_SET_R6 Set R6; result=R6
\$0d MB_SET_RAL Set RA low; result=RA
\$0e MB_SET_RAH Set RA high; result=RA
\$0f MB_SET_RBL Set RB low; result=RB
\$10 MB_SET_RBH Set RB high; result=RB
\$11 MB_SCREEN_X Set R5 high;
R7 = (R0 * R4) - (R1 * R5) + R2
R8 = (R1 * R4) + (R0 * R5) + R3
result = R8 / R7
\$12 MB_ROT_X Data ignored;
when called after \$0b:
result = (R1 * R4) + (R0 * R5)
\$13 MB_DIVIDE_87 Data ignored; result=R8 / R7
\$14 MB_DIVIDE_B7 Data ignored; result=RB / R7
\$15 MB_SET_R7L Set R7 low; result=R7
\$16 MB_SET_R7H Set R7 high; result=R7
\$17 MB_GET_R7 Data ignored; result=R7
\$18 MB_GET_R9 Data ignored; result=R9
\$19 MB_GET_R8 Data ignored; result=R8
\$1a MB_SET_R8L Set R8 low; result=R8
\$1b MB_SET_R8H Set R8 high; result=R8
\$1c MB_CLIP Set R5 high; result=midpoint subdivision
\$1d MB_CALC_DIST Set R3 high;
R2=abs(R2-R0), R3=abs(R3-R1)
continue into \$1e
\$1e MB_CALC_HYPOT Data ignored; result=approximation of sqrt(R2^2 + R3^2)
\$1f MB_UNKNOWN Behavior unknown

Battlezone invokes all functions except \$13, \$18, \$1a, \$1b, \$1c, and \$1f (marked in italics). Function \$13 is used as part of \$11 but not invoked directly. Function \$1c appears to have been intended for a line clipping function that used midpoint subdivision, but the vector hardware performs that function. The system diagnostics code has a routine that rapidly invokes every function in sequence, but it doesn't check the results.

Function \$0c is used to set R6 to \$0a once each frame. Note there's no way to set the high byte of R6, but since it's used to specify a small integer count there's really no need.

### Function Usage

Battlezone uses the math box to do five things:

1. 3D "view" transform
2. 3D "model" transform and perspective projection
4. 2D distance calculation
5. integer division for arctangent

Before we go into the details, it's worth taking a minute to review how 3D graphics work.

#### 3D Transformations

In the classic implementation you take an object, rotate it, and translate all of its vertices to the correct position and orientation in the world (the Model transform). Then you rotate and translate it so it's correctly positioned relative to the viewer (the View transform). Finally you Project the coordinates into 2D "clip space", and apply a Viewport transform to put it in the right place on the screen.

Battlezone rearranges this a bit. It performs the View translation and rotation first, so that it can detect when objects are completely off-screen and exclude them from further consideration. It generates a list of visible objects, with four values for each: object type, facing, object center X position, and object center Z position. These values are fed into the vertex transformation function, which performs the Model transform and projects the vertex positions onto screen X/Y coordinates. Clipping at window edges is performed by the hardware.

Battlezone's objects can rise above ground level but can only rotate about the Y axis, so for the Model and View transforms we need to apply a single-axis rotation and translation along all axes.

Object positions are tracked in world space with 16-bit X/Z values that wrap around at the map edges. The object cull "near" plane is \$3ff and the "far" plane is \$7aff, meaning objects positioned closer or farther than that are not considered visible. Note the far plane is nearly half the width of the battlefield. You can tell that the game uses a clip plane rather than a clip distance because, if you back up until an object in the center of the viewer just disappears, rotating to the left or right will make it reappear.

The formula for rotation about the Y axis is:

```  newX = X * cos(theta) - Z * sin(theta)
newZ = X * sin(theta) + Z * cos(theta)
```

Battlezone uses a table of sin/cos values stored as 16-bit signed fixed-point fractions. After multiplication, the result must be right-shifted 15x, because the fractional part is only 15 of the 16 bits. The math box code right-shifts it 16x, effectively halving the result. (This is compensated for in the code or in the data.)

#### View Transform (\$5946)

The game must take the center coordinates of the various objects (enemy unit or flying chunks, friendly and enemy projectiles and projectile explosions, the saucer, obstacles), and compute a new position that is relative to the position and facing of the player. Once an object's position is known, it can be evaluated to see if it's currently in the player's field of view. If it's behind the viewer, beyond the far plane, or too far to the left or right, we can save time by not transforming the object's vertices.

The position calculation is straightforward. Starting with the object's position in "world space" coordinates, we subtract the viewer's position to get the object's position relative to the viewer:

```  rel_X = obj_world_X - viewer_X
rel_Z = obj_world_Z - viewer_Z
```

Then just plug the coordinates into the rotation formula, using the viewer's facing angle as theta, to get the "view space" coordinates:

```  view_X = rel_X * cos(theta) - rel_Z * sin(theta)
view_Z = rel_X * sin(theta) + rel_Z * cos(theta)
```

The mathbox implementation is a direct implementation, with a bit of confusion about how the axes are defined. The 6502 code begins by setting up registers for the viewer:

```  R0 = cos(theta) as signed 1.15 fraction
R1 = -sin(theta) as signed 1.15 fraction
R2 = 16-bit viewer_Z
R3 = 16-bit viewer_X
```

Note that R1 is set to negative sin(theta). For each object under consideration:

```  R4 = 16-bit obj_world_Z
R5 = 16-bit obj_world_X

invoke function \$0b:
R4 -= R2            # rel_Z = obj_world_Z - viewer_Z
R5 -= R3            # rel_X = obj_world_X - viewer_X
RC = R4 * R0
R7 = R5 * -R1
result = R7 + RC    # view_Z = rel_X * sin(theta) + rel_Z * cos(theta)

invoke function \$12:
RC = R4 * R1
R8 = R5 * R0
result = R8 + RC    # view_X = rel_X * cos(theta) - rel_Z * sin(theta)
```

The results are doubled to compensate for the 16-bit shift.

Once we have the position, we cull any shapes that are outside the view frustum. Objects whose center points are closer than the near plane (\$03ff) or farther than the far plane (\$7aff) are dropped. The left/right frustum bounds clipping is done by comparing the absolute value of the X coordinate to the Z coordinate, and culling any object where abs(X) > abs(Z). This is a very fast clip for a 90-degree FOV. Since the game uses a 45 degree FOV it's a little loose. The clip is based on the object center points, so it needs to be a little loose or things would vanish when they're still halfway on screen. The frustum bounds check is simple enough that the math box doesn't need to get involved.

Side note: saucers don't make noises when they're not visible, but the definition of visibility is the 90-degree FOV, so they're still audible when off screen to the left or right.

#### Model Transform and Perspective Projection (Vertex -> Screen) (\$5d4a)

The code projects the X/Y/Z coordinates of an object to X/Y coordinates on screen. The inputs to the function are the four values output from the View transform: type, facing, X position, Z position. We need to apply a transformation that rotates and translates the object's individual vertices (Model transform), then divides X and Y by Z to perform perspective projection.

So, given the object's "view space" X/Y/Z and vertex X/Y/Z, we need to compute "screen space" X/Y, like this:

```  rotated_Z = vertex_X * sin(theta) + vertex_Z * cos(theta)
model_Z = rotated_Z + object_Z

rotated_X = vertex_X * cos(theta) - vertex_Z * sin(theta)
model_X = rotated_X + object_X

screen_X = model_X / model_Z

model_Y = vertex_Y + object_Y
screen_Y = model_Y / model_Z
```

Here, the angle theta is the object's facing relative to the viewer.

The math box functions again implement this directly. For each object, the 6502 code sets math box registers for the facing angle and center position:

```  theta = player facing - object facing
theta += 180 degrees
R0 = -cos(theta) as signed 1.15 fraction
R1 = sin(theta) as signed 1.15 fraction
R2 = 16-bit object_Z
R3 = 16-bit object_X
RA = 0
```

Note R0 is set to negative cos(theta), and the object is rotated 180 degrees. Then, for each vertex:

```  R4 = 16-bit vertex_Z
R5 = 16-bit vertex_X

invoke function \$11:
RC = R4 * R0        # RC = vertex_Z * -cos(theta)
R7 = R5 * -R1       # R7 = vertex_X * -sin(theta)
R7 += RC            # rotated_Z = -(vertex_X * sin(theta) + vertex_Z * cos(theta))
R7 += R2            # model_Z = rotated_Z + object_Z

(continue into function \$12)
RC = R4 * R1        # RC = vertex_Z * sin(theta)
R8 = R5 * R0        # R8 = vertex_X * -cos(theta)
R8 += RC            # rotated_X = -(vertex_X * cos(theta) - vertex_Z * sin(theta))
R8 += R3            # model_X = rotated_X + object_X

(continue into function \$13)
result = R8 / R7    # model_X / model_Z

screen_X = result

RB = vertexY + object_Y

invoke function \$14:
result = RB / R7    # model_Y / model_Z

screen_Y = result
```

Note the use of -cos(theta) negates the rotated X/Z values. A couple of other details that balance out some of the odd math:

• The `object_Y` coordinate is modified by the horizon shift that happens when the player is hit or drives into something.
• As noted on the object definition page, the X coordinates in the mesh definitions are flipped.
• The `screen_X` result is negated, effectively mirror-imaging the screen but only for the 3D-rendered elements (i.e. not the background or messages).

The description of the math box implementation has been simplified greatly. If you want to dig into it, the source code is dense but fairly brief. There are a couple of finer points that should be called out here though:

• As noted earlier, the sin/cos values are signed 16-bit fractions, making them 1.15 values, so the results should be right-shifted 15x. The math box code shifts them 16x, halving the result. This makes every shape half look tall and skinny, because the halving occurs in the rotation equations, and the Y coordinate isn't part of that. Battlezone works around this by doubling the X/Z coordinates in the shape meshes.
• The way division works is affected by R6, which determines the number of iterations performed by the divide routine. For correct behavior, the division routine should iterate 16 times, but Battlezone sets the value to 10. This effectively scales the screen coordinates down by a factor of 64.

The API seems to be designed to minimize the interactions between the 6502 and the math box. For example, the 6502 code sets the object's X/Z position once, then supplies the X/Z coordinates for the vertices, and lets the mathbox add the object position to the vertex position. For the Y coordinate, the same calculation is performed on the 6502, presumably because it's cheap and doesn't come after a rotation.

The position of the blip on the radar requires essentially the same calculation as the model transform (translate then rotate), but without the perspective projection. The easiest way to do that is to invoke function \$11 and ignore the result. The center of the radar is at screen coordinate (0,316), which we can drop into the equations.

The code looks like this:

```  R0 = sin(theta)
R1 = cos(theta)
R2 = 0
R3 = 316
R4 = distance     # computed distance / 256
R5 = 0

invoke function \$11:
RC = R4 * R0
R7 = R5 * -R1
R7 += RC            # R7 = distance * sin(theta)
R7 += R2

(continue into function \$12)
RC = R4 * R1
R8 = R5 * R0
R8 += RC            # R8 = distance * cos(theta)
R8 += R3            # R8 += 316

(continue into function \$13)
result = R8 / R7
```

R7 is used as the X coordinate, R8 as the Y coordinate.

#### 2D Distance Calculation

An article on distance approximations describes "a fast approximation of 2D distance based on an octagonal boundary", with the formula:

```  distance = 0.41 * dx + 0.941246 * dy
(for dy > dx; flip the values if dy < dx)
```

Math box function \$1e uses an approximation to the approximation:

```  distance = 0.375 * dx + 1.0 * dy
```

0.375 is 3/8, so this is trivial to compute with a few adds and shifts.

The math box provides two entry points. Function \$1d subtracts two sets of 16-bit coordinate values and stores their absolute values in R2/R3, then falls into function \$1e. If you view these as the lengths of the short sides of a right triangle, then function \$1e is calculating the length of the hypotenuse.

The distance between two objects is used to determine whether or not they have collided. Collisions between units (e.g. a tank driving into an obstacle) use different values than collisions with a projectile, which is why you can shoot past obstacles that you can't drive past. Projectile collisions also take unit facing into account.

#### Integer Division for Arctangent

Suppose you have the positions of the enemy unit and the player, and want to compute the heading to which the enemy unit must rotate so it can fire its cannon and hit the player. We can treat this as a basic trigonometry problem by drawing a right triangle with the units at opposite corners of the hypotenuse. The lengths of the other sides are simply the difference between the unit X coordinates and Z coordinates, respectively.

Given a right triangle, you can compute the (non-90-degree) angle with arccos(), arcsin(), or arctan(). arccos() and arcsin() require knowing the length of the hypotenuse, so arctan() is the function of choice. You divide the length of one side by the other side and plug the result into the arctan() function.

Battlezone uses math box function \$14 to perform integer division, then uses a lookup table to get the angle.