Mercurial > molko
changeset 515:2e05c1804b25
core: doxygenize sprite
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sat, 04 Mar 2023 11:02:48 +0100 |
parents | daf085bf8a8c |
children | 6af0524913b3 |
files | libmlk-core/mlk/core/animation.h libmlk-core/mlk/core/sprite.c libmlk-core/mlk/core/sprite.h |
diffstat | 3 files changed, 120 insertions(+), 23 deletions(-) [+] |
line wrap: on
line diff
--- a/libmlk-core/mlk/core/animation.h Sat Mar 04 10:49:20 2023 +0100 +++ b/libmlk-core/mlk/core/animation.h Sat Mar 04 11:02:48 2023 +0100 @@ -102,7 +102,7 @@ * \param animation the animation * \param x the x coordinate * \param y the y coordinate - * \return 0 on success or any error from ::mlk_sprite_draw function + * \return 0 on success or any error propagated from ::mlk_sprite_draw. */ int mlk_animation_draw(const struct mlk_animation *animation, int x, int y);
--- a/libmlk-core/mlk/core/sprite.c Sat Mar 04 10:49:20 2023 +0100 +++ b/libmlk-core/mlk/core/sprite.c Sat Mar 04 11:02:48 2023 +0100 @@ -22,17 +22,10 @@ #include "texture.h" void -mlk_sprite_init(struct mlk_sprite *sprite, - struct mlk_texture *tex, - unsigned int cellw, - unsigned int cellh) +mlk_sprite_init(struct mlk_sprite *sprite) { - assert(sprite); - assert(tex && mlk_texture_ok(tex)); + assert(mlk_sprite_ok(sprite)); - sprite->texture = tex; - sprite->cellw = cellw; - sprite->cellh = cellh; sprite->nrows = tex->h / cellh; sprite->ncols = tex->w / cellw; } @@ -40,12 +33,14 @@ int mlk_sprite_ok(const struct mlk_sprite *sprite) { - return sprite && mlk_texture_ok(sprite->texture) && sprite->cellw != 0 && sprite->cellh != 0; + return sprite && sprite->cellw && sprite->cellh && mlk_texture_ok(sprite->texture); } int mlk_sprite_draw(const struct mlk_sprite *sprite, unsigned int r, unsigned int c, int x, int y) { + assert(mlk_sprite_ok(sprite)); + return mlk_sprite_scale(sprite, r, c, x, y, sprite->cellw, sprite->cellh); }
--- a/libmlk-core/mlk/core/sprite.h Sat Mar 04 10:49:20 2023 +0100 +++ b/libmlk-core/mlk/core/sprite.h Sat Mar 04 11:02:48 2023 +0100 @@ -19,37 +19,139 @@ #ifndef MLK_CORE_SPRITE_H #define MLK_CORE_SPRITE_H +/** + * \file mlk/core/sprite.h + * \brief Image sprites + * + * The sprite is a module to help rendering a large image that is split into + * individual parts. This improves memory usage as several images are loaded in + * a unique one instead of individual parts. + * + * \note The image may not contain space, margins or padding within each cell. + * + * ## Usage + * + * To use a sprite, fill up the required fields in ::mlk_sprite and then call + * ::mlk_sprite_init which will calculate the number of rows and columns + * available in the image. + */ + #include "core.h" struct mlk_texture; +/** + * \struct mlk_sprite + * \brief Sprite structure + */ struct mlk_sprite { + /** + * (read-write, borrowed) + * + * The texture to render. + */ struct mlk_texture *texture; + + /** + * (read-write) + * + * The width of individual cell. + */ unsigned int cellw; + + /** + * (read-write) + * + * The height of individual cell. + */ unsigned int cellh; + + /** + * (read-only) + * + * Number of rows in the image. + * + * \note only available after calling ::mlk_sprite_init. + */ unsigned int nrows; + + /** + * (read-only) + * + * Number of columns in the image. + * + * \note only available after calling ::mlk_sprite_init. + */ unsigned int ncols; }; MLK_CORE_BEGIN_DECLS +/** + * Initialize the sprite by computing the number of rows and columns. + * + * Pre-initialize the sprite with required fields before calling this function, + * it is not required if you compute the number of rows and columns yourself. + * + * \pre mlk_sprite_ok(sprite) + * \param sprite the sprite + */ void -mlk_sprite_init(struct mlk_sprite *, struct mlk_texture *, unsigned int, unsigned int); +mlk_sprite_init(struct mlk_sprite *sprite); +/** + * Indicates if the sprite is properly initialized. + * + * \param sprite the sprite to check + * \return non-zero if structure is usable + */ int -mlk_sprite_ok(const struct mlk_sprite *); - -int -mlk_sprite_draw(const struct mlk_sprite *, unsigned int, unsigned int, int, int); +mlk_sprite_ok(const struct mlk_sprite *sprite); +/** + * Draw an individual cell from the sprite at the given location. + * + * \pre mlk_sprite_ok(sprite) + * \pre row < sprite->nrows + * \pre column < sprite->ncols + * \param sprite the sprite + * \param row the row index + * \param column the column index + * \param x the x coordinate + * \param y the y coordinate + * \return 0 on success or any error propagated from ::mlk_texture_draw. + */ int -mlk_sprite_scale(const struct mlk_sprite *, - unsigned int, - unsigned int, - int, - int, - unsigned int, - unsigned int); +mlk_sprite_draw(const struct mlk_sprite *sprite, + unsigned int row, + unsigned int column, + int x, + int y); + +/** + * Similar to ::mlk_sprite_draw but scale the cell into the bounding rectangle + * destination. + * + * \pre mlk_sprite_ok(sprite) + * \pre row < sprite->nrows + * \pre column < sprite->ncols + * \param sprite the sprite + * \param row the row index + * \param column the column index + * \param x the x coordinate + * \param y the y coordinate + * \param w the rectangle width + * \param h the rectangle height + * \return 0 on success or any error propagated from ::mlk_texture_draw. + */ +int +mlk_sprite_scale(const struct mlk_sprite *sprite, + unsigned int row, + unsigned int column, + int x, + int y, + unsigned int w, + unsigned int h); MLK_CORE_END_DECLS