2D engine documentation
========================

Important: make sure to set the PIPE to 2D before using the 2D engine. Otherwise, the device will hang.

As the complete state footprint is pretty small, it is recommended to program all relevant
2D engine state for an operation (before flushing) at once before a command instead 
of relying on a context to be maintained as with 3D rendering (although this is still a possibility).

2D commands
-----------------

- Clear
- Line
- Bit blit
- Stretch blit
- Multi source blit

Video rasterizer
-----------------

- Horizontal filter blit
- Vertical filter blit
- One-pass filter blit

Does hardware scaling using an arbitrary 9-tap separable filter and 5 bit subpixel precision,

Input: Y/U/V planar or interleaved images or RGBA images
Output: RGBA formats (planar may be possible too)

Monochrome blits
-----------------

Mono expansion can be used for primitive font rendering or b/w patterns such as checkerboards.

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 registers
`SRC_COLOR_FG` and `SRC_COLOR_BG`
to determine the colors to use for 0 and 1 pixels respectively.

Restrictions:

- 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
    00001111  0x0f   !pattern

Patterns
---------
An repeated 8x8 pattern can be used with 2D engine operations `LINE` and `BIT_BLT`.
This pattern can be combined with the color using ROP.

Alpha blending
---------------
- The blend equation is always akin OpenGL's `GL_FUNC_ADD`, source and destination (multiplied by blend factor) are added.

- Alpha values can come from the source/destination per pixel or a global value defined in the state.

Rotation and mirroring
-----------------------

- There are two ways to do source and destination rotation: through register `ROT_ANGLE` and through
register `SOURCE_ROTATION_CONFIG` / `DEST_ROTATION_CONFIG`.
The former is more flexible and can rotate (0, 90, 180, 270) as well as flip in X and Y. However it is not supported
on every GPU (which ones?).

- There are also two ways to do mirroring: though register `ROT_ANGLE` and through
register `CONFIG` (enable "mirror blit"). Both methods seem roughly equivalent, but hardware support may be
different. Mirroring seems to be `ROT_ANGLE` is supported with the `NEW_2D` capability ("mirror blit extension").
This is only available in very new hardware (gc880, gc2000).

PE10/PE20
==========
GPUs with feature bit `PE20` have various different features from GPUs without the bit
(considered `PE10`). Also the registers that are used for the same features can be different. `PE20` registers
are usually a superset of the `PE10` equivalent. Make sure to use the right registers according to the PE type or
it will not work.