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


-- | Portable TrueType font rendering for OpenGL using the Freetype2 library
--   
--   A Haskell binding for the portable TrueType to OpenGL font rendering
--   library FTGL. This package provides OpenGL with polygonal, texture
--   mapped, and extruded fonts using Freetype2 and any truetype font.
@package FTGL
@version 1.0


-- | <ul>
--   <li>Author: Jefferson Heard (jefferson.r.heard at gmail.com)</li>
--   <li>Copyright 2008 Renaissance Computing Institute <a>
--   http://www.renci.org </a></li>
--   <li>License: GNU LGPL</li>
--   <li>Compatibility GHC (I could change the data declarations to not be
--   empty and that would make it more generally compatible, I
--   believe)</li>
--   <li>Description:</li>
--   </ul>
--   
--   Use FreeType 2 Fonts in OpenGL. Requires the FTGL library and FreeType
--   libraries. available at <a> http://ftgl.wiki.sourceforge.net/ </a> .
--   The most important functions for everyday use are renderFont and the
--   create*Font family of functions. To render a simple string inside
--   OpenGL, assuming you have OpenGL initialized and a current pen color,
--   all you need is:
--   
--   <pre>
--   do font &lt;- createTextureFont "Font.ttf"
--     setFontFaceSize font 24 72
--     renderFont font "Hello world!"
--   </pre>
--   
--   Fonts are rendered so that a single point is an OpenGL unit, and a
--   point is 1:72 of an inch.
module Graphics.Rendering.FTGL

-- | Create a bitmapped version of a TrueType font. Bitmapped versions will
--   not | respond to matrix transformations, but rather must be
--   transformed using the | raster positioning functions in OpenGL
createBitmapFont :: String -> IO Font

-- | Create a buffered version of a TrueType font. This stores the entirety
--   of | a string in a texture, <a>buffering</a> it before rendering. Very
--   fast if you | will be repeatedly rendering the same strings over and
--   over.
createBufferFont :: String -> IO Font

-- | Create an outline version of a TrueType font. This uses actual
--   geometry | and will scale independently without loss of quality.
--   Faster than polygons | but slower than texture or buffer fonts.
createOutlineFont :: String -> IO Font

-- | Create a pixmap version of a TrueType font. Higher quality than the
--   bitmap | font without losing any performance. Use this if you don't
--   mind using | set and get RasterPosition.
createPixmapFont :: String -> IO Font

-- | Create polygonal display list fonts. These scale independently without
--   | losing quality, unlike texture or buffer fonts, but can be
--   impractical | for large amounts of text because of the high number of
--   polygons needed. | Additionally, they do not, unlike the textured
--   fonts, create artifacts | within the square formed at the edge of each
--   character.
createPolygonFont :: String -> IO Font

-- | Create textured display list fonts. These can scale somewhat well, |
--   but lose quality quickly. They are much faster than polygonal fonts, |
--   though, so are suitable for large quantities of text. Especially
--   suited | well to text that changes with most frames, because it
--   doesn't incur the | (normally helpful) overhead of buffering.
createTextureFont :: String -> IO Font

-- | Create a 3D extruded font. This is the only way of creating 3D fonts |
--   within FTGL. Could be fun to use a geometry shader to get different |
--   effects by warping the otherwise square nature of the font. Polygonal.
--   | Scales without losing quality. Slower than all other fonts.
createExtrudeFont :: String -> IO Font
type Glyph = Ptr Glyph_Opaque
type Font = Ptr Font_Opaque
type Layout = Ptr Layout_Opaque
createSimpleLayout :: IO Layout
getLayoutFont :: Layout -> Font
setLayoutFont :: Layout -> Font -> IO ()

-- | Get the alignment of text in this layout.
getLayoutAlignment :: Layout -> TextAlignment
setLayoutAlignment :: Layout -> CInt -> IO ()

-- | Get the embedded font from the Layout
--   
--   Get the line length in points (1:72in) of lines in the layout
getLayoutLineLength :: Layout -> Float
setLayoutLineLength :: Layout -> CFloat -> IO ()
setLayoutLineSpacing :: Layout -> CFloat -> IO ()
destroyFont :: Font -> IO ()
attachData :: Font -> Ptr () -> IO ()

-- | Attach a metadata file to a font.
attachFile :: Font -> String -> IO ()
setFontCharMap :: Font -> CInt -> IO ()
setFontFaceSize :: Font -> Int -> Int -> IO CInt

-- | Get the different character mappings available in this font.
--   
--   Get the current font face size in points.
getFontFaceSize :: Font -> Int
setFontFaceDepth :: Font -> CInt -> IO ()

-- | Get the text extents of a string as a list of
--   (lower-left,lower-right,upper-left,upper-right)
getFontBBox :: Font -> String -> [Float]

-- | Get the horizontal span of a string of text using the current font.
--   Input as the xcoord | in any translate operation
getFontAdvance :: Font -> String -> Float

-- | Render a string of text in the current font.
renderFont :: Font -> String -> RenderMode -> IO ()

-- | Get any errors associated with loading a font. FIXME return should be
--   a type, not an Int.
getFontError :: Font -> Int
destroyLayout :: Layout -> IO ()
renderLayout :: Layout -> String -> IO ()
getLayoutError :: Layout -> CInt

-- | Whether or not in polygonal or extrusion mode, the font will render
--   equally front and back
data RenderMode
Front :: RenderMode
Back :: RenderMode
Side :: RenderMode
All :: RenderMode

-- | In a Layout directed render, the layout mode of the text
data TextAlignment
AlignLeft :: TextAlignment
AlignCenter :: TextAlignment
AlignRight :: TextAlignment
Justify :: TextAlignment