knightfox75/nds_nflib
1
Fork 0
mirror of https://github.com/knightfox75/nds_nflib.git synced 2025-06-18 16:55:32 -04:00
Code Issues Actions Packages Projects Releases Wiki Activity

doxygen: Document collision and sound modules

Browse Source
This commit is contained in:
Antonio Niño Díaz 2023-04-30 15:47:47 +01:00
parent 027e5579be
commit be55199098
3 changed files with 159 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
include/nf_2d.h
View File

@ -247,7 +247,7 @@ void NF_DisableSpriteRotScale(u8 screen, u8 sprite);
/// </pre>
///
/// @param screen Screen (0 - 1).
/// @param sprite Sprite ID (0 - 127).
/// @param id Sprite ID (0 - 127).
/// @param angle Angle (-512 to 512).
/// @param sx X scale (0 to 512), 100% = 256.
/// @param sy Y scale (0 to 512), 100% = 256.

137
include/nf_collision.h
View File

@ -15,75 +15,119 @@ extern "C" {
#include <nds.h>
/// @file nf_collision.h
/// @brief Collision map support.
/// @defgroup nf_collision Collision map support.
///
/// Collision maps only have map information, so the collisions have a
/// granularity of 8x8 pixels. This is useful for games where the map is simple
/// and it doesn't have many details that affect collisions.
///
/// Collision backgrounds also have tile information, so they can have
/// information at a pixel granularity.
///
/// @{
// Define los slots maximos para los mapas de colisiones
/// Maximum number of available collision maps
#define NF_SLOTS_CMAP 32
// Define la estructura de control de mapas de colisiones
/// Struct that holds collision map information
typedef struct {
char* tiles; // Buffer para almacenar los tiles
char* map; // Buffer para almacenar el mapa
char* pal; // Buffer para almacenar la paleta
u32 tiles_size; // Tamaño de los archivos
u32 map_size;
u32 pal_size;
u16 width; // Ancho del mapa (en pixeles)
u16 height; // Alto del mapa (en pixeles)
bool inuse; // Esta en uso el slot?
char* tiles; ///< Tileset data
char* map; ///< Map data
char* pal; ///< Palette data (TODO: Remove, it looks unused)
u32 tiles_size; ///< Size of the tileset
u32 map_size; ///< Size of the map
u32 pal_size; ///< Size of the palette (TODO: Remove, it looks unused)
u16 width; ///< Width of map in pixels
u16 height; ///< Height of map in pixels
bool inuse; ///< True if the slot is in use
} NF_TYPE_CMAP_INFO;
extern NF_TYPE_CMAP_INFO NF_CMAP[NF_SLOTS_CMAP]; // Datos de los mapas de colision
/// Information of all collision maps
extern NF_TYPE_CMAP_INFO NF_CMAP[NF_SLOTS_CMAP];
// Funcion NF_InitCmapBuffers();
/// Initialize buffers to store collision map data.
///
/// You must call this function once in you code before loading any collision
/// map.
void NF_InitCmapBuffers(void);
// Inicializa los buffers que almacenaran los mapas de colision
// Debes usar esta funcion una unica vez antes de cargar ningun mapa de colision
// Funcion NF_ResetCmapBuffers();
/// Reset collision map buffers, clearing all data in RAM.
///
/// It's useful to use this function during game level changes, for example, to
/// easily clear all data before loading the new level.
void NF_ResetCmapBuffers(void);
// Reinicia los buffers y variables de los mapas de colisiones.
/// Load a collision map into RAM in the specified slot.
///
/// You must specify the width and height of the map in pixels. Remember to make
/// your collision map 8 pixels taller than your background and to use this
/// first row of tiles to define your tileset for the collision map.
///
/// Use the "Convert_CMaps.bat" script in the GRIT folder to convert your maps.
/// You need to copy the ".cmp" file to your game data folder.
///
/// @param file File name
/// @param id Slot number (0 - 31)
/// @param width Map width (in pixels)
/// @param height Map height (in pixels)
void NF_LoadCollisionMap(const char* file, u8 id, u16 width, u16 height);
// Carga un mapa de colisiones en el slot indicado.
/// Unload from RAM the collision map at the specified slot.
///
/// @param id Slot number (0 - 31)
void NF_UnloadCollisionMap(u8 id);
// Borra de la RAM el mapa de colisiones con el nº de slot indicado.
/// Return the tile number at the specified position.
///
/// You must place your tileset in the first row of the collision map image.
///
/// @param slot Slot number (0 - 31)
/// @param x X coordinate in pixels.
/// @param y Y coordinate in pixels.
/// @return Tile index.
u16 NF_GetTile(u8 slot, s32 x, s32 y);
// Funcion NF_GetTile();
extern u16 NF_GetTile(u8 slot, s32 x, s32 y);
// Devuelve el numero de tile de la posicion especificada.
// Funcion NF_SetTile();
/// Set the value of the tile of a collision map at the specified position.
///
/// @param slot Slot number (0 - 31)
/// @param x X coordinate in pixels.
/// @param y Y coordinate in pixels.
/// @param value New tile.
void NF_SetTile(u8 slot, s32 x, s32 y, u16 value);
// Cambia el valor del tile en la posicion especificada.
/// Load a collision background to RAM at the specified slot.
///
/// You must specify the width and height of the background in pixels. Remember
/// to make your colision background 8 pixels taller than your real background
/// and to use this first row of tiles to define your color tileset for the
/// collision background.
///
/// Use the "Convert_CMaps.bat" script in the GRIT folder to convert you maps.
/// You need to copy the ".cmp" and ".dat" files to your game data folder.
///
/// @param file File name
/// @param id Slot number (0 - 31)
/// @param width Map width (in pixels)
/// @param height Map height (in pixels)
void NF_LoadCollisionBg(const char* file, u8 id, u16 width, u16 height);
// Carga un fondo de colisiones para pixel perfect
/// Unload from RAM the collision background at the specified slot.
///
/// @param id Slot number (0 - 31)
void NF_UnloadCollisionBg(u8 id);
// Descarga un fondo de colisiones para pixel perfect
// Funcion NF_GetPoint();
extern u8 NF_GetPoint(u8 slot, s32 x, s32 y);
// Obten el color del pixel de las coordenadas dadas
/// Returns the color number at the specified coordinates.
///
/// If the coordinates are outside of the background, it returns 0.
///
/// @param slot Slot number (0 - 31)
/// @param x X coordinate in pixels.
/// @param y Y coordinate in pixels.
/// @return Tile index (0 - 255).
u8 NF_GetPoint(u8 slot, s32 x, s32 y);
// Defines for backwards compatibility
#define NF_LoadColisionMap NF_LoadCollisionMap
@ -91,6 +135,7 @@ extern u8 NF_GetPoint(u8 slot, s32 x, s32 y);
#define NF_LoadColisionBg NF_LoadCollisionBg
#define NF_UnloadColisionBg NF_UnloadCollisionBg
/// @}
#endif

114
include/nf_sound.h
View File

@ -15,72 +15,92 @@ extern "C" {
#include <nds.h>
/// @file nf_sound.h
/// @brief Sound support functions.
/// @defgroup nf_sound Sound support functions.
///
/// Simple helpers to load and play raw PCM sound files.
///
/// @{
// Define los Slots para archivos de audio
/// Number of slot availables for raw sound effects
#define NF_SLOTS_RAWSOUND 32
// Define los Buffers para almacenar los archivos de audio
/// Buffers of all loaded sound files
extern char* NF_BUFFER_RAWSOUND[NF_SLOTS_RAWSOUND];
// Define la estructura de datos de los buffers (Audio)
// Struct that holds information about the loaded sound files
typedef struct {
bool available; // Disponibilidat del Slot
u32 size; // Tamaño (en bytes) del sonido
u16 freq; // Frecuencia del sample
u8 format; // Formato del sample
bool available; ///< True if this slot is available
u32 size; ///< Size of the sound effect in bytes
u16 freq; ///< Frecuency of the sample
u8 format; ///< Format of the sample
} NF_TYPE_RAWSOUND_INFO;
extern NF_TYPE_RAWSOUND_INFO NF_RAWSOUND[NF_SLOTS_RAWSOUND]; // Datos de los sonidos cargado
/// Information of all sound effects.
extern NF_TYPE_RAWSOUND_INFO NF_RAWSOUND[NF_SLOTS_RAWSOUND];
// Funcion NF_InitRawSoundBuffers();
/// Initialize all buffers and variables to load sound files.
///
/// You must use this function once before loading or using any sound file.
/// Remember to initialize the DS sound engine using soundEnable().
void NF_InitRawSoundBuffers(void);
// Iniciliaza los buffers y estructuras de datos para cargar sonidos en
// formato RAW. Debes de ejecutar esta funcion una vez antes de cargar
// ningun sonido en este formato
// Funcion NF_ResetRawSoundBuffers();
/// Resets all sound buffers and clears the data in them.
///
/// It's useful when you change a level in the game, for example.
void NF_ResetRawSoundBuffers(void);
// Reinicia todos los buffers de sonido. Esta funcion es util para vaciar todos los datos
// en un cambio de pantalla, etc.
// Funcion NF_LoadRawSound();
/// Load a RAW file from the filesystem to RAM.
///
/// To convert sound files to "RAW" format you can use the free program "Switch"
/// http://www.nch.com.au/switch/plus.html. The best parameters for "RAW" files
/// on the DS are: 8 bits signed, mono, 11025 Hz or 22050 Hz.
///
/// Example:
/// ```
/// // Load "music.raw" to slot 1. This file is encoded as 8 bit at 22050 Hz
/// NF_LoadRawSound("music", 1, 22050, 0);
/// ```
///
/// @param file File name without extension
/// @param id Destination slot number (0 - 31)
/// @param freq Frequency of the sample in Hz (11025, 22050, etc)
/// @param format Sample format (0 -> 8 bits, 1 -> 16 bits, 2 -> ADPCM).
void NF_LoadRawSound(const char* file, u16 id, u16 freq, u8 format);
// Carga un archivo RAW a la RAM desde la FAT o EFS
// Debes especificar el nombre del archivo sin extension, el slot
// donde lo guardaras (0 - 31), la frecuencia del sample (en Hz,
// por ejemplo 11050) y el formato de datos
// (0 - > 8 bits, 1 - > 16 bits, 2 -> ADPCM)
// Funcion UnloadRawSound();
/// Deletes from RAM the sound file stored in the specified slot.
///
/// @param id Slot number (0 - 31)
void NF_UnloadRawSound(u8 id);
// Borra de la RAM el archivo cargado en el slot indicado.
// Debes especificar el slot a borrar (0 - 31)
// Funcion NF_PlayRawSound();
extern u8 NF_PlayRawSound(u8 id, u8 volume, u8 pan, bool loop, u16 loopfrom);
// Reproduce un archivo de sonido cargado en RAM.
// Debes especificar el slot donde se ha cargado el sonido, el volumen (0 - 127),
// el balance (0 Izquierda, 64 Centro, 127 Derecha), si se reproducira en bucle y
// de ser asi, a partir de que sample se producira este.
// Esta funcion devuelve el canal asignado a esta reproduccion
/// Play the sound file loaded in the specified slot.
///
/// If you want to loop the sound you must also set the sample number where the
/// loop starts.
///
/// This fuction also returns the channel number asigned to the playback.
///
/// Example:
/// ```
/// // Play the sound stored in slot 1 with full volume (127), centered (64),
/// // with looping enabled from the beginning.
/// NF_PlayRawSound(1, 127, 64, true, 0);
/// ```
///
/// You can use libnds functions to pause, stop and set the volume of the sound
/// while it plays.
///
/// @param id Slot number (0 - 31)
/// @param volume Volume (0 - 127)
/// @param pan Panning. 0: left, 64: center, 127: right.
/// @param loop True if you want the sound to loop.
/// @param loopfrom Loop starting point
/// @return Channel number that is playing the sound.
u8 NF_PlayRawSound(u8 id, u8 volume, u8 pan, bool loop, u16 loopfrom);
/// @}
#endif