Implement hardware blitter

1 files changed, 59 insertions, 0 deletions

diff --git a/README.md b/README.md
index 06ad4f3..b65173e 100644
--- a/README.md
+++ b/README.md
@@ -62,9 +62,68 @@ You can then compile and run the example with `make example`.
 
 | Port | Type | Result |
 | --- | --- | --- |
+| 0xb0 | write | Blitter control |
+| 0xb1 | write | Blitter settings |
 | 0xf0 | read | Status of the controller 1 |
 | 0xf1 | read | Status of the controller 2 |
 
+### The blitter
+
+TR8 implements a hardware blitter that can be controlled by writing to ports.
+
+On a successful port call, the read value equals to the port number, so the call preserves the port register.
+
+To draw with the blitter the following steps are required:
+
+1. put the blitter in settings mode using control port `0xb0`
+2. provide the source address, and destination coordinates (x, y, width and height) using settings port `0xb1`
+3. set the blitter in one of the write modes using the control port `0xb0`
+
+Step 3 can be repeated as many times as needed, the blitter will keep the settings until the control port is set in settings mode.
+
+The settings byte is as follow:
+
+| Bits | Effect
+| --- | --- |
+| `x0000000` | Set blitter in settings mode |
+| `0000000x` | Write |
+| `000000x0` | The source includes a transparent bit |
+| `0xxxxx00` | Unused |
+
+Example:
+
+```asm
+    ; blitter in settings mode
+    ld x, 128
+    ld a, 0xb0
+    port a, x
+
+    ; setup
+    inc a
+    ; source
+    ld x, <sprite
+    port a, x
+    ld x, >sprite
+    port a, x
+    ; destination (56, 56)
+    ld x, 56
+    port a, x
+    port a, x
+    ; size 16x16
+    ld x, 16
+    port a, x
+    port a, x
+
+    ; now blit
+    dec a
+    ld x, 3
+    ; 3: write with transparent color support
+    port a, x
+```
+
+When bit 2 in the settings byte is set to 1 and the most significant bit in the
+source data is set (e.g. `128`), that pixel won't be drawn (transparent).
+
 ### Controller
 
 The controller support d-pad with 4 directions, 2 action buttons, select and start.