test2d: add a few 2D engine tests

Having fun with the 2D engine.
Lines, blitting, stretching, filtering, palette expansion, ...
Current tests work on the cubox, which has PE10.
Still has to be tested on PE20 (which is most other vivante hardware).
There are some subtle but possibly significant differences.

1 files changed, 68 insertions, 0 deletions

diff --git a/doc/2d.md b/doc/2d.md
new file mode 100644
index 0000000..ec26693
--- /dev/null
+++ b/doc/2d.md
@@ -0,0 +1,68 @@
+2D engine documentation
+========================
+
+Make sure to set the PIPE to 2D before using the 2D engine.
+
+As the complete state footprint is pretty small, it is recommended to program all relevant
+2D engine state for an operation at once before a command instead of relying on a context as with 
+3D rendering.
+
+Monochrome blits
+-----------------
+     
+When blitting from `LOCATION_STREAM` make sure that there are
+enough bytes available in the stream.
+Source size is ignored in the case of monochrome blits.
+
+Mono expansion uses
+`SRC_COLOR_FG`
+`SRC_COLOR_BG`
+to determine the colors to use for 0 and 1 pixels respectively.
+
+In case of `LOCATION_STREAM` source can only draw one rectangle at a time.
+
+Raster operations
+------------------
+Raster operation foreground and background codes. Even though ROP
+is not used in `CLEAR`, `HOR_FILTER_BLT`, `VER_FILTER_BLT` and alpha-enabled
+`BIT_BLT`s, ROP code still has to be programmed, because the engine makes the
+decision whether source, destination and pattern are involved in the current
+operation and the correct decision is essential for the engine to complete
+the operation as expected.
+
+ROP builds a lookup table for a logical operation with 2, 3 or 4 inputs
+(depending on ROP type). So for a ROP3, for example, the rop pattern will be
+2^3=8 bits.
+
+`ROP2_PATTERN` [untested]
+    bit 0 destination
+    bit 1 pattern
+
+`ROP2_SOURCE` [untested]
+    bit 0 destination
+    bit 1 source
+
+`ROP3` (uses `ROP_FG` only)
+    bit 0 destination
+    bit 1 source
+    bit 2 pattern
+
+`ROP4` (uses `ROP_FG` and `ROP_BG`)
+    bit 0 destination
+    bit 1 source
+    bit 2 pattern
+    bit "3" foreground/background (`ROP_FG` / `ROP_BG`)
+    
+ROP3/4 examples:
+
+    10101010  0xaa   destination
+    01010101  0x55   !destination
+    11001100  0xcc   source
+    00110011  0x33   !source
+    11110000  0xf0   pattern (8x8)
+    00001111  0x0f   !pattern (8x8)
+
+Patterns
+---------
+An repeated 8x8 pattern can be used with 2D engine operations `LINE` and `BIT_BLT`.
+