SDL2-ttf

FreeType interface to render text in SDL2

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

Attributes

Rendering

Rendering modes

Solid - Quick and Dirty
Shaded - Slow and Nice, but with a Solid Box
Blended - Slow Slow Slow, but Ultra Nice over another image

`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 to check for.
- Or: 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 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 font with 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 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

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

NAME

SYNOPSIS

DESCRIPTION

Enumerations

Subroutines:

General

Attributes

Rendering

Rendering modes

TTF_Init()

TTF_WasInit

TTF_Quit

TTF_GetError

TTF_OpenFont($file, $ptsize)

TTF_OpenFontIndex($file, $ptsize, $index)

TTF_CloseFont($font)

TTF_GetFontStyle($font)

TTF_GetFontStyles($font)

TTF_SetFontStyle($font, $style)

TTF_GetFontOutline($font)

TTF_SetFontOutline($font, $outline)

TTF_GetFontHinting($font)

TTF_SetFontHinting($font, $hint)

TTF_GetFontKerning($font)

TTF_SetFontKerning($font, $allowed)

TTF_FontHeight($font)

TTF_FontAscent($font)

TTF_FontDescent($font)

TTF_FontLineSkip($font)

TTF_FontFaces($font)

TTF_FontFaceIsFixedWidth($font)

TTF_FontFaceFamilyName($font)

TTF_FontFaceStyleName($font)

TTF_GlyphIsProvided($font, $character or $ordinal)

TTF_GlyphMetrics($font, $character)

TTF_GetTextSize($font, $text)

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

TTF_Render_Solid($font, $text, $fg)

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

TTF_Render_Blended($font, $text, $fg)

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