Andrew Kesterson
f0858b0d38
The Doxygen comments were generated from the declarations, so 217 @throws lines across 21 headers read "When the corresponding validation or operation fails" and told a caller nothing beyond the status name. The @param lines were the same shape: every output was "Output destination populated by the function", every instance "Object to initialize, inspect, or modify". Rewritten against the implementations, following the pattern libakstdlib already uses: - @throws names the condition. akgl_sprite_load_json separated AKERR_KEY (absent) from AKERR_TYPE (present, wrong type) from AKERR_OUTOFBOUNDS (filename too long, or array indexed past its end), and gained AKGL_ERR_SDL and AKGL_ERR_HEAP, which it raises and never declared. - Parameters say whether they are required, what a NULL means, and what is written on a failure path. Where an argument is not checked, the doc says so: akgl_heap_next_actor's dest is a crash on NULL, not an error, and akgl_render_2d_frame_start dereferences self before testing it. - The conventions move up to the file blocks so the per-function docs stay short. json_helpers.h states once that absence is an error here and that json_t * results are borrowed; heap.h explains the pool model and the acquire asymmetry; physics.h carries the thrust/environmental/velocity table. - Struct fields, enum values, macros and exported globals are documented, including the dead ones - sprite_w/sprite_h, movetimer, p_scale and timer_gravity are read by nothing, and say so. Also fixes ten comments in error.h and audio.h that opened with /** rather than /**<, so Doxygen attached them to the following entity and rendered the text as part of the macro's value. Verified against the generated HTML. Comments only - no declaration changed. Doxygen builds clean under WARN_AS_ERROR, scripts/reindent.sh --check passes, 19/19 suites pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
125 lines
6.6 KiB
C
125 lines
6.6 KiB
C
/**
|
|
* @file text.h
|
|
* @brief Loading fonts and drawing or measuring strings with them.
|
|
*
|
|
* Fonts are `TTF_Font *` handles kept in the #AKGL_REGISTRY_FONT property
|
|
* registry under a caller-chosen name; there is no akgl font type wrapping them.
|
|
* SDL_ttf must be initialized (akgl_game_init does it) before any of this.
|
|
*
|
|
* The two measure functions do not touch the renderer, so they are usable
|
|
* before -- or entirely without -- a window. Drawing is immediate mode: each
|
|
* akgl_text_rendertextat() call rasterizes, uploads, blits, and throws the
|
|
* texture away, which is fine for a HUD line and wrong for a large body of
|
|
* static text redrawn every frame.
|
|
*/
|
|
|
|
#ifndef _TEXT_H_
|
|
#define _TEXT_H_
|
|
|
|
#include <SDL3/SDL.h>
|
|
#include <SDL3_ttf/SDL_ttf.h>
|
|
#include <akerror.h>
|
|
|
|
/**
|
|
* @brief Open a TrueType font at one size and publish it in the font registry.
|
|
*
|
|
* A size is baked into the handle, so the same file at two sizes is two calls
|
|
* under two names. Nothing releases these: the handles live until the process
|
|
* ends.
|
|
*
|
|
* @param name Registry key to publish the font under. Required. An existing
|
|
* entry with the same name is replaced, and the font it
|
|
* displaced is leaked rather than closed.
|
|
* @param filepath Path to a `.ttf`/`.otf` file. Required. Used verbatim -- not
|
|
* resolved against `SDL_GetBasePath()`.
|
|
* @param size Point size to rasterize at. Passed straight to SDL_ttf, which
|
|
* rejects anything that is not positive.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p name or @p filepath is `NULL`.
|
|
* @throws AKGL_ERR_SDL If the font cannot be opened -- missing, unreadable, not
|
|
* a font, or a @p size SDL_ttf refuses. The message carries
|
|
* `SDL_GetError()`.
|
|
* @throws AKERR_KEY If the font cannot be written into #AKGL_REGISTRY_FONT --
|
|
* in practice, because akgl_registry_init has not run.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_text_loadfont(char *name, char *filepath, int size);
|
|
/**
|
|
* @brief Rasterize a string and blit it at a screen position, in one call.
|
|
*
|
|
* Renders blended (anti-aliased, alpha-blended) through SDL_ttf, uploads the
|
|
* result to a texture, draws it through the global `renderer`, and destroys both
|
|
* the texture and the surface before returning. The text is drawn at its natural
|
|
* size -- @p x and @p y are the top-left corner, not a centre.
|
|
*
|
|
* Coordinates are screen coordinates, not world ones: this does not go through
|
|
* the camera, so a HUD stays put while the world scrolls under it.
|
|
*
|
|
* @param font Font to render with, from akgl_text_loadfont. Required.
|
|
* @param text UTF-8 text. Required. May contain newlines, which break
|
|
* lines on either path.
|
|
* @param color Text colour, including alpha.
|
|
* @param wraplength Wrap width in pixels. Greater than 0 wraps on word
|
|
* boundaries at that width; 0 or less draws a single line and
|
|
* breaks only on newlines in @p text.
|
|
* @param x Left edge of the text, in screen pixels.
|
|
* @param y Top edge of the text, in screen pixels.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p font or @p text is `NULL`; if SDL_ttf cannot
|
|
* rasterize the string; or if the surface cannot be uploaded as a
|
|
* texture. The last two carry `SDL_GetError()` and are a reused status
|
|
* rather than a pointer problem.
|
|
* @throws AKERR_* Whatever the backend's `draw_texture` raises.
|
|
*
|
|
* @note On a failure after rasterizing -- the texture upload, or the draw -- the
|
|
* surface and texture are not destroyed, because the error returns before
|
|
* the cleanup. Repeated failures leak.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_text_rendertextat(TTF_Font *font, char *text, SDL_Color color, int wraplength, int x, int y);
|
|
/**
|
|
* @brief Report the size, in pixels, that @p text would occupy on one line.
|
|
*
|
|
* Nothing is drawn and no renderer is required. A caller building a character
|
|
* grid measures one cell with this -- the advance width of a single glyph in a
|
|
* monospaced font -- and derives the rest of the grid from it.
|
|
*
|
|
* @param font Font to measure with, from akgl_text_loadfont. Required.
|
|
* @param text UTF-8 text to measure. Required. The empty string is legal and
|
|
* measures 0 wide by one line high.
|
|
* @param w Receives the width in pixels. Required.
|
|
* @param h Receives the height in pixels -- one line, whatever @p text
|
|
* contains, since this form does not wrap. Required.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p font, @p text, @p w, or @p h is `NULL`.
|
|
* @throws AKGL_ERR_SDL If SDL_ttf cannot measure the string -- a corrupt font,
|
|
* or text that is not valid UTF-8. The message carries `SDL_GetError()`.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_text_measure(TTF_Font *font, char *text, int *w, int *h);
|
|
/**
|
|
* @brief Report the size, in pixels, that @p text would occupy when wrapped.
|
|
*
|
|
* The companion to akgl_text_measure() for the wrapping case, matching the
|
|
* @p wraplength argument akgl_text_rendertextat() already takes: a string
|
|
* longer than @p wraplength reports the height of every line it breaks onto.
|
|
* A @p wraplength of zero wraps only on newlines in @p text.
|
|
*
|
|
* @param font Font to measure with, from akgl_text_loadfont. Required.
|
|
* @param text UTF-8 text to measure. Required.
|
|
* @param wraplength Wrap width in pixels. 0 wraps on newlines only. Negative is
|
|
* refused rather than passed through: SDL_ttf reads a negative
|
|
* width as a very large unsigned one and silently stops
|
|
* wrapping, which would return a measurement that is wrong
|
|
* rather than an error.
|
|
* @param w Receives the width in pixels: the longest line, not
|
|
* @p wraplength. Required.
|
|
* @param h Receives the height in pixels, covering every line the text
|
|
* wraps onto. Required.
|
|
* @return `NULL` on success, otherwise an error context owned by the caller.
|
|
* @throws AKERR_NULLPOINTER If @p font, @p text, @p w, or @p h is `NULL`.
|
|
* @throws AKERR_OUTOFBOUNDS If @p wraplength is negative.
|
|
* @throws AKGL_ERR_SDL If SDL_ttf cannot measure the string -- a corrupt font,
|
|
* or text that is not valid UTF-8. The message carries `SDL_GetError()`.
|
|
*/
|
|
akerr_ErrorContext AKERR_NOIGNORE *akgl_text_measure_wrapped(TTF_Font *font, char *text, int wraplength, int *w, int *h);
|
|
|
|
#endif // _TEXT_H_
|