Mercurial > molko
changeset 538:80242343d152
core: doxygenize texture
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sun, 05 Mar 2023 11:32:36 +0100 |
parents | 1546a92c51f6 |
children | 7fb5a859bcb4 |
files | libmlk-core/mlk/core/texture.c libmlk-core/mlk/core/texture.h |
diffstat | 2 files changed, 164 insertions(+), 30 deletions(-) [+] |
line wrap: on
line diff
--- a/libmlk-core/mlk/core/texture.c Sun Mar 05 11:10:11 2023 +0100 +++ b/libmlk-core/mlk/core/texture.c Sun Mar 05 11:32:36 2023 +0100 @@ -115,15 +115,15 @@ int mlk_texture_scale(const struct mlk_texture *tex, - int src_x, - int src_y, - unsigned src_w, - unsigned src_h, - int dst_x, - int dst_y, - unsigned dst_w, - unsigned dst_h, - double angle) + int src_x, + int src_y, + unsigned src_w, + unsigned src_h, + int dst_x, + int dst_y, + unsigned dst_w, + unsigned dst_h, + double angle) { const SDL_Rect src = { .x = src_x,
--- a/libmlk-core/mlk/core/texture.h Sun Mar 05 11:10:11 2023 +0100 +++ b/libmlk-core/mlk/core/texture.h Sun Mar 05 11:32:36 2023 +0100 @@ -19,19 +19,80 @@ #ifndef MLK_CORE_TEXTURE_H #define MLK_CORE_TEXTURE_H +/** + * \file texture.h + * \brief Basic texture management + */ + #include "err.h" +/** + * \struct mlk_texture + * \brief Texture structure + */ struct mlk_texture { + /** + * (read-only) + * + * Texture's width. + */ unsigned int w; + + /** + * (read-only) + * + * Texture's height. + */ unsigned int h; + + /** \cond MLK_PRIVATE_DECLS */ void *handle; + /** \endcond MLK_PRIVATE_DECLS */ }; +/** + * \enum mlk_texture_blend + * \brief Controls how to blend alpha/colors. + */ enum mlk_texture_blend { + /** + * No blending. + */ MLK_TEXTURE_BLEND_NONE, + + /** + * Alpha blending. + * + * ``` + * RGB = (SRC_RGB * SRC_A) + (DST_RGB * (1 - SRC_A)) + * A = SRC_A + (DST_A * (1 - SRC_A)) + * ``` + */ MLK_TEXTURE_BLEND_BLEND, + + /** + * Additive blending. + * + * ``` + * RGB = (SRC_RGB * SRC_A) + DST_RGB + * A = A + * ``` + */ MLK_TEXTURE_BLEND_ADD, + + /** + * Color modulation. + * + * ``` + * RGB = SRC_RGB * DST_RGB + * A = A + * ``` + */ MLK_TEXTURE_BLEND_MODULATE, + + /** + * Unused sentinel value. + */ MLK_TEXTURE_BLEND_LAST }; @@ -39,38 +100,111 @@ extern "C" { #endif +/** + * Create a new texture with the given dimensions. + * + * \pre texture != NULL + * \pre w > 0 && h > 0 + * \param texture the texture to initialize + * \param w the texture width + * \param h the texture height + * \return 0 on success or an error code on failure + */ int -mlk_texture_new(struct mlk_texture *, unsigned int, unsigned int); +mlk_texture_new(struct mlk_texture *texture, unsigned int w, unsigned int h); -int -mlk_texture_ok(const struct mlk_texture *); - +/** + * Tells if the texture structure is usable. + * + * \param texture the texture to check + * \return non-zero if the texture structure is usable + */ int -mlk_texture_set_blend_mode(struct mlk_texture *, enum mlk_texture_blend); +mlk_texture_ok(const struct mlk_texture *texture); +/** + * Change color/alpha blending mode. + * + * \pre texture != NULL + * \param texture the texture to update + * \param blend the new blend mode + * \return 0 on success or an error code on failure + */ int -mlk_texture_set_alpha_mod(struct mlk_texture *, unsigned int); +mlk_texture_set_blend_mode(struct mlk_texture *texture, enum mlk_texture_blend blend); -int -mlk_texture_set_color_mod(struct mlk_texture *, unsigned long); - +/** + * Change alpha value. + * + * \pre texture != NULL + * \pre alpha >= 0 && alpha <= 255 + * \param texture the texture to update + * \param alpha transparency value + * \return 0 on success or an error code on failure + */ int -mlk_texture_draw(const struct mlk_texture *, int, int); +mlk_texture_set_alpha_mod(struct mlk_texture *texture, unsigned int alpha); +/** + * Change color modulation. + * + * \pre texture != NULL + * \param texture the texture to update + * \param color the color modulation + * \return 0 on success or an error code on failure + */ +int +mlk_texture_set_color_mod(struct mlk_texture *texture, unsigned long color); + +/** + * Draw the entire texture at the given location. + * + * \pre texture != NULL + * \param texture the texture to draw + * \param x the x coordinate + * \param y the y coordinate + * \return 0 on success or an error code on failure + */ int -mlk_texture_scale(const struct mlk_texture *, - int, - int, - unsigned int, - unsigned int, - int, - int, - unsigned int, - unsigned int, - double); +mlk_texture_draw(const struct mlk_texture *texture, int x, int y); +/** + * Scale a clip of the texture at the given rectangle destination, applying an + * optional rotation. + * + * \pre texture != NULL + * \param texture the texture to scale + * \param src_x texture x coordinate + * \param src_y texture y coordinate + * \param src_w texture width to clip + * \param src_h texture height to clip + * \param dst_x destination rectangle x coordinate + * \param dst_y destination rectangle y coordinate + * \param dst_w destination rectangle width + * \param dst_h destination rectangle height + * \param angle optional angle to apply + * \return 0 on success or an error code on failure + */ +int +mlk_texture_scale(const struct mlk_texture *texture, + int src_x, + int src_y, + unsigned src_w, + unsigned src_h, + int dst_x, + int dst_y, + unsigned dst_w, + unsigned dst_h, + double angle); + +/** + * Destroy the texture. + * + * \pre texture != NULL + * \param texture the texture to destroy + */ void -mlk_texture_finish(struct mlk_texture *); +mlk_texture_finish(struct mlk_texture *texture); #if defined(__cplusplus) }