Graphics.Rendering.TrueType.STB

This is a wrapper around Sean Barrett's TrueType font rasterizer code. The original can be found at http://nothings.org/stb/stb_truetype.h. The version of stb-truetype used here is v1.19.

This is a very low-level library; if you just want to render text using OpenGL, look at the the higher-level library minitypeset-opengl

Note: the glyph coordinate system uses te is the mathematical convention, that is, the Y coordinate increases upwards; unlike the screen and/or bitmap coordinate system, where Y increases downwards.

Documentation

newtype TrueType

A TrueType font file (containing maybe multiple font sets) loaded into memory.

Constructors

TrueType ByteString

data Offset

A font offset inside a TrueType font file.

Instances

Eq Offset

Defined in Graphics.Rendering.TrueType.STB

Methods

(==) :: Offset -> Offset -> Bool

(/=) :: Offset -> Offset -> Bool

Ord Offset

Defined in Graphics.Rendering.TrueType.STB

Methods

compare :: Offset -> Offset -> Ordering

(<) :: Offset -> Offset -> Bool

(<=) :: Offset -> Offset -> Bool

(>) :: Offset -> Offset -> Bool

(>=) :: Offset -> Offset -> Bool

max :: Offset -> Offset -> Offset

min :: Offset -> Offset -> Offset

Show Offset

Defined in Graphics.Rendering.TrueType.STB

Methods

showsPrec :: Int -> Offset -> ShowS

show :: Offset -> String

showList :: [Offset] -> ShowS

data Font

Constructors

Font

Fields

• _fontData :: TrueType
• _fontInfo :: ForeignPtr CFontInfo
• _glyphMap :: UnicodeCache (Maybe Glyph)

data CFontInfo

Instances

Storable CFontInfo

Defined in Graphics.Rendering.TrueType.STB

Methods

sizeOf :: CFontInfo -> Int

alignment :: CFontInfo -> Int

peekElemOff :: Ptr CFontInfo -> Int -> IO CFontInfo

pokeElemOff :: Ptr CFontInfo -> Int -> CFontInfo -> IO ()

peekByteOff :: Ptr b -> Int -> IO CFontInfo

pokeByteOff :: Ptr b -> Int -> CFontInfo -> IO ()

peek :: Ptr CFontInfo -> IO CFontInfo

poke :: Ptr CFontInfo -> CFontInfo -> IO ()

data Glyph

A glyph inside a font.

Instances

Eq Glyph

Defined in Graphics.Rendering.TrueType.STB

Methods

(==) :: Glyph -> Glyph -> Bool

(/=) :: Glyph -> Glyph -> Bool

Ord Glyph

Defined in Graphics.Rendering.TrueType.STB

Methods

compare :: Glyph -> Glyph -> Ordering

(<) :: Glyph -> Glyph -> Bool

(<=) :: Glyph -> Glyph -> Bool

(>) :: Glyph -> Glyph -> Bool

(>=) :: Glyph -> Glyph -> Bool

max :: Glyph -> Glyph -> Glyph

min :: Glyph -> Glyph -> Glyph

Show Glyph

Defined in Graphics.Rendering.TrueType.STB

Methods

showsPrec :: Int -> Glyph -> ShowS

show :: Glyph -> String

showList :: [Glyph] -> ShowS

Initialization

loadTTF :: FilePath -> IO TrueType

withTTF :: FilePath -> (TrueType -> IO a) -> IO a

enumerateFonts :: TrueType -> IO [Offset]

Enumerates the fonts found in a TrueType file. Often there is only one, but there may be more.

initFont :: TrueType -> Offset -> IO Font

findGlyph :: Font -> Char -> IO (Maybe Glyph)

Maps unicode characters to glyphs. As a hack, we map 0xffff (which is not a valid unicode code point) to the "not defined glyph" (glyph #0), which has no character counterpart.

Note: this is cached, so you can call it many times if necessary.

notDefinedGlyphChar :: Char

The character 0xffff (which is not a valid unicode code point) which maps to the "not defined glyph"

Font metrics

type Unscaled = Int

type Scaling = (Float, Float)

data HorizontalMetrics a

Constructors

HMetrics

Fields

• advanceWidth :: !a
• leftSideBearing :: !a

Instances

Functor HorizontalMetrics

Defined in Graphics.Rendering.TrueType.STB

Methods

fmap :: (a -> b) -> HorizontalMetrics a -> HorizontalMetrics b

(<$) :: a -> HorizontalMetrics b -> HorizontalMetrics a

Show a => Show (HorizontalMetrics a)

Defined in Graphics.Rendering.TrueType.STB

Methods

showsPrec :: Int -> HorizontalMetrics a -> ShowS

show :: HorizontalMetrics a -> String

showList :: [HorizontalMetrics a] -> ShowS

data VerticalMetrics a

ascent is the coordinate above the baseline the font extends; descent is the coordinate below the baseline the font extends (i.e. it is typically negative) lineGap is the spacing between one row's descent and the next row's ascent... so you should advance the vertical position by ascent - descent + lineGap

Constructors

VMetrics

Fields

• ascent :: !a
• descent :: !a
• lineGap :: !a

Instances

Functor VerticalMetrics

Defined in Graphics.Rendering.TrueType.STB

Methods

fmap :: (a -> b) -> VerticalMetrics a -> VerticalMetrics b

(<$) :: a -> VerticalMetrics b -> VerticalMetrics a

Show a => Show (VerticalMetrics a)

Defined in Graphics.Rendering.TrueType.STB

Methods

showsPrec :: Int -> VerticalMetrics a -> ShowS

show :: VerticalMetrics a -> String

showList :: [VerticalMetrics a] -> ShowS

data BoundingBox a

The convention is BBox (x0,y0) (x1,y1).

Constructors

BBox (a, a) (a, a)

Instances

Show a => Show (BoundingBox a)

Defined in Graphics.Rendering.TrueType.STB

Methods

showsPrec :: Int -> BoundingBox a -> ShowS

show :: BoundingBox a -> String

showList :: [BoundingBox a] -> ShowS

lineAdvance :: Num a => VerticalMetrics a -> a

As calculated by (ascent - descent + lineGap).

verticalSize :: Num a => VerticalMetrics a -> a

As calculated by (ascent - descent).

scaleForPixelHeight :: VerticalMetrics Unscaled -> Float -> Float

getFontVerticalMetrics :: Font -> IO (VerticalMetrics Unscaled)

getGlyphHorizontalMetrics :: Font -> Glyph -> IO (HorizontalMetrics Unscaled)

getGlyphKernAdvance :: Font -> Glyph -> Glyph -> IO Unscaled

An additional amount to add to the 'advance' value between two glyphs

getGlyphBoundingBox :: Font -> Glyph -> IO (Maybe (BoundingBox Unscaled))

Bitmaps

data Bitmap

A 8-bit grayscale bitmap.

Constructors

Bitmap

Fields

• bitmapSize :: !(Int, Int)
• bitmapPtr :: !(ForeignPtr Word8)

newBitmap :: (Int, Int) -> IO Bitmap

withBitmap :: Bitmap -> (Int -> Int -> Ptr Word8 -> IO a) -> IO a

flipBitmap :: Bitmap -> IO Bitmap

Flips the bitmap vertically (leaving the original unchanged)

type BitmapOfs = (Int, Int)

An offset (for example the pivot of the glyph)

bitmapArray :: Bitmap -> IO (UArray (Int, Int) Word8)

NOTE: because of the way Haskell indexes rectangular arrays, the resulting array is indexed with (y,x), as opposed to what you would expect.

bitmapFloatArray :: Bitmap -> IO (UArray (Int, Int) Float)

Vanilla (non-subpixel) rendering

getGlyphBitmapBox :: Font -> Glyph -> Scaling -> IO (BoundingBox Int)

Returns the size of the bitmap (in pixels) needed to render the glyph with the given scaling.

The box is centered around the glyph origin; so the bitmap width is x1-x0, height is y1-y0, and location to place the bitmap top left is (leftSideBearing*scale,y0). Note that the bitmap uses y-increases-down, but the shape uses y-increases-up, so the results of getGlyphBitmapBox and getGlyphBoundingBox are inverted.

newGlyphBitmap :: Font -> Glyph -> Scaling -> IO (Bitmap, BitmapOfs)

Creates a new bitmap just enough to fit the glyph with the given scaling, and renders the glyph into it. The offset returned is the offset in pixel space from the glyph origin to the top-left of the bitmap (so it's almost always negative).

renderGlyphIntoBitmap' :: Font -> Glyph -> Scaling -> Bitmap -> BitmapOfs -> IO ()

The offset is the top-left corner of the bounding box of the glyph, and must be nonnegative (otherwise nothing will happen).

renderGlyphIntoBitmap :: Font -> Glyph -> Scaling -> Bitmap -> BitmapOfs -> IO ()

The offset is the origin of the glyph. If the glyph extends from the bitmap in the positive direction, it is clipped; however, if it extends in the negative direction, no drawing will happen!

Subpixel rendering

type SubpixelShift = (Float, Float)

The subpixel version of the rendering functions accept an additional fractional shift

getGlyphBitmapBoxSubpixel :: Font -> Glyph -> Scaling -> SubpixelShift -> IO (BoundingBox Int)

Returns the size of the bitmap (in pixels) needed to render the glyph with the given scaling.

The box is centered around the glyph origin; so the bitmap width is x1-x0, height is y1-y0, and location to place the bitmap top left is (leftSideBearing*scale,y0). Note that the bitmap uses y-increases-down, but the shape uses y-increases-up, so the results of getGlyphBitmapBox and getGlyphBoundingBox are inverted.

newGlyphBitmapSubpixel :: Font -> Glyph -> Scaling -> SubpixelShift -> IO (Bitmap, BitmapOfs)

Creates a new bitmap just enough to fit the glyph with the given scaling, and renders the glyph into it. The offset returned is the offset in pixel space from the glyph origin to the top-left of the bitmap (so it's almost always negative).

renderGlyphIntoBitmapSubpixel' :: Font -> Glyph -> Scaling -> SubpixelShift -> Bitmap -> BitmapOfs -> IO ()

The offset is the top-left corner of the bounding box of the glyph, and must be nonnegative (otherwise nothing will happen).

renderGlyphIntoBitmapSubpixel :: Font -> Glyph -> Scaling -> SubpixelShift -> Bitmap -> BitmapOfs -> IO ()

The offset is the origin of the glyph. If the glyph extends from the bitmap in the positive direction, it is clipped; however, if it extends in the negative direction, no drawing will happen!

Cached glyph storage

data CachedBitmap

Note: the metrics are scaled!

Constructors

CBM !Glyph !Bitmap !BitmapOfs !(HorizontalMetrics Float)

data BitmapCache

A "bitmap cache".

Constructors

BMCache

Fields

• bmc_fontinfo :: !Font
• bmc_scaling :: !(Float, Float)
• bmc_cache :: !(UnicodeCache (Maybe CachedBitmap))
• bmc_vmetrics :: !(VerticalMetrics Float)
• bmc_flipped :: !Bool

bmcVerticalMetrics :: BitmapCache -> VerticalMetrics Float

Note: these metrics are scaled!

bmcScaling :: BitmapCache -> Scaling

newBitmapCache :: Font -> Bool -> (Float, Float) -> IO BitmapCache

Creates a new cache where glyph bitmaps with the given scaling will be stored. The second argument is whether the resulting bitmaps should be flipped vertically or not (this is useful with OpenGL).

getCachedBitmap :: BitmapCache -> Char -> IO (Maybe CachedBitmap)

Fetches a rendered glyph bitmap from the cache (rendering it first if it was not present in the cache before).

Unicode tables

data UnicodeCache a

A table indexed by unicode code points.

Organized into small continous blocks (say 128 characters) so lookup should be pretty fast

newUnicodeCache :: IO (UnicodeCache a)

lookupUnicodeCache :: Char -> (Char -> IO a) -> UnicodeCache a -> IO a