========================== "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.