mirror of
https://github.com/knightfox75/nds_nflib.git
synced 2025-06-18 08:45:35 -04:00
418791f8f2
It's better to use the natural extensions of grit rather than the modified extensions of NFLib. Update the documentation to reflect that. Also, remove references to bat scripts.
428 lines
14 KiB
C
428 lines
14 KiB
C
// SPDX-License-Identifier: MIT
|
||
//
|
||
// Copyright (c) 2009-2014 Cesar Rincon "NightFox"
|
||
// Copyright (c) 2023 Antonio Niño Díaz "AntonioND"
|
||
//
|
||
// NightFox LIB - 3D sprite functions
|
||
// http://www.nightfoxandco.com/
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
#ifndef NF_SPRITE3D_H__
|
||
#define NF_SPRITE3D_H__
|
||
|
||
#include <nds.h>
|
||
|
||
/// @file nf_sprite3d.h
|
||
/// @brief Functions related to sprites rendered by the 3D GPU.
|
||
|
||
/// @defgroup nf_sprite3d 3D sprite functions.
|
||
///
|
||
/// These functions are special, since they use the 3D engine to draw sprites
|
||
/// by using textured polygons. It can only be used in one screen at the same
|
||
/// time, and background layer 0 is replaced by the 3D output.
|
||
///
|
||
/// In return we can create up to 256 sprites of a maximum size of 1024x1024, we
|
||
/// can use any size in base 2, and use a maximum of 32 palettes simultaneously.
|
||
///
|
||
/// For the loading of graphics and palettes, use the same functions as with 2D
|
||
/// sprites. You can convert indexed images of 256 colors to create textures for
|
||
/// 3D sprites with the following grit command:
|
||
///
|
||
/// ```
|
||
/// grit image.png -ftb -fh! -gb -gu8 -gB8 -pu8 -gTFF00FF
|
||
/// ```
|
||
///
|
||
/// You can also use the same command used for 8 bit backgrounds.
|
||
///
|
||
/// @{
|
||
|
||
/// Maximum number of slots of 3D sprites
|
||
#define NF_3DSPRITES 256
|
||
|
||
/// Struct that holds information about 3D sprites
|
||
typedef struct {
|
||
s16 x; ///< X coordinate
|
||
s16 y; ///< Y coordinate
|
||
s16 z; ///< Z coordinate
|
||
s16 rx; ///< X axis rotation (-512 << 6 to 512 << 6)
|
||
s16 ry; ///< Y axis rotation (-512 << 6 to 512 << 6)
|
||
s16 rz; ///< Z axis rotation (-512 << 6 to 512 << 6)
|
||
bool rot; ///< True if the sprite is being rotated
|
||
u16 sx; ///< X scale (0 to 64 << 6 to more than 512 << 6)
|
||
u16 sy; ///< Y scale (0 to 64 << 6 to more than 512 << 6)
|
||
bool scale; ///< True if the sprite is being scaled
|
||
s16 width; ///< Sprite width
|
||
s16 height; ///< Sprite height
|
||
bool inuse; ///< True if the sprite is being used
|
||
bool show; ///< True if the sprite has to be drawn
|
||
u32 gfx_tex_format; ///< Texture format
|
||
u32 gfx; ///< Address of the texture in VRAM
|
||
u16 gfxid; ///< ID of the texture/graphics being used by the sprite
|
||
u16 frame; ///< Current frame
|
||
u16 newframe; ///< Next frame
|
||
u16 framesize; ///< Frame size in bytes
|
||
u16 lastframe; ///< Last frame
|
||
u32 gfx_pal_format; ///< Palette format
|
||
u32 pal; ///< Address of the palette in VRAM
|
||
u16 palid; ///< ID of the palette being used by the sprite
|
||
u16 prio; ///< Sprite priority (lower values are higher priorities)
|
||
u8 poly_id; ///< Polygon ID (0 by default, don't use 63)
|
||
u8 alpha; ///< Alpha value (0 - 31) (31 by default)
|
||
} NF_TYPE_3DSPRITE_INFO;
|
||
|
||
/// Information of all 3D sprites
|
||
extern NF_TYPE_3DSPRITE_INFO NF_3DSPRITE[NF_3DSPRITES];
|
||
|
||
/// Struct that holds information about 3D sprite textures in VRAM
|
||
typedef struct {
|
||
u32 size; ///< Size of the texture in bytes
|
||
u16 width; ///< Width
|
||
u16 height; ///< Height
|
||
u32 address; ///< Address in VRAM
|
||
u16 ramid; ///< RAM slot where it comes from
|
||
u16 framesize; ///< Frame size in bytes
|
||
u16 lastframe; ///< Last frame
|
||
bool keepframes; ///< For animated sprites, keep all frames in RAM
|
||
bool inuse; ///< True if this slot is in use
|
||
} NF_TYPE_TEX256VRAM_INFO;
|
||
|
||
/// Information of all 3D sprite textures in VRAM
|
||
extern NF_TYPE_TEX256VRAM_INFO NF_TEX256VRAM[NF_3DSPRITES];
|
||
|
||
/// Struct that holds information about 3D 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_3DSPRPALSLOT_INFO;
|
||
|
||
/// Information of all 3D sprite palettes in VRAM
|
||
extern NF_TYPE_3DSPRPALSLOT_INFO NF_TEXPALSLOT[32];
|
||
|
||
/// Struct with information of 3D sprite allocation in VRAM
|
||
typedef struct {
|
||
s32 free; ///< Free VRAM
|
||
u32 next; ///< Next free location
|
||
u32 last; ///< Last used location
|
||
u32 pos[NF_3DSPRITES]; ///< Location in VRAM to reuse after a free
|
||
u32 size[NF_3DSPRITES]; ///< Size of the block to reuse
|
||
u16 deleted; ///< Number of free'd blocks
|
||
s32 fragmented; ///< Fragmented VRAM
|
||
s32 inarow; ///< Contiguous VRAM
|
||
} NF_TYPE_TEXVRAM_INFO;
|
||
|
||
/// Information of 3D sprite allocation in VRAM
|
||
extern NF_TYPE_TEXVRAM_INFO NF_TEXVRAM;
|
||
|
||
/// Struct with information about created 3D sprites
|
||
typedef struct {
|
||
s16 total; ///< Total number of 3D sprites created
|
||
u16 id[NF_3DSPRITES]; ///< Sprite IDs
|
||
u16 bck[NF_3DSPRITES]; ///< Backup IDs
|
||
} NF_TYPE_CREATED_3DSPRITE_INFO;
|
||
|
||
/// Information of created 3D sprites
|
||
extern NF_TYPE_CREATED_3DSPRITE_INFO NF_CREATED_3DSPRITE;
|
||
|
||
/// Initialize 3D sprite system.
|
||
///
|
||
/// Asigns 128 KB of VRAM for textures and 16 KB for palettes.
|
||
///
|
||
/// It enables extended palettes.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Initialize the 3D sprite system
|
||
/// NF_Init3dSpriteSys();
|
||
/// ```
|
||
void NF_Init3dSpriteSys(void);
|
||
|
||
/// Copy a texture from RAM to VRAM to use it for 3D sprites.
|
||
///
|
||
/// You must specify if you want to copy all frames to VRAM (false) or just the
|
||
/// first one (true).
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Copy the texture stored in slot 160 of RAM to slot 23 of VRAM, copying
|
||
/// // all frames if it's animated.
|
||
/// NF_Vram3dSpriteGfx(160, 23, false);
|
||
/// ```
|
||
///
|
||
/// @param ram RAM slot (0 - 255)
|
||
/// @param vram VRAM slot (0 - 255)
|
||
/// @param keepframes For animated sprites. If true, copy all frames to VRAM.
|
||
void NF_Vram3dSpriteGfx(u32 ram, u32 vram, bool keepframes);
|
||
|
||
/// Delete from VRAM the texture in the selected slot.
|
||
///
|
||
/// You mustn't delete the graphics while a sprite is using them.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Delete from VRAM the texture in slot 34.
|
||
/// NF_Free3dSpriteGfx(34);
|
||
/// ```
|
||
///
|
||
/// @param id VRAM slot (0 - 255)
|
||
void NF_Free3dSpriteGfx(u32 id);
|
||
|
||
/// Defragments the free VRAM used for 3D sprite textures.
|
||
///
|
||
/// 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_TEXVRAM[screen].free // Total free VRAM
|
||
/// NF_TEXVRAM[screen].fragmented // Total fragmented free VRAM
|
||
/// NF_TEXVRAM[screen].inarow // Largest free block of VRAM at the end
|
||
/// NF_TEXVRAM[screen].lost // Unusable free VRAM because fragmentation
|
||
/// ```
|
||
void NF_Vram3dSpriteGfxDefrag(void);
|
||
|
||
/// Copy a palette from RAM to the specified slot in VRAM.
|
||
///
|
||
/// If the slot is in use, its contents are overwritten.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Copy the palette from RAM slot 56 to VRAM slot 8
|
||
/// NF_VramSpritePal(56, 8);
|
||
/// ```
|
||
///
|
||
/// @param id RAM slot (0 - 64)
|
||
/// @param slot VRAM slot (0 - 31)
|
||
void NF_Vram3dSpritePal(u32 id, u32 slot);
|
||
|
||
/// Create a 3D sprite with the specified ID and display it on the screen.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Create a sprite with ID 12, using the texture stored in slot 30 of VRAM
|
||
/// // and the palette in slot 1. The sprite is created at coordinates (100, 50)
|
||
/// NF_Create3dSprite(12, 30, 1, 100, 50);
|
||
/// ```
|
||
///
|
||
/// @param id Sprite ID (0 - 255).
|
||
/// @param gfx Texture slot (0 - 255).
|
||
/// @param pal Palette slot (0 - 31).
|
||
/// @param x X coordinate.
|
||
/// @param y Y coordinate.
|
||
void NF_Create3dSprite(u32 id, u32 gfx, u32 pal, s32 x, s32 y);
|
||
|
||
/// Remove the sprite with the specified ID from the screen.
|
||
///
|
||
/// The texture and palette used by the sprite won't be deleted from VRAM.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Delete from screen the sprite with ID 12
|
||
/// NF_Delete3dSprite(12);
|
||
/// ```
|
||
///
|
||
/// @param id Sprite ID (0 - 255).
|
||
void NF_Delete3dSprite(u32 id);
|
||
|
||
/// Sets the priorities of 3D sprites based on their sprite IDs.
|
||
///
|
||
/// Lower sprite IDs have higher priorities.
|
||
void NF_Sort3dSprites(void);
|
||
|
||
/// Changes the draw priority of the 3D sprite with the specified ID.
|
||
///
|
||
/// Lower priority values have a higher priority.
|
||
///
|
||
/// @param id Sprite ID (0 - 255).
|
||
/// @param prio Priority (0 - 255).
|
||
void NF_Set3dSpritePriority(u32 id, u32 prio);
|
||
|
||
/// Swaps the priority of two 3D sprites.
|
||
///
|
||
/// @param id_a Sprite ID A (0 - 255).
|
||
/// @param id_b Sprite ID B (0 - 255).
|
||
void NF_Swap3dSpritePriority(u32 id_a, u32 id_b);
|
||
|
||
/// Move a 3D sprite to the specified position.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Moves 3D sprite 35 to coordinates (100, 50).
|
||
/// NF_Move3dSprite(35, 100, 50);
|
||
/// ```
|
||
///
|
||
/// @param id Sprite ID (0 - 255).
|
||
/// @param x X coordinate.
|
||
/// @param y Y coordinate.
|
||
static inline void NF_Move3dSprite(u32 id, s32 x, s32 y)
|
||
{
|
||
NF_3DSPRITE[id].x = x;
|
||
NF_3DSPRITE[id].y = y;
|
||
}
|
||
|
||
/// Show or hide a 3D sprite.
|
||
///
|
||
/// If you hide it, the 3D sprite becomes invisible, but it isn't deleted.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Hide 3D sprite 35.
|
||
/// NF_Show3dSprite(35, false);
|
||
/// // Make 3D sprite 45 visible
|
||
/// NF_Show3dSprite(45, true);
|
||
/// ```
|
||
///
|
||
/// @param id Sprite ID (0 - 255).
|
||
/// @param show True to show the sprite, false to hide it.
|
||
static inline void NF_Show3dSprite(u32 id, bool show)
|
||
{
|
||
NF_3DSPRITE[id].show = show;
|
||
}
|
||
|
||
/// Select the frame of an animation to display in the 3D sprite.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Make sprite 20 show frame 5
|
||
/// NF_Set3dSpriteFrame(20, 5);
|
||
/// ```
|
||
///
|
||
/// @param id Sprite ID (0 - 255).
|
||
/// @param frame Frame index.
|
||
void NF_Set3dSpriteFrame(u32 id, u32 frame);
|
||
|
||
/// Draw all created 3D sprites on the screen.
|
||
///
|
||
/// You need to call this function once per frame. This is the basic code to
|
||
/// show them:
|
||
/// ```
|
||
/// // Draw all 3D Sprites
|
||
/// NF_Draw3dSprites();
|
||
/// // Tell the 3D hardware that all commands for this frame have been sent
|
||
/// glFlush(0);
|
||
/// // Wait for the vertical sync
|
||
/// swiWaitForVBlank();
|
||
/// ```
|
||
void NF_Draw3dSprites(void);
|
||
|
||
/// Update the textures of all animated 3D sprites that need it.
|
||
///
|
||
/// Use this if any of your 3D sprites has the flag "keepframes" set to true.
|
||
///
|
||
/// Call this function just after swiWaitForVBlank().
|
||
void NF_Update3dSpritesGfx(void);
|
||
|
||
/// Rotates a 3D sprite on its 3 axes.
|
||
///
|
||
/// You can set a rotation between -512 and 512, with 0 meaning no rotation.
|
||
///
|
||
/// @param id Sprite ID (0 - 255).
|
||
/// @param x Rotation by X axis.
|
||
/// @param y Rotation by Y axis.
|
||
/// @param z Rotation by Z axis.
|
||
void NF_Rotate3dSprite(u32 id, s32 x, s32 y, s32 z);
|
||
|
||
/// Scales 3D sprite on X and Y axes.
|
||
///
|
||
/// The scale range goes from 0 to 64 (original size) to any greater value.
|
||
///
|
||
/// @param id Sprite ID (0 - 255).
|
||
/// @param x X axis scale.
|
||
/// @param y Y axis scale.
|
||
void NF_Scale3dSprite(u32 id, u32 x, u32 y);
|
||
|
||
/// Set the alpha level of a 3D sprite.
|
||
///
|
||
/// For transparency to work properly between different translucent sprites you
|
||
/// need to use different polygon IDs for them (between 1 and 62). The alpha
|
||
/// range is 0 to 31, with 31 being fully opaque.
|
||
///
|
||
/// To disable transparency, select an alpha value of 31 or a polygon ID of 0.
|
||
///
|
||
/// @param sprite Sprite ID (0 - 255).
|
||
/// @param poly_id Polygon ID (1 - 62).
|
||
/// @param alpha Transparency (0 - 31).
|
||
void NF_Blend3dSprite(u32 sprite, u32 poly_id, u32 alpha);
|
||
|
||
/// Select the layer where 3D sprites are drawn.
|
||
///
|
||
/// This function only changes the priority of background layer 0. The 3D output
|
||
/// can only be sent to layer 0 because of how the hardware was designed.
|
||
///
|
||
/// @param layer Layer (0 - 3).
|
||
void NF_3dSpritesLayer(u32 layer);
|
||
|
||
/// Changes one color of one 3D sprite palette.
|
||
///
|
||
/// The change is made to the RAM copy of the palette, so you won't see any
|
||
/// change until you update the VRAM copy with NF_3dSpriteUpdatePalette(). Use
|
||
/// this function to make cool effects with your 3D sprites.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Set color 1 of palette 3 to red
|
||
/// NF_3dSpriteSetPalColor(3, 1, 31, 0, 0);
|
||
/// ```
|
||
///
|
||
/// @param pal Palette slot (0 - 31).
|
||
/// @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_3dSpriteEditPalColor(u32 pal, u32 number, u32 r, u32 g, u32 b);
|
||
|
||
/// Updates the VRAM copy of a palette with the RAM copy of it.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Update palette 2
|
||
/// NF_3dSpriteUpdatePalette(2);
|
||
/// ```
|
||
///
|
||
/// @param pal Palette slot (0 - 31).
|
||
void NF_3dSpriteUpdatePalette(u32 pal);
|
||
|
||
/// Gets the RGB value of a color from a 3D sprite palette loaded in RAM.
|
||
///
|
||
/// Example:
|
||
/// ```
|
||
/// // Gets the RGB values of color 200 of sprite palette 3 and stores it in
|
||
/// // variables "red", "green" and "blue".
|
||
/// u8 red;
|
||
/// u8 green;
|
||
/// u8 blue;
|
||
/// NF_3dSpriteGetPalColor(3, 200, &red, &green, &blue);
|
||
/// ```
|
||
///
|
||
/// @param pal Palette slot (0 - 31).
|
||
/// @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_3dSpriteGetPalColor(u32 pal, u32 number, u8 *r, u8 *g, u8 *b);
|
||
|
||
/// Sets the depth of the selected 3D sprite.
|
||
///
|
||
/// -512 is highest priority (on top of the other sprites). 0 is the default
|
||
/// value, and 512 the lowest priority.
|
||
///
|
||
/// Change the sprite depth to prevent it from intersecting with other sprites
|
||
/// when rotation or zoom are applied.
|
||
///
|
||
/// @param id Sprite ID (0 - 255).
|
||
/// @param z Depth (-512 - 512)
|
||
void NF_3dSpriteSetDepth(u32 id, s32 z);
|
||
|
||
// Defines for backwards compatibility
|
||
#define NF_3dSpriteSetDeep NF_3dSpriteSetDepth
|
||
|
||
/// @}
|
||
|
||
#endif // NF_SPRITE3D_H__
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|