From 7a67f3c9e8d2d81bef6d498b135ca93007bb1706 Mon Sep 17 00:00:00 2001
From: Sylvain <[EMAIL REDACTED]>
Date: Sat, 18 Jun 2022 11:20:07 +0200
Subject: [PATCH] Update to doxygen syntax
---
SDL_ttf.h | 847 ++++++++++++++++++++++++++++++++++++++++++++----------
1 file changed, 689 insertions(+), 158 deletions(-)
diff --git a/SDL_ttf.h b/SDL_ttf.h
index 4e0e4fe..e0872f5 100644
--- a/SDL_ttf.h
+++ b/SDL_ttf.h
@@ -19,15 +19,20 @@
3. This notice may not be removed or altered from any source distribution.
*/
-/* This library is a wrapper around the excellent FreeType 2.0 library,
- available at:
- http://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
- confusion. */
+/**
+ * \file SDL_render.h
+ *
+ * Header file for SDL_ttf library
+ *
+ * This library is a wrapper around the excellent FreeType 2.0 library,
+ * available at: http://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
+ * confusion.
+ *
+ */
#ifndef SDL_TTF_H_
#define SDL_TTF_H_
@@ -39,13 +44,15 @@
extern "C" {
#endif
-/* Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
-*/
+/**
+ * Printable format: "%d.%d.%d", MAJOR, MINOR, PATCHLEVEL
+ */
#define SDL_TTF_MAJOR_VERSION 2
#define SDL_TTF_MINOR_VERSION 19
#define SDL_TTF_PATCHLEVEL 2
-/* This macro can be used to fill a version structure with the compile-time
+/**
+ * This macro can be used to fill a version structure with the compile-time
* version of the SDL_ttf library.
*/
#define SDL_TTF_VERSION(X) \
@@ -55,7 +62,9 @@ extern "C" {
(X)->patch = SDL_TTF_PATCHLEVEL; \
}
-/* Backwards compatibility */
+/**
+ * Backwards compatibility
+ */
#define TTF_MAJOR_VERSION SDL_TTF_MAJOR_VERSION
#define TTF_MINOR_VERSION SDL_TTF_MINOR_VERSION
#define TTF_PATCHLEVEL SDL_TTF_PATCHLEVEL
@@ -88,154 +97,447 @@ extern "C" {
#define SDL_DEPRECATED
#endif
-/* This function gets the version of the dynamically linked SDL_ttf library.
- it should NOT be used to fill a version structure, instead you should
- use the SDL_TTF_VERSION() macro.
+/**
+ * This function gets the version of the dynamically linked SDL_ttf library.
+ * it should NOT be used to fill a version structure, instead you should
+ * use the SDL_TTF_VERSION() macro.
+ *
+ * \returns SDL version
*/
extern DECLSPEC const SDL_version * SDLCALL TTF_Linked_Version(void);
-/* This function stores the version of the FreeType2 library in use.
- TTF_Init() should be called before calling this function.
+/**
+ * This function stores the version of the FreeType2 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
+ *
+ * \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.
+/**
+ * This function stores the version of the HarfBuzz library in use,
+ * or 0 if HarfBuzz is not available.
+ *
+ * \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
*/
extern DECLSPEC void SDLCALL TTF_GetHarfBuzzVersion(int *major, int *minor, int *patch);
-/* ZERO WIDTH NO-BREAKSPACE (Unicode byte order mark) */
+/**
+ * ZERO WIDTH NO-BREAKSPACE (Unicode byte order mark)
+ */
#define UNICODE_BOM_NATIVE 0xFEFF
#define UNICODE_BOM_SWAPPED 0xFFFE
-/* This function tells the library whether UNICODE text is generally
- byteswapped. A UNICODE BOM character in a string will override
- this setting for the remainder of that string.
-*/
+/**
+ * This function tells the library 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
+ */
extern DECLSPEC void SDLCALL TTF_ByteSwappedUNICODE(SDL_bool swapped);
-/* The internal structure containing font information */
+/**
+ * The internal structure containing font information
+ */
typedef struct _TTF_Font TTF_Font;
-/* Initialize the TTF engine - returns 0 if successful, -1 on error */
+/**
+ * Initialize the TTF engine
+ *
+ * \returns 0 if successful, -1 on error
+ *
+ * \sa TTF_Quit
+ */
extern DECLSPEC int SDLCALL TTF_Init(void);
-/* Open a font file and create a font of the specified point size.
+/**
+ * Open a font file and create a font of the 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. */
+ * 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
+ *
+ * \sa TTF_CloseFont
+ */
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFont(const char *file, int ptsize);
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndex(const char *file, int ptsize, long index);
-/* Open a font file from a SDL_RWops: 'src' must be kept alive for the lifetime of the TTF_Font.
- * 'freesrc' can be set so that TTF_CloseFont closes the RWops */
+
+/**
+ * Open a font file from a SDL_RWops.
+ *
+ * \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
+ *
+ * \sa TTF_CloseFont
+ */
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontRW(SDL_RWops *src, int freesrc, int ptsize);
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).
- * DPI scaling only applies to scalable fonts (e.g. TrueType). */
+/**
+ * Opens a font using the given horizontal and vertical 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
+ *
+ * \sa TTF_CloseFont
+ */
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontDPI(const char *file, int ptsize, unsigned int hdpi, unsigned int vdpi);
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontIndexDPI(const char *file, int ptsize, long index, unsigned int hdpi, unsigned int vdpi);
extern DECLSPEC TTF_Font * SDLCALL TTF_OpenFontDPIRW(SDL_RWops *src, int freesrc, int ptsize, unsigned int hdpi, unsigned int vdpi);
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. This clears already generated glyphs, if any, from the cache. */
+/**
+ * Set font size dynamically.
+ * This clears already generated glyphs, if any, from the cache.
+ *
+ * \param font TTF_Font handle
+ * \param ptsize point size
+ *
+ * \returns 0 if successful, -1 on error
+ */
extern DECLSPEC int SDLCALL TTF_SetFontSize(TTF_Font *font, int ptsize);
+
+/**
+ * Set font size dynamically. 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
+ *
+ * \returns 0 if successful, -1 on error
+ */
extern DECLSPEC int SDLCALL TTF_SetFontSizeDPI(TTF_Font *font, int ptsize, unsigned int hdpi, unsigned int vdpi);
-/* Set and retrieve the font style. Setting the style clears already generated glyphs, if any, from the cache. */
+/**
+ * Font style flags
+ */
#define TTF_STYLE_NORMAL 0x00
#define TTF_STYLE_BOLD 0x01
#define TTF_STYLE_ITALIC 0x02
#define TTF_STYLE_UNDERLINE 0x04
#define TTF_STYLE_STRIKETHROUGH 0x08
+
+/**
+ * Retrieve the font style.
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns font style
+ *
+ * \sa TTF_SetFontStyle
+ */
extern DECLSPEC int SDLCALL TTF_GetFontStyle(const TTF_Font *font);
+
+/**
+ * Set the font style. Setting the style clears already generated glyphs, if any, from the cache.
+ *
+ * \param font TTF_Font handlea
+ * \param style style flags OR'ed
+ *
+ * \sa TTF_GetFontStyle
+ */
extern DECLSPEC void SDLCALL TTF_SetFontStyle(TTF_Font *font, int style);
+
+/**
+ * Retrieve the font outline.
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns font outline
+ *
+ * \sa TTF_SetFontOutline
+ */
extern DECLSPEC int SDLCALL TTF_GetFontOutline(const TTF_Font *font);
+
+/**
+ * Set the font outline.
+ *
+ * \param font TTF_Font handle
+ * \param outline positive outline value, 0 to default
+ *
+ * \sa TTF_GetFontOutline
+ */
extern DECLSPEC void SDLCALL TTF_SetFontOutline(TTF_Font *font, int outline);
-/* Set and retrieve FreeType hinter settings. Setting it clears already generated glyphs, if any, from the cache. */
+
+/**
+ * Hinting flags
+ */
#define TTF_HINTING_NORMAL 0
#define TTF_HINTING_LIGHT 1
#define TTF_HINTING_MONO 2
#define TTF_HINTING_NONE 3
#define TTF_HINTING_LIGHT_SUBPIXEL 4
+
+/**
+ * Retrieve FreeType hinter setting.
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns hinting flag
+ *
+ * \sa TTF_SetFontHinting
+ */
extern DECLSPEC int SDLCALL TTF_GetFontHinting(const TTF_Font *font);
+
+/**
+ * Set FreeType hinter settings. Setting it clears already generated glyphs, if any, from the cache.
+ *
+ * \param font TTF_Font handle
+ * \param hinting hinting flag
+ *
+ * \sa TTF_GetFontHinting
+ */
extern DECLSPEC void SDLCALL TTF_SetFontHinting(TTF_Font *font, int hinting);
-/* Special layout option for rendering wrapped text */
+/**
+ * Special layout option for rendering wrapped text
+ */
#define TTF_WRAPPED_ALIGN_LEFT 0
#define TTF_WRAPPED_ALIGN_CENTER 1
#define TTF_WRAPPED_ALIGN_RIGHT 2
+
+/**
+ * Get wrap alignment option
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns wrap alignment option
+ *
+ * \sa TTF_SetFontWrappedAlign
+ */
extern DECLSPEC int SDLCALL TTF_GetFontWrappedAlign(const TTF_Font *font);
+
+/**
+ * Set wrap alignment option
+ *
+ * \param font TTF_Font handle
+ *
+ * \param align wrap alignment option
+ *
+ * \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 */
+/**
+ * Get the total height of the font - usually equal to point size
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns font height
+ */
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.
+/**
+ * Get the offset from the baseline to the top of the font
+ * This is a positive value, relative to the baseline.
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns font ascent
*/
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.
+/**
+ * Get the offset from the baseline to the bottom of the font
+ * This is a negative value, relative to the baseline.
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns font descent
*/
extern DECLSPEC int SDLCALL TTF_FontDescent(const TTF_Font *font);
-/* Get the recommended spacing between lines of text for this font */
+/**
+ * Get the recommended spacing between lines of text for this font
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns spacing value
+ */
extern DECLSPEC int SDLCALL TTF_FontLineSkip(const TTF_Font *font);
-/* Get/Set whether or not kerning is allowed for this font */
+/**
+ * Get whether or not kerning is allowed for this font
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns tell is kerning is enabled
+ */
extern DECLSPEC int SDLCALL TTF_GetFontKerning(const TTF_Font *font);
+
+/**
+ * Set if kerning is allowed for this font
+ *
+ * \param font TTF_Font handle
+ * \param allowed enable or not kerning
+ *
+ */
extern DECLSPEC void SDLCALL TTF_SetFontKerning(TTF_Font *font, int allowed);
-/* Get the number of faces of the font */
+/**
+ * Get the number of faces of the font
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns number of FreeType font faces
+ */
extern DECLSPEC long SDLCALL TTF_FontFaces(const TTF_Font *font);
-/* Get the font face attributes, if any */
+/**
+ * Tell whether it is a fixed width font.
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns 1 if true, 0 if not, -1 on error
+ */
extern DECLSPEC int SDLCALL TTF_FontFaceIsFixedWidth(const TTF_Font *font);
+
+/**
+ * Get font family name
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns font family name, NULL on error
+ */
extern DECLSPEC char * SDLCALL TTF_FontFaceFamilyName(const TTF_Font *font);
+
+/**
+ * Get font style name
+ *
+ * \param font TTF_Font handle
+ *
+ * \returns font style name, NULL on error
+ */
extern DECLSPEC char * SDLCALL TTF_FontFaceStyleName(const TTF_Font *font);
-/* Check wether a glyph is provided by the font or not */
+/**
+ * Check wether a glyph is provided by the font or not
+ *
+ * \param font TTF_Font handle
+ * \param ch char index, 16bits
+ *
+ * \returns 1 if provided
+ *
+ * \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
+ *
+ * \param font TTF_Font handle
+ * \param ch char index, 32bits
+ *
+ * \returns 1 if provided
+ *
+ * \sa TTF_GlyphIsProvided
+ */
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
+/**
+ * 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
+ *
+ * \param font TTF_Font handle
+ * \param ch char index, 16bits
+ *
+ * \sa TTF_GlyphIsProvided32
*/
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
+ *
+ * \param font TTF_Font handle
+ * \param ch char index, 32bits
+ *
+ * \sa TTF_GlyphMetrics
+ */
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 */
+/**
+ * Get the dimensions of a rendered string of 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
+ *
+ * \sa TTF_SizeText
+ * \sa TTF_SizeUTF8
+ * \sa TTF_SizeUNICODE
+ */
extern DECLSPEC int SDLCALL TTF_SizeText(TTF_Font *font, const char *text, int *w, int *h);
extern DECLSPEC int SDLCALL TTF_SizeUTF8(TTF_Font *font, const char *text, int *w, int *h);
extern DECLSPEC int SDLCALL TTF_SizeUNICODE(TTF_Font *font, const Uint16 *text, int *w, int *h);
-/* Get the measurement string of text without rendering
- e.g. the number of characters that can be rendered before reaching 'measure_width'
-
- in:
- measure_width - in pixels to measure this text
- out:
- count - number of characters that can be rendered
- extent - latest calculated width
-*/
+/**
+ * Get the measurement string of text without rendering
+ * e.g. the number of characters that can be rendered before reaching 'measure_width'
+ *
+ * \param font TTF_Font handle
+ * \param text text to render
+ *
+ * \param measure_width in pixels to measure this text (input)
+ * \param count number of characters that can be rendered (output)
+ * \param extent latest calculated width (output)
+ *
+ * \returns 0 if successful, -1 on error
+ *
+ * \sa TTF_MeasureText
+ * \sa TTF_MeasureUTF8
+ * \sa TTF_MeasureUNICODE
+ */
extern DECLSPEC int SDLCALL TTF_MeasureText(TTF_Font *font, const char *text, int measure_width, int *extent, int *count);
extern DECLSPEC int SDLCALL TTF_MeasureUTF8(TTF_Font *font, const char *text, int measure_width, int *extent, int *count);
extern DECLSPEC int SDLCALL TTF_MeasureUNICODE(TTF_Font *font, const Uint16 *text, int measure_width, int *extent, int *count);
-/* Create an 8-bit palettized surface and render the given text at
- fast quality with the given font and color. The 0 pixel is the
- colorkey, giving a transparent background, and the 1 pixel is set
- to the text color.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create an 8-bit palettized surface and render the given text at
+ * fast quality with the given font and color. The 0 pixel is the
+ * colorkey, giving a transparent background, and the 1 pixel is set
+ * to the text color.
+ *
+ * \param font TTF_Font handle
+ * \param text text to render
+ * \param fg foreground color
+ *
+ * \returns the new surface, or NULL if there was an error.
+ *
+ * \sa TTF_RenderText_Solid
+ * \sa TTF_RenderUTF8_Solid
+ * \sa TTF_RenderUNICODE_Solid
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Solid(TTF_Font *font,
const char *text, SDL_Color fg);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Solid(TTF_Font *font,
@@ -243,15 +545,24 @@ extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Solid(TTF_Font *font,
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Solid(TTF_Font *font,
const Uint16 *text, SDL_Color fg);
-/* Create an 8-bit palettized surface and render the given text at
- fast quality with the given font and color. The 0 pixel is the
- colorkey, giving a transparent background, and the 1 pixel is set
- to the text color.
- Text is wrapped to multiple lines on line endings and on word boundaries
- if it extends beyond wrapLength in pixels.
- If wrapLength is 0, only wrap on new lines.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create an 8-bit palettized surface and render the given text at fast quality with the given font and color.
+ * The 0 pixel is the
+ * colorkey, giving a transparent background, and the 1 pixel is set to the text color.
+ * Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.
+ * If wrapLength is 0, only wrap on new lines.
+ *
+ * \param font TTF_Font handle
+ * \param text text to render
+ * \param fg foreground color
+ * \param wrapLength wrap length
+ *
+ * \returns the new surface, or NULL if there was an error.
+ *
+ * \sa TTF_RenderText_Solid_Wrapped
+ * \sa TTF_RenderUTF8__Wrapped
+ * \sa TTF_RenderUNICODE_Solid_Wrapped
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Solid_Wrapped(TTF_Font *font,
const char *text, SDL_Color fg, Uint32 wrapLength);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Solid_Wrapped(TTF_Font *font,
@@ -259,23 +570,45 @@ extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Solid_Wrapped(TTF_Font *fon
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Solid_Wrapped(TTF_Font *font,
const Uint16 *text, SDL_Color fg, Uint32 wrapLength);
-/* Create an 8-bit palettized surface and render the given glyph at
- fast quality with the given font and color. The 0 pixel is the
- colorkey, giving a transparent background, and the 1 pixel is set
- to the text color. The glyph is rendered without any padding or
- centering in the X direction, and aligned normally in the Y direction.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create an 8-bit palettized surface and render the given glyph at
+ * fast quality with the given font and color. The 0 pixel is the
+ * colorkey, giving a transparent background, and the 1 pixel is set
+ * to the text color. The glyph is rendered without any padding or
+ * centering in the X direction, and aligned normally in the Y direction.
+ * This function returns the new surface, or NULL if there was an error.
+ *
+ * \param font TTF_Font handle
+ * \param ch character index
+ * \param fg foreground color
+ *
+ * \returns the new surface, or NULL if there was an error.
+ *
+ * \sa TTF_RenderGlyph_Solid
+ * \sa TTF_RenderGlyph32_Solid
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph_Solid(TTF_Font *font,
Uint16 ch, SDL_Color fg);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph32_Solid(TTF_Font *font,
Uint32 ch, SDL_Color fg);
-/* Create an 8-bit palettized surface and render the given text at
- high quality with the given font and colors. The 0 pixel is background,
- while other pixels have varying degrees of the foreground color.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create an 8-bit palettized surface and render the given text at
+ * high quality with the given font and colors. The 0 pixel is background,
+ * while other pixels have varying degrees of the foreground color.
+ * This function returns the new surface, or NULL if there was an error.
+ *
+ * \param font TTF_Font handle
+ * \param text text to render
+ * \param fg foreground color
+ * \param bg background color
+ *
+ * \returns the new surface, or NULL if there was an error.
+ *
+ * \sa TTF_RenderText_Shaded
+ * \sa TTF_RenderUTF8_Shaded
+ * \sa TTF_RenderUNICODE_Shaded
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Shaded(TTF_Font *font,
const char *text, SDL_Color fg, SDL_Color bg);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Shaded(TTF_Font *font,
@@ -283,14 +616,27 @@ extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Shaded(TTF_Font *font,
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Shaded(TTF_Font *font,
const Uint16 *text, SDL_Color fg, SDL_Color bg);
-/* Create an 8-bit palettized surface and render the given text at
- high quality with the given font and colors. The 0 pixel is background,
- while other pixels have varying degrees of the foreground color.
- Text is wrapped to multiple lines on line endings and on word boundaries
- if it extends beyond wrapLength in pixels.
- If wrapLength is 0, only wrap on new lines.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create an 8-bit palettized surface and render the given text at
+ * high quality with the given font and colors. The 0 pixel is background,
+ * while other pixels have varying degrees of the foreground color.
+ * Text is wrapped to multiple lines on line endings and on word boundaries
+ * if it extends beyond wrapLength in pixels.
+ * If wrapLength is 0, only wrap on new lines.
+ * This function returns the new surface, or NULL if there was an error.
+ *
+ * \param font TTF_Font handle
+ * \param text text to render
+ * \param fg foreground color
+ * \param bg background color
+ * \param wrapLength wrap length
+ *
+ * \returns the new surface, or NULL if there was an error.
+ *
+ * \sa TTF_RenderText_Shaded_Wrapped
+ * \sa TTF_RenderUTF8_Shaded_Wrapped
+ * \sa TTF_RenderUNICODE_Shaded_Wrapped
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Shaded_Wrapped(TTF_Font *font,
const char *text, SDL_Color fg, SDL_Color bg, Uint32 wrapLength);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Shaded_Wrapped(TTF_Font *font,
@@ -298,22 +644,44 @@ extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Shaded_Wrapped(TTF_Font *fo
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Shaded_Wrapped(TTF_Font *font,
const Uint16 *text, SDL_Color fg, SDL_Color bg, Uint32 wrapLength);
-/* Create an 8-bit palettized surface and render the given glyph at
- high quality with the given font and colors. The 0 pixel is background,
- while other pixels have varying degrees of the foreground color.
- The glyph is rendered without any padding or centering in the X
- direction, and aligned normally in the Y direction.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create an 8-bit palettized surface and render the given glyph at
+ * high quality with the given font and colors. The 0 pixel is background,
+ * while other pixels have varying degrees of the foreground color.
+ * The glyph is rendered without any padding or centering in the X
+ * direction, and aligned normally in the Y direction.
+ * This function returns the new surface, or NULL if there was an error.
+ *
+ * \param font TTF_Font handle
+ * \param ch character index
+ * \param fg foreground color
+ * \param bg background color
+ *
+ * \returns the new surface, or NULL if there was an error.
+ *
+ * \sa TTF_RenderGlyph_Shaded
+ * \sa TTF_RenderGlyph32_Shaded
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph_Shaded(TTF_Font *font,
Uint16 ch, SDL_Color fg, SDL_Color bg);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph32_Shaded(TTF_Font *font,
Uint32 ch, SDL_Color fg, SDL_Color bg);
-/* Create a 32-bit ARGB surface and render the given text at high quality,
- using alpha blending to dither the font with the given color.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create a 32-bit ARGB surface and render the given text at high quality,
+ * using alpha blending to dither the font with the given color.
+ * This function returns the new surface, or NULL if there was an error.
+ *
+ * \param font TTF_Font handle
+ * \param text text to render
+ * \param fg foreground color
+ *
+ * \returns the new surface, or NULL if there was an error.
+ *
+ * \sa TTF_RenderText_Blended
+ * \sa TTF_RenderUTF8_Blended
+ * \sa TTF_RenderUNICODE_Blended
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Blended(TTF_Font *font,
const char *text, SDL_Color fg);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Blended(TTF_Font *font,
@@ -322,13 +690,25 @@ extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Blended(TTF_Font *font,
const Uint16 *text, SDL_Color fg);
-/* Create a 32-bit ARGB surface and render the given text at high quality,
- using alpha blending to dither the font with the given color.
- Text is wrapped to multiple lines on line endings and on word boundaries
- if it extends beyond wrapLength in pixels.
- If wrapLength is 0, only wrap on new lines.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create a 32-bit ARGB surface and render the given text at high quality,
+ * using alpha blending to dither the font with the given color.
+ * Text is wrapped to multiple lines on line endings and on word boundaries
+ * if it extends beyond wrapLength in pixels.
+ * If wrapLength is 0, only wrap on new lines.
+ * This function returns the new surface, or NULL if there was an error.
+ *
+ * \param font TTF_Font handle
+ * \param text text to render
+ * \param fg foreground color
+ * \param wrapLength wrap length
+ *
+ * \returns the new surface, or NULL if there was an error.
+ *
+ * \sa TTF_RenderText_Blended_Wrapped
+ * \sa TTF_RenderUTF8_Blended_Wrapped
+ * \sa TTF_RenderUNICODE_Blended_Wrapped
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_Blended_Wrapped(TTF_Font *font,
const char *text, SDL_Color fg, Uint32 wrapLength);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Blended_Wrapped(TTF_Font *font,
@@ -336,21 +716,43 @@ extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_Blended_Wrapped(TTF_Font *f
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_Blended_Wrapped(TTF_Font *font,
const Uint16 *text, SDL_Color fg, Uint32 wrapLength);
-/* Create a 32-bit ARGB surface and render the given glyph at high quality,
- using alpha blending to dither the font with the given color.
- The glyph is rendered without any padding or centering in the X
- direction, and aligned normally in the Y direction.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create a 32-bit ARGB surface and render the given glyph at high quality,
+ * using alpha blending to dither the font with the given color.
+ * The glyph is rendered without any padding or centering in the X
+ * direction, and aligned normally in the Y direction.
+ * This function returns the new surface, or NULL if there was an error.
+ *
+ * \param font TTF_Font handle
+ * \param ch character index
+ * \param fg foreground color
+ *
+ * \returns the new surface, or NULL if there was an error.
+ *
+ * \sa TTF_RenderGlyph_Blended
+ * \sa TTF_RenderGlyph32_Blended
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph_Blended(TTF_Font *font,
Uint16 ch, SDL_Color fg);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderGlyph32_Blended(TTF_Font *font,
Uint32 ch, SDL_Color fg);
-/* Create a 32-bit surface (SDL_PIXELFORMAT_ARGB8888) and render the given text
- using FreeType LCD rendering, with the given font and colors.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create a 32-bit surface (SDL_PIXELFORMAT_ARGB8888) and render the given text
+ * using FreeType LCD rendering, with the given font and colors.
+ * This function returns the new surface, or NULL if there was an error.
+ *
+ * \param font TTF_Font handle
+ * \param text text to render
+ * \param fg foreground color
+ * \param bg background color
+ *
+ * \returns the new surface, or NULL if there was an error.a
+ *
+ * \sa TTF_RenderText_LCD
+ * \sa TTF_RenderUTF8_LCD
+ * \sa TTF_RenderUNICODE_LCD
+ */
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderText_LCD(TTF_Font *font,
const char *text, SDL_Color fg, SDL_Color bg);
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_LCD(TTF_Font *font,
@@ -358,12 +760,25 @@ extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUTF8_LCD(TTF_Font *font,
extern DECLSPEC SDL_Surface * SDLCALL TTF_RenderUNICODE_LCD(TTF_Font *font,
const Uint16 *text, SDL_Color fg, SDL_Color bg);
-/* Create a 32-bit surface (SDL_PIXELFORMAT_ARGB8888) and render the given text
- using FreeType LCD rendering, with the given font and colors.
- Text is wrapped to multiple lines on line endings and on word boundaries
- if it extends beyond wrapLength in pixels.
- This function returns the new surface, or NULL if there was an error.
-*/
+/**
+ * Create a 32-bit surface (SDL_PIXELFORMAT_ARGB8888) and render the given text
+ * using FreeType LCD rendering, with the given font and colors.
+ * Text is wrapped to multiple lines on line endings and on word boundaries
+ * if
(Patch may be truncated, please check the link at the top of this post.)