// SPDX-License-Identifier: MIT // // Copyright (c) 2009-2014 Cesar Rincon "NightFox" // // NightFox LIB - Include de Sprites a 256 colores // http://www.nightfoxandco.com/ // Version 20140413 #ifdef __cplusplus extern "C" { #endif #ifndef __NF_SPRITE256_H__ #define __NF_SPRITE256_H__ /// @file nf_sprite256.h /// @brief Functions related to 256 color sprites. /// @defgroup nf_sprite256 256 color sprites /// /// Functions to load and handle 256 color sprites. /// /// @{ #include /// Maximum number of slots of 256 color sprites #define NF_SLOTS_SPR256GFX 256 /// Maximum number of slots of palettes of 256 color sprites #define NF_SLOTS_SPR256PAL 64 /// Buffers to hold 256 color sprite graphics extern char* NF_BUFFER_SPR256GFX[NF_SLOTS_SPR256GFX]; /// Buffers to hold 256 color sprite palettes extern char* NF_BUFFER_SPR256PAL[NF_SLOTS_SPR256PAL]; /// Struct that holds information about sprite graphics in RAM typedef struct { u32 size; ///< Size in bytes of the graphics data u16 width; ///< Width of graphics data u16 height; ///< Height of graphics data bool available; ///< True if this slot is free, false otherwise } NF_TYPE_SPR256GFX_INFO; /// Information of all sprite graphics in RAM extern NF_TYPE_SPR256GFX_INFO NF_SPR256GFX[NF_SLOTS_SPR256GFX]; /// Struct that holds information about sprite palettes in RAM typedef struct { u32 size; ///< Size in bytes of the palette bool available; ///< True if this slot is free, false otherwise } NF_TYPE_SPR256PAL_INFO; /// Information of all palettes in RAM extern NF_TYPE_SPR256PAL_INFO NF_SPR256PAL[NF_SLOTS_SPR256PAL]; /// Struct that holds information about sprite graphics in VRAM typedef struct { u32 size; ///< Size in bytes of the graphics data u16 width; ///< Width of graphics data u16 height; ///< Height of graphics data u32 address; ///< Address of the graphics in VRAM u16 ramid; ///< RAM slot with the original copy of the graphics u16 framesize; ///< Size of a frame in bytes u16 lastframe; ///< Last frame index bool keepframes; ///< For animated sprites, keep all frames in RAM bool inuse; ///< True if this slot is in use } NF_TYPE_SPR256VRAM_INFO; /// Information of all sprite graphics in VRAM extern NF_TYPE_SPR256VRAM_INFO NF_SPR256VRAM[2][128]; /// Struct that holds information about sprite palettes in VRAM typedef struct { bool inuse; ///< True if this slot is in use u8 ramslot; ///< Slot index of the original palette in RAM } NF_TYPE_SPRPALSLOT_INFO; /// Information of all palettes in VRAM extern NF_TYPE_SPRPALSLOT_INFO NF_SPRPALSLOT[2][16]; /// Struct that defines OAM information typedef struct { u8 index; ///< Sprite number s16 x; ///< X coordinate s16 y; ///< Y coordinate u8 layer; ///< Layer priority u8 pal; ///< Palette index u32 size; ///< Sprite of the sprite (macro) u32 color; ///< Color mode (macro) u32* gfx; ///< Pointer to the graphics data s8 rot; ///< Rotation matrix index (0 - 31, -1 = none) bool doublesize; ///< Enable double size mode when rotating bool hide; ///< Hide the sprite bool vflip; ///< Vertical flip bool hflip; ///< Horizontal flip bool mosaic; ///< Enable mosaic effect u16 gfxid; ///< Graphics object ID u16 frame; ///< Current frame u16 framesize; ///< Size of the frame in bytes u16 lastframe; ///< Last frame bool created; ///< True if this sprite has been created } NF_TYPE_SPRITEOAM_INFO; /// OAM information of all sprites extern NF_TYPE_SPRITEOAM_INFO NF_SPRITEOAM[2][128]; /// Struct with information of sprite allocation in VRAM typedef struct { s32 free; ///< Free VRAM u32 next; ///< Next free location u32 last; ///< Last used location u32 pos[128]; ///< Location in VRAM to reuse after a free u32 size[128]; ///< Size of the block to reuse u16 deleted; ///< Number of free'd blocks s32 fragmented; ///< Fragmented VRAM s32 inarow; ///< Contiguous VRAM s32 max; ///< Maxmimum addressable VRAM } NF_TYPE_SPRVRAM_INFO; /// Information of sprite allocation in VRAM of both screens extern NF_TYPE_SPRVRAM_INFO NF_SPRVRAM[2]; /// Initialize library to load files from the filesystem to create 256 color /// sprites. /// /// Use this function once before loading any sprite from FAT. Don't call it /// more than once. /// /// Example: /// ``` /// // Init buffers and variables to load sprites. /// NF_InitSpriteBuffers(); /// ``` void NF_InitSpriteBuffers(void); /// Reset state used for 256 color sprites 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: /// ``` /// // Empty all buffers and reset variable values /// NF_ResetSpriteBuffers(); /// ``` void NF_ResetSpriteBuffers(void); /// Initialize sprite system in the specified screen. /// /// - Initializes OAM with default parameters. /// - It assigns 128 KB of VRAM for graphics and palettes. /// - It enables extended palettes. /// /// The VRAM mapping parameter is optional, if you don’t set it, 64 is set by /// default. You can use up to 1024 chunks of 64 bytes (64 mapping mode) or 128 /// bytes (128 mapping mode) and 16 palettes. The use of mode 64 limits the /// amount of usable VRAM to 64 KB. When using mode 128, 8x8 pixels sprites /// can't be used. /// /// Example: /// ``` /// // Initialize 256 color sprite system in screen 0 in 64 mapping mode and in /// // screen 1 in 128 mapping mode /// NF_InitSpriteSys(0); /// NF_InitSpriteSys(1, 128); /// ``` /// /// @param screen Screen (0 - 1). /// @param ... VRAM mapping mode (64 or 128). void NF_InitSpriteSys(int screen, ...); /// Load sprite graphics from the filesystem to RAM to use it later. /// /// You must specify the filename without extension. You must use the ".img" /// extension in the filename of you sprite graphics file. You must select the /// RAM slot to hold the graphics (0 to 255), and the graphics sizes. If it's /// an animated sprite, put the size in pixels of first frame. /// /// There are 256 available slots, as specified in: /// ``` /// #define NF_SLOTS_SPR256GFX 256 /// ``` /// /// Example: /// ``` /// // Loads file "name.img" from folder "stage3" and stores it in slot 100 of /// // RAM. This graphics objectx has a size of 64 x 32. /// NF_LoadSpriteGfx("stage3/nave", 100, 64, 32); /// ``` /// /// @param file File name without extension. /// @param id Slot number (0 - 255). /// @param width Width of the graphics object (in pixels). /// @param height Height of the graphics object (in pixels). void NF_LoadSpriteGfx(const char* file, u16 id, u16 width, u16 height); /// Delete from RAM the graphics of the selected slot and mark it as free. /// /// You can delete the graphics from RAM once the sprite is created if you /// don't need it anymore or, if it's animated, after transferring all frames to /// VRAM. /// /// Example: /// ``` /// // Delete from RAM the graphics in slot 100 and mark it as free /// NF_UnloadSpriteGfx(100); /// ``` /// @param id Slot number (0 - 255). void NF_UnloadSpriteGfx(u16 id); /// Load a palette from the filesystem to RAM to be used for a sprite. /// /// You must enter the filename without extension. You must use ".pal" extension /// in all your palette files. /// /// You can store up to 64 palettes, as specified in: /// ``` /// #define NF_SLOTS_SPR256PAL 64 /// ``` /// /// Example: /// ``` /// // Load file "player.pal" from folder "stage3" and store it in slot 34 /// NF_LoadSpritePal(“stage3/player”, 34); /// ``` /// /// @param file File name without extension. /// @param id Slot number (0 - 63). void NF_LoadSpritePal(const char* file, u8 id); /// Delete the selected palette from RAM and mark it as free. /// /// You can delete it if you don't need it anymore or if it's already in VRAM. /// /// @param id Slot number (0 - 63). void NF_UnloadSpritePal(u8 id); /// Copy a graphics object from RAM to VRAM of the selected screen to be used as /// a sprite. /// /// You must specify if you want to copy all frames to VRAM (false) or just the /// first one (true). /// /// Example: /// ``` /// // Copy the graphics object stored in slot 160 of RAM to slot 23 of VRAM of /// // screen 1, copying all frames if it’s animated. /// NF_VramSpriteGfx(1, 160, 23, false); /// ``` /// /// @param screen Screen (0 - 1). /// @param ram RAM slot (0 - 255). /// @param vram VRAM slot (0 - 127). /// @param keepframes For animated sprites. If true, copy all frames to VRAM. void NF_VramSpriteGfx(u8 screen, u16 ram, u16 vram, bool keepframes); /// Delete from VRAM the graphics object of the selected slot and a screen. /// /// You mustn't delete the graphics while a sprite is using them. /// /// Example: /// ``` /// // Delete from VRAM of screen 1 the graphics in slot 34 /// NF_FreeSpriteGfx(1, 34); /// ``` /// @param screen Screen (0 - 1). /// @param id VRAM slot (0 - 127). void NF_FreeSpriteGfx(u8 screen, u16 id); /// Defragments the free VRAM used for sprite graphics. /// /// This function is automaticaly executed when fragmented free VRAM is bigger /// than 50% of the total free VRAM. You don’t need to manually execute this /// function. You can get the state of VRAM reading the following variables: /// /// ``` /// NF_SPRVRAM[u8 screen].free // Total free VRAM /// NF_SPRVRAM[u8 screen].fragmented // Total fragmented free VRAM /// NF_SPRVRAM[u8 screen].inarow // Largest free block of VRAM at the end /// NF_SPRVRAM[u8 screen].lost // Unusable free VRAM because fragmentation /// ``` /// /// Example: /// ``` /// // Defragments the free VRAM of sprites of screen 1 /// NF_VramSpriteGfxDefrag(1); /// ``` /// /// @param screen Screen (0 - 1). void NF_VramSpriteGfxDefrag(u8 screen); /// Copy the palette from RAM to a slot of extended palettes in VRAM. /// /// If the slot is in use, its contents are overwritten. /// /// Example: /// ``` /// // Copy palette from RAM slot 56 to the extended palettes slot 8 of screen 1 /// NF_VramSpritePal(1, 56, 8); /// ``` /// /// @param screen Screen (0 - 1). /// @param id VRAM slot (0 - 64). /// @param slot VRAM slot (0 - 15). void NF_VramSpritePal(u8 screen, u8 id, u8 slot); /// Create a sprite with the specified ID in the selcted screen. /// /// You have to select the graphics object to use, as well as the palette to /// use. You also have to select the initial coordinates of the sprite. /// /// Example: /// ``` /// // Create a sprite on screen 0, with ID 12, using the graphics stored in /// // slot 30 of VRAM and the palette in slot 1. The sprite is created at the /// // coordinates (100, 50). /// NF_CreateSprite(0, 12, 30, 1, 100, 50); /// ``` /// /// @param screen Screen (0 - 1). /// @param id Sprite ID (0 - 127). /// @param gfx Graphics object ID (0 - 127). /// @param pal Palette (0 - 15). /// @param x X coordinate. /// @param y Y coordinate. void NF_CreateSprite(u8 screen, u8 id, u16 gfx, u8 pal, s16 x, s16 y); /// Delete the selected sprite ID from the specified screen. /// /// The graphics and palette used by the sprite won't be deleted from VRAM. /// /// Example: /// ``` /// // Delete sprite ID 12 from screen 0 /// NF_DeleteSprite(0, 12); /// ``` /// /// @param screen Screen (0 - 1). /// @param id Sprite ID (0 - 127). void NF_DeleteSprite(u8 screen, u8 id); /// Copy data from the shadow OAM used by NFLib to the real OAM of libnds. /// /// OAM must be updated only during the vertical blanking period. For example, /// if you don't have a vertical blanking interrupt handler, you can do: /// ``` /// NF_SpriteOamSet(0); /// NF_SpriteOamSet(1); /// swiWaitForVBlank(); /// oamUpdate(&oamMain); /// oamUpdate(&oamSub); /// ``` /// /// If your vertical blanking interrupt handler takes too long to finish, /// oamUpdate() will be called outside of the vertical blanking period, which /// will cause issues. In that case, call the functions from the interrupt /// handler. /// /// @param screen Screen (0 - 1). void NF_SpriteOamSet(u8 screen); /// Changes a color of a sprite palette in the specified screen. /// /// The change is made directly in VRAM, so it may be overwritten from the copy /// in RAM. /// /// Example: /// ``` /// // Set color 1 of palette 3 of the top screen to red. /// NF_SpriteSetPalColor(0, 3, 1, 31, 0, 0); /// ``` /// /// @param screen Screen (0 - 1). /// @param pal Palette index (0 - 15). /// @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_SpriteSetPalColor(u8 screen, u8 pal, u8 number, u8 r, u8 g, u8 b); /// Changes the value of one color in a sprite palettes of the specified screen. /// /// The change is made in the RAM copy of the palette, so you won't see any /// change until you update it on VRAM with NF_SpriteUpdatePalette(). /// /// Use this function to make cool effect on your sprites. /// /// Example: /// ``` /// // Set the value of color 1 of palette 3 of the top screen to red. /// NF_SpriteSetPalColor(0, 3, 1, 31, 0, 0); /// ``` /// /// @param screen Screen (0 - 1). /// @param pal Palette index (0 - 15). /// @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_SpriteEditPalColor(u8 screen, u8 pal, u8 number, u8 r, u8 g, u8 b); /// Updates a sprite palette in VRAM with the copy in RAM of it. /// ///Example: /// ``` /// // Updates palette 2 of the bottom screen. /// NF_SpriteUpdatePalette(1, 2); /// ``` /// /// @param screen Screen (0 - 1). /// @param pal Palette index (0 - 15). void NF_SpriteUpdatePalette(u8 screen, u8 pal); /// Gets the RGB value of a color of a sprites palette in RAM. /// /// Example: /// ``` /// // Gets the RGB value of color 200 from sprites palette 3 of the bottom /// // screen, and stores it in variables "red", "green" and "blue". /// u8 red; /// u8 green; /// u8 blue; /// NF_SpriteGetPalColor(1, 3, 200, &red, &green, &blue); /// ``` /// /// @param screen Screen (0 - 1). /// @param pal Palette index (0 - 15). /// @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_SpriteGetPalColor(u8 screen, u8 pal, u8 number, u8* r, u8* g, u8* b); /// @} #endif #ifdef __cplusplus } #endif