Copyright	(c) 2015 Siniša Biđin
License	MIT
Stability	experimental
Safe Haskell	None
Language	Haskell2010

SDL.Font

Contents

General
Loading
Rendering
Attributes
Glyphs

Description

Bindings to the SDL2_ttf library http://www.libsdl.org/projects/SDL_ttf/docs/SDL_ttf.html which itself is a wrapper around the FreeType library. The bindings should allow you to load fonts and render Text in various styles to an SDL Surface.

You can safely assume that any monadic function listed here is capable of throwing an SDLException in case it encounters an error.

Synopsis

initialize :: MonadIO m => m ()
version :: (Integral a, MonadIO m) => m (a, a, a)
quit :: MonadIO m => m ()
newtype Font = Font {
- unwrap :: Ptr Font
}
type PointSize = Int
load :: MonadIO m => FilePath -> PointSize -> m Font
type Index = Int
loadIndex :: MonadIO m => FilePath -> PointSize -> Index -> m Font
decode :: MonadIO m => ByteString -> PointSize -> m Font
decodeIndex :: MonadIO m => ByteString -> PointSize -> Index -> m Font
free :: MonadIO m => Font -> m ()
type Color = V4 Word8
solid :: MonadIO m => Font -> Color -> Text -> m Surface
shaded :: MonadIO m => Font -> Color -> Color -> Text -> m Surface
blended :: MonadIO m => Font -> Color -> Text -> m Surface
size :: MonadIO m => Font -> Text -> m (Int, Int)
data Style
- = Bold
- | Italic
- | Underline
- | Strikethrough
getStyle :: MonadIO m => Font -> m [Style]
setStyle :: MonadIO m => Font -> [Style] -> m ()
type Outline = Int
getOutline :: MonadIO m => Font -> m Outline
setOutline :: MonadIO m => Font -> Outline -> m ()
data Hinting
- = Normal
- | Light
- | Mono
- | None
getHinting :: MonadIO m => Font -> m Hinting
setHinting :: MonadIO m => Font -> Hinting -> m ()
type Kerning = Bool
getKerning :: MonadIO m => Font -> m Kerning
setKerning :: MonadIO m => Font -> Kerning -> m ()
isMonospace :: MonadIO m => Font -> m Bool
familyName :: MonadIO m => Font -> m (Maybe Text)
styleName :: MonadIO m => Font -> m (Maybe Text)
height :: MonadIO m => Font -> m Int
ascent :: MonadIO m => Font -> m Int
descent :: MonadIO m => Font -> m Int
lineSkip :: MonadIO m => Font -> m Int
getKerningSize :: MonadIO m => Font -> Index -> Index -> m Int
glyphProvided :: MonadIO m => Font -> Char -> m Bool
glyphIndex :: MonadIO m => Font -> Char -> m (Maybe Int)
glyphMetrics :: MonadIO m => Font -> Char -> m (Maybe (Int, Int, Int, Int, Int))
solidGlyph :: MonadIO m => Font -> Color -> Char -> m Surface
shadedGlyph :: MonadIO m => Font -> Color -> Color -> Char -> m Surface
blendedGlyph :: MonadIO m => Font -> Color -> Char -> m Surface
blendedWrapped :: MonadIO m => Font -> Color -> Int -> Text -> m Surface

General

initialize :: MonadIO m => m () #

Initializes the library.

Unless noted otherwise, this must be called before any other part of the library is used.

You may call this multiple times.

version :: (Integral a, MonadIO m) => m (a, a, a) #

Gets the major, minor, patch versions of the linked SDL2_ttf library.

You may call this without initializing the library with initialize.

quit :: MonadIO m => m () #

Cleans up any resources still in use by the library.

If called, you must call initialize again before using any other parts of the library.

Loading

Use the following functions to load TTF and FON file formats.

newtype Font #

Represents a loaded font.

Constructors

Font
Fields unwrap :: Ptr Font

Instances

Eq Font #
Instance details Defined in SDL.Font Methods (==) :: Font -> Font -> Bool # (/=) :: Font -> Font -> Bool #
Show Font #
Instance details Defined in SDL.Font Methods showsPrec :: Int -> Font -> ShowS # show :: Font -> String # showList :: [Font] -> ShowS #

type PointSize = Int #

Point size (based on 72DPI) to load font as. Translates to pixel height.

load :: MonadIO m => FilePath -> PointSize -> m Font #

Given a path to a font file, loads it for use as a Font at a certain PointSize.

type Index = Int #

Designates a font face, the default and first one being 0.

loadIndex :: MonadIO m => FilePath -> PointSize -> Index -> m Font #

Given a path to a font file, loads one of its font faces (designated by the given index) for use as a Font at a certain PointSize.

The first face is always index 0, and is the one chosen by default when using load.

decode :: MonadIO m => ByteString -> PointSize -> m Font #

Same as load, but accepts a ByteString containing a font instead.

decodeIndex :: MonadIO m => ByteString -> PointSize -> Index -> m Font #

Same as loadIndex, but accepts a ByteString containing a font instead.

free :: MonadIO m => Font -> m () #

Frees a loaded Font.

Rendering

Use the following functions to render text to a Surface.

The methods available are described in more detail in the original SDL2_ttf documentation here.

type Color = V4 Word8 #

Color as an RGBA byte vector.

solid :: MonadIO m => Font -> Color -> Text -> m Surface #

Renders Text using the quick and dirty method.

Is the fastest of the rendering methods, but results in text that isn't as smooth.

shaded :: MonadIO m => Font -> Color -> Color -> Text -> m Surface #

Uses the slow and nice, but with a solid box method.

Renders slower than solid, but in about the same time as blended.

Results in a Surface containing antialiased text of a foreground color surrounded by a box of a background color. This Surface will blit as fast as the one from solid.

blended :: MonadIO m => Font -> Color -> Text -> m Surface #

The slow slow slow, but ultra nice over another image method, blended renders text at high quality.

The text is antialiased and surrounded by a transparent box. Renders slower than solid, but in about the same time as shaded.

The resulting Surface will blit slower than the ones from solid or shaded.

size :: MonadIO m => Font -> Text -> m (Int, Int) #

Use this function to discover how wide and tall a Surface needs to be in order to accommodate a given text when it is rendered.

Note that no actual rendering takes place.

The values returned are the width and height, respectively, in pixels. The height returned is the same one returned by height.

Attributes

data Style #

Possible styles that can be applied to a Font.

Constructors

Bold
Italic
Underline
Strikethrough

Instances

Bounded Style #
Instance details Defined in SDL.Font Methods minBound :: Style # maxBound :: Style #
Enum Style #
Instance details Defined in SDL.Font Methods succ :: Style -> Style # pred :: Style -> Style # toEnum :: Int -> Style # fromEnum :: Style -> Int # enumFrom :: Style -> [Style] # enumFromThen :: Style -> Style -> [Style] # enumFromTo :: Style -> Style -> [Style] # enumFromThenTo :: Style -> Style -> Style -> [Style] #
Eq Style #
Instance details Defined in SDL.Font Methods (==) :: Style -> Style -> Bool # (/=) :: Style -> Style -> Bool #
Ord Style #
Instance details Defined in SDL.Font Methods compare :: Style -> Style -> Ordering # (<) :: Style -> Style -> Bool # (<=) :: Style -> Style -> Bool # (>) :: Style -> Style -> Bool # (>=) :: Style -> Style -> Bool # max :: Style -> Style -> Style # min :: Style -> Style -> Style #
Read Style #
Instance details Defined in SDL.Font Methods readsPrec :: Int -> ReadS Style # readList :: ReadS [Style] # readPrec :: ReadPrec Style # readListPrec :: ReadPrec [Style] #
Show Style #
Instance details Defined in SDL.Font Methods showsPrec :: Int -> Style -> ShowS # show :: Style -> String # showList :: [Style] -> ShowS #
Generic Style #
Instance details Defined in SDL.Font Associated Types type Rep Style :: * -> * # Methods from :: Style -> Rep Style x # to :: Rep Style x -> Style #
type Rep Style #
Instance details Defined in SDL.Font type Rep Style = D1 (MetaData "Style" "SDL.Font" "sdl2-ttf-2.1.0-7awVJENalKuJ4uw5dpGH6X" False) ((C1 (MetaCons "Bold" PrefixI False) (U1 :: * -> ) :+: C1 (MetaCons "Italic" PrefixI False) (U1 :: -> )) :+: (C1 (MetaCons "Underline" PrefixI False) (U1 :: -> ) :+: C1 (MetaCons "Strikethrough" PrefixI False) (U1 :: -> *)))

getStyle :: MonadIO m => Font -> m [Style] #

Gets the rendering styles of a given Font.

If none were ever set, this will be an empty list.

setStyle :: MonadIO m => Font -> [Style] -> m () #

Sets the rendering style of a Font.

Use an empty list to reset the style.

type Outline = Int #

The size of the Font outline, in pixels.

Use 0 to turn off outlining.

getOutline :: MonadIO m => Font -> m Outline #

Gets the current outline size of a given Font.

setOutline :: MonadIO m => Font -> Outline -> m () #

Sets the outline size for a given Font.

Use 0 to turn off outlining.

data Hinting #

The hinting setting of a Font.

Constructors

Normal
Light
Mono
None

Instances

Bounded Hinting #
Instance details Defined in SDL.Font Methods minBound :: Hinting # maxBound :: Hinting #
Enum Hinting #
Instance details Defined in SDL.Font Methods succ :: Hinting -> Hinting # pred :: Hinting -> Hinting # toEnum :: Int -> Hinting # fromEnum :: Hinting -> Int # enumFrom :: Hinting -> [Hinting] # enumFromThen :: Hinting -> Hinting -> [Hinting] # enumFromTo :: Hinting -> Hinting -> [Hinting] # enumFromThenTo :: Hinting -> Hinting -> Hinting -> [Hinting] #
Eq Hinting #
Instance details Defined in SDL.Font Methods (==) :: Hinting -> Hinting -> Bool # (/=) :: Hinting -> Hinting -> Bool #
Ord Hinting #
Instance details Defined in SDL.Font Methods compare :: Hinting -> Hinting -> Ordering # (<) :: Hinting -> Hinting -> Bool # (<=) :: Hinting -> Hinting -> Bool # (>) :: Hinting -> Hinting -> Bool # (>=) :: Hinting -> Hinting -> Bool # max :: Hinting -> Hinting -> Hinting # min :: Hinting -> Hinting -> Hinting #
Read Hinting #
Instance details Defined in SDL.Font Methods readsPrec :: Int -> ReadS Hinting # readList :: ReadS [Hinting] # readPrec :: ReadPrec Hinting # readListPrec :: ReadPrec [Hinting] #
Show Hinting #
Instance details Defined in SDL.Font Methods showsPrec :: Int -> Hinting -> ShowS # show :: Hinting -> String # showList :: [Hinting] -> ShowS #
Generic Hinting #
Instance details Defined in SDL.Font Associated Types type Rep Hinting :: * -> * # Methods from :: Hinting -> Rep Hinting x # to :: Rep Hinting x -> Hinting #
type Rep Hinting #
Instance details Defined in SDL.Font type Rep Hinting = D1 (MetaData "Hinting" "SDL.Font" "sdl2-ttf-2.1.0-7awVJENalKuJ4uw5dpGH6X" False) ((C1 (MetaCons "Normal" PrefixI False) (U1 :: * -> ) :+: C1 (MetaCons "Light" PrefixI False) (U1 :: -> )) :+: (C1 (MetaCons "Mono" PrefixI False) (U1 :: -> ) :+: C1 (MetaCons "None" PrefixI False) (U1 :: -> *)))

getHinting :: MonadIO m => Font -> m Hinting #

Gets the hinting setting of a given Font.

setHinting :: MonadIO m => Font -> Hinting -> m () #

Sets the hinting setting of a font.

type Kerning = Bool #

Whether kerning is enabled or not.

The default for a newly-loaded Font is enabled.

getKerning :: MonadIO m => Font -> m Kerning #

Gets the current kerning setting of a given Font.

setKerning :: MonadIO m => Font -> Kerning -> m () #

Sets the kerning setting for a given Font.

Use False to turn off kerning.

isMonospace :: MonadIO m => Font -> m Bool #

Tests whether the current face of a Font is a fixed width font or not.

familyName :: MonadIO m => Font -> m (Maybe Text) #

Gets the current font face family name, if any.

styleName :: MonadIO m => Font -> m (Maybe Text) #

Gets the current font face style name, if any.

height :: MonadIO m => Font -> m Int #

Gets the maximum pixel height of all glyphs of a given Font.

ascent :: MonadIO m => Font -> m Int #

Gets the maximum pixel ascent of all glyphs of a given Font.

This can be interpreted as the distance from the top of the font to the baseline.

descent :: MonadIO m => Font -> m Int #

Gets the maximum pixel descent of all glyphs of a given Font.

Also interpreted as the distance from the baseline to the bottom of the font.

lineSkip :: MonadIO m => Font -> m Int #

Gets the recommended pixel height of a rendered line of text of a given Font.

This is usually larger than what height would return.

getKerningSize :: MonadIO m => Font -> Index -> Index -> m Int #

From a given Font get the kerning size of two glyphs.

Glyphs

Functions that work with individual glyphs.

glyphProvided :: MonadIO m => Font -> Char -> m Bool #

Does a Font provide a certain unicode character?

glyphIndex :: MonadIO m => Font -> Char -> m (Maybe Int) #

Same as glyphProvided, but returns an index of the glyph for the given character instead, if one is provided.

glyphMetrics :: MonadIO m => Font -> Char -> m (Maybe (Int, Int, Int, Int, Int)) #

Get glyph metrics for a given unicode character. The values returned are:

minimum x offset
maximum x offset
minimum y offset
maximum y offset
advance offset

You can see more information about these values in the original SDL2_ttf documentation here.

solidGlyph :: MonadIO m => Font -> Color -> Char -> m Surface #

Same as solid, but renders a single glyph instead.

shadedGlyph :: MonadIO m => Font -> Color -> Color -> Char -> m Surface #

Same as shaded, but renders a single glyph instead.

blendedGlyph :: MonadIO m => Font -> Color -> Char -> m Surface #

Same as blended, but renders a single glyph instead.

blendedWrapped :: MonadIO m => Font -> Color -> Int -> Text -> m Surface #

Same as blended, but renders across multiple lines. Text is wrapped to multiple lines on line endings and on word boundaries if it extends beyond wrapLength in pixels.