## Block Transfer operations

NOTE: Paragraphs below are design notes for an upcoming refactoring. Nothing is
implemented yet.

The unit at [gr/blt.fs] provides highly optimized routines to move pixels from
one pixbuf [gr/pix] to another, even when they have a different color encoding
[gr/color].

This sounds simple, right? Yes it is, but when you consider the combination
possibilities and speed constraints, that's quite a lot of routines to write.

Yes, a routine has to be written for each combination. For example, there's a
big performance penalty with doing sub-32-bit reads and writes to memory. One
wants to group them in 32-bit chunks. See where it leads? yeah.

While this unit provides convenient ready to use words for common BLT
operations, this unit also exposes its low level routines that other drawint
units such as [gr/font/ufx] will use for compiling their own specialized drawing
routines.

## The Mixel as the atomic unit

For BLT operations to be as flexible as possible while staying as fast as
possible, routines operate on what we creatively call a "mixel" (multiple
pixels). That's a group of pixels that can be both read and written as 32-bit
values. It can be more than one on one side or the other (or both!).

For example, in a 4-bit to 16-bit BLT, mixel size is 8 pixels, which results in
a single 32-bit read in the source for 4 32-writes in the dest.

Low level BLT routines supplied here all copy a single mixel. Convenience words
for wrapping those routines are provided so you don't need to handroll your
loops all the time.

## When to compile?

This unit provides *compiler* routines. When to compile? Should you pre-compile
all possible combinations for your specialized drawing unit?

If you want, sure. But usually, what you'll want to do, at the end of the day,
is to draw to the screen, which stays the same all the time.

It can therefore be a good idea to take advantage of Dusk's compiling
superpowers and compile your drawing routines only when a destination pixbuf is
chosen for your specialized drawing routine.

In other words, your specialized drawing routine could be a compiler too!

## Low level BLT routines

BLT routine name scheme is "blt[srcsize]>[dstsize],". For example, a BLT
operation from a 4-bit depth to a 16-bit depth is done with "blt4>16,". It
copies a single mixel.

Those routines all have a "( -- )" compile time signature and the same runtime
signature, "( W=src A=dst -- W=src+x A=dst+y )" with "src" being the source
address for the mixel to copy, "dst" being the destination address for the mixel
and "x" being the size in bytes of a mixel in the source pixbuf, "y" being the
size in bytes of a mixel in the destination pixebuf.

For each pixel in the mixel, the "colorconv" routines, which has been set up
prior to calling the BLT routine, is called. Its compile time signature is
"( -- )" and its runtime signature is "( S=oldcolor -- S=newcolor )". It must
preserve both W and A, which means you'll probably want to use [hal/vreg].

## Unaligned BLTs

The system above is fine and dandy for aligned source and destination. Super
fast, rather simple.

However, sometimes, life is unaligned. But we still want those mixels!

That's what the "ublt" family of routines is about. There is one "ublt" for each
"blt" ones, with the same naming scheme. So, the only difference is the "u"
prefix... and being slower.

Those routines also copy a single mixel, but depending on W and A alignment at
runtime, it possibly does 8b and 16b read/writes.

"ublt" routines involving depth under 8-bit also use the S register in their
signature. It contains bit-level offsets, the modulo of the division necessary
to get an address from a X position. For example, if depth is 1-bit and X is 10,
S is going to be 2 because 10 mod 8 is 2.

Finally, there is also "bltaligned?[srcsz]>[dstsz]," which dynamically checks
whether W/A/S register indicate that we're aligned. If aligned, Z is set.
Otherwise, it's unset.

## Compile helpers

To help with compiling full loops around the low level BLT routines, this unit
provides a few helper words.

TODO: come up with those words

## High level routines

At the highest level, this unit provides two dynamic words: movepixels and
mappixels.

"movepixels" is for copying pixels, possibly with color conversion. "mappixels"
is for mapping source colors as indexes in a palette.

Both those words dynamically choose the proper BLT routine depending on source
and dest pixbufs and then do their thing.
