# Mixing pixels

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

The unit at [gr/mix.fs] provides optimized routines for mixing pixels together
in a memory space, that is, get or set a pixel in color encoding [gr/color] that
possibly implies that more than one pixel live at that address.

## Speed considerations

Although the routines of this unit are designed to be as fast as possible,
handling pixels one at a time is inherently slow. When processing a group of
pixels, consider specialized units such as [gr/blt] first. But sometimes,
picking pixels one at a time is necessary, so here we are.

## Source and destination setup

This unit is a collection of specialized routines segregated by color depth.
Because you don't want to spend time checking the depth of your buffer [gr/buf]
every time you access a pixel, this unit requires setting up your source (for
"pixel@") and destination ("pixel!") buffers before you begin accessing pixels.

You do so with "pixelsrc" and "pixeldst".

## No palette logic

Note that this unit doesn't contain palette resolution code. To it, a pixel is
a simple number.

## Example usage

  srcbuf pixsrc \ srcbuf is a gr/buf
  dstbuf pixdst
  42 12 pixel@ 54 14 pixel!

The pixel at X/Y position 54/14 in "dstbuf" is now the same color as

## API

### Words

pixelsrc ( pixbuf -- )
  Set the target for "pixel@".

pixeldst ( pixbuf -- )
  Set the target for "pixel!".

pixel@ ( x y -- n )
  Get pixel at X/Y coordinates in current target pixbuf.

pixel! ( n x y -- )
  Set pixel at X/Y coordinates in current target pixbuf.
