Help for Jello Part 4
---------------------

The layout of the assembly program is not entirely obvious, as a lot of the
routines are in separate library programs. The layout of Part 1 is shown
below, where / denotes a macro being used and | denotes a subroutine being
called.

main
  |
  gravity, jello, cls, rotate_cube, rotate_jello, draw
                         /            /
                         rotation     rotation

jello / boing
  |       |
  |       isqrt
  |
  check_point

draw / screen_jello / draw_jello / screen_cube / cube_visible / draw_cube_back / draw_cube_front
                                                   /              /                /
                                                   see_face       draw_face        draw_face
                                                                                     /
                                                                                     move_to, draw_to

adr macro used throughout

Note that draw subroutine is actually assembled in JelloMain.

Program Flow
------------

1. main: Set up mode, palette, screen addresses, cursor, graphics origin
and mouse rectangle.

2. main loop: Get mouse coordinates and put into (xrot,yrot), clipping to
the range 0..360. Swap display banks and then call subroutines gravity,
jello, cls, rotate_jello, rotate_jello and draw in that order.

3. gravity: Gravity vector (0,-256,0) is rotated through angles (xrot,yrot)
into (gravx,gravy,gravz).

4. jello: The jello in (xj,yj,zj) and (cenx,ceny,cenz) is put through the
spring equations and gravitational pull, where the co-ordinate velocities
are placed in (xv,yv,zv) and (cenxv,cenyv,cenzv). Then the Jello is checked
against a fixed orthogonally aligned cube, and is put back into (xj,yj,zj)
and (cenx,ceny,cenz).

5. cls: Simply clears the screen by filling the screen memory with zeros.

6. rotate_cube: The orthogonally aligned cube in (xcF,ycF,zcf) is rotated
through angles (-xrot,-yrot) into (xc,yc,zc).

7. rotate_jello: The jello in (xj,yj,zj) and (cenx,ceny,cenz) is rotated
through angles (-xrot,-yrot) into (xt,yt,zt) and (cenxt,cenyt,cenzt). The
centre co-ordinates are stored separately to ease jello calculations in
part 4, when the jello is jellified. The angles are negated for reasons
outlined in part 4, when collision with the cube will be considered.

8. draw: Macro screen_cube is called to project the cube from (xc,yc,zc)
into (xcs,ycs). Next macro cube_visible is called to decide which faces of
the cube are behind the jello, and which are in front. Then macro
draw_cube_back is called to draw the faces of the cube which are behind the
jello. Then screen_jello is called to project the jello from (xt,yt,zt) and
(cenxt,cenyt,cenzt) into (xjs,yjs), and then the jello is moved to
(0,0,zdist%) and projected into (xjs5,yjs5). Macro draw_jello is then
called to calculate which sides of the jello are visible using (xjs,yjs),
and how bright the visible sides should be using (xjs5,yjs5), and then the
visible triangles are plotted. The second set of projection co-ordinates is
used to calculate the illumination so the intensity of the light seems to
be the same however far or near the jello is to the viewer. Finally macro
draw_cube_front is called to draw those faces of the cube which are in
front of the jello.

[Note jello in (xj,yj,zj) includes zdist% component in zj.]

The reason for all the rotating in stages 3, 6 and 7 is that if we rotate
the jello, we can check for collision with the cube just by testing the
magnitudes of the x,y,z components, as the cube will then be orthogonally
aligned. Then we rotate the jello and cube back again, so the whole
rotation business has the effect of rotating the cube (but not the jello)
and checking for collision against skew planes, but it is more accurate and
quicker then the skew version.
