# Plane

A plane is a filled Rect (gr/rect). It extends Rect and adds a color buffer to
it, one color per pixel. The size of the buffer depends on its color encoding
(see gr/color).

The buffer is a sequence of horizontal lines with each line being "pitch" bytes
in size, beginning with the top line. Each line is a sequence of pixels, with
the size in bytes of each pixel depending on the color encoding, beginning with
the leftmost pixel.

Drawing on a plane is stateful. You set "tx" and "ty" (your target point), set
the active color with the "color" field and then call the appropriate drawing
method.

## API

Fields:

encoding  A color encoding ID from gr/color
pitch     Size in bytes of each line
tx        Target point X
ty        Target point Y
color     Color that is currently drawn
buffer    Pointer to the pixel buffer

Methods:

:new ( width height encoding -- plane )
  Create a new plane and calculate pitch from color encoding. Does not allocate
  a buffer and initializes it to 0.

:allotbuf ( self -- )
  Allocate a new buffer of the proper size (considering height and pitch) and
  set "buffer" to it.

:xyoff ( x y self -- n )
  Returns the offset, relative to "buffer", corresponding to position "x,y" and
  do all preparation necessary (for example bank switching) to make that offset
  readily accessible.

:pixel! ( self -- )
  Set a pixel at tx,ty to the value of field "color".

:pos! ( x y self -- )
  Set current target position.

:tx+ ( n self -- )
  Increase tx by n, wrapping around if necessary.

:ty+ ( n self -- )
  Increase ty by n, wrapping around if necessary.

:fill ( width height self -- )
  Fill the area in the rect tx,ty,width,height with field "color".

:copy< ( rect src self -- )
  Copy the contents of "rect" from plane "src" into self at target position
  tx,ty. Color encodings must be the same but pitch doesn't have to.

:copy> ( rect dst self -- )
  Copy the contents with the size of "rect" from "self" into plane "dst"'s. The
  position of the rectangle at source is self.tx,self.ty and the origin of the
  rectangle at dst is rect.x,rect,y.

  Confused? yeah, it is a little bit. Here's the idea: :copy< and :copy> allows
  a plane to copy contents in and out of another plane without changing that
  other plane's tx/ty fields. In both copy directions, it is "self" fields that
  change.

   self            src/dst
+-----------+   +-----------+
|  ty       |   |  rectxy   |
|tx+--+     |   |  +--+     |
|  |  |-------copy>|  |     |
|  |  |     |   |  |  |     |
|  |  |copy<-------|  |     |
|  +--+     |   |  +--+     |
|    rectwh |   |    rectwh |
+-----------+   +-----------+
