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


-- | Cairo backend for diagrams drawing EDSL
--   
--   A full-featured backend for rendering diagrams using the cairo
--   rendering engine.
--   
--   <ul>
--   <li><a>Diagrams.Backend.Cairo.CmdLine</a> - if you're just getting
--   started with diagrams, begin here.</li>
--   <li><a>Diagrams.Backend.Cairo</a> - look at this next. The general API
--   for the cairo backend.</li>
--   <li><a>Diagrams.Backend.Cairo.Internal</a> - the implementation guts
--   of the cairo backend. Users should normally not need to import this
--   module.</li>
--   <li><a>Diagrams.Backend.Cairo.Text</a> - cairo-specific text support,
--   including automatic bounding boxes.</li>
--   <li><a>Diagrams.Backend.Cairo.List</a> - render diagrams to
--   two-dimensional lists of colors (<i>i.e.</i> pixels).</li>
--   <li><a>Diagrams.Backend.Cairo.Ptr</a> - render diagrams to buffers in
--   memory.</li>
--   </ul>
@package diagrams-cairo
@version 0.7


-- | This module contains the internal implementation guts of the diagrams
--   cairo backend. If you want to see how the cairo backend works under
--   the hood, you are in the right place (try clicking on the "Source"
--   links). (Guts under the hood, what an awful mixed metaphor.) If you
--   know what you are doing and really want access to the internals of the
--   implementation, you are also in the right place. Otherwise, you should
--   have no need of this module; import
--   <a>Diagrams.Backend.Cairo.CmdLine</a> or <a>Diagrams.Backend.Cairo</a>
--   instead.
--   
--   The one exception is that this module may have to be imported
--   sometimes to work around an apparent bug in certain versions of GHC,
--   which results in a "not in scope" error for <a>CairoOptions</a>.
--   
--   The types of all the <tt>fromX</tt> functions look funny in the
--   Haddock output, which displays them like <tt>Type -&gt; Type</tt>. In
--   fact they are all of the form <tt>Type -&gt;
--   Graphics.Rendering.Cairo.Type</tt>, <i>i.e.</i> they convert from a
--   diagrams type to a cairo type of the same name.
module Diagrams.Backend.Cairo.Internal

-- | This data declaration is simply used as a token to distinguish the
--   cairo backend: (1) when calling functions where the type inference
--   engine would otherwise have no way to know which backend you wanted to
--   use, and (2) as an argument to the <a>Backend</a> and
--   <a>Renderable</a> type classes.
data Cairo
Cairo :: Cairo

-- | Output types supported by cairo, including four different file types
--   (PNG, PS, PDF, SVG). If you want to output directly to GTK windows,
--   see the <tt>diagrams-gtk</tt> package.
data OutputType

-- | Portable Network Graphics output.
PNG :: OutputType

-- | PostScript output
PS :: OutputType

-- | Portable Document Format output.
PDF :: OutputType

-- | Scalable Vector Graphics output.
SVG :: OutputType

-- | Don't output any file; the returned <tt>IO ()</tt> action will do
--   nothing, but the <tt>Render ()</tt> action can be used (<i>e.g.</i> to
--   draw to a Gtk window; see the <tt>diagrams-gtk</tt> package).
RenderOnly :: OutputType

-- | The custom monad in which intermediate drawing options take place;
--   <a>Render</a> is cairo's own rendering monad. Right now we simply
--   maintain a Bool state to track whether or not we saw any lines in the
--   most recent path (as opposed to loops). If we did, we should ignore
--   any fill attribute. diagrams-lib separates lines and loops into
--   separate path primitives so we don't have to worry about seeing them
--   together in the same path.
type RenderM a = StateT Bool Render a

-- | Push the current context onto a stack.
save :: RenderM ()

-- | Restore the context from a stack.
restore :: RenderM ()

-- | Render an object that the cairo backend knows how to render.
renderC :: (Renderable a Cairo, V a ~ R2) => a -> RenderM ()

-- | Handle "miscellaneous" style attributes (clip, font stuff, fill color
--   and fill rule).
cairoMiscStyle :: Style v -> RenderM ()
fromFontSlant :: FontSlant -> FontSlant
fromFontWeight :: FontWeight -> FontWeight

-- | Handle style attributes having to do with stroke.
cairoStrokeStyle :: Bool -> Style v -> Render ()

-- | Set the source color.
setSource :: Color c => c -> Style v -> Render ()

-- | Multiply the current transformation matrix by the given 2D
--   transformation.
cairoTransf :: T2 -> Render ()
fromLineCap :: LineCap -> LineCap
fromLineJoin :: LineJoin -> LineJoin
fromFillRule :: FillRule -> FillRule
instance Typeable Cairo
instance Typeable OutputType
instance Eq Cairo
instance Ord Cairo
instance Read Cairo
instance Show Cairo
instance Eq OutputType
instance Ord OutputType
instance Read OutputType
instance Show OutputType
instance Bounded OutputType
instance Enum OutputType
instance Show (Options Cairo R2)
instance Renderable Text Cairo
instance Renderable Image Cairo
instance Renderable (Path R2) Cairo
instance Renderable (Trail R2) Cairo
instance Renderable (Segment Closed R2) Cairo
instance Backend Cairo R2
instance Monoid (Render Cairo R2)


-- | This module provides convenience functions for querying information
--   from cairo. In particular, this provides utilities for information
--   about fonts, and creating text primitives with bounds based on the
--   font being used. To render text with automatically determined
--   envelopes, use <a>textLineBounded</a>, <a>textLineBoundedIO</a>,
--   <a>textVisualBounded</a>, or <a>textVisualBoundedIO</a>.
--   
--   Many of these functions take a <a>Style</a> <a>R2</a> parameter,
--   determining the style to apply to the text before rendering / querying
--   information about the text. These <a>Style</a> <a>R2</a> parameters
--   can be created a variety of ways, but the most direct will likely be
--   by applying style-transforming functions such as <a>font</a>,
--   <a>fontSize</a>, <tt>fontSlant</tt>, and <tt>fontWeight</tt> to
--   <a>mempty</a>. This works because there are instances of
--   <a>HasStyle</a> and <a>Monoid</a> for <tt><a>Style</a> v</tt>.
module Diagrams.Backend.Cairo.Text

-- | Creates text diagrams with their envelopes set such that using
--   <tt><a>vcat</a> . map (<a>textLineBounded</a> style)</tt> stacks them
--   in the way that the font designer intended.
textLineBoundedIO :: Style R2 -> String -> IO (Diagram Cairo R2)

-- | Creates a text diagram with its envelope set to enclose the glyphs of
--   the text, including leading (though not trailing) whitespace.
textVisualBoundedIO :: Style R2 -> String -> IO (Diagram Cairo R2)

-- | Queries the amount of horizontal offset that needs to be applied in
--   order to position the second character properly, in the event that it
--   is <a>hcat</a>-ed <a>baselineText</a>. See <a>kerningCorrectionIO</a>;
--   this variant uses <a>unsafePerformIO</a> but should be fairly safe in
--   practice.
kerningCorrection :: Style R2 -> Char -> Char -> Double

-- | Creates text diagrams with their envelopes set such that using
--   <tt><a>vcat</a> . map (<a>textLineBounded</a> style)</tt> stacks them
--   in the way that the font designer intended. See
--   <a>textLineBoundedIO</a>; this variant uses <a>unsafePerformIO</a> but
--   should be fairly safe in practice.
textLineBounded :: Style R2 -> String -> Diagram Cairo R2

-- | Creates a text diagram with its envelope set to enclose the glyphs of
--   the text, including leading (though not trailing) whitespace. See
--   <a>textVisualBoundedIO</a>; this variant uses <a>unsafePerformIO</a>
--   but should be fairly safe in practice.
textVisualBounded :: Style R2 -> String -> Diagram Cairo R2

-- | A more convenient data structure for the results of a text-extents
--   query.
data TextExtents
TextExtents :: R2 -> R2 -> R2 -> TextExtents
bearing :: TextExtents -> R2
textSize :: TextExtents -> R2
advance :: TextExtents -> R2

-- | A more convenient data structure for the results of a font-extents
--   query.
data FontExtents
FontExtents :: Double -> Double -> Double -> R2 -> FontExtents
ascent :: FontExtents -> Double
descent :: FontExtents -> Double
height :: FontExtents -> Double
maxAdvance :: FontExtents -> R2

-- | Get the extents of a string of text, given a style to render it with.
getTextExtents :: Style R2 -> String -> Render TextExtents

-- | Gets the intrinsic extents of a font.
getFontExtents :: Style R2 -> Render FontExtents

-- | Gets both the <a>FontExtents</a> and <a>TextExtents</a> of the string
--   with the a particular style applied. This is more efficient than
--   calling both <a>getFontExtents</a> and <a>getTextExtents</a>.
getExtents :: Style R2 -> String -> Render (FontExtents, TextExtents)

-- | Queries the amount of horizontal offset that needs to be applied in
--   order to position the second character properly, in the event that it
--   is <a>hcat</a>-ed <a>baselineText</a>.
kerningCorrectionIO :: Style R2 -> Char -> Char -> IO Double

-- | Executes a cairo action on a dummy, zero-size image surface, in order
--   to query things like font information.
queryCairo :: Render a -> IO a

-- | Unsafely invokes <a>queryCairo</a> using <a>unsafePerformIO</a>.
unsafeCairo :: Render a -> a

-- | Executes the given cairo action, with styling applied. This does not
--   do all styling, only attributes that are processed by
--   <a>cairoMiscStyle</a>, which does clip, fill color, fill rule, and,
--   importantly for this module, font face, style, and weight.
cairoWithStyle :: Render a -> Style R2 -> Render a


-- | A full-featured rendering backend for diagrams using the cairo
--   rendering engine.
--   
--   To invoke the cairo backend, you have three options.
--   
--   <ul>
--   <li>You can use the <a>Diagrams.Backend.Cairo.CmdLine</a> module to
--   create standalone executables which output images when invoked.</li>
--   <li>You can use the <a>renderCairo</a> function provided by this
--   module, which gives you more flexible programmatic control over when
--   and how images are output (making it easy to, for example, write a
--   single program that outputs multiple images, or one that outputs
--   images dynamically based on user input, and so on).</li>
--   <li>Finally, for the most flexibility, you can directly use methods
--   from the <a>Backend</a> instance for <tt>Cairo</tt>. In particular,
--   <a>renderDia</a> has the generic type</li>
--   </ul>
--   
--   <pre>
--   renderDia :: b -&gt; Options b v -&gt; QDiagram b v m -&gt; Result b v
--   </pre>
--   
--   (omitting a few type class constraints). <tt>b</tt> represents the
--   backend type, <tt>v</tt> the vector space, and <tt>m</tt> the type of
--   monoidal query annotations on the diagram. <a>Options</a> and
--   <a>Result</a> are associated data and type families, respectively,
--   which yield the type of option records and rendering results specific
--   to any particular backend. For <tt>b ~ Cairo</tt> and <tt>v ~ R2</tt>,
--   we have
--   
--   <pre>
--   data family Options Cairo R2 = CairoOptions
--            { cairoFileName     :: String     -- ^ The name of the file you want generated
--            , cairoSizeSpec     :: SizeSpec2D -- ^ The requested size of the output
--            , cairoOutputType   :: OutputType -- ^ the output format and associated options
--            , cairoBypassAdjust :: Bool       -- ^ Should the 'adjustDia' step be bypassed during rendering?
--            }
--   </pre>
--   
--   <pre>
--   type family Result Cairo R2 = (IO (), <a>Render</a> ())
--   </pre>
--   
--   So the type of <a>renderDia</a> resolves to
--   
--   <pre>
--   renderDia :: Cairo -&gt; Options Cairo R2 -&gt; QDiagram Cairo R2 m -&gt; (IO (), <a>Render</a> ())
--   </pre>
--   
--   which you could call like so:
--   
--   <pre>
--   renderDia Cairo (CairoOptions "foo.png" (Width 250) PNG False) (myDiagram :: Diagram Cairo R2)
--   </pre>
--   
--   This would return a pair; the first element is an <tt>IO ()</tt>
--   action which will write out <tt>foo.png</tt> to disk, and the second
--   is a cairo rendering action which can be used, for example, to
--   directly draw to a Gtk window. Note the type annotation on
--   <tt>myDiagram</tt> which may be necessary to fix the type variable
--   <tt>m</tt>; this example uses the type synonym <tt>Diagram b v =
--   QDiagram b v Any</tt> to fix <tt>m = Any</tt>.
module Diagrams.Backend.Cairo

-- | Render a diagram using the cairo backend, writing to the given output
--   file and using the requested size. The output type (PNG, PS, PDF, or
--   SVG) is determined automatically from the output file extension.
--   
--   This function is provided as a convenience; if you need more
--   flexibility than it provides, you can call <a>renderDia</a> directly,
--   as described above.
renderCairo :: FilePath -> SizeSpec2D -> Diagram Cairo R2 -> IO ()

-- | Output types supported by cairo, including four different file types
--   (PNG, PS, PDF, SVG). If you want to output directly to GTK windows,
--   see the <tt>diagrams-gtk</tt> package.
data OutputType

-- | Portable Network Graphics output.
PNG :: OutputType

-- | PostScript output
PS :: OutputType

-- | Portable Document Format output.
PDF :: OutputType

-- | Scalable Vector Graphics output.
SVG :: OutputType

-- | Don't output any file; the returned <tt>IO ()</tt> action will do
--   nothing, but the <tt>Render ()</tt> action can be used (<i>e.g.</i> to
--   draw to a Gtk window; see the <tt>diagrams-gtk</tt> package).
RenderOnly :: OutputType

-- | This data declaration is simply used as a token to distinguish the
--   cairo backend: (1) when calling functions where the type inference
--   engine would otherwise have no way to know which backend you wanted to
--   use, and (2) as an argument to the <a>Backend</a> and
--   <a>Renderable</a> type classes.
data Cairo
Cairo :: Cairo


-- | Convenient creation of command-line-driven executables for rendering
--   diagrams using the cairo backend.
--   
--   <ul>
--   <li><a>defaultMain</a> creates an executable which can render a single
--   diagram at various options.</li>
--   <li><a>multiMain</a> is like <a>defaultMain</a> but allows for a list
--   of diagrams from which the user can choose one to render.</li>
--   <li><a>animMain</a> is like <a>defaultMain</a> but for animations
--   instead of diagrams.</li>
--   </ul>
--   
--   If you want to generate diagrams programmatically---<i>i.e.</i> if you
--   want to do anything more complex than what the below functions
--   provide---you have several options.
--   
--   <ul>
--   <li>A simple but somewhat inflexible approach is to wrap up
--   <a>defaultMain</a> (or <a>multiMain</a>, or <a>animMain</a>) in a call
--   to <a>withArgs</a>.</li>
--   <li>A more flexible approach is to use the <a>renderCairo</a> function
--   provided in the <a>Diagrams.Backend.Cairo</a> module.</li>
--   <li>For the most flexibility, you can call the generic
--   <a>renderDia</a> function directly; see <a>Diagrams.Backend.Cairo</a>
--   for more information.</li>
--   </ul>
module Diagrams.Backend.Cairo.CmdLine

-- | This is the simplest way to render diagrams, and is intended to be
--   used like so:
--   
--   <pre>
--   ... other definitions ...
--   myDiagram = ...
--   
--   main = defaultMain myDiagram
--   </pre>
--   
--   Compiling a source file like the above example will result in an
--   executable which takes command-line options for setting the size,
--   output file, and so on, and renders <tt>myDiagram</tt> with the
--   specified options.
--   
--   On Unix systems, the generated executable also supports a rudimentary
--   "looped" mode, which watches the source file for changes and
--   recompiles itself on the fly.
--   
--   Pass <tt>--help</tt> to the generated executable to see all available
--   options. Currently it looks something like
--   
--   <pre>
--    Command-line diagram generation.
--   
--   Foo [OPTIONS]
--   
--   Common flags:
--      -w --width=INT         Desired width of the output image
--      -h --height=INT        Desired height of the output image
--      -o --output=FILE       Output file
--      -f --fpu=FLOAT         Frames per unit time (for animations)
--      -l --loop              Run in a self-recompiling loop
--      -s --src=FILE          Source file to watch
--      -i --interval=SECONDS  When running in a loop, check for changes every n
--                             seconds.
--      -? --help              Display help message
--      -V --version           Print version information
--   </pre>
--   
--   For example, a couple common scenarios include
--   
--   <pre>
--    $ ghc --make MyDiagram
--   
--   # output image.png with a width of 400px (and auto-determined height)
--    $ ./MyDiagram -o image.png -w 400
--   
--   # output 200x200 dia.pdf, then watch for changes every 10 seconds
--    $ ./MyDiagram -o dia.pdf -h 200 -w 200 -l -i 10
--   </pre>
defaultMain :: Diagram Cairo R2 -> IO ()

-- | <tt>multiMain</tt> is like <a>defaultMain</a>, except instead of a
--   single diagram it takes a list of diagrams paired with names as input.
--   The generated executable then takes a <tt>--selection</tt> option
--   specifying the name of the diagram that should be rendered. The list
--   of available diagrams may also be printed by passing the option
--   <tt>--list</tt>.
--   
--   Example usage:
--   
--   <pre>
--   $ ghc --make MultiTest
--   [1 of 1] Compiling Main             ( MultiTest.hs, MultiTest.o )
--   Linking MultiTest ...
--   $ ./MultiTest --list
--   Available diagrams:
--     foo bar
--   $ ./MultiTest --selection bar -o Bar.png -w 200
--   </pre>
multiMain :: [(String, Diagram Cairo R2)] -> IO ()

-- | <tt>animMain</tt> is like <a>defaultMain</a>, but renders an animation
--   instead of a diagram. It takes as input an animation and produces a
--   command-line program which will crudely "render" the animation by
--   rendering one image for each frame, named by extending the given
--   output file name by consecutive integers. For example if the given
--   output file name is <tt>foo/blah.png</tt>, the frames will be saved in
--   <tt>foo/blah001.png</tt>, <tt>foo/blah002.png</tt>, and so on (the
--   number of padding digits used depends on the total number of frames).
--   It is up to the user to take these images and stitch them together
--   into an actual animation format (using, <i>e.g.</i> <tt>ffmpeg</tt>).
--   
--   Of course, this is a rather crude method of rendering animations; more
--   sophisticated methods will likely be added in the future.
--   
--   The <tt>--fpu</tt> option can be used to control how many frames will
--   be output for each second (unit time) of animation.
animMain :: Animation Cairo R2 -> IO ()

-- | This data declaration is simply used as a token to distinguish the
--   cairo backend: (1) when calling functions where the type inference
--   engine would otherwise have no way to know which backend you wanted to
--   use, and (2) as an argument to the <a>Backend</a> and
--   <a>Renderable</a> type classes.
data Cairo
instance Typeable DiagramOpts
instance Show DiagramOpts
instance Data DiagramOpts


-- | Render diagrams to buffers in memory.
module Diagrams.Backend.Cairo.Ptr

-- | Render a diagram to a new buffer in memory, with the format ARGB32.
renderPtr :: Int -> Int -> Diagram Cairo R2 -> IO (Ptr Word8)

-- | Like <a>renderPtr</a> but automatically garbage collected by Haskell.
renderForeignPtr :: Int -> Int -> Diagram Cairo R2 -> IO (ForeignPtr Word8)


-- | Render a diagram directly to a list of lists of Colour values
--   (<i>i.e.</i> pixels).
module Diagrams.Backend.Cairo.List

-- | Render to a regular list of Colour values.
renderToList :: (Ord a, Floating a) => Int -> Int -> Diagram Cairo R2 -> IO [[AlphaColour a]]
