backgrounds
***********

This module makes it possible to work with "background" assets, each of which consists of *tile image data*, *tile map data*, and *palette data*.

Tutorial
========

To add a new background asset in your game.

1. Create a 256x256 image:

   .. image:: media/planet.png
  
   Save it to `backgrounds/planet.png`.

2. Add a line to your project's `backgrounds.nims`:
   
   .. code-block:: nim
      
      # ...
      
      bg "planet.png", kind = bkReg4bpp, flags = { bfScreenblock }
  
   A handle called `bgPlanet` will be created for use in your code.

3. Import `natu/backgrounds` in your game and load the new asset like so:

   .. code-block:: nim
      
      import natu/[video, backgrounds]
      
      # Use a BG Control register to select a charblock and screenblock:
      bgcnt[0].init(cbb = 0, sbb = 31)
      
      # Load the tiles, map and palette into memory:
      bgcnt[0].load(bgPlanet)
      
      # Show the background:
      dispcnt.init(layers = {lBg0})



Background Config Files
=======================

.. nim:proc:: bg(name: string, kind: BgKind, palOffset = 0, tileOffset = 0, flags: set[BgFlag] = {}, regions: openArray[BgRegion] = @[])

   Specify an image to be converted to a background.
   
   :name:
      Path to PNG file.
   
   :kind:
      The kind of BG data that the PNG should be converted to.
      
      * `bkReg4bpp` - Regular background, 16 colors per-tile.
      * `bkReg8bpp` - Regular background, 256 colors.
      * `bkAff` - Affine background, 256 colors.
   
   :palOffset:
      Number of 16-color palettes to shift the map entries by. This also determines to which location the palette data will be copied when calling `load` in your game code.
   
   :tileOffset:
      Number of tiles to shift the map entries by. This also determines to which location the tile image data will be copied when calling `load` in your game code.
   
   :flags:
      Various options that affect conversion:
      
      * `bfScreenblock`
         Arrange the map data into blocks of 32x32 tiles (for non-affine BGs only!)
      
      * `bfBlankTile`
         First tile in the tileset will be empty. (Uuuuhhh avoid this one for now.)
         
         .. "This is recommended for transparent BGs, but note that the blank tile will not be offset by the ``tileOffset``".
            
         .. Wait what.   but it exists in the tileset which gets copied in at an offset, right? What the heck was I thinking?
         
         .. warning::
            This behaviour is flawed and will probably change in a future version. Ensuring the first tile in the tileset is blank vs. stripping the blank tile so that tile index 0 can be shared between multiple tilesets, should become two separate flags I guess.
      
      * `bfAutoPal`
         For 4bpp BGs, attempt to build a set of 16-color palettes from the image. If this flag is omitted, the PNG's own palette will be strictly followed, and each 8x8 tile in the image must only refer to colors from a single group of 16.
  
   
   :regions:
      An array of rectangular areas of the map to be exempt from tile deduplication & flipping. Tiles touching a region are guaranteed to be unique and arranged in a predictable order, allowing you to render text onto them with :doc:`tte`.
      
      Each element is a tuple of the form ``(layout, x1, y1, x2, y2)``, where `layout` is either `Chr4c` or `Chr4r` (see :doc:`surfaces` for explanation), and the coordinates are measured in pixels and are *inclusive*.


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

Types
=====

.. autonim:: backgrounds.BgKind
.. autonim:: backgrounds.BgFlag
.. autonim:: backgrounds.BgData

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



.. autonim:: backgrounds.kind
.. autonim:: backgrounds.flags
.. autonim:: backgrounds.palOffset
.. autonim:: backgrounds.tileOffset
.. autonim:: backgrounds.is8bpp

BG Loading Procedures
=====================

.. autonim:: backgrounds.load
.. autonim:: backgrounds.loadTiles
.. autonim:: backgrounds.loadMap
.. autonim:: backgrounds.loadPal
.. autonim:: backgrounds.loadPal_2