kb-text-shape-0.3.0.0: src/KB/Text/Shape.hs
module KB.Text.Shape
( -- * The slow part
withContext
, Context(..)
, createContext
, createContextWith
, destroyContext
, ShapeException(..)
-- ** Adding fonts
-- $stack
, Handles.Font
, pushFontFromFile
, pushFontFromMemory
, pushFont
, pushFontVariations
, popFont
, withFontVariations
-- * Turning texts into glyphs
, run
, Run(..)
, Glyph(..)
, gpos
, GPOS(..)
-- ** Feeding input
, Handles.ShapeContext
, text_
, char_
, withFont_
, withFontVariations_
, Structs.Variation(..)
, Enums.fourcc
-- $features
, withFeature_
, pushFeature_
, popFeature_
-- * Internals
, stripGlyph
, iterateGlyphs
) where
import Control.Monad
import Data.IORef
import Foreign hiding (void)
import Foreign.C
import Prelude hiding (id)
import Control.Exception (Exception, bracket, bracket_, throwIO)
import Data.ByteString (ByteString)
import Data.ByteString.Unsafe qualified as ByteString
import Data.Char (chr, ord)
import Data.IntMap (IntMap)
import Data.IntMap.Strict qualified as IntMap
import Data.Text (Text)
import Data.Text.Foreign qualified as Text
import GHC.Records (HasField(..))
import KB.Text.Shape.FFI.API.Context qualified as ShapeContext
import KB.Text.Shape.Font qualified as Font
import KB.Text.Shape.FFI.Enums qualified as Enums
import KB.Text.Shape.FFI.Flags qualified as Flags
import KB.Text.Shape.FFI.Handles qualified as Handles
import KB.Text.Shape.FFI.Iterators qualified as Iterators
import KB.Text.Shape.FFI.Structs qualified as Structs
withContext :: (Context -> IO r) -> IO r
withContext = bracket createContext destroyContext
data Context = Context
{ handle :: Handles.ShapeContext
, fonts :: IORef (IntMap ByteStringRC)
}
data ByteStringRC = ByteStringRC ByteString Int
createContext :: IO Context
createContext = createContextWith mempty
-- | Create a context with 'Flags.ShapeContextFlags' set.
createContextWith :: Flags.ShapeContextFlags -> IO Context
createContextWith flags = do
handle <- ShapeContext.kbts_CreateShapeContext2 nullFunPtr nullPtr flags
when (handle == Handles.ShapeContext nullPtr) $
-- XXX: assuming the default allocator didn't allocate anything yet
throwIO $ ContextError "kbts_CreateShapeContext2" Enums.SHAPE_ERROR_OUT_OF_MEMORY
fonts <- newIORef mempty
pure Context{handle, fonts}
destroyContext :: Context -> IO ()
destroyContext Context{handle} = ShapeContext.kbts_DestroyShapeContext handle
{- | Failures reported while loading fonts and shaping.
The first field names the call that failed.
-}
data ShapeException
= ContextError String Enums.ShapeError
-- ^ The context failed for good. Every later call on it does nothing. Create a new context.
| FontError String String
-- ^ A font was rejected, for the given reason. The context is still usable.
deriving (Show)
instance Exception ShapeException
{- $stack
The context is capable of managing multiple fonts through a font stack.
The font stack will hold references to all fonts in use by the context. Whenever
you try to shape some text, the context will check to see if it is supported by
the font at the top of the stack. If it is not, it will try the next font down,
and so on, until all fonts have been tried. As such, you should push your fallback
fonts first, and your preferred fonts last. 'createContextWith' and
'Flags.SHAPE_CONTEXT_FLAG_FONT_PRIORITY_BOTTOM_TO_TOP' reverse that order.
The stack grows as needed.
-}
{- | Load a font file and push it.
Throws 'FontError' when the font does not load or has unusable metrics.
Throws 'ContextError' when the context fails.
-}
pushFontFromFile :: Context -> FilePath -> Int -> IO Handles.Font
pushFontFromFile ctx path fontIndex = do
font <- withCString path \pathPtr ->
ShapeContext.kbts_ShapePushFontFromFile ctx.handle pathPtr (fromIntegral fontIndex)
throwContextError origin ctx.handle
validateFont ctx origin font
_ <- keepFont ctx font mempty -- register the empty blob so the counters would look nicer
pure font
where
origin = "kbts_ShapePushFontFromFile: " <> path
{- | Reject fonts that failed to load or whose metrics would poison layout downstream.
The loader hands back a null handle without setting the shape error when the
file is missing, unreadable, or not a font.
A zero 'KB.Text.Shape.Font.Info.unitsPerEm' means the font did not parse.
A missing capital height (OS/2 @sCapHeight@) breaks cap-normalized sizing
with no sensible fallback.
A rejected font that made it onto the stack gets popped again.
-}
validateFont :: Context -> String -> Handles.Font -> IO ()
validateFont ctx origin font
| font == Handles.Font nullPtr = throwIO $ FontError origin "failed to load font"
| otherwise = do
info <- Font.getFontInfo font
forM_ (rejection info) \reason -> do
_ <- ShapeContext.kbts_ShapePopFont ctx.handle
throwIO $ FontError origin reason
where
rejection info
| info.unitsPerEm == 0 = Just "font reports zero unitsPerEm"
| info.capitalHeight <= 0 = Just "font has no capital height (OS/2 sCapHeight)"
| otherwise = Nothing
{- | Load a font from memory and push it.
Throws like 'pushFontFromFile'.
-}
pushFontFromMemory :: Context -> ByteString -> Int -> IO Handles.Font
pushFontFromMemory ctx fontData fontIndex =
ByteString.unsafeUseAsCStringLen fontData \(memoryPtr, memorySize) -> do
font <- ShapeContext.kbts_ShapePushFontFromMemory ctx.handle (castPtr memoryPtr) (fromIntegral memorySize) (fromIntegral fontIndex)
throwContextError origin ctx.handle
validateFont ctx origin font
_ <- keepFont ctx font fontData
pure font
where
origin = "kbts_ShapePushFontFromMemory"
keepFont :: Context -> Handles.Font -> ByteString -> IO Int
keepFont ctx font bytes = atomicModifyIORef' ctx.fonts $ swap . IntMap.alterF addRef (Handles.intHandle font)
where
swap (a, b) = (b, a)
addRef :: Maybe ByteStringRC -> (Int, Maybe ByteStringRC)
addRef = \case
Nothing -> (1, Just $ ByteStringRC bytes 1)
Just (ByteStringRC oldBytes oldC) -> (newC, Just $ ByteStringRC oldBytes newC)
where
newC = oldC + 1
releaseFont :: Context -> Handles.Font -> IO Int
releaseFont ctx font = atomicModifyIORef' ctx.fonts $ swap . IntMap.alterF delRef (Handles.intHandle font)
where
swap (a, b) = (b, a)
delRef :: Maybe ByteStringRC -> (Int, Maybe ByteStringRC)
delRef = \case
Nothing -> (-1, Nothing)
Just (ByteStringRC _old 1) -> (0, Nothing)
Just (ByteStringRC stillUsed oldC) -> (newC, Just $ ByteStringRC stillUsed newC)
where newC = oldC - 1
{- | Push an already loaded font and count its use.
Throws 'FontError' when the font has no blob, leaving the stack as it was.
Throws 'ContextError' when the context fails.
-}
pushFont :: Context -> Handles.Font -> IO Int
pushFont ctx font = pushFontVariations ctx font []
{- | Push an already loaded variable font, set to the given axis values, and count its use.
Build tags with 'Enums.fourcc', e.g. @Variation (fourcc \'w\' \'g\' \'h\' \'t\') 700@.
Axes left out take their default values.
An axis listed more than once takes its last value.
Throws like 'pushFont'.
-}
pushFontVariations :: Context -> Handles.Font -> [Structs.Variation] -> IO Int
pushFontVariations ctx font variations = do
pushContextFont ctx.handle font variations
keepFont ctx font mempty
{- | Run an action with a font on top of the stack, set to the given axis values.
Wrap 'run' with it to shape the whole run in that font:
> withFontVariations ctx font [Variation (fourcc 'w' 'g' 'h' 't') 700] $
> run ctx (text_ "Bold")
Unlike 'withFont_', the font is in place before the input starts and stays until the run ends.
The font comes off the stack even when the action throws.
The pop does not throw, so a 'ContextError' from the action comes through unchanged.
-}
withFontVariations :: Context -> Handles.Font -> [Structs.Variation] -> IO r -> IO r
withFontVariations ctx font variations =
bracket_ (pushFontVariations ctx font variations) dropFont
where
dropFont = do
_ <- ShapeContext.kbts_ShapePopFont ctx.handle
void $ releaseFont ctx font
{- | Pop the top font and drop one use of it.
A failed context pops nothing and throws 'ContextError'.
-}
popFont :: Context -> IO (Int, Handles.Font)
popFont ctx = do
font <- ShapeContext.kbts_ShapePopFont ctx.handle
throwContextError "kbts_ShapePopFont" ctx.handle
kept <- releaseFont ctx font
pure (kept, font)
pushContextFont :: Handles.ShapeContext -> Handles.Font -> [Structs.Variation] -> IO ()
pushContextFont handle font variations =
withArrayLen lastValuePerAxis \variationCount variationsPtr ->
alloca \contextFontPtr -> do
_ <- ShapeContext.kbts_ShapePushFont2 handle font variationsPtr (fromIntegral variationCount) contextFontPtr
peek contextFontPtr >>= \case
Handles.CONTEXT_FONT_HANDLE_INVALID -> do
throwContextError origin handle
throwIO $ FontError origin "the font has no blob"
_pushed ->
pure ()
where
origin = "kbts_ShapePushFont2"
lastValuePerAxis =
IntMap.elems $ IntMap.fromList [(fromIntegral variation.tag, variation) | variation <- variations]
throwContextError :: String -> Handles.ShapeContext -> IO ()
throwContextError origin handle =
ShapeContext.kbts_ShapeError handle >>= \case
Enums.SHAPE_ERROR_NONE -> pure ()
err -> throwIO $ ContextError origin err
{- | Run the segmentation and shaping.
NB: Make sure you did load some fonts and text data!
Add content with 'text_' and 'char_', which you may wrap in feature tag sections.
Throws 'ContextError' when the context fails, e.g. out of memory or 'Enums.SHAPE_ERROR_GENERATED_TOO_MANY_GLYPHS'.
The context stays failed after that.
-}
run :: Context -> ((?shapeContext :: Handles.ShapeContext) => IO ()) -> IO [(Run, [Glyph])]
run ctx action = do
ShapeContext.kbts_ShapeBegin ctx.handle Enums.DIRECTION_DONT_KNOW Enums.LANGUAGE_DONT_KNOW
shapeAction
ShapeContext.kbts_ShapeEnd ctx.handle
runs <- iterateRun ctx
throwContextError "kbts_ShapeRun" ctx.handle
pure runs
where
shapeAction = let ?shapeContext = ctx.handle in action
-- | Add one codepoint to the shaping run.
char_ :: (?shapeContext :: Handles.ShapeContext) => Char -> IO ()
char_ c = ShapeContext.kbts_ShapeCodepoint ?shapeContext (fromIntegral (ord c))
{- | Add a chunk of text to the shaping run.
This will not add extra characters like newlines or whitespace.
You may want to call this multiple times instead of concatentating everything.
-}
text_ :: (?shapeContext :: Handles.ShapeContext) => Text -> IO ()
text_ t =
Text.withCStringLen t \(strPtr, strLen) ->
ShapeContext.kbts_ShapeUtf8
?shapeContext
strPtr
(fromIntegral strLen)
Enums.USER_ID_GENERATION_MODE_CODEPOINT_INDEX
{- | Run a section with extra fonts on the stack.
The text added here will first consider the new font.
This may be used to implement text styles by pushing bold/italic variants.
NB: the shaper samples the font stack when it resolves text breaks, which
trails the fed codepoints. A font pushed mid-input takes effect a segment
or so /before/ the section, shifting the styled range. Feed a text with
break opportunities (e.g. spaces) around the section edges to contain it.
The last breaks resolve only when the run ends, after the section has popped its font.
A section at the end of the input thus shapes its tail in the font below it.
A short section can lose its font entirely.
To shape a whole run in one font, wrap 'run' in 'withFontVariations' instead.
The font comes off the stack even when the section throws.
Throws 'FontError' when the font has no blob, leaving the stack as it was.
-}
withFont_ :: (?shapeContext :: Handles.ShapeContext) => Handles.Font -> IO r -> IO r
withFont_ font = withFontVariations_ font []
{- | Run a section with a variable font on the stack, set to the given axis values.
Build tags with 'Enums.fourcc', e.g. @Variation (fourcc \'w\' \'g\' \'h\' \'t\') 700@.
Axes left out take their default values.
An axis listed more than once takes its last value.
An empty list is the same as 'withFont_', which has the same caveats.
-}
withFontVariations_ :: (?shapeContext :: Handles.ShapeContext) => Handles.Font -> [Structs.Variation] -> IO r -> IO r
withFontVariations_ font variations =
bracket_
(pushContextFont ?shapeContext font variations)
(ShapeContext.kbts_ShapePopFont ?shapeContext)
{- $features
The context has a feature stack that allows you to manipulate font features hierarchically.
When you give text to the context, it will apply all feature overrides that are on the
stack at the time.
If two feature overrides use the same tag, then only the latest one, i.e. the one higher
in the stack, is applied.
-}
{- | Run a section with a feature override on the stack.
The context keeps its feature stack across runs.
The override comes off the stack even when the section throws.
-}
withFeature_ :: (?shapeContext :: Handles.ShapeContext) => Enums.FeatureTag -> Int -> IO r -> IO r
withFeature_ tag value = bracket_ (pushFeature_ tag value) (popFeature_ tag)
pushFeature_ :: (?shapeContext :: Handles.ShapeContext) => Enums.FeatureTag -> Int -> IO ()
pushFeature_ tag value = ShapeContext.kbts_ShapePushFeature ?shapeContext tag (fromIntegral value)
{- | Remove the latest override with the tag.
Reports whether an override was found and removed.
-}
popFeature_ :: (?shapeContext :: Handles.ShapeContext) => Enums.FeatureTag -> IO Int
popFeature_ tag = fromIntegral <$> ShapeContext.kbts_ShapePopFeature ?shapeContext tag
{- | Text runs with uniform direction and script.
The result of a text segmentation work.
-}
data Run = Run
{ font :: Handles.Font
, script :: Enums.Script
, paragraphDirection :: Enums.Direction
, direction :: Enums.Direction
, flags :: Flags.BreakFlags
} deriving (Eq, Show)
iterateRun :: Context -> IO [(Run, [Glyph])]
iterateRun ctx =
alloca \runPtr ->
alloca \glyphOutPtr ->
stepWhile (step runPtr) (collect runPtr glyphOutPtr)
where
step runPtr = (/= 0) <$> ShapeContext.kbts_ShapeRun ctx.handle runPtr
collect runPtr glyphOutPtr = do
Structs.Run{..} <- peek runPtr
(Run{..},) <$> iterateGlyphs glyphOutPtr (Structs.runGlyphIterator runPtr)
-- | Drain a glyph iterator, e.g. the 'Structs.GlyphIterator' filled by @kbts_ShapeDirect@.
iterateGlyphs :: Ptr (Ptr Structs.Glyph) -> Ptr Structs.GlyphIterator -> IO [Glyph]
iterateGlyphs glyphOutPtr it = stepWhile step fetch
where
step = (/= 0) <$> Iterators.kbts_GlyphIteratorNext it glyphOutPtr
fetch = do
peek glyphOutPtr >>= peek >>= stripGlyph
stepWhile :: Monad m => m Bool -> m a -> m [a]
stepWhile step fetch = do
result <- step
if result then do
x <- fetch
(x :) <$> stepWhile step fetch
else
pure []
{- | Glyphs ready to rasterize.
The result of a text shaping work.
-}
data Glyph = Glyph
{ -- omitted: prev :: Ptr Glyph
-- omitted: next :: Ptr Glyph
codepoint :: Char -- was: Word32
, id :: Word16 -- ^ Glyph index. This is what you want to use to query outline data.
, uid :: Word16
, codepointIndex :: Int -- was: userIdOrCodepointIndex
{- ^ Index of the source codepoint this glyph maps to, in codepoints,
relative to the whole shaped input (not the run). Several glyphs may
share an index (marks), and a ligature carries the index of its first
codepoint, leaving the rest without glyphs.
-}
, offsetX :: Int
{- ^ This, and the next few are in the "font units".
Those have to be scaled appropriately using font metrics.
To get the consistent results when using multiple fonts divide by 'KB.Text.Shape.Font.capHeight',
then scale to the desired height.
-}
, offsetY :: Int
, advanceX :: Int
, advanceY :: Int
, attachGlyph :: Maybe Glyph -- was: Ptr Glyph
-- omitted: config :: Ptr () -- kbts_glyph_config *Config;
, classes :: Word32 -- kbts_glyph_classes Classes;
, flags :: Flags.GlyphFlags
-- omitted: parentInfo :: Word32
-- omitted: ligatureUid :: Word16
-- omitted: ligatureComponentIndexPlusOne :: Word16
-- omitted: ligatureComponentCount :: Word16
-- omitted: joiningFeature :: Word8 -- kbts_joining_feature JoiningFeature;
-- Unicode properties filled in by CodepointToGlyph.
, joiningType :: Enums.UnicodeJoiningType
, unicodeFlags :: Word8
, syllabicClass :: Word8
, syllabicPosition :: Word8
, useClass :: Word8
, combiningClass :: Word8
}
deriving (Eq, Show)
instance HasField "gpos" Glyph (GPOS Int) where
{-# INLINE getField #-}
getField = gpos
-- | Extract glyph positioning information.
{-# INLINE gpos #-}
gpos :: Glyph -> GPOS Int
gpos Glyph{offsetX, offsetY, advanceX, advanceY} = GPOS{offsetX, offsetY, advanceX, advanceY}
{- | A container for glyph positioning information.
You may want to use its Functor instance to convert between different units.
-}
data GPOS a = GPOS
{ offsetX, offsetY, advanceX, advanceY :: a
}
deriving (Eq, Show, Functor)
-- | Remove the internals and pointer data
stripGlyph :: Structs.Glyph -> IO Glyph
stripGlyph Structs.Glyph{..} = do
attached <-
if attachGlyph == nullPtr then
pure Nothing
else
Just <$> (peek attachGlyph >>= stripGlyph)
pure Glyph
{ codepoint = chr (fromIntegral codepoint)
, codepointIndex = userIdOrCodepointIndex -- XXX: always codepoint when using context api
, attachGlyph = attached
, offsetX = fromIntegral offsetX
, offsetY = fromIntegral offsetY
, advanceX = fromIntegral advanceX
, advanceY = fromIntegral advanceY
, ..
}