Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell98 |
Introduction from SDL_ttf documentation at: http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf.html
This library is a wrapper around the excellent FreeType 1.2 library, available at: Freetype Homepage
WARNING: There may be patent issues with using the FreeType library. Check the FreeType website for up-to-date details.
This library allows you to use TrueType fonts to render text in SDL applications.
Be careful when including fonts with your application, as many of them are copyrighted. The Microsoft fonts, for example, are not freely redistributable and even the free "web" fonts they provide are only redistributable in their special executable installer form (May 1998). There are plenty of freeware and shareware fonts available on the Internet though, which may suit your purposes.
Enjoy! -Sam Lantinga slouken@devolution.com (5198)
- init :: IO CInt
- wasInit :: IO Bool
- quit :: IO ()
- withInit :: IO a -> IO a
- openFont :: String -> Int -> IO TTFFont
- closeFont :: TTFFont -> IO ()
- openFontIndex :: String -> Int -> Int -> IO TTFFont
- getFontStyle :: TTFFont -> IO TTFStyle
- setFontStyle :: TTFFont -> TTFStyle -> IO ()
- getFontHinting :: TTFFont -> IO TTFHinting
- setFontHinting :: TTFFont -> TTFHinting -> IO ()
- getFontHeight :: TTFFont -> IO Int
- getFontAscent :: TTFFont -> IO Int
- getFontDescent :: TTFFont -> IO Int
- fontKerningEnabled :: TTFFont -> IO KerningStatus
- setFontKerning :: TTFFont -> KerningStatus -> IO ()
- fontFaces :: TTFFont -> IO Int64
- fontFaceIsFixedWidth :: TTFFont -> IO Bool
- fontFaceFamilyName :: TTFFont -> IO String
- fontFaceStyleName :: TTFFont -> IO String
- sizeText :: TTFFont -> String -> IO (Int, Int)
- sizeUTF8 :: TTFFont -> String -> IO (Int, Int)
- sizeUNICODE :: TTFFont -> String -> IO (Int, Int)
- renderTextSolid :: TTFFont -> String -> Color -> IO (Ptr Surface)
- renderTextShaded :: TTFFont -> String -> Color -> Color -> IO (Ptr Surface)
- renderTextBlended :: TTFFont -> String -> Color -> IO (Ptr Surface)
- renderUTF8Solid :: TTFFont -> String -> Color -> IO (Ptr Surface)
- renderUTF8Shaded :: TTFFont -> String -> Color -> Color -> IO (Ptr Surface)
- renderUTF8Blended :: TTFFont -> String -> Color -> IO (Ptr Surface)
- peekInts :: (TTFFont -> CString -> Ptr CInt -> Ptr CInt -> IO CInt) -> TTFFont -> String -> IO (Int, Int)
Documentation
Initialize the truetype font API. This must be called before using other functions in this library, except TTF_WasInit.
SDL does not have to be initialized before this call. Returns: 0 on success, -1 on any error.
Query if TTF API has been initialised. Query the initilization status of the truetype font API. You may, of course, use this before TTF_Init to avoid initializing twice in a row. Or use this to determine if you need to call TTF_Quit.
Shut down the TTF system. Shutdown and cleanup the truetype font API. After calling this the SDL_ttf functions should not be used, excepting TTF_WasInit. You may, of course, use TTF_Init to use the functionality again.
withInit :: IO a -> IO a Source
Initialise the TTF system, run the given action(s), then quit TTF. This function handles the initialisation and shut down of the TTF system however if the initialisation fails an exception will be thrown and your program will crash.
:: String | File name to load font from. |
-> Int | Point size (based on 72DPI) to load font as. |
-> IO TTFFont | Pointer to the font as a TTF_Font. NULL is returned on errors. |
Load file for use as a font, at ptsize size.
This basically translates to pixel height. Equivalent to TTF_OpenFontIndex(file, ptsize, 0). It can also can load TTF and FON files.
Free the memory used by font, and free font itself as well.
Do not use font after this without loading a new font to it.
:: String | File name to load font from. |
-> Int | Point size (based on 72DPI) to load font as. |
-> Int | Font face index. The first face is always index 0. |
-> IO TTFFont | Pointer to the font as a TTF_Font. |
Load file, face index, for use as a font, at ptsize size.
This is equivalent to TTF_OpenFontIndexRW(SDL_RWFromFile(file), ptsize, index), but checks that the RWops it creates is not NULL. This can load TTF and FON files.
Get the rendering style of the loaded font.
If no style is set then TTF_STYLE_NORMAL is returned.
Extra pointers: http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf.html#SEC21
Set the rendering style of the loaded font.
This will flush the internal cache of previously rendered glyphs, even if there is no change in style, so it may be best to check the current style using TTF_GetFontStyle first.
Extra pointers: http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf.html#SEC22
:: TTFFont | Font |
-> IO TTFHinting | The current hinting setting of the loaded font. |
Get the current hinting setting of the loaded font.
If no hinting is set then TTF_HINTING_NORMAL is returned.
:: TTFFont | Font |
-> TTFHinting | The hinting setting desired. |
-> IO () |
Set the hinting of the loaded font.
You should experiment with this setting if you know which font you are using beforehand, especially when using smaller sized fonts. If the user is selecting a font, you may wish to let them select the hinting mode for that font as well.
Get the maximum pixel height of all glyphs of the loaded font.
You may use this height for rendering text as close together vertically as possible, though adding at least one pixel height to it will space it so they can't touch. Remember that SDL_ttf doesn't handle multiline printing, so you are responsible for line spacing, see the TTF_FontLineSkip as well.
Get the maximum pixel ascent of all glyphs of the loaded font.
This can also be interpreted as the distance from the top of the font to the baseline. It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.
Warning: C code (ewwwww)
rect.y = top + TTF_FontAscent(font) - glyph_metric.maxy;
Get the maximum pixel descent of all glyphs of the loaded font.
This can also be interpreted as the distance from the baseline to the bottom of the font. It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's maxy metric to resolve the top of the rectangle used when blitting the glyph on the screen.
:: TTFFont | Font |
-> IO KerningStatus | Current Kerning status. |
Get the current kerning setting of the loaded font.
The default for a newly loaded font is enabled(True).
:: TTFFont | Font |
-> KerningStatus | Desired Kerning status. |
-> IO () |
Set whther to use kerning when rendering the loaded font.
This has no effect on individual glyphs, but rather when rendering whole strings of characters, at least a word at a time. Perhaps the only time to disable this is when kerning is not working for a specific font, resulting in overlapping glyphs or abnormal spacing within words.
Get the number of faces ("sub-fonts") available in the loaded font.
This is a count of the number of specific fonts (based on size and style and other typographical features perhaps) contained in the font itself. It seems to be a useless fact to know, since it can't be applied in any other SDL_ttf functions.
Test if the current font face of the loaded font is a fixed width font.
Fixed width fonts are monospace, meaning every character that exists in the font is the same width, thus you can assume that a rendered string's width is going to be the result of a simple calculation:
glyph_width * string_length
Get the current font face family name from the loaded font.
This function may return a NULL pointer, in which case the information is not available.
Get the current font face style name from the loaded font.
This function may return a NULL pointer, in which case the information is not available.
Calculate the resulting surface size of the LATIN1 encoded text rendered using font.
No actual rendering is done, however correct kerning is done to get the actual
width. The height returned in h is the same as you can get using getFontHeight
.
Calculate the resulting surface size of the UTF8 encoded text rendered using font.
No actual rendering is done, however correct kerning is done to get the actual width.
The height returned in h is the same as you can get using getFontHeight
.
Calculate the resulting surface size of the UNICODE encoded text rendered using font.
No actual rendering is done, however correct kerning is done to get the actual width.
The height returned in h is the same as you can get using getFontHeight
.
:: TTFFont | Font |
-> String | The LATIN1 null terminated string to render. |
-> Color | The color to render the text in. Colormap index 1. |
-> IO (Ptr Surface) | Pointer to a new SDL_Surface. NULL is returned on errors. |
Render the LATIN1 encoded text, using the Solid mode
Render the LATIN1 encoded text using font with fg color onto a new surface, using the Solid mode.
The caller (you!) is responsible for freeing any returned surface.
:: TTFFont | Font |
-> String | The LATIN1 null terminated string to render. |
-> Color | The color to render the text in. Colormap index 1. |
-> Color | The color to render the background box in. Colormap index 0. |
-> IO (Ptr Surface) | Pointer to a new SDL_Surface. NULL is returned on errors. |
Render the LATIN1 encoded text, using the Shaded mode
Render the LATIN1 encoded text using font with fg color onto a new surface, using the Shaded mode.
The caller (you!) is responsible for freeing any returned surface.
:: TTFFont | Font |
-> String | The LATIN1 null terminated string to render. |
-> Color | The color to render the text in. Colormap index 1. |
-> IO (Ptr Surface) | Pointer to a new SDL_Surface. NULL is returned on errors. |
Render the LATIN1 encoded text, using the Blended mode
Render the LATIN1 encoded text using font with fg color onto a new surface, using the Blended mode.
The caller (you!) is responsible for freeing any returned surface.
:: TTFFont | Font |
-> String | The UTF8 null terminated string to render. |
-> Color | The color to render the text in. Colormap index 1. |
-> IO (Ptr Surface) | Pointer to a new SDL_Surface. NULL is returned on errors. |
Render the UTF8 encoded text, using the Solid mode
Render the UTF8 encoded text using font with fg color onto a new surface, using the Solid mode.
The caller (you!) is responsible for freeing any returned surface.
:: TTFFont | Font |
-> String | The UTF8 null terminated string to render. |
-> Color | The color to render the text in. Colormap index 1. |
-> Color | The color to render the background box in. Colormap index 0. |
-> IO (Ptr Surface) | Pointer to a new SDL_Surface. NULL is returned on errors. |
Render the UTF8 encoded text, using the Shaded mode
Render the UTF8 encoded text using font with fg color onto a new surface, using the Shaded mode.
The caller (you!) is responsible for freeing any returned surface.
:: TTFFont | Font |
-> String | The UTF8 null terminated string to render. |
-> Color | The color to render the text in. Colormap index 1. |
-> IO (Ptr Surface) | Pointer to a new SDL_Surface. NULL is returned on errors. |
Render the UTF8 encoded text, using the Blended mode
Render the UTF8 encoded text using font with fg color onto a new surface, using the Blended mode.
The caller (you!) is responsible for freeing any returned surface.