NAME

SDL2-ttf - FreeType interface to render text in SDL2

SYNOPSIS

use SDL2::Raw;
use SDL2-ttf;

# initialize
TTF_Init();

# set a render color
my $color = TTF_Color(255, 28, 174); # Pink

# select a font file
my $font-file = '/path/to/font/my_Font.ttf';

# open it at a certain point size (May be scaled later by SDL2)
my $font = TTF_OpenFont($font-file, 64);

# render text using the selected font and color as a SDL2 texture
my $raku = SDL_CreateTextureFromSurface(
    SDL_CreateRenderer(), TTF_Render_Blended($font, ' Raku ', $color)
);

# Clean up afterwords
TTF_CloseFont($font);
TTF_Quit();

The $raku variable now contains a rendered texture that may be used in SDL2.

DESCRIPTION

Provides a convenient interface to FreeType to assist in loading and using TrueType fonts as rendering textures in SDL2.

Needs to have the libsdl2-dev and libsdl2-ttf-dev development libraries installed.

On Debian derived distributions:

sudo apt-get install libsdl2-dev libsdl2-ttf-dev

Similar for others.

Documentation for the SDL2_ttf library, which works very similar to, but not exactly the same as these bindings: https://www.libsdl.org/projects/SDL_ttf/docs/index.html

Several routines are called slightly differently, and many are not exposed at due to the different requirements and capabilities of the Raku runtime and the C library.

Try out the ttftest.p6 script in the examples folder to get a feel for how it can be used.

Enumerations

There are a few enumerations provided.

TTF_STYLE - The various font styles that may be available and/or specified:

TTF_HINTING - The various font hints that may be available and/or specified:

Subroutines:

General

• TTF_Init

• TTF_WasInit

• TTF_Quit

• TTF_GetError

• TTF_OpenFont

• TTF_OpenFontIndex

• TTF_CloseFont

Attributes

• TTF_GetFontStyle

• TTF_GetFontStyles

• TTF_SetFontStyle

• TTF_GetFontOutline

• TTF_SetFontOutline

• TTF_GetFontHinting

• TTF_SetFontHinting

• TTF_GetFontKerning

• TTF_SetFontKerning

• TTF_FontHeight

• TTF_FontAscent

• TTF_FontDescent

• TTF_FontLineSkip

• TTF_FontFaces

• TTF_FontFaceIsFixedWidth

• TTF_FontFaceFamilyName

• TTF_FontFaceStyleName

• TTF_GlyphIsProvided

• TTF_GlyphMetrics

• TTF_GetTextSize

Rendering

• TTF_Color

• TTF_Render_Solid

• TTF_Render_Shaded

• TTF_Render_Blended

• TTF_Render_Blended_Wrapped

Rendering modes

• Solid - Quick and Dirty

  • Create an 8-bit palettized surface and render the given text at fast quality with the given font and color. The pixel value of 0 is the colorkey, giving a transparent background when blitted. Pixel and colormap value 1 is set to the text foreground color. This results in no box around the text, but the text is not as smooth.

• Shaded - Slow and Nice, but with a Solid Box

  • Create an 8-bit palettized surface and render the given text at high quality with the given font and colors. The 0 pixel value is background, while other pixels have varying degrees of the foreground color from the background color. This results in a box of the background color around the text in the foreground color. The text is antialiased. This will render slower than Solid, but in about the same time as Blended mode.

• Blended - Slow Slow Slow, but Ultra Nice over another image

  • 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 results in a surface with alpha transparency, so you don’t have a solid colored box around the text. The text is antialiased. This will render slower than Solid, but in about the same time as Shaded mode. Use this when you want high quality, and the text isn’t changing too fast.

  ---

TTF_Init()

• Initialize the truetype font API.

• Must be called before using other functions in this library, except TTF_WasInit or TTF_Color.

• SDL does not have to be initialized before this call.

• Takes: Nothing.

• Returns: 0 on success, -1 on any error

TTF_WasInit

• Query the initilization status of the truetype font API.

• Takes: Nothing.

• Returns: 1 if already initialized, 0 if not initialized.

TTF_Quit

• Shutdown and cleanup the truetype font API.

• Takes: Nothing.

• Returns: Nothing.

TTF_GetError

• Returns the last error set as a string.

• Takes: Nothing

• Returns: String.

TTF_OpenFont($file, $ptsize)

• Load file for use as a font, at ptsize size.

• Takes:

  • $file - File name to load font from.

  • $ptsize - Point size (based on 72DPI) to load font as. Basically pixel height.

• Returns: Pointer to the font as a TTF_Font. NULL is returned on error.

TTF_OpenFontIndex($file, $ptsize, $index)

• Load file for use as a font, at ptsize size, selecting $index face.

• Takes:

  • $file - File name to load font from.

  • $ptsize - Point size (based on 72DPI) to load font as. Basically pixel height.

  • $index - Choose a font face from a file containing multiple font faces. The first face is always index 0.

• Returns: Pointer to the font as a TTF_Font. NULL is returned on error.

TTF_CloseFont($font)

• Free the memory used by font, and free font itself as well.

• Takes: $font - Pointer to loaded font.

• Returns: Nothing.

TTF_GetFontStyle($font)

• Get the rendering style of the loaded font.

• Takes: $font - Pointer to loaded font.

• Returns: The bitwise or of the set styles codes. See the TTF_STYLE ENUM

TTF_GetFontStyles($font)

• Get the rendering style of the loaded font, enumerated list.

• Takes: $font - Pointer to loaded font.

• Returns: An enumerated list of the set styles. See the TTF_STYLE ENUM

TTF_SetFontStyle($font, $style)

• Set the rendering style of the loaded font.

• Takes:

  • $font - Pointer to loaded font.

  • $style - The bitwise or of the desired styles codes. See the TTF_STYLE ENUM

• Returns: Nothing

TTF_GetFontOutline($font)

• Get the current outline size of the loaded font.

• Takes: $font - Pointer to loaded font.

• Returns: The size of the outline currently set on the font, in pixels.

TTF_SetFontOutline($font, $outline)

• Set the current outline size of the loaded font.

• Takes:

  • $font - Pointer to loaded font.

  • $outline - The size of outline desired, in pixels.

• Returns: Nothing.

TTF_GetFontHinting($font)

• Get the current hinting setting of the loaded font.

• Takes: $font - Pointer to loaded font.

• Returns: The hinting type matching one of the enumerated values. See the TTF_HINTING ENUM

TTF_SetFontHinting($font, $hint)

• Set the current hinting setting of the loaded font.

• Takes:

  • $font - Pointer to loaded font.

  • $hint - One of the enumerated Hint values. See the TTF_HINTING ENUM

• Returns: Nothing.

TTF_GetFontKerning($font)

• Get the current kerning setting of the loaded font.

• Takes: $font - Pointer to loaded font.

• Returns: Returns: 0(zero) if kerning is disabled; a non-zero value when enabled.

TTF_SetFontKerning($font, $allowed)

• Set the current hinting setting of the loaded font.

• Takes:

  • $font - Pointer to loaded font.

  • $allowed - 0 to disable kerning; non-zero to enable kerning. The default is 1, enabled.

• Returns: Nothing.

TTF_FontHeight($font)

• Get the maximum pixel height of all glyphs of the loaded font. Minimum size for adjacent rows of text to not overlap.

• Takes: $font - Pointer to loaded font.

• Returns: The maximum pixel height of all glyphs in the font.

TTF_FontAscent($font)

• Get the maximum pixel ascent of all glyphs of the loaded font. - The maximum distance from the baseline to the top.

• Takes: $font - Pointer to loaded font.

• Returns: The maximum pixel ascent of all glyphs in the font.

TTF_FontDescent($font)

• Get the maximum pixel descent of all glyphs of the loaded font. - The maximum distance from the baseline to the bottom.

• Takes: $font - Pointer to loaded font.

• Returns: The maximum pixel descent of all glyphs in the font.

TTF_FontLineSkip($font)

• Get the recommended pixel height of a rendered line of text of the loaded font. - Usually larger than the TTF_FontHeight of the font.

• Takes: $font - Pointer to loaded font.

• Returns: The maximum pixel height of all glyphs in the font.

TTF_FontFaces($font)

• Get the number of faces ("sub-fonts") available in the loaded font.

• Takes: $font - Pointer to loaded font.

• Returns: The number of faces in the font.

TTF_FontFaceIsFixedWidth($font)

• Test if the current font face of the loaded font is a fixed width font.

• Takes: $font - Pointer to loaded font.

• Returns: >0 if $font is a fixed width font. 0 if not a fixed width font.

TTF_FontFaceFamilyName($font)

• Get the current font face family name from the loaded font.

• Takes: $font - Pointer to loaded font.

• Returns: The current family name of the face of the font, or NULL if not available.

TTF_FontFaceStyleName($font)

• Get the current font face style name from the loaded font.

• Takes: $font - Pointer to loaded font.

• Returns: The current style name of the face of the font, or NULL if not available.

TTF_GlyphIsProvided($font, $character or $ordinal)

• Get the status of the availability of the glyph for $character from the loaded font.

• Takes:

  • $font - Pointer to loaded font.

  • Either: $character - String containing the $character to check for.

  • Or: $ordinal - Integer $ordinal of character.

• Returns: The index of the glyph location in the font for $character, or 0 for an undefined character code. (Note: returns the font file index, NOT the character ordinal.)

TTF_GlyphMetrics($font, $character)

• Get the metrics of the char given in $character from the loaded font.

• Takes:

  • $font - Pointer to loaded font.

  • $character - String containing the character to get metrics for.

• Returns: A hash containing the following information:

  • :font(TTF_FontFaceFamilyName($font)) - The Family Face name

  • :style(TTF_FontFaceStyleName($font)) - The style

  • :char($character) - The character checked

  • :$min-x - The minimum X offset into the character.

  • :$max-x - The maximum X offset into the character.

  • :$min-y - The minimum Y offset into the character.

  • :$max-y - The maximum Y offset into the character.

  • :$advance - The distance from the end of the previous glyph to the start of the next.

Glyph Metrics explained: (image copyright libsdl.org)

TTF_GetTextSize($font, $text)

• Get the width and height in pixels of the given text in the currently loaded font.

• Takes:

  • $font - Pointer to loaded font.

  • $text - Text string to get the dimensions.

• Returns: A list of Pairs

  • :width(width)

  • :height(height)

TTF_Color($red, $green, $blue, $alpha = 255)

• Generate a packed ARGB TTF_color suitable to pass to the rendering routines.

• Takes:

  • $red - 0-255 integer value for red.

  • $green - 0-255 integer value for green.

  • $blue - 0-255 integer value for blue.

  • $alpha - 0-255 integer value for alpha. Optional, default 255

• Returns: The packed TTF_Color.

TTF_Render_Solid($font, $text, $fg)

• Render the passed $text using $font with $fg color onto a new surface, using Solid mode.

• Takes:

  • $font - Pointer to loaded font.

  • $text - Text string to render.

  • $fg - TTF_Color to use as the foreground color.

• Returns: A pointer to a new SDL Surface.

TTF_Render_Shaded($font, $text, $fg, $bg)

• Render the passed $text using $font with $fg color onto a new $bg colored surface, using Shaded mode.

• Takes:

  • $font - Pointer to loaded font.

  • $text - Text string to render.

  • $fg - TTF_Color to use as the foreground color.

  • $bg - TTF_Color to use as the background color.

• Returns: A pointer to a new SDL Surface.

TTF_Render_Blended($font, $text, $fg)

• Render the passed $text using $font with $fg color onto a new surface, using Blended mode.

• Takes:

  • $font - Pointer to loaded font.

  • $text - Text string to render.

  • $fg - TTF_Color to use as the foreground color.

• Returns: A pointer to a new SDL Surface.

TTF_Render_Blended_Wrapped($font, $text, $fg, $length)

• A convenience routine to render wrapped text, in Blended mode.

• Takes:

  • $font - Pointer to loaded font.

  • $text - Text string to render.

  • $fg - TTF_Color to use as the foreground color.

  • $length - Length in pixels to use as a wrap threshold.

• Returns: A pointer to a new SDL Surface.

AUTHOR

SDL2_ttf library: Sam Lantinga

Raku bindings: Steve Schulze (thundergnat)

COPYRIGHT AND LICENSE

Copyright 2020 Steve Schulze (thundergnat)

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.