Rotatrix

==========================


"ROTATRIX" by Einar Saukas


==========================





Rotatrix is a Rainbow Graphics utility to rotate images in the upper border,


outside the regular ZX-Spectrum screen.





This utility is compatible with all standard Spectrum models (48K, 128K, +2,


+2A, and +3). It will automatically detect the current model at startup and


adjust timings accordingly.








=====


USAGE


=====





In Assembly, use "call 64974" to activate Rotatrix, then "call 65012" to


deactivate it later.





The rotation speed is reconfigured by directly altering address 64941. This


value (from 0 to 255) indicates how many times each frame is repeated before


the image is shifted again. Notice you can even change the speed "on the


fly", while Rotatrix is running.








======


TIMING


======





Border routines require very precise timing. Because of this, while Rotatrix


is enabled, your program should "halt" before each frame, otherwise it will


produce a "shaking" image due to delayed interrupts.





Even so, Rotatrix timing is adjusted for "normal timing" machines only.


Certain Spectrum machines have "late timing", in this case the easiest way


to make Rotatrix work would be to reconfigure it, by altering address 64868


to value 87 (for "late timing") instead of 0 ("normal timing"). However,


it's not easy to detect if the current machine has "late timing", and this


would not be reliable anyway since certain computers may change to "late


timing" after warmup.





A much better solution is to re-synchronize the computer timing against the


TV raster beam before each interrupt, so the normal Rotatrix configuration


will work properly in all cases. This can be done as follows:








call 64974 ; enable Rotatrix


loop:


ld b, 6 ; synchronize with TV raster beam


sync:


ld a,($4000)


djnz sync





halt ; wait for next frame





; custom code starts here...


ld a, (23560) ; last pressed key


cp ' ' ; pressed SPACE?


jr nz, loop ; repeat otherwise





jp 65012 ; disable Rotatrix and exit








In this example above, the custom code can be altered to perform all kinds


of different tasks instead. The only restriction is that it must repeat the


synchronization code before the TV raster beam finishes drawing the screen


image, otherwise it won't be able to synchronize. In most cases, this is not


really a problem, since it means the custom code is still going to have more


than 40K T-states available per frame, which is usually enough anyway.








=====


IMAGE


=====





A rotating image contains 24 lines with an arbitrary number of columns. Each


image component is a wide colored block of 32x1 pixels.





A rotating image is defined as follows:





* Background border color (1 byte)


* Number of columns (1 byte)


* 24 "offsets" indicating a color sequence for each line (24x2 bytes)


* Several color sequences





The "offset" stores the address of a color sequence, minus the current


address. Using "offsets", different lines can reuse the same color sequence,


thus typically reducing the total image size.





The image definition format is fully relocatable, thus it still works


when loaded at a different address. By default, Rotatrix expects a rotating


image starting at address 64000, but if you want to use a different address


IMAGE_ADDRESS, you just have to store value IMAGE_ADDRESS+49 at addresses


64878/64879.





See the source code files for a practical example about how to use it.








=======


LICENSE


=======





You can freely use Rotatrix in your own programs, or implement routines


based on it. The only condition is that, in either case, you must clearly


indicate somehow that you are using Rotatrix (directly or indirectly)!








=======


CREDITS


=======





Rotatrix was designed and implemented by Einar Saukas.





This idea was inspired by "BorderTron 3000" (by Chris Cowley), which was


inspired by "BorderTrix" (by Andrew Owen), although Rotatrix was developed


independently and it's not based on code from either of them.