Add more doxygen comments to library

include/nf_tiledbg.h

@@ -88,107 +88,231 @@ extern NF_TYPE_TBGLAYERS_INFO NF_TILEDBG_LAYERS[2][4];	//[screen][layer]
 extern u8 NF_TILEBLOCKS[2][NF_MAX_BANKS_TILES];
 extern u8 NF_MAPBLOCKS[2][NF_MAX_BANKS_MAPS];
 
-
-
-// Funcion NF_InitTiledBgBuffers();
+/// Initialize library to load files from the filesystem to create tiled BGs.
+///
+/// Use this function once before loading any BG from FAT.
+///
+/// Example:
+/// <pre>
+/// // Init buffers and variables to load tiled BGs
+/// NF_InitTiledBgBuffers();
+/// </pre>
 void NF_InitTiledBgBuffers(void);
-// Inicializa los buffers y estructuras de control para usar los fondos "tileados"
-// Se debe usar antes de cargar o usar cualquier fondo
-// No uses esta funcion mas de una vez en tu codigo
 
-
-
-// Funcion NF_ResetTiledBgBuffers();
+/// Reset state used for tiled BGs loaded from FAT.
+///
+/// This function empties all buffers in use and resets variables to their
+/// default values. It’s useful to do this when you change a level in a game,
+/// to clean all stuff from RAM and make free space to load the new level.
+///
+/// Example:
+/// <pre>
+/// // Empty all buffers and reset variable values
+/// NF_ResetTiledBgBuffers();
+/// </pre>
 void NF_ResetTiledBgBuffers(void);
-// Borra todos los buffers y reinicia las estructuras de fondos "tileados"
-// Usala para los cambios de nivel y similares
 
-
-
-// Funcion NF_InitTiledBgSys();
+/// Initialize the tiled BG engine of the selected screen.
+///
+/// You must call this function before using any tiled BG. This function:
+///
+/// - Inititializes all variables to control BGs, tiles, palettes and maps.
+/// - Configures VRAM to use 128 KB for BGs (96 KB for tiles, 32 KB for maps).
+/// - Activates all 4 layers to use with tiled BGs.
+/// - Reserves 8 banks of 16 KB for tiles (2 for maps, 6 for tiles).
+/// - Reserves 16 banks of 2 KB for maps. The first 2 tile banks will be used
+///   for this.
+/// - Enables extended palettes.
+///
+/// The memory allocated for tiles and maps is defined in:
+/// <pre>
+/// #define NF_BANKS_TILES 8
+/// #define NF_BANKS_MAPS 16
+/// </pre>
+/// Each tile bank is as big as 8 map banks.
+///
+/// Example:
+/// <pre>
+/// // Init tiled BG system of screen 1
+/// NF_InitTiledBgSys(1);
+/// </pre>
+///
+/// @param screen Screen (0 - 1).
 void NF_InitTiledBgSys(u8 screen);
-// Inicializa las variables de control de tiles, mapas y paletas
-// Asigna 128kb de RAM para fondos tileados
-// Se debe especificar la pantalla (0 o 1)
 
-
-
-// Funcion NF_LoadTiledBg();
+/// Load all files needed to create a tiled BG from FAT to RAM.
+///
+/// All files for a BG must have the same name, using IMG extension for tiles
+/// files, MAP for map files and PAL for palette files.
+///
+/// Check the GRIT folder for more info about BG files conversion.
+///
+/// You can load up to 32 BGs at the same time, this is defined in:
+/// <pre>
+/// #define NF_SLOTS_TBG 32
+/// </pre>
+///
+/// Example:
+/// <pre>
+/// // Load to RAM files "mainstage.img", "mainstage.map" and "mainstage.pal"
+/// // from the "stage1" subfolder and call it “mifondo”. Also store the size of
+/// // the BG (2048 x 256).
+/// NF_LoadTiledBg("stage1/mainstage", "mifondo", 2048, 256);
+/// </pre>
+///
+/// @param file File path without extension.
+/// @param name Name used for the BG for other functions.
+/// @param width BG width.
+/// @param height BG height.
 void NF_LoadTiledBg(const char* file, const char* name, u16 width, u16 height);
-// Carga un fondo tileado desde FAT
-// Debes de especificar el archivo que se cargara (sin extension) y el nombre
-// que le quieres dar y las medidas en pixeles
 
-
-
-// Funcion NF_LoadTilesForBg();
+/// Load a tilesed and palette from FAT to RAM.
+///
+/// It works like NF_LoadTiledBg() but it lets you specify the range of tiles to
+/// load. Also, no actual map is loaded. Instead, a blank map of the given size
+/// is created. The background is created using NF_CreateTiledBg().
+///
+/// Example:
+/// <pre>
+/// // Load to RAM tiles 0 to 23 (24 tiles in total) from "mainstage.img" and
+/// // the palette (from "mainstage.pal") file, from "stage1" subfolder and
+/// // assigns the "mifondo" name to the background. It also sets the size of
+/// // background to 256x256 pixels. This creates a 32x32 tiles blank map.
+/// NF_LoadTilesForBg("stage1/mainstage", "mifondo", 256, 256, 0, 23);
+/// </pre>
+///
+/// @param file File name, without extension.
+/// @param name Name of the BG.
+/// @param width Width of the BG in pixels.
+/// @param height Height of the BG in pixels.
+/// @param tile_start First tile to load.
+/// @param tile_end Last tile to load.
 void NF_LoadTilesForBg(const char* file, const char* name, u16 width, u16 height, u16 tile_start, u16 tile_end);
-// Carga desde la FAT los tiles especificados y su paleta
-// Ademas, crea un mapa vacio de la medida especificada
-// Esta funcion es util para cargar varios tiles y despues generar fondos
-// modificando el MAP desde cogido (Generador de escenarios, animaciones, etc)
 
-
-
-// Funcion NF_UnloadTiledBg();
+/// Delete from RAM the BG with the specified name.
+///
+/// You can delete from RAM the BG if you don't need it more or if the size of
+/// the BG size is less or equal than 512 x 512. If it's bigger, you must keep
+/// it in RAM until you don't need it anymore.
+///
+/// Example:
+/// <pre>
+/// // Delete from RAM the BG with name "mifondo" and mark as free the slot it
+/// // uses.
+/// NF_UnloadTiledBg("mifondo");
+/// </pre>
+///
+/// @param name Name used for the BG.
 void NF_UnloadTiledBg(const char* name);
-// Borra de la RAM un fondo cargado con NF_LoadTiledBg();
-// Debes especificar el nombre que le diste al fondo
 
-
-
-// Funcion NF_CreateTiledBg();
+/// Create a BG on the screen, using data loaded in RAM.
+///
+/// This function copies to VRAM all required data. Before you create the BG,
+/// you must load data to RAM using NF_LoadTiledBg(). The BG is created on the
+/// specified screen and layer.
+///
+/// Example:
+/// <pre>
+/// // Create a tiled BG on layer 3 of screen 0, using the BG called "mifondo"
+/// NF_CreateTiledBg(0, 3, "mifondo");
+/// </pre>
+///
+/// @param screen Screen (0 - 1).
+/// @param layer Layer (0 - 3).
+/// @param name Name used for the BG.
 void NF_CreateTiledBg(u8 screen, u8 layer, const char* name);
-// Crea un fondo con los parametros dados, indicale la pantalla, capa y nombre
 
-
-
-// Funcion NF_DeleteTiledBg();
+/// Delete the BG of the specified screen and layer.
+///
+/// This also deletes from VRAM the data used by this BG.
+///
+/// Example:
+/// <pre>
+/// // Deletes the tiled BG from layer 3 of screen 0
+/// NF_DeleteTiledBg(0, 3);
+/// </pre>
+///
+/// @param screen Screen (0 - 1).
+/// @param layer Layer (0 - 3).
 void NF_DeleteTiledBg(u8 screen, u8 layer);
-// Borra un fondo de la memoria VRAM
-// Debes especificar la pantalla y numero de capa
 
+/// Gets the address of the tile at the specified position.
+///
+/// Internal use.
+///
+/// @param screen Screen (0 - 1).
+/// @param layer Layer (0 - 3).
+/// @param tile_x X coordinate.
+/// @param tile_y Y coordinate.
+/// @return Tile address.
+u32 NF_GetTileMapAddress(u8 screen, u8 layer, u16 tile_x, u16 tile_y);
 
+/// Gets the value of the tile at the specified position.
+///
+/// Example:
+/// <pre>
+/// // Gets the value of the tile at (20, 10) of the map loaded on screen 0,
+/// // layer 2.
+/// u16 mytile = NF_GetTileOfMap(0, 2, 10, 20);
+/// </pre>
+///
+/// @param screen Screen (0 - 1).
+/// @param layer Layer (0 - 3).
+/// @param tile_x X coordinate.
+/// @param tile_y Y coordinate.
+/// @return Tile index.
+u16 NF_GetTileOfMap(u8 screen, u8 layer, u16 tile_x, u16 tile_y);
 
-
-
-// Funcion NF_GetTileMapAddress();
-extern u32 NF_GetTileMapAddress(u8 screen, u8 layer, u16 tile_x, u16 tile_y);
-// Funcion de uso interno de la libreria
-// Devuelve la direccion en el buffer de un tile concreto
-
-
-
-
-
-// Funcion NF_GetTileOfMap();
-extern u16 NF_GetTileOfMap(u8 screen, u8 layer, u16 tile_x, u16 tile_y);
-// Obten el valor del tile del mapa indicado en las coordenadas (en tiles) indicadas.
-
-
-
-
-// Funcion NF_SetTileOfMap();
+/// Sets the value of the tile at the specified position.
+///
+/// Example:
+/// <pre>
+/// // Sets to 5 the tile at (20, 10) of the map loaded on screen 0, layer 2.
+/// NF_SetTileOfMap(0, 2, 10, 20, 5);
+/// </pre>
+///
+/// @param screen Screen (0 - 1).
+/// @param layer Layer (0 - 3).
+/// @param tile_x X coordinate.
+/// @param tile_y Y coordinate.
+/// @param tile Tile index.
 void NF_SetTileOfMap(u8 screen, u8 layer, u16 tile_x, u16 tile_y, u16 tile);
-// Cambia el valor del tile del mapa indicado en las coordenadas (en tiles) indicadas.
 
-
-
-
-// Funcion NF_UpdateVramMap();
+/// Updates the map of the specified screen and layer specified.
+///
+/// This updates the map on VRAM with the copy of RAM, that can be modified. Use
+/// this fuction to apply changes made with NF_SetTileOfMap().
+///
+/// Example:
+/// <pre>
+/// // Update the map in VRAM with the modified copy in RAM of screen 0, layer 2
+/// NF_UpdateVramMap(0, 2);
+/// </pre>
+///
+/// @param screen Screen (0 - 1).
+/// @param layer Layer (0 - 3).
 void NF_UpdateVramMap(u8 screen, u8 layer);
-// Actualiza en VRAM el contenido del mapa seleccionado.
 
-
-
-
-// Funcion NF_BgSetPalColor();
+/// Changes the value of one color of the palette of a background.
+///
+/// The change is made directly in VRAM, so it may be overwritten from the copy
+/// in RAM. It's also a very slow function, use it twice or 3 times per frame.
+///
+/// Example:
+/// <pre>
+/// // Change the value of color 1 of the palette of layer 3 on top screen to
+/// // red. If this layer is a text layer with the default font, the text
+/// // becomes red.
+/// NF_BgSetPalColor(0, 3, 1, 31, 0, 0);
+/// </pre>
+///
+/// @param screen Screen (0 - 1).
+/// @param layer Layer (0 - 3).
+/// @param number Color number (0 - 255).
+/// @param r Red component (0 - 31).
+/// @param g Green component (0 - 31).
+/// @param b Blue component (0 - 31).
 void NF_BgSetPalColor(u8 screen, u8 layer, u8 number, u8 r, u8 g, u8 b);
-// Cambia al momento el valor de un color de la paleta
-// Cuidado! Funcion Muy lenta, usar solo para 2 o 3 colores por ciclo
-// Cambia el color directamente en la VRAM
-
-
 
 
 
@@ -219,7 +343,7 @@ void NF_BgGetPalColor(u8 screen, u8 layer, u8 number, u8* r, u8* g, u8* b);
 
 
 // Funcion NF_GetTilePal();
-extern u8 NF_GetTilePal(u8 screen, u8 layer, u16 tile_x, u16 tile_y);
+u8 NF_GetTilePal(u8 screen, u8 layer, u16 tile_x, u16 tile_y);
 // Devuelve que numero de paleta (0 - 15) esta usando el tile del fondo especificado.
 // Por defecto, todos los tiles usan la paleta del Slot nº0
 // Los datos se obtienen de la compia en RAM del mapa del fondo.