Concepts

Surface 2 has some concepts that might not be apparent at first.
Here is a summary and explanation of many of Surface 2's concepts and design choices.

###Coordinate system
Surface 2 uses a (0,0) based coordinate system, this means that the pixel at (0,0) is the top-leftmost pixel,
and that the pixel at (width - 1, height - 1) is the lower-rightmost pixel.

###The stencil stack
Stencils are clipping regions, and surfaces can have multiple of these on top of each other in the form of a stencil stack, so you can push and pop stencils.
You can only draw to the area inside this clipping region.

###Transparency
Surface 2 supports transparency per layer, that means the background colour, text colour and character (or R, G and B) can be transparent.
The representation for this is nil, so if a pixel is transparent it means that it is nil.
Because you can have transparency per layer, you can for example have a non-transparent background colour but a transparent character, which means when you draw it it overwrites the background colour but not the character.

You can overwrite all layers, no matter if a part of the colour contains nil, using surf.overwrite = true.

###Palettes
Palettes are represented as lookup tables with 24-bit RGB hex colours in string form as values.
For example, the ComputerCraft palette contains [8]="99B2F2", which is light blue.
When you convert a surface from palette form (b, t, c) to RGB (r = b, g = t, b = c) and back, it only uses the background colour layer (b).

###Fonts
Surface 2 supports pixel font drawing, but it has its own format.
You can load fonts from surfaces without any metadata, because the image itself contains everything.
Fonts start at ASCII value 32, which is the space character.
Characters are separated by dots at the bottom line of the image.

Here's an example: