Mercurial > molko
changeset 521:338a4436e255
core: doxygenize font
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sat, 04 Mar 2023 15:39:21 +0100 |
parents | 7e7c6786d21e |
children | f45a023f6690 |
files | libmlk-core/mlk/core/font.c libmlk-core/mlk/core/font.h |
diffstat | 2 files changed, 131 insertions(+), 12 deletions(-) [+] |
line wrap: on
line diff
--- a/libmlk-core/mlk/core/font.c Sat Mar 04 15:10:35 2023 +0100 +++ b/libmlk-core/mlk/core/font.c Sat Mar 04 15:39:21 2023 +0100 @@ -40,7 +40,10 @@ } int -mlk_font_openmem(struct mlk_font *font, const void *buffer, size_t buflen, unsigned int size) +mlk_font_openmem(struct mlk_font *font, + const void *buffer, + size_t buflen, + unsigned int size) { assert(font); assert(buffer); @@ -120,8 +123,8 @@ { assert(font); - if (font->handle) + if (font->handle) { TTF_CloseFont(font->handle); - - memset(font, 0, sizeof (*font)); + font->handle = NULL; + } }
--- a/libmlk-core/mlk/core/font.h Sat Mar 04 15:10:35 2023 +0100 +++ b/libmlk-core/mlk/core/font.h Sat Mar 04 15:39:21 2023 +0100 @@ -19,43 +19,159 @@ #ifndef MLK_CORE_FONT_H #define MLK_CORE_FONT_H +/** + * \file font.h + * \brief Basic font management + * + * Open and use fonts for rendering UTF-8 text. + */ + #include <stddef.h> struct mlk_texture; +/** + * \enum mlk_font_style + * \brief Font style + */ enum mlk_font_style { + /** + * Rendered text is antialiased, default. + */ MLK_FONT_STYLE_ANTIALIASED, + + /** + * Simple rendering, no antialiasing. + */ MLK_FONT_STYLE_NONE, + + /** + * Last enumeration constant. + */ MLK_FONT_STYLE_LAST }; +/** + * \struct mlk_font + * \brief Font structure + * + * You can fill font attributes before calling ::mlk_font_open or + * ::mlk_font_openmem. + */ struct mlk_font { + /** + * (read-write) + * + * Style used for rendering, can be changed at runtime. + */ enum mlk_font_style style; + + /** \cond MLK_PRIVATE_DECLS */ void *handle; + /** \endcond MLK_PRIVATE_DECLS */ }; #if defined(__cplusplus) extern "C" { #endif -int -mlk_font_open(struct mlk_font *, const char *, unsigned int); - +/** + * Open a font from the file system path. + * + * \pre font != NULL + * \pre path != NULL + * \param font the font to open + * \param path path to the font file (e.g. .ttf, .otf, etc) + * \param size desired font height in pixels + * \return 0 on success or an error code on failure + */ int -mlk_font_openmem(struct mlk_font *, const void *, size_t, unsigned int); +mlk_font_open(struct mlk_font *font, const char *path, unsigned int size); +/** + * Open a font from a const binary data. + * + * The binary data must be kept alive until the font is no longer used. + * + * \pre font != NULL + * \param font the font to open + * \param data the font content + * \param datasz the font content length + * \param size desired font height in pixels + * \return 0 on success or an error code on failure + */ int -mlk_font_ok(const struct mlk_font *); +mlk_font_openmem(struct mlk_font *font, + const void *data, + size_t datasz, + unsigned int size); + +/** + * Tells if the font is usable. + * + * \param font the font to check + * \return non-zero if the font structure is usable + */ +int +mlk_font_ok(const struct mlk_font *font); +/** + * Render some text using the font and generate a texture. + * + * The texture destination must be deallocated once no longer used using + * ::mlk_texture_finish. + * + * \pre mlk_font_ok(font) + * \pre texture != NULL + * \pre text != NULL && strlen(text) > 0 + * \param font the font to use + * \param texture the texture to initialize + * \param text the non NULL and non empty UTF-8 text + * \param color foreground color + * \return 0 on success or an error code on failure + */ int -mlk_font_render(struct mlk_font *, struct mlk_texture *, const char *, unsigned long); +mlk_font_render(struct mlk_font *font, + struct mlk_texture *texture, + const char *text, + unsigned long color); +/** + * Return the font height in pixels + * + * \pre mlk_font_ok(font) + * \param font the font to use + * \return the font height + */ unsigned int -mlk_font_height(const struct mlk_font *); +mlk_font_height(const struct mlk_font *font); +/** + * Query a dimension required to draw a text. + * + * Both w and h pointers can be NULL if one of the dimension isn't required. + * + * If the function fails, *w and *h are set to 0. + * + * \pre mlk_font_ok(font) + * \param font the font to use + * \param text the non NULL and non empty UTF-8 text + * \param w pointer receiving width (or NULL) + * \param h pointer receiving height (or NULL) + * \return 0 on success or an error code on failure + */ int -mlk_font_query(const struct mlk_font *, const char *, unsigned int *, unsigned int *); +mlk_font_query(const struct mlk_font *font, + const char *text, + unsigned int *w, + unsigned int *h); +/** + * Destroy this font. + * + * \pre mlk_font_ok(font) + * \param font the font to destroy + */ void mlk_font_finish(struct mlk_font *);