-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | PCF font parsing and rendering library.
--   
--   pcf-font is a library for parsing and rendering X11 PCF fonts.
@package pcf-font
@version 0.2.2.0


-- | Rendering bitmap text with <b>pcf-font</b> is easy. For instance, a
--   program that renders text into a PNG is trivial:
--   
--   <pre>
--   import Codec.Picture.Png
--   import Codec.Picture.Types
--   import Data.List
--   import Graphics.Text.PCF
--   import System.Environment
--   
--   -- | USAGE: program &lt;font.pcf.gz&gt; &lt;output.png&gt; &lt;text&gt;
--   main :: IO ()
--   main = do
--       [input_file, output_file, text] &lt;- getArgs
--       pcf &lt;- either fail return =&lt;&lt; loadPCF input_file
--       case renderPCFText pcf text of
--           Just (PCFText _ w h img) -&gt;
--               writePng output_file (Image w h img :: Image Pixel8)
--           Nothing -&gt;
--               putStrLn "ERROR: Unable to render input text."
--   </pre>
--   
--   Rendering some text as an ASCII bitmap is also convenient:
--   
--   <pre>
--   import Graphics.Text.PCF
--   import System.Environment
--   
--   -- | USAGE: program &lt;font.pcf.gz&gt; &lt;text&gt;
--   main :: IO ()
--   main = do
--       [font_file, text] &lt;- getArgs
--       pcf &lt;- either fail return =&lt;&lt; loadPCF font_file
--       case renderPCFText pcf text of
--           Just pcf_text -&gt;
--               putStrLn $ pcf_text_ascii pcf_text
--           Nothing -&gt;
--               putStrLn "ERROR: Unable to render input text."
--   </pre>
module Graphics.Text.PCF

-- | Load a PCF font file. Both uncompressed and GZip compressed files are
--   allowed, i.e. ".pcf" and ".pcf.gz" files.
loadPCF :: FilePath -> IO (Either String PCF)

-- | Decode a PCF font from an in-memory <a>ByteString</a>. Uncompressed
--   and GZip compressed input are allowed.
decodePCF :: ByteString -> Either String PCF

-- | Generate a vector of black and white pixels from a PCF font and a
--   string. Black and white pixels are represented by 0x00 and 0xFF byte
--   values respectively.
renderPCFText :: PCF -> String -> Maybe PCFText

-- | Generate a vector of opaque and blank pixels from a PCF font and a
--   string.
renderPCFTextColor :: PCF -> Word8 -> Word8 -> String -> Maybe PCFText

-- | Extract a single glyph bitmap from a PCF font.
getPCFGlyph :: PCF -> Char -> Maybe PCFGlyph

-- | Calculate the color of a pixel in a glyph given its (x,y) coordinates.
getPCFGlyphPixel :: PCFGlyph -> Int -> Int -> Bool

-- | Scan over every pixel in a glyph, constructing some value in the
--   process.
foldPCFGlyphPixels :: PCFGlyph -> (Int -> Int -> Bool -> a -> a) -> a -> a

-- | ASCII rendering of a whole PCFText string rendering.
pcf_text_ascii :: PCFText -> String

-- | Render glyph bitmap as a string where <tt>X</tt> represents opaque
--   pixels and whitespace represents blank pixels.
glyph_ascii :: PCFGlyph -> String

-- | Render glyph bitmap as a list of strings representing lines where
--   <tt>X</tt> represents opaque pixels and whitespace represents blank
--   pixels.
glyph_ascii_lines :: PCFGlyph -> [String]

-- | List key-value pairs found in PCF properties table.
getPCFProps :: PCF -> [(ByteString, Either ByteString Int)]

-- | Container of tables extracted from a PCF font file.
data PCF

-- | Container of a single glyph bitmap and its metadata.
data PCFGlyph
PCFGlyph :: Metrics -> Char -> Int -> Int -> Int -> ByteString -> PCFGlyph
[glyph_metrics] :: PCFGlyph -> Metrics

-- | Unicode character corresponding to glyph
[glyph_char] :: PCFGlyph -> Char

-- | Pixel width of glyph once rendered
[glyph_width] :: PCFGlyph -> Int

-- | Pixel height of glyph once rendered
[glyph_height] :: PCFGlyph -> Int

-- | Number of bytes in each bitmap row
[glyph_pitch] :: PCFGlyph -> Int

-- | <a>glyph_height</a> rows of <a>glyph_pitch</a> bytes containing the
--   glyph's bitmap image starting from the left-most bit and ending at the
--   <a>glyph_width</a> bit in each row
[glyph_bitmap] :: PCFGlyph -> ByteString

-- | Representation of string and its corresponding bitmap content.
--   Metadata regarding source font is not included.
data PCFText
PCFText :: [PCFGlyph] -> Int -> Int -> Vector Word8 -> PCFText

-- | Metadata of each glyph rendered to the image bitmap
[pcf_text_glyphs] :: PCFText -> [PCFGlyph]

-- | Width of the rendered bitmap image
[pcf_text_width] :: PCFText -> Int

-- | Height of the rendered bitmap image
[pcf_text_height] :: PCFText -> Int

-- | Text rendered as a bitmap image where 0 is opaque and 255 is empty in
--   each cell
[pcf_text_image] :: PCFText -> Vector Word8

-- | Container of glyph dimension and position metrics.
data Metrics
Metrics :: Int16 -> Int16 -> Int16 -> Int16 -> Int16 -> Int16 -> Metrics
[metrics_left_sided_bearings] :: Metrics -> Int16
[metrics_right_sided_bearings] :: Metrics -> Int16
[metrics_character_width] :: Metrics -> Int16
[metrics_character_ascent] :: Metrics -> Int16
[metrics_character_descent] :: Metrics -> Int16
[metrics_character_attributes] :: Metrics -> Int16
