From 5ed7f45f80edd28464112cb134ba6319537fb260 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 23 Jun 2022 15:49:05 -0400
Subject: [PATCH] SDL_ttf.h: Complete overhaul of Doxygen comments.
---
SDL_ttf.h | 2115 +++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 1723 insertions(+), 392 deletions(-)
diff --git a/SDL_ttf.h b/SDL_ttf.h
index 1f87279..afcbf11 100644
--- a/SDL_ttf.h
+++ b/SDL_ttf.h
@@ -26,7 +26,7 @@
* Header file for SDL_ttf library
*
* This library is a wrapper around the excellent FreeType 2.0 library,
- * available at: http://www.freetype.org/
+ * available at: https://www.freetype.org/
*
* Note: In many places, SDL_ttf will say "glyph" when it means "code point."
* Unicode is hard, we learn as we go, and we apologize for adding to the
@@ -78,7 +78,7 @@ extern "C" {
* the thousands digit: for example, 2.23.0 is encoded as 4300.
* This macro will not be available in SDL 3.x or SDL_ttf 3.x.
*
- * Deprecated, use SDL_TTF_VERSION_ATLEAST or SDL_TTF_VERSION instead.
+ * \deprecated, use SDL_TTF_VERSION_ATLEAST or SDL_TTF_VERSION instead.
*/
#define SDL_TTF_COMPILEDVERSION \
SDL_VERSIONNUM(SDL_TTF_MAJOR_VERSION, SDL_TTF_MINOR_VERSION, SDL_TTF_PATCHLEVEL)
@@ -98,35 +98,45 @@ extern "C" {
#endif
/**
+ * Query the version of SDL_ttf that the program is linked against.
+ *
* This function gets the version of the dynamically linked SDL_ttf library.
+ * This is separate from the SDL_TTF_VERSION() macro, which tells you what
+ * version of the SDL_ttf headers you compiled against.
+ *
+ * This returns static internal data; do not free or modify it!
*
- * it should NOT be used to fill a version structure, instead you should use
- * the SDL_TTF_VERSION() macro.
+ * \returns a pointer to the version information.
*
- * \returns SDL_ttf version
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC const SDL_version * SDLCALL TTF_Linked_Version(void);
/**
- * This function stores the version of the FreeType2 library in use.
+ * Query the version of the FreeType library in use.
*
* TTF_Init() should be called before calling this function.
*
- * \param major pointer to get the major version number
- * \param minor pointer to get the minor version number
- * \param patch pointer to get the param version number
+ * \param major to be filled in with the major version number. Can be NULL.
+ * \param minor to be filled in with the minor version number. Can be NULL.
+ * \param patch to be filled in with the param version number. Can be NULL.
+ *
+ * \since This function is available since SDL_ttf 2.0.18.
*
* \sa TTF_Init
*/
extern DECLSPEC void SDLCALL TTF_GetFreeTypeVersion(int *major, int *minor, int *patch);
/**
- * This function stores the version of the HarfBuzz library in use, or 0 if
- * HarfBuzz is not available.
+ * Query the version of the HarfBuzz library in use.
+ *
+ * If HarfBuzz is not available, the version reported is 0.0.0.
*
- * \param major pointer to get the major version number
- * \param minor pointer to get the minor version number
- * \param patch pointer to get the param version number
+ * \param major to be filled in with the major version number. Can be NULL.
+ * \param minor to be filled in with the minor version number. Can be NULL.
+ * \param patch to be filled in with the param version number. Can be NULL.
+ *
+ * \since This function is available since SDL_ttf 2.0.18.
*/
extern DECLSPEC void SDLCALL TTF_GetHarfBuzzVersion(int *major, int *minor, int *patch);
@@ -137,100 +147,282 @@ extern DECLSPEC void SDLCALL TTF_GetHarfBuzzVersion(int *major, int *minor, int
#define UNICODE_BOM_SWAPPED 0xFFFE
/**
- * This function tells the library whether UNICODE text is generally
- * byteswapped.
+ * Tell SDL_ttf whether UNICODE text is generally byteswapped.
*
* A UNICODE BOM character in a string will override this setting for the
* remainder of that string.
*
* \param swapped boolean to indicate whether text is byteswapped
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC void SDLCALL TTF_ByteSwappedUNICODE(SDL_bool swapped);
/**
- * The internal structure containing font information
+ * The internal structure containing font information. Opaque data!
*/
typedef struct _TTF_Font TTF_Font;
/**
- * Initialize the TTF engine
+ * Initialize SDL_ttf.
*
- * \returns 0 if successful, -1 on error
+ * You must successfully call this function before it is safe to call any
+ * other function in this library, with one exception: a human-readable error
+ * message can be retrieved from TTF_GetError() if this function fails.
+ *
+ * SDL must be initialized before calls to functions in this library, because
+ * this library uses utility functions from the SDL library.
+ *
+ * It is safe to call this more than once; the library keeps a counter of init
+ * calls, and decrements it on each call to TTF_Quit, so you must pair your
+ * init and quit calls.
+ *
+ * \returns 0 on success, -1 on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_Quit
*/
extern DECLSPEC int SDLCALL TTF_Init(void);
/**
- * Open a font file and create a font of the specified point size.
+ * Create a font from a file, using a specified point size.
*
* Some .fon fonts will have several sizes embedded in the file, so the point
* size becomes the index of choosing which size. If the value is too high,
* the last indexed size will be the default.
*
- * \param file file name
- * \param ptsize point size
- * \returns a valid TTF_Font, NULL on error
+ * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.
+ *
+ * \param file path to font file.
+ * \param ptsize point size to use for the newly-opened font.
+ * \returns a valid TTF_Font, or NULL on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_CloseFont
*/
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFont(const char *file, int ptsize);
+
+/**
+ * Create a font from a file, using a specified face index.
+ *
+ * Some .fon fonts will have several sizes embedded in the file, so the point
+ * size becomes the index of choosing which size. If the value is too high,
+ * the last indexed size will be the default.
+ *
+ * Some fonts have multiple "faces" included. The index specifies which face
+ * to use from the font file. Font files with only one face should specify
+ * zero for the index.
+ *
+ * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.
+ *
+ * \param file path to font file.
+ * \param ptsize point size to use for the newly-opened font.
+ * \param index index of the face in the font file.
+ * \returns a valid TTF_Font, or NULL on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
+ *
+ * \sa TTF_CloseFont
+ */
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndex(const char *file, int ptsize, long index);
/**
- * Open a font file from a SDL_RWops.
+ * Create a font from an SDL_RWops, using a specified point size.
+ *
+ * Some .fon fonts will have several sizes embedded in the file, so the point
+ * size becomes the index of choosing which size. If the value is too high,
+ * the last indexed size will be the default.
+ *
+ * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * whether this function succeeds or not. SDL_ttf reads everything it needs
+ * from the RWops during this call in any case.
+ *
+ * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.
*
- * \param src SDL_RWops to use. 'src' must be kept alive for the lifetime of
- * the TTF_Font.
- * \param freesrc can be set so that TTF_CloseFont closes the RWops
- * \param ptsize point size
- * \returns a valid TTF_Font, NULL on error
+ * \param src an SDL_RWops to provide a font file's data.
+ * \param freesrc non-zero to close the RWops before returning, zero to leave
+ * it open.
+ * \param ptsize point size to use for the newly-opened font.
+ * \returns a valid TTF_Font, or NULL on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_CloseFont
*/
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontRW(SDL_RWops *src, int freesrc, int ptsize);
+
+/**
+ * Create a font from an SDL_RWops, using a specified face index.
+ *
+ * Some .fon fonts will have several sizes embedded in the file, so the point
+ * size becomes the index of choosing which size. If the value is too high,
+ * the last indexed size will be the default.
+ *
+ * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * whether this function succeeds or not. SDL_ttf reads everything it needs
+ * from the RWops during this call in any case.
+ *
+ * Some fonts have multiple "faces" included. The index specifies which face
+ * to use from the font file. Font files with only one face should specify
+ * zero for the index.
+ *
+ * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.
+ *
+ * \param src an SDL_RWops to provide a font file's data.
+ * \param freesrc non-zero to close the RWops before returning, zero to leave
+ * it open.
+ * \param ptsize point size to use for the newly-opened font.
+ * \param index index of the face in the font file.
+ * \returns a valid TTF_Font, or NULL on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
+ *
+ * \sa TTF_CloseFont
+ */
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndexRW(SDL_RWops *src, int freesrc, int ptsize, long index);
/**
- * Opens a font using the given horizontal and vertical target resolutions (in
- * DPI).
+ * Create a font from a file, using target resolutions (in DPI).
*
* DPI scaling only applies to scalable fonts (e.g. TrueType).
*
- * \param file file name
- * \param ptsize point size
- * \param hdpi horizontal DPI
- * \param vdpi vertical DPI
- * \returns a valid TTF_Font, NULL on error
+ * Some .fon fonts will have several sizes embedded in the file, so the point
+ * size becomes the index of choosing which size. If the value is too high,
+ * the last indexed size will be the default.
+ *
+ * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.
+ *
+ * \param file path to font file.
+ * \param ptsize point size to use for the newly-opened font.
+ * \param hdpi the target horizontal DPI.
+ * \param vdpi the target vertical DPI.
+ * \returns a valid TTF_Font, or NULL on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.18.
*
* \sa TTF_CloseFont
*/
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontDPI(const char *file, int ptsize, unsigned int hdpi, unsigned int vdpi);
+
+/**
+ * Create a font from a file, using target resolutions (in DPI).
+ *
+ * DPI scaling only applies to scalable fonts (e.g. TrueType).
+ *
+ * Some .fon fonts will have several sizes embedded in the file, so the point
+ * size becomes the index of choosing which size. If the value is too high,
+ * the last indexed size will be the default.
+ *
+ * Some fonts have multiple "faces" included. The index specifies which face
+ * to use from the font file. Font files with only one face should specify
+ * zero for the index.
+ *
+ * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.
+ *
+ * \param file path to font file.
+ * \param ptsize point size to use for the newly-opened font.
+ * \param index index of the face in the font file.
+ * \param hdpi the target horizontal DPI.
+ * \param vdpi the target vertical DPI.
+ * \returns a valid TTF_Font, or NULL on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.18.
+ *
+ * \sa TTF_CloseFont
+ */
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndexDPI(const char *file, int ptsize, long index, unsigned int hdpi, unsigned int vdpi);
+
+/**
+ * Opens a font from an SDL_RWops with target resolutions (in DPI).
+ *
+ * DPI scaling only applies to scalable fonts (e.g. TrueType).
+ *
+ * Some .fon fonts will have several sizes embedded in the file, so the point
+ * size becomes the index of choosing which size. If the value is too high,
+ * the last indexed size will be the default.
+ *
+ * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * whether this function succeeds or not. SDL_ttf reads everything it needs
+ * from the RWops during this call in any case.
+ *
+ * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.
+ *
+ * \param src an SDL_RWops to provide a font file's data.
+ * \param freesrc non-zero to close the RWops before returning, zero to leave
+ * it open.
+ * \param ptsize point size to use for the newly-opened font.
+ * \param hdpi the target horizontal DPI.
+ * \param vdpi the target vertical DPI.
+ * \returns a valid TTF_Font, or NULL on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.18.
+ *
+ * \sa TTF_CloseFont
+ */
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontDPIRW(SDL_RWops *src, int freesrc, int ptsize, unsigned int hdpi, unsigned int vdpi);
+
+
+/**
+ * Opens a font from an SDL_RWops with target resolutions (in DPI).
+ *
+ * DPI scaling only applies to scalable fonts (e.g. TrueType).
+ *
+ * Some .fon fonts will have several sizes embedded in the file, so the point
+ * size becomes the index of choosing which size. If the value is too high,
+ * the last indexed size will be the default.
+ *
+ * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * whether this function succeeds or not. SDL_ttf reads everything it needs
+ * from the RWops during this call in any case.
+ *
+ * Some fonts have multiple "faces" included. The index specifies which face
+ * to use from the font file. Font files with only one face should specify
+ * zero for the index.
+ *
+ * When done with the returned TTF_Font, use TTF_CloseFont() to dispose of it.
+ *
+ * \param src an SDL_RWops to provide a font file's data.
+ * \param freesrc non-zero to close the RWops before returning, zero to leave
+ * it open.
+ * \param ptsize point size to use for the newly-opened font.
+ * \param index index of the face in the font file.
+ * \param hdpi the target horizontal DPI.
+ * \param vdpi the target vertical DPI.
+ * \returns a valid TTF_Font, or NULL on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.18.
+ *
+ * \sa TTF_CloseFont
+ */
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndexDPIRW(SDL_RWops *src, int freesrc, int ptsize, long index, unsigned int hdpi, unsigned int vdpi);
/**
- * Set font size dynamically.
+ * Set a font's size dynamically.
*
- * This clears already generated glyphs, if any, from the cache.
+ * This clears already-generated glyphs, if any, from the cache.
*
- * \param font TTF_Font handle
- * \param ptsize point size
+ * \param font the font to resize.
+ * \param ptsize the new point size.
* \returns 0 if successful, -1 on error
+ *
+ * \since This function is available since SDL_ttf 2.0.18.
*/
extern DECLSPEC int SDLCALL TTF_SetFontSize(TTF_Font *font, int ptsize);
/**
- * Set font size dynamically.
+ * Set font size dynamically with target resolutions (in DPI).
*
- * This clears already generated glyphs, if any, from the cache.
+ * This clears already-generated glyphs, if any, from the cache.
*
- * \param font TTF_Font handle
- * \param ptsize point size
- * \param hdpi horizontal DPI
- * \param vdpi vertical DPI
+ * \param font the font to resize.
+ * \param ptsize the new point size.
+ * \param hdpi the target horizontal DPI.
+ * \param vdpi the target vertical DPI.
* \returns 0 if successful, -1 on error.
+ *
+ * \since This function is available since SDL_ttf 2.0.18.
*/
extern DECLSPEC int SDLCALL TTF_SetFontSizeDPI(TTF_Font *font, int ptsize, unsigned int hdpi, unsigned int vdpi);
@@ -244,42 +436,66 @@ extern DECLSPEC int SDLCALL TTF_SetFontSizeDPI(TTF_Font *font, int ptsize, unsig
#define TTF_STYLE_STRIKETHROUGH 0x08
/**
- * Retrieve the font style.
+ * Query a font's current style.
+ *
+ * The font styles are a set of bit flags, OR'd together:
+ *
+ * - `TTF_STYLE_NORMAL` (is zero)
+ * - `TTF_STYLE_BOLD`
+ * - `TTF_STYLE_ITALIC`
+ * - `TTF_STYLE_UNDERLINE`
+ * - `TTF_STYLE_STRIKETHROUGH`
*
- * \param font TTF_Font handle
- * \returns font style
+ * \param font the font to query.
+ * \returns the current font style, as a set of bit flags.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_SetFontStyle
*/
extern DECLSPEC int SDLCALL TTF_GetFontStyle(const TTF_Font *font);
/**
- * Set the font style.
+ * Set a font's current style.
+ *
+ * Setting the style clears already-generated glyphs, if any, from the cache.
+ *
+ * The font styles are a set of bit flags, OR'd together:
+ *
+ * - `TTF_STYLE_NORMAL` (is zero)
+ * - `TTF_STYLE_BOLD`
+ * - `TTF_STYLE_ITALIC`
+ * - `TTF_STYLE_UNDERLINE`
+ * - `TTF_STYLE_STRIKETHROUGH`
*
- * Setting the style clears already generated glyphs, if any, from the cache.
+ * \param font the font to set a new style on.
+ * \param style the new style values to set, OR'd together.
*
- * \param font TTF_Font handlea
- * \param style style flags OR'ed
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_GetFontStyle
*/
extern DECLSPEC void SDLCALL TTF_SetFontStyle(TTF_Font *font, int style);
/**
- * Retrieve the font outline.
+ * Query a font's current outline.
*
- * \param font TTF_Font handle
- * \returns font outline
+ * \param font the font to query.
+ * \returns the font's current outline value.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_SetFontOutline
*/
extern DECLSPEC int SDLCALL TTF_GetFontOutline(const TTF_Font *font);
/**
- * Set the font outline.
+ * Set a font's current outline.
+ *
+ * \param font the font to set a new outline on.
+ * \param outline positive outline value, 0 to default.
*
- * \param font TTF_Font handle
- * \param outline positive outline value, 0 to default
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_GetFontOutline
*/
@@ -296,22 +512,42 @@ extern DECLSPEC void SDLCALL TTF_SetFontOutline(TTF_Font *font, int outline);
#define TTF_HINTING_LIGHT_SUBPIXEL 4
/**
- * Retrieve FreeType hinter setting.
+ * Query a font's current FreeType hinter setting.
+ *
+ * The hinter setting is a single value:
+ *
+ * - `TTF_HINTING_NORMAL`
+ * - `TTF_HINTING_LIGHT`
+ * - `TTF_HINTING_MONO`
+ * - `TTF_HINTING_NONE`
+ * - `TTF_HINTING_LIGHT_SUBPIXEL` (available in SDL_ttf 2.0.18 and later)
*
- * \param font TTF_Font handle
- * \returns hinting flag
+ * \param font the font to query.
+ * \returns the font's current hinter value.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_SetFontHinting
*/
extern DECLSPEC int SDLCALL TTF_GetFontHinting(const TTF_Font *font);
/**
- * Set FreeType hinter settings.
+ * Set a font's current hinter setting.
+ *
+ * Setting it clears already-generated glyphs, if any, from the cache.
+ *
+ * The hinter setting is a single value:
+ *
+ * - `TTF_HINTING_NORMAL`
+ * - `TTF_HINTING_LIGHT`
+ * - `TTF_HINTING_MONO`
+ * - `TTF_HINTING_NONE`
+ * - `TTF_HINTING_LIGHT_SUBPIXEL` (available in SDL_ttf 2.0.18 and later)
*
- * Setting it clears already generated glyphs, if any, from the cache.
+ * \param font the font to set a new hinter setting on.
+ * \param hinting the new hinter setting.
*
- * \param font TTF_Font handle
- * \param hinting hinting flag
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_GetFontHinting
*/
@@ -325,484 +561,1469 @@ extern DECLSPEC void SDLCALL TTF_SetFontHinting(TTF_Font *font, int hinting);
#define TTF_WRAPPED_ALIGN_RIGHT 2
/**
- * Get wrap alignment option
+ * Query a font's current wrap alignment option.
*
- * \param font TTF_Font handle
- * \returns wrap alignment option
+ * The wrap alignment option can be one of the following:
+ *
+ * - `TTF_WRAPPED_ALIGN_LEFT`
+ * - `TTF_WRAPPED_ALIGN_CENTER`
+ * - `TTF_WRAPPED_ALIGN_RIGHT`
+ *
+ * \param font the font to query.
+ * \returns the font's current wrap alignment option.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_SetFontWrappedAlign
*/
extern DECLSPEC int SDLCALL TTF_GetFontWrappedAlign(const TTF_Font *font);
/**
- * Set wrap alignment option
+ * Set a font's current wrap alignment option.
+ *
+ * The wrap alignment option can be one of the following:
*
- * \param font TTF_Font handle
- * \param align wrap alignment option
+ * - `TTF_WRAPPED_ALIGN_LEFT`
+ * - `TTF_WRAPPED_ALIGN_CENTER`
+ * - `TTF_WRAPPED_ALIGN_RIGHT`
+ *
+ * \param font the font to set a new wrap alignment option on.
+ * \param align the new wrap alignment option.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_GetFontWrappedAlign
*/
extern DECLSPEC void SDLCALL TTF_SetFontWrappedAlign(TTF_Font *font, int align);
/**
- * Get the total height of the font - usually equal to point size
+ * Query the total height of a font.
+ *
+ * This is usually equal to point size.
+ *
+ * \param font the font to query.
+ * \returns the font's height.
*
- * \param font TTF_Font handle
- * \returns font height
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC int SDLCALL TTF_FontHeight(const TTF_Font *font);
/**
- * Get the offset from the baseline to the top of the font This is a positive
- * value, relative to the baseline.
+ * Query the offset from the baseline to the top of a font.
*
- * \param font TTF_Font handle
- * \returns font ascent
+ * This is a positive value, relative to the baseline.
+ *
+ * \param font the font to query.
+ * \returns the font's ascent.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC int SDLCALL TTF_FontAscent(const TTF_Font *font);
/**
- * Get the offset from the baseline to the bottom of the font This is a
- * negative value, relative to the baseline.
+ * Query the offset from the baseline to the bottom of a font.
+ *
+ * This is a negative value, relative to the baseline.
+ *
+ * \param font the font to query.
+ * \returns the font's descent.
*
- * \param font TTF_Font handle
- * \returns font descent
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC int SDLCALL TTF_FontDescent(const TTF_Font *font);
/**
- * Get the recommended spacing between lines of text for this font
+ * Query the recommended spacing between lines of text for a font.
*
- * \param font TTF_Font handle
- * \returns spacing value
+ * \param font the font to query.
+ * \returns the font's recommended spacing.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC int SDLCALL TTF_FontLineSkip(const TTF_Font *font);
/**
- * Get whether or not kerning is allowed for this font
+ * Query whether or not kerning is allowed for a font.
+ *
+ * \param font the font to query.
+ * \returns non-zero if kerning is enabled, zero otherwise.
*
- * \param font TTF_Font handle
- * \returns tell is kerning is enabled
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC int SDLCALL TTF_GetFontKerning(const TTF_Font *font);
/**
- * Set if kerning is allowed for this font
+ * Set if kerning is allowed for a font.
+ *
+ * Newly-opened fonts default to allowing kerning. This is generally a good
+ * policy unless you have a strong reason to disable it, as it tends to
+ * produce better rendering (with kerning disabled, some fonts might render
+ * the word `kerning` as something that looks like `keming` for example).
+ *
+ * \param font the font to set kerning on.
+ * \param allowed non-zero to allow kerning, zero to disallow.
*
- * \param font TTF_Font handle
- * \param allowed enable or not kerning
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC void SDLCALL TTF_SetFontKerning(TTF_Font *font, int allowed);
/**
- * Get the number of faces of the font
+ * Query the number of faces of a font.
*
- * \param font TTF_Font handle
- * \returns number of FreeType font faces
+ * \param font the font to query.
+ * \returns the number of FreeType font faces.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC long SDLCALL TTF_FontFaces(const TTF_Font *font);
/**
- * Tell whether it is a fixed width font.
+ * Query whether a font is fixed-width.
+ *
+ * A "fixed-width" font means all glyphs are the same width across; a
+ * lowercase 'i' will be the same size across as a capital 'W', for example.
+ * This is common for terminals and text editors, and other apps that treat
+ * text as a grid. Most other things (WYSIWYG word processors, web pages, etc)
+ * are more likely to not be fixed-width in most cases.
*
- * \param font TTF_Font handle
- * \returns 1 if true, 0 if not, -1 on error
+ * \param font the font to query.
+ * \returns non-zero if fixed-width, zero if not.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC int SDLCALL TTF_FontFaceIsFixedWidth(const TTF_Font *font);
/**
- * Get font family name
+ * Query a font's family name.
+ *
+ * This string is dictated by the contents of the font file.
*
- * The returned value shouldn't be modified nor freed.
+ * Note that the returned string is to internal storage, and should not be
+ * modifed or free'd by the caller. The string becomes invalid, with the rest
+ * of the font, when `font` is handed to TTF_CloseFont().
*
- * \param font TTF_Font handle
- * \returns font family name, NULL on error
+ * \param font the font to query.
+ * \returns the font's family name.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC const char * SDLCALL TTF_FontFaceFamilyName(const TTF_Font *font);
/**
- * Get font style name
+ * Query a font's style name.
+ *
+ * This string is dictated by the contents of the font file.
*
- * The returned value shouldn't be modified nor freed.
+ * Note that the returned string is to internal storage, and should not be
+ * modifed or free'd by the caller. The string becomes invalid, with the rest
+ * of the font, when `font` is handed to TTF_CloseFont().
*
- * \param font TTF_Font handle
- * \returns font style name, NULL on error
+ * \param font the font to query.
+ * \returns the font's style name.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*/
extern DECLSPEC const char * SDLCALL TTF_FontFaceStyleName(const TTF_Font *font);
/**
- * Check wether a glyph is provided by the font or not
+ * Check whether a glyph is provided by the font for a 16-bit codepoint.
+ *
+ * Note that this version of the function takes a 16-bit character code, which
+ * covers the Basic Multilingual Plane, but is insufficient to cover the
+ * entire set of possible Unicode values, including emoji glyphs. You should
+ * use TTF_GlyphIsProvided32() instead, which offers the same functionality
+ * but takes a 32-bit codepoint instead.
*
- * \param font TTF_Font handle
- * \param ch char index, 16bits
- * \returns 1 if provided
+ * The only reason to use this function is that it was available since the
+ * beginning of time, more or less.
+ *
+ * \param font the font to query.
+ * \param ch the character code to check.
+ * \returns non-zero if font provides a glyph for this character, zero if not.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
*
* \sa TTF_GlyphIsProvided32
*/
extern DECLSPEC int SDLCALL TTF_GlyphIsProvided(TTF_Font *font, Uint16 ch);
/**
- * Check wether a glyph is provided by the font or not
+ * Check whether a glyph is provided by the font for a 32-bit codepoint.
*
- * \param font TTF_Font handle
- * \param ch char index, 32bits
- * \returns 1 if provided
+ * This is the same as TTF_GlyphIsProvided(), but takes a 32-bit character
+ * instead of 16-bit, and thus can query a larger range. If you are sure
+ * you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason
+ * not to use this function exclusively.
*
- * \sa TTF_GlyphIsProvided
+ * \param font the font to query.
+ * \param ch the character code to check.
+ * \returns non-zero if font provides a glyph for this character, zero if not.
+ *
+ * \since This function is available since SDL_ttf 2.0.18.
*/
extern DECLSPEC int SDLCALL TTF_GlyphIsProvided32(TTF_Font *font, Uint32 ch);
/**
- * Get the metrics (dimensions) of a glyph To understand what these metrics
- * mean, here is a useful link:
- * http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html
+ * Query the metrics (dimensions) of a font's 16-bit glyph.
*
- * \param font TTF_Font handle
- * \param ch char index, 16bits
+ * To understand what these metrics mean, here is a useful link:
*
- * \sa TTF_GlyphIsProvided32
+ * https://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html
+ *
+ * Note that this version of the function takes a 16-bit character code, which
+ * covers the Basic Multilingual Plane, but is insufficient to cover the
+ * entire set of possible Unicode values, including emoji glyphs. You should
+ * use TTF_GlyphMetrics32() instead, which offers the same functionality but
+ * takes a 32-bit codepoint instead.
+ *
+ * The only reason to use this function is that it was available since the
+ * beginning of time, more or less.
+ *
+ * \param font the font to query.
+ * \param ch the character code to check.
+ *
+ * \since This function is available since SDL_ttf 2.0.0.
+ *
+ * \sa TTF_GlyphMetrics32
*/
extern DECLSPEC int SDLCALL TTF_GlyphMetrics(TTF_Font *font, Uint16 ch,
int *minx, int *maxx,
int *miny, int *maxy, int *advance);
/**
- * Get the metrics (dimensions) of a glyph To understand what these metrics
- * mean, here is a useful link:
- * http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html
+ * Query the metrics (dimensions) of a font's 32-bit glyph.
+ *
+ * To understand what these metrics mean, here is a useful link:
+ *
+ * https://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html
+ *
+ * This is the same as TTF_GlyphMetrics(), but takes a 32-bit character
+ * instead of 16-bit, and thus can query a larger range. If you are sure
+ * you'll have an SDL_ttf that's version 2.0.18 or newer, there's no reason
+ * not to use this function exclusively.
*
- * \param font TTF_Font handle
- * \param ch char index, 32bits
+ * \param font the font to query.
+ * \param ch the character code to check.
*
- * \sa TTF_GlyphMetrics
+ * \since This function is available since SDL_ttf 2.0.18.
*/
extern DECLSPEC int SDLCALL TTF_GlyphMetrics32(TTF_Font *font, Uint32 ch,
int *minx, int *maxx,
int *miny, int *maxy, int *advance);
/**
- * Get the dimensions of a rendered string of text
+ * Calculate the dimensions of a rendered string of Latin1 text.
*
- * \param font TTF_Font handle
- * \param text text to render
- * \param w output width
- * \param h output height
- * \returns 0 if successful, -1 on error
+ * This will report the width and height, in pixels, of the space that the
+ * specified string will take to fully render.
+ *
+ * This does not need to render the string to do this calculation.
+ *
+ * You almost certainly want TTF_SizeUTF8() unless you're sure you have a
+ * 1-byte Latin1 encoding. US ASCII characters will work with either function,
+ * but most other Unicode characters packed into a `const char *` will need
+ * UTF-8.
+ *
+ * \param font the font to query.
+ * \param text text to calculate, in Latin1 encoding.
+ *
(Patch may be truncated, please check the link at the top of this post.)