surfaces
********
Libtonc's Surface system provides the basic functionality for
drawing onto graphic surfaces of different types.

- ``srfBmp8``: 8bpp linear (Mode 4 / affine BGs)
- ``srfBmp16``: 16bpp bitmaps (Mode 3/5 / regular BGs to some extent)
- ``srfChr4c``: 4bpp tiles, column-major (Regular tiled BG)
- ``srfChr4r``: 4bpp tiles, row-major (Regular tiled BG, OBJs)

For each of these, procedures exist for the most important drawing
options: plotting, lines and rectangles. For BMP8/BMP16 and to
some extent CHR4C, there are blitters as well.

.. admonition:: **Column-major vs row-major**
  
  A (4bpp) tiled surface is formed when each tilemap entry
  references a unique tile (this is done by :xref:`prepMap`).
  The pixels on the tiles will then uniquely map onto pixels on the
  screen. There are two ways of map-layout here: *row-major* indexing and
  *column-major* indexing. The difference if is that tile 1 is to the
  right of tile 0 in the former, but under it in the latter.
  
  e.g. on a 30x20 tile screen::
  
    Row-major:
      0  1  2  3 ...
      30 31 32 33 ...
      60 61 62 63 ...
  
    Column-major:
      0 20 40 60 ...
      1 21 41 61 ...
      2 22 41 62 ...
  
  With 4bpp tiles, the column-major version makes the **Y**
  coordinate match up nicely with successive words. For this reason,
  column-major is usually preferred over row-major.

-----------------------------


Types
=====

.. autonim:: surfaces.SurfaceKind
.. autonim:: surfaces.Surface

.. note::
   While Tonc has one `Surface` type, below we provide several `distinct` versions of it.
   This allows us to simplify the names of procedures via overloading, and it
   becomes impossible to call the wrong procedure on the wrong kind of surface.

.. autonim:: surfaces.SurfaceBmp16
.. autonim:: surfaces.SurfaceBmp8
.. autonim:: surfaces.SurfaceChr4r
.. autonim:: surfaces.SurfaceChr4c
.. autonim:: surfaces.SomeSurface
.. autonim:: surfaces.SurfacePtr
.. autonim:: surfaces.SurfaceBmp16Ptr
.. autonim:: surfaces.SurfaceBmp8Ptr
.. autonim:: surfaces.SurfaceChr4cPtr
.. autonim:: surfaces.SurfaceChr4rPtr
.. autonim:: surfaces.SomeSurfacePtr

-----------------------------

Variables
=========

These allow you to access the bitmap mode drawing targets as surfaces. This seems overkill, you might prefer to use the :ref:`bitmap drawing <bitmapdrawing>` routines directly instead.

.. autonim:: surfaces.m3Surface
.. autonim:: surfaces.m4Surface
.. autonim:: surfaces.m5Surface
.. autonim:: surfaces.bmp16Tab
.. autonim:: surfaces.bmp8Tab
.. autonim:: surfaces.chr4cTab

-----------------------------

Common Procedures
=================

.. autonim:: surfaces.init
.. autonim:: surfaces.copyColors
.. autonim:: surfaces.getPtr
.. autonim:: surfaces.getPtr_2
.. autonim:: surfaces.setPtr
.. autonim:: surfaces.align
.. autonim:: surfaces.setPal

-----------------------------

16bpp bitmap surfaces
=====================

Routines for 16bpp linear surfaces. For use in modes 3 and 5. Can
also be used for regular tilemaps to a point.

.. autonim:: surfaces.init_4
.. autonim:: surfaces.getPixel
.. autonim:: surfaces.plot
.. autonim:: surfaces.hline
.. autonim:: surfaces.vline
.. autonim:: surfaces.line
.. autonim:: surfaces.rect
.. autonim:: surfaces.frame
.. autonim:: surfaces.blit
.. autonim:: surfaces.floodfill

-----------------------------

8bpp bitmap surfaces
====================

Routines for 8bpp linear surfaces. For use in mode 4 and affine tilemaps.

.. autonim:: surfaces.init_5
.. autonim:: surfaces.getPixel_2
.. autonim:: surfaces.plot_2
.. autonim:: surfaces.hline_2
.. autonim:: surfaces.vline_2
.. autonim:: surfaces.line_2
.. autonim:: surfaces.rect_2
.. autonim:: surfaces.frame_2
.. autonim:: surfaces.blit_2
.. autonim:: surfaces.floodfill_2

-----------------------------

4bpp tiled surfaces, column-major
=================================

.. autonim:: surfaces.init_2
.. autonim:: surfaces.getPixel
.. autonim:: surfaces.plot_3
.. autonim:: surfaces.hline_3
.. autonim:: surfaces.vline_3
.. autonim:: surfaces.line_3
.. autonim:: surfaces.rect_3
.. autonim:: surfaces.frame_3
.. autonim:: surfaces.blit_3
.. autonim:: surfaces.floodfill_3
.. autonim:: surfaces.prepMap
.. autonim:: surfaces.getPtr_2

-----------------------------

4bpp tiled surfaces, row-major
==============================

.. autonim:: surfaces.init_3
.. autonim:: surfaces.getPixel_3
.. autonim:: surfaces.plot_4
.. autonim:: surfaces.hline_4
.. autonim:: surfaces.vline_4
.. autonim:: surfaces.line_4
.. autonim:: surfaces.rect_4
.. autonim:: surfaces.frame_4
.. autonim:: surfaces.prepMap_2
.. autonim:: surfaces.getPtr_3