libakgl/include/akgl/text.h

/**
 * @file text.h
 * @brief Declares the public text API.
 */

#ifndef _TEXT_H_
#define _TEXT_H_

#include <SDL3/SDL.h>
#include <SDL3_ttf/SDL_ttf.h>
#include <akerror.h>

/**
 * @brief Text loadfont.
 * @param name Registry key or human-readable object name.
 * @param filepath Path to the requested file.
 * @param size Requested font size.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_KEY When the corresponding validation or operation fails.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 * @throws AKGL_ERR_SDL When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_text_loadfont(char *name, char *filepath, int size);
/**
 * @brief Text rendertextat.
 * @param font Font used to render the text.
 * @param text UTF-8 text to render.
 * @param color Text color.
 * @param wraplength Maximum rendered line width; zero disables wrapping.
 * @param x Horizontal destination coordinate.
 * @param y Vertical destination coordinate.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
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 used to render the text.
 * @param text UTF-8 text to measure.
 * @param w Output destination populated with the rendered width in pixels.
 * @param h Output destination populated with the rendered height in pixels.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 * @throws AKGL_ERR_SDL When the corresponding validation or operation fails.
 */
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 used to render the text.
 * @param text UTF-8 text to measure.
 * @param wraplength Maximum rendered line width; zero wraps on newlines only.
 * @param w Output destination populated with the rendered width in pixels.
 * @param h Output destination populated with the rendered height in pixels.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 * @throws AKERR_OUTOFBOUNDS When the corresponding validation or operation fails.
 * @throws AKGL_ERR_SDL When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_text_measure_wrapped(TTF_Font *font, char *text, int wraplength, int *w, int *h);

#endif // _TEXT_H_