<!-- DO NOT EDIT THIS PAGE ON THE WIKI. IT WILL BE OVERWRITTEN BY WIKIHEADERS AND CHANGES WILL BE LOST! -->

# QuickReference

If you want to paste this into a text editor that can't handle
the fancy Unicode section headers, try using
[QuickReferenceNoUnicode](QuickReferenceNoUnicode) instead.

```c
// SDL3_ttf API Quick Reference
//
// https://libsdl.org/
//
// The latest version of this document can be found at https://wiki.libsdl.org/SDL3_ttf/QuickReference
// Based on SDL_ttf version 3.3.0
//
// This can be useful in an IDE with search and syntax highlighting.
//
// Original idea for this document came from Dan Bechard (thanks!)
// ASCII art generated by: https://patorjk.com/software/taag/#p=display&f=ANSI%20Shadow (with modified 'S' for readability)


//  ██████╗ ██████╗  ██╗      ████████╗ ████████╗ ███████╗
// ██╔════╝ ██╔══██╗ ██║      ╚══██╔══╝ ╚══██╔══╝ ██╔════╝
// ███████╗ ██║  ██║ ██║         ██║       ██║    █████╗
// ╚════██║ ██║  ██║ ██║         ██║       ██║    ██╔══╝
// ██████╔╝ ██████╔╝ ███████╗    ██║       ██║    ██║
// ╚═════╝  ╚═════╝  ╚══════╝    ╚═╝       ╚═╝    ╚═╝

#define SDL_TTF_MAJOR_VERSION                                                                                                              // Printable format: "%d.%d.%d", MAJOR, MINOR, MICRO
#define SDL_TTF_VERSION                                                                                                                    // This is the version number macro for the current SDL_ttf version.
#define SDL_TTF_VERSION_ATLEAST(X, Y, Z)                                                                                                   // This macro will evaluate to true if compiled with SDL_ttf at least X.Y.Z.
int TTF_Version(void);                                                                                                                     // This function gets the version of the dynamically linked SDL_ttf library.
void TTF_GetFreeTypeVersion(int *major, int *minor, int *patch);                                                                           // Query the version of the FreeType library in use.
void TTF_GetHarfBuzzVersion(int *major, int *minor, int *patch);                                                                           // Query the version of the HarfBuzz library in use.
bool TTF_Init(void);                                                                                                                       // Initialize SDL_ttf.
TTF_Font * TTF_OpenFont(const char *file, float ptsize);                                                                                   // Create a font from a file, using a specified point size.
TTF_Font * TTF_OpenFontIO(SDL_IOStream *src, bool closeio, float ptsize);                                                                  // Create a font from an SDL_IOStream, using a specified point size.
TTF_Font * TTF_OpenFontWithProperties(SDL_PropertiesID props);                                                                             // Create a font with the specified properties.
TTF_Font * TTF_CopyFont(TTF_Font *existing_font);                                                                                          // Create a copy of an existing font.
SDL_PropertiesID TTF_GetFontProperties(TTF_Font *font);                                                                                    // Get the properties associated with a font.
Uint32 TTF_GetFontGeneration(TTF_Font *font);                                                                                              // Get the font generation.
bool TTF_AddFallbackFont(TTF_Font *font, TTF_Font *fallback);                                                                              // Add a fallback font.
void TTF_RemoveFallbackFont(TTF_Font *font, TTF_Font *fallback);                                                                           // Remove a fallback font.
void TTF_ClearFallbackFonts(TTF_Font *font);                                                                                               // Remove all fallback fonts.
bool TTF_SetFontSize(TTF_Font *font, float ptsize);                                                                                        // Set a font's size dynamically.
bool TTF_SetFontSizeDPI(TTF_Font *font, float ptsize, int hdpi, int vdpi);                                                                 // Set font size dynamically with target resolutions, in dots per inch.
float TTF_GetFontSize(TTF_Font *font);                                                                                                     // Get the size of a font.
bool TTF_GetFontDPI(TTF_Font *font, int *hdpi, int *vdpi);                                                                                 // Get font target resolutions, in dots per inch.
void TTF_SetFontStyle(TTF_Font *font, TTF_FontStyleFlags style);                                                                           // Set a font's current style.
TTF_FontStyleFlags TTF_GetFontStyle(const TTF_Font *font);                                                                                 // Query a font's current style.
bool TTF_SetFontOutline(TTF_Font *font, int outline);                                                                                      // Set a font's current outline.
int TTF_GetFontOutline(const TTF_Font *font);                                                                                              // Query a font's current outline.
void TTF_SetFontHinting(TTF_Font *font, TTF_HintingFlags hinting);                                                                         // Set a font's current hinter setting.
int TTF_GetNumFontFaces(const TTF_Font *font);                                                                                             // Query the number of faces of a font.
TTF_HintingFlags TTF_GetFontHinting(const TTF_Font *font);                                                                                 // Query a font's current FreeType hinter setting.
bool TTF_SetFontSDF(TTF_Font *font, bool enabled);                                                                                         // Enable Signed Distance Field rendering for a font.
bool TTF_GetFontSDF(const TTF_Font *font);                                                                                                 // Query whether Signed Distance Field rendering is enabled for a font.
int TTF_GetFontWeight(const TTF_Font *font);                                                                                               // Query a font's weight, in terms of the lightness/heaviness of the strokes.
void TTF_SetFontWrapAlignment(TTF_Font *font, TTF_HorizontalAlignment align);                                                              // Set a font's current wrap alignment option.
TTF_HorizontalAlignment TTF_GetFontWrapAlignment(const TTF_Font *font);                                                                    // Query a font's current wrap alignment option.
int TTF_GetFontHeight(const TTF_Font *font);                                                                                               // Query the total height of a font.
int TTF_GetFontAscent(const TTF_Font *font);                                                                                               // Query the offset from the baseline to the top of a font.
int TTF_GetFontDescent(const TTF_Font *font);                                                                                              // Query the offset from the baseline to the bottom of a font.
void TTF_SetFontLineSkip(TTF_Font *font, int lineskip);                                                                                    // Set the spacing between lines of text for a font.
int TTF_GetFontLineSkip(const TTF_Font *font);                                                                                             // Query the spacing between lines of text for a font.
void TTF_SetFontKerning(TTF_Font *font, bool enabled);                                                                                     // Set if kerning is enabled for a font.
bool TTF_GetFontKerning(const TTF_Font *font);                                                                                             // Query whether or not kerning is enabled for a font.
bool TTF_FontIsFixedWidth(const TTF_Font *font);                                                                                           // Query whether a font is fixed-width.
bool TTF_FontIsScalable(const TTF_Font *font);                                                                                             // Query whether a font is scalable or not.
const char * TTF_GetFontFamilyName(const TTF_Font *font);                                                                                  // Query a font's family name.
const char * TTF_GetFontStyleName(const TTF_Font *font);                                                                                   // Query a font's style name.
bool TTF_SetFontDirection(TTF_Font *font, TTF_Direction direction);                                                                        // Set the direction to be used for text shaping by a font.
TTF_Direction TTF_GetFontDirection(TTF_Font *font);                                                                                        // Get the direction to be used for text shaping by a font.
bool TTF_SetFontCharSpacing(TTF_Font *font, int spacing);                                                                                  // Set additional space in pixels to be applied between any two rendered characters.
int TTF_GetFontCharSpacing(TTF_Font *font);                                                                                                // Get the additional character spacing in pixels to be applied between any two rendered characters.
Uint32 TTF_StringToTag(const char *string);                                                                                                // Convert from a 4 character string to a 32-bit tag.
void TTF_TagToString(Uint32 tag, char *string, size_t size);                                                                               // Convert from a 32-bit tag to a 4 character string.
bool TTF_SetFontScript(TTF_Font *font, Uint32 script);                                                                                     // Set the script to be used for text shaping by a font.
Uint32 TTF_GetFontScript(TTF_Font *font);                                                                                                  // Get the script used for text shaping a font.
Uint32 TTF_GetGlyphScript(Uint32 ch);                                                                                                      // Get the script used by a 32-bit codepoint.
bool TTF_SetFontLanguage(TTF_Font *font, const char *language_bcp47);                                                                      // Set language to be used for text shaping by a font.
bool TTF_FontHasGlyph(TTF_Font *font, Uint32 ch);                                                                                          // Check whether a glyph is provided by the font for a UNICODE codepoint.
SDL_Surface * TTF_GetGlyphImage(TTF_Font *font, Uint32 ch, TTF_ImageType *image_type);                                                     // Get the pixel image for a UNICODE codepoint.
SDL_Surface * TTF_GetGlyphImageForIndex(TTF_Font *font, Uint32 glyph_index, TTF_ImageType *image_type);                                    // Get the pixel image for a character index.
bool TTF_GetGlyphMetrics(TTF_Font *font, Uint32 ch, int *minx, int *maxx, int *miny, int *maxy, int *advance);                             // Query the metrics (dimensions) of a font's glyph for a UNICODE codepoint.
bool TTF_GetGlyphKerning(TTF_Font *font, Uint32 previous_ch, Uint32 ch, int *kerning);                                                     // Query the kerning size between the glyphs of two UNICODE codepoints.
bool TTF_GetStringSize(TTF_Font *font, const char *text, size_t length, int *w, int *h);                                                   // Calculate the dimensions of a rendered string of UTF-8 text.
bool TTF_GetStringSizeWrapped(TTF_Font *font, const char *text, size_t length, int wrap_width, int *w, int *h);                            // Calculate the dimensions of a rendered string of UTF-8 text.
bool TTF_MeasureString(TTF_Font *font, const char *text, size_t length, int max_width, int *measured_width, size_t *measured_length);      // Calculate how much of a UTF-8 string will fit in a given width.
SDL_Surface * TTF_RenderText_Solid(TTF_Font *font, const char *text, size_t length, SDL_Color fg);                                         // Render UTF-8 text at fast quality to a new 8-bit surface.
SDL_Surface * TTF_RenderText_Solid_Wrapped(TTF_Font *font, const char *text, size_t length, SDL_Color fg, int wrapLength);                 // Render word-wrapped UTF-8 text at fast quality to a new 8-bit surface.
SDL_Surface * TTF_RenderGlyph_Solid(TTF_Font *font, Uint32 ch, SDL_Color fg);                                                              // Render a single 32-bit glyph at fast quality to a new 8-bit surface.
SDL_Surface * TTF_RenderText_Shaded(TTF_Font *font, const char *text, size_t length, SDL_Color fg, SDL_Color bg);                          // Render UTF-8 text at high quality to a new 8-bit surface.
SDL_Surface * TTF_RenderText_Shaded_Wrapped(TTF_Font *font, const char *text, size_t length, SDL_Color fg, SDL_Color bg, int wrap_width);  // Render word-wrapped UTF-8 text at high quality to a new 8-bit surface.
SDL_Surface * TTF_RenderGlyph_Shaded(TTF_Font *font, Uint32 ch, SDL_Color fg, SDL_Color bg);                                               // Render a single UNICODE codepoint at high quality to a new 8-bit surface.
SDL_Surface * TTF_RenderText_Blended(TTF_Font *font, const char *text, size_t length, SDL_Color fg);                                       // Render UTF-8 text at high quality to a new ARGB surface.
SDL_Surface * TTF_RenderText_Blended_Wrapped(TTF_Font *font, const char *text, size_t length, SDL_Color fg, int wrap_width);               // Render word-wrapped UTF-8 text at high quality to a new ARGB surface.
SDL_Surface * TTF_RenderGlyph_Blended(TTF_Font *font, Uint32 ch, SDL_Color fg);                                                            // Render a single UNICODE codepoint at high quality to a new ARGB surface.
SDL_Surface * TTF_RenderText_LCD(TTF_Font *font, const char *text, size_t length, SDL_Color fg, SDL_Color bg);                             // Render UTF-8 text at LCD subpixel quality to a new ARGB surface.
SDL_Surface * TTF_RenderText_LCD_Wrapped(TTF_Font *font, const char *text, size_t length, SDL_Color fg, SDL_Color bg, int wrap_width);     // Render word-wrapped UTF-8 text at LCD subpixel quality to a new ARGB surface.
SDL_Surface * TTF_RenderGlyph_LCD(TTF_Font *font, Uint32 ch, SDL_Color fg, SDL_Color bg);                                                  // Render a single UNICODE codepoint at LCD subpixel quality to a new ARGB surface.
TTF_TextEngine * TTF_CreateSurfaceTextEngine(void);                                                                                        // Create a text engine for drawing text on SDL surfaces.
bool TTF_DrawSurfaceText(TTF_Text *text, int x, int y, SDL_Surface *surface);                                                              // Draw text to an SDL surface.
void TTF_DestroySurfaceTextEngine(TTF_TextEngine *engine);                                                                                 // Destroy a text engine created for drawing text on SDL surfaces.
TTF_TextEngine * TTF_CreateRendererTextEngine(SDL_Renderer *renderer);                                                                     // Create a text engine for drawing text on an SDL renderer.
TTF_TextEngine * TTF_CreateRendererTextEngineWithProperties(SDL_PropertiesID props);                                                       // Create a text engine for drawing text on an SDL renderer, with the specified properties.
bool TTF_DrawRendererText(TTF_Text *text, float x, float y);                                                                               // Draw text to an SDL renderer.
void TTF_DestroyRendererTextEngine(TTF_TextEngine *engine);                                                                                // Destroy a text engine created for drawing text on an SDL renderer.
TTF_TextEngine * TTF_CreateGPUTextEngine(SDL_GPUDevice *device);                                                                           // Create a text engine for drawing text with the SDL GPU API.
TTF_TextEngine * TTF_CreateGPUTextEngineWithProperties(SDL_PropertiesID props);                                                            // Create a text engine for drawing text with the SDL GPU API, with the specified properties.
TTF_GPUAtlasDrawSequence * TTF_GetGPUTextDrawData(TTF_Text *text);                                                                         // Get the geometry data needed for drawing the text.
void TTF_DestroyGPUTextEngine(TTF_TextEngine *engine);                                                                                     // Destroy a text engine created for drawing text with the SDL GPU API.
void TTF_SetGPUTextEngineWinding(TTF_TextEngine *engine, TTF_GPUTextEngineWinding winding);                                                // Sets the winding order of the vertices returned by TTF_GetGPUTextDrawData for a particular GPU text engine.
TTF_GPUTextEngineWinding TTF_GetGPUTextEngineWinding(const TTF_TextEngine *engine);                                                        // Get the winding order of the vertices returned by TTF_GetGPUTextDrawData for a particular GPU text engine
TTF_TextEngine * TTF_CreateGLTextEngine(void);                                                                                             // Create a text engine for drawing text with OpenGL.
TTF_TextEngine * TTF_CreateGLTextEngineWithProperties(SDL_PropertiesID props);                                                             // Create a text engine for drawing text with OpenGL, with extra properties.
TTF_GLAtlasDrawSequence * TTF_GetGLTextDrawData(TTF_Text *text);                                                                           // Get the geometry data needed for drawing the text.
void TTF_DestroyGLTextEngine(TTF_TextEngine *engine);                                                                                      // Destroy a text engine created for drawing text with OpenGL.
void TTF_SetGLTextEngineWinding(TTF_TextEngine *engine, TTF_GLTextEngineWinding winding);                                                  // Sets the winding order of the vertices returned by TTF_GetGLTextDrawData for a particular GL text engine.
TTF_GLTextEngineWinding TTF_GetGLTextEngineWinding(const TTF_TextEngine *engine);                                                          // Get the winding order of the vertices returned by TTF_GetGLTextDrawData for a particular GL text engine.
TTF_Text * TTF_CreateText(TTF_TextEngine *engine, TTF_Font *font, const char *text, size_t length);                                        // Create a text object from UTF-8 text and a text engine.
SDL_PropertiesID TTF_GetTextProperties(TTF_Text *text);                                                                                    // Get the properties associated with a text object.
bool TTF_SetTextEngine(TTF_Text *text, TTF_TextEngine *engine);                                                                            // Set the text engine used by a text object.
TTF_TextEngine * TTF_GetTextEngine(TTF_Text *text);                                                                                        // Get the text engine used by a text object.
bool TTF_SetTextFont(TTF_Text *text, TTF_Font *font);                                                                                      // Set the font used by a text object.
TTF_Font * TTF_GetTextFont(TTF_Text *text);                                                                                                // Get the font used by a text object.
bool TTF_SetTextDirection(TTF_Text *text, TTF_Direction direction);                                                                        // Set the direction to be used for text shaping a text object.
TTF_Direction TTF_GetTextDirection(TTF_Text *text);                                                                                        // Get the direction to be used for text shaping a text object.
bool TTF_SetTextScript(TTF_Text *text, Uint32 script);                                                                                     // Set the script to be used for text shaping a text object.
Uint32 TTF_GetTextScript(TTF_Text *text);                                                                                                  // Get the script used for text shaping a text object.
bool TTF_SetTextColor(TTF_Text *text, Uint8 r, Uint8 g, Uint8 b, Uint8 a);                                                                 // Set the color of a text object.
bool TTF_SetTextColorFloat(TTF_Text *text, float r, float g, float b, float a);                                                            // Set the color of a text object.
bool TTF_GetTextColor(TTF_Text *text, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);                                                             // Get the color of a text object.
bool TTF_GetTextColorFloat(TTF_Text *text, float *r, float *g, float *b, float *a);                                                        // Get the color of a text object.
bool TTF_SetTextPosition(TTF_Text *text, int x, int y);                                                                                    // Set the position of a text object.
bool TTF_GetTextPosition(TTF_Text *text, int *x, int *y);                                                                                  // Get the position of a text object.
bool TTF_SetTextWrapWidth(TTF_Text *text, int wrap_width);                                                                                 // Set whether wrapping is enabled on a text object.
bool TTF_GetTextWrapWidth(TTF_Text *text, int *wrap_width);                                                                                // Get whether wrapping is enabled on a text object.
bool TTF_SetTextWrapWhitespaceVisible(TTF_Text *text, bool visible);                                                                       // Set whether whitespace should be visible when wrapping a text object.
bool TTF_TextWrapWhitespaceVisible(TTF_Text *text);                                                                                        // Return whether whitespace is shown when wrapping a text object.
bool TTF_SetTextString(TTF_Text *text, const char *string, size_t length);                                                                 // Set the UTF-8 text used by a text object.
bool TTF_InsertTextString(TTF_Text *text, int offset, const char *string, size_t length);                                                  // Insert UTF-8 text into a text object.
bool TTF_AppendTextString(TTF_Text *text, const char *string, size_t length);                                                              // Append UTF-8 text to a text object.
bool TTF_DeleteTextString(TTF_Text *text, int offset, int length);                                                                         // Delete UTF-8 text from a text object.
bool TTF_GetTextSize(TTF_Text *text, int *w, int *h);                                                                                      // Get the size of a text object.
bool TTF_GetTextSubString(TTF_Text *text, int offset, TTF_SubString *substring);                                                           // Get the substring of a text object that surrounds a text offset.
bool TTF_GetTextSubStringForLine(TTF_Text *text, int line, TTF_SubString *substring);                                                      // Get the substring of a text object that contains the given line.
TTF_SubString ** TTF_GetTextSubStringsForRange(TTF_Text *text, int offset, int length, int *count);                                        // Get the substrings of a text object that contain a range of text.
bool TTF_GetTextSubStringForPoint(TTF_Text *text, int x, int y, TTF_SubString *substring);                                                 // Get the portion of a text string that is closest to a point.
bool TTF_GetPreviousTextSubString(TTF_Text *text, const TTF_SubString *substring, TTF_SubString *previous);                                // Get the previous substring in a text object
bool TTF_GetNextTextSubString(TTF_Text *text, const TTF_SubString *substring, TTF_SubString *next);                                        // Get the next substring in a text object
bool TTF_UpdateText(TTF_Text *text);                                                                                                       // Update the layout of a text object.
void TTF_DestroyText(TTF_Text *text);                                                                                                      // Destroy a text object created by a text engine.
void TTF_CloseFont(TTF_Font *font);                                                                                                        // Dispose of a previously-created font.
void TTF_Quit(void);                                                                                                                       // Deinitialize SDL_ttf.
int TTF_WasInit(void);                                                                                                                     // Check if SDL_ttf is initialized.
```

