|
libdragon
|
2D Graphics More...
Go to the source code of this file.
Data Structures | |
| struct | sprite_t |
| Sprite structure. More... | |
| struct | sprite_detail_t |
| Sprite detail texture information structure. More... | |
| union | sprite_t.__unnamed36__ |
Functions | |
| sprite_t * | sprite_load (const char *fn) |
| Load a sprite from a filesystem (eg: ROM) More... | |
| sprite_t * | sprite_load_buf (void *buf, int sz) |
| Load a sprite from a buffer. More... | |
| void | sprite_free (sprite_t *sprite) |
| Deallocate a sprite. | |
| tex_format_t | sprite_get_format (sprite_t *sprite) |
| Get the sprite texture format. More... | |
| surface_t | sprite_get_pixels (sprite_t *sprite) |
| Create a surface_t pointing to the full sprite contents. More... | |
| surface_t | sprite_get_lod_pixels (sprite_t *sprite, int num_level) |
| Create a surface_t pointing to the contents of a LOD level. More... | |
| surface_t | sprite_get_detail_pixels (sprite_t *sprite, sprite_detail_t *info, rdpq_texparms_t *infoparms) |
| Create a surface_t pointing to the contents of a detail texture. More... | |
| surface_t | sprite_get_tile (sprite_t *sprite, int h, int v) |
| Return a surface_t pointing to a specific tile of the spritemap. More... | |
| uint16_t * | sprite_get_palette (sprite_t *sprite) |
| Access the sprite palette (if any) More... | |
| bool | sprite_get_texparms (sprite_t *sprite, rdpq_texparms_t *parms) |
| Get a copy of the RDP texparms, optionally stored within the sprite. More... | |
| int | sprite_get_lod_count (sprite_t *sprite) |
| Return the number of LOD levels stored within the sprite (including the main image). More... | |
| bool | sprite_fits_tmem (sprite_t *sprite) |
| Return true if the sprite fits in TMEM without splitting. More... | |
2D Graphics
| struct sprite_t |
Sprite structure.
A "sprite" (as saved in a .sprite file) is a 2D image with metadata attached to them to facilitate drawing it onto N64.
Despite the name, a libdragon sprite is basically the basic format to handle assets for images. It is commonly used for handling textures, full screen images like splash screens, tile maps, font pictures, and even "real" 2D sprites.
If the sprite uses a color-indexed format like FMT_CI4 or FMT_CI8, the sprite contains also the corresponding palette.
To convert an image file to libdragon's sprite format, use the mksprite tool. To load a sprite into memory, use sprite_load.
| Data Fields | ||
|---|---|---|
| uint16_t | width | Width in pixels. |
| uint16_t | height | Height in pixels. |
| uint8_t | bitdepth |
DEPRECATED: do not use this field. Use TEX_FORMAT_BITDEPTH(sprite->format) instead. |
| union sprite_t.__unnamed36__ | __unnamed__ | |
| uint8_t | hslices |
Number of horizontal sub-tiles |
| uint8_t | vslices | Number of vertical sub-tiles. |
| uint32_t | data[0] | Start of graphics data. |
| struct sprite_detail_t |
Sprite detail texture information structure.
A "detail texture" is a 2D image with metadata attached to it to increase the perceived resolution of the main sprite when rendering with little to no additional TMEM usage.
If the sprite uses a detail texture, its information can be retreived using the sprite_get_detail_pixels function.
To include a detail texture to libdragon's sprite format, use the mksprite tool with –detail argument.
rdpq_sprite_upload automatically uploads detail textures associated with the sprite.
| Data Fields | ||
|---|---|---|
| bool | use_main_tex | Is the detail texture the same as the main surface of the sprite, used for fractal detailing. |
| float | blend_factor | Blend factor of the detail texture in range of 0 to 1. |
| union sprite_t.__unnamed36__ |
| sprite_t * sprite_load | ( | const char * | fn | ) |
Load a sprite from a filesystem (eg: ROM)
This function loads a full sprite from a filesystem. Notice that there is no streaming support, so the file is fully loaded into RDRAM, in its final uncompressed format.
sprite_load internally uses the asset API (asset_load), so the sprite file is transparently uncompressed if needed.
| fn | Filename of the sprite, including filesystem specifier. For instance: "rom:/hero.sprite" to load from DFS. |
| sprite_t * sprite_load_buf | ( | void * | buf, |
| int | sz | ||
| ) |
Load a sprite from a buffer.
This function loads a sprite from a buffer corresponding to sprite file data in memory. The function also performs any necessary processing to load the sprite file data.
sprite_load_buf functions in-place which means it does not allocate another buffer for the loaded sprite. So, sprite_free will not remove the sprite data from memory. This means that the input buffer must be freed manually after sprite_free is called.
| buf | Pointer to the sprite file data |
| sz | Size of the sprite file buffer |
|
inline |
Get the sprite texture format.
| sprite | The sprite |
Create a surface_t pointing to the full sprite contents.
This function can be used to pass a full sprite to functions accepting a surface_t.
Notice that no memory allocations or copies are performed: the returned surface will point to the sprite contents.
| sprite | The sprite |
Create a surface_t pointing to the contents of a LOD level.
This function can be used to access LOD images within a sprite file. It is useful for sprites created by mksprite containing multiple mipmap levels.
LOD levels are indexed from 1 upward. 0 refers to the main sprite, so calling sprite_get_lod_pixels(s, 0) is equivalent to sprite_get_pixels(s).
Notice that no memory allocations or copies are performed: the returned surface will point to the sprite contents.
| sprite | The sprite to access |
| num_level | The number of LOD level. 0 is the main sprite. |
| surface_t sprite_get_detail_pixels | ( | sprite_t * | sprite, |
| sprite_detail_t * | info, | ||
| rdpq_texparms_t * | infoparms | ||
| ) |
Create a surface_t pointing to the contents of a detail texture.
This function can be used to access detail texture within a sprite file. It is useful for sprites created by mksprite containing one.
If there isn't a detail texture, the returned surface is 0.
Additional detail information such as factor or texparms are accessible through the filled sprite_detail_t and rdpq_texparms_t structure. If you don't wish to use this information, pass NULL to the info argument(s).
Notice that no memory allocations or copies are performed: the returned surface will point to the sprite contents.
| sprite | The sprite to access |
| info | The detail information struct to fill if needed |
| infoparms | The detail texture sampling struct to fill if needed |
Return a surface_t pointing to a specific tile of the spritemap.
A sprite can be used as a spritemap, that is a collection of multiple smaller images of equal size, called "tiles". In this case, the number of tiles is stored in the members hslices and vslices of the sprite structure.
This function allows to get a surface that points to the specific sub-tile, so that it can accessed directly.
| sprite | The sprite used as spritemap |
| h | Horizontal index of the tile to access |
| v | Vertical index of the tile to access |
| uint16_t * sprite_get_palette | ( | sprite_t * | sprite | ) |
Access the sprite palette (if any)
A sprite can also contain a palette, in case the sprite data is color-indexed (that is, the format is either FMT_CI4 or FMT_CI8).
This function returns a pointer to the raw palette data contained in the sprite.
| sprite | The sprite to access |
| bool sprite_get_texparms | ( | sprite_t * | sprite, |
| rdpq_texparms_t * | parms | ||
| ) |
Get a copy of the RDP texparms, optionally stored within the sprite.
This function allows to obtain the RDP texparms structure stored within the sprite, if any. This structure is used by the RDP to set texture properties such as wrapping, mirroring, etc. It can be added to the sprite via the mksprite tool, using the --texparms option.
| sprite | The sprite to access |
| parms | The texparms structure to fill |
| int sprite_get_lod_count | ( | sprite_t * | sprite | ) |
Return the number of LOD levels stored within the sprite (including the main image).
| sprite | The sprite to access |
| bool sprite_fits_tmem | ( | sprite_t * | sprite | ) |
Return true if the sprite fits in TMEM without splitting.
This function returns true if the sprite can be fully uploaded in TMEM (including all its LODs, detail texture and palettes).
When working on 3D graphics, each texture must fit into RDP TMEM (4 KiB), otherwise it cannot be used. All sprites that are meant to be used as textures should fit in TMEM.
In case of 2D graphics, it is more common to have images of arbitrary size. They can be drawn with rdpq_sprite_blit (accelerated) or graphics_draw_sprite (CPU) without specific limits (the RDP accelerated version does internally need to split the sprite in multiple parts, but that is indeed possible).
This function is mostly for debugging purposes, as it can help validating whether a sprite can be used as a texture or not.
| sprite | The sprite to access |
1.9.4