-- 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.
--   
--   This ultimately depends on a C library, via Haskell's FFI, and can be
--   difficult to install on some platforms. If you are just looking for a
--   quick way to visualize diagrams, try the diagrams-svg backend; if you
--   want raster output like PNG, try the diagrams-rasterific backend; if
--   you want to embed diagrams in LaTeX documents, try diagrams-pgf.
--   
--   <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.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 1.5


-- | 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
type B = 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

-- | Custom state tracked in the <tt>RenderM</tt> monad.
data CairoState
CairoState :: Style V2 Double -> Bool -> CairoState

-- | The current accumulated style.
[_accumStyle] :: CairoState -> Style V2 Double

-- | 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.
[_ignoreFill] :: CairoState -> Bool
accumStyle :: Lens' CairoState (Style V2 Double)
ignoreFill :: Lens' CairoState Bool

-- | The custom monad in which intermediate drawing options take place;
--   <a>Render</a> is cairo's own rendering monad.
type RenderM a = StateStackT CairoState Render a
liftC :: Render a -> RenderM a
runRenderM :: RenderM a -> Render a

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

-- | Restore the context from a stack.
restore :: RenderM ()
runC :: Render Cairo V2 Double -> RenderM ()
toRender :: RTree Cairo V2 Double a -> Render Cairo V2 Double
cairoFileName :: Lens' (Options Cairo V2 Double) String
cairoSizeSpec :: Lens' (Options Cairo V2 Double) (SizeSpec V2 Double)
cairoOutputType :: Lens' (Options Cairo V2 Double) OutputType
cairoBypassAdjust :: Lens' (Options Cairo V2 Double) Bool

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

-- | Get an accumulated style attribute from the render monad state.
getStyleAttrib :: AttributeClass a => (a -> b) -> RenderM (Maybe b)

-- | Handle those style attributes for which we can immediately emit cairo
--   instructions as we encounter them in the tree (clip, font size, fill
--   rule, line width, cap, join, and dashing). Other attributes (font
--   face, slant, weight; fill color, stroke color, opacity) must be
--   accumulated.
cairoStyle :: forall (v :: Type -> Type). Style v Double -> RenderM ()
fromFontSlant :: FontSlant -> FontStyle
fromFontWeight :: FontWeight -> Weight

-- | Multiply the current transformation matrix by the given 2D
--   transformation.
cairoTransf :: T2 Double -> Render ()
fromLineCap :: LineCap -> LineCap
fromLineJoin :: LineJoin -> LineJoin
fromFillRule :: FillRule -> FillRule
cairoPath :: Path V2 Double -> RenderM ()
addStop :: MonadIO m => Pattern -> GradientStop Double -> m ()
cairoSpreadMethod :: SpreadMethod -> Extend
setTexture :: Maybe (Texture Double) -> RenderM ()
toImageRGBA8 :: DynamicImage -> Image PixelRGBA8
toARGB :: PixelRGBA8 -> Word32
if' :: Monad m => (a -> m ()) -> Maybe a -> m ()
layoutStyledText :: Style V2 Double -> Text Double -> Render PangoLayout
instance Diagrams.Core.Types.Backend Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double
instance GHC.Internal.Enum.Bounded Diagrams.Backend.Cairo.Internal.OutputType
instance Data.Default.Internal.Default Diagrams.Backend.Cairo.Internal.CairoState
instance GHC.Internal.Enum.Enum Diagrams.Backend.Cairo.Internal.OutputType
instance GHC.Classes.Eq Diagrams.Backend.Cairo.Internal.Cairo
instance GHC.Classes.Eq (Diagrams.Core.Types.Options Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double)
instance GHC.Classes.Eq Diagrams.Backend.Cairo.Internal.OutputType
instance GHC.Internal.Generics.Generic Diagrams.Backend.Cairo.Internal.OutputType
instance Data.Hashable.Class.Hashable (Diagrams.Core.Types.Options Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double)
instance Data.Hashable.Class.Hashable Diagrams.Backend.Cairo.Internal.OutputType
instance GHC.Internal.Base.Monoid (Diagrams.Core.Types.Render Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double)
instance GHC.Classes.Ord Diagrams.Backend.Cairo.Internal.Cairo
instance GHC.Classes.Ord Diagrams.Backend.Cairo.Internal.OutputType
instance GHC.Internal.Read.Read Diagrams.Backend.Cairo.Internal.Cairo
instance GHC.Internal.Read.Read Diagrams.Backend.Cairo.Internal.OutputType
instance Diagrams.Core.Types.Renderable (Diagrams.TwoD.Image.DImage GHC.Types.Double Diagrams.TwoD.Image.External) Diagrams.Backend.Cairo.Internal.Cairo
instance Diagrams.Core.Types.Renderable (Diagrams.TwoD.Image.DImage GHC.Types.Double Diagrams.TwoD.Image.Embedded) Diagrams.Backend.Cairo.Internal.Cairo
instance Diagrams.Core.Types.Renderable (Diagrams.Path.Path Linear.V2.V2 GHC.Types.Double) Diagrams.Backend.Cairo.Internal.Cairo
instance Diagrams.Core.Types.Renderable (Diagrams.Segment.Segment Diagrams.Segment.Closed Linear.V2.V2 GHC.Types.Double) Diagrams.Backend.Cairo.Internal.Cairo
instance Diagrams.Core.Types.Renderable (Diagrams.TwoD.Text.Text GHC.Types.Double) Diagrams.Backend.Cairo.Internal.Cairo
instance Diagrams.Core.Types.Renderable (Diagrams.Trail.Trail Linear.V2.V2 GHC.Types.Double) Diagrams.Backend.Cairo.Internal.Cairo
instance GHC.Internal.Base.Semigroup (Diagrams.Core.Types.Render Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double)
instance GHC.Internal.Show.Show Diagrams.Backend.Cairo.Internal.Cairo
instance GHC.Internal.Show.Show (Diagrams.Core.Types.Options Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double)
instance GHC.Internal.Show.Show Diagrams.Backend.Cairo.Internal.OutputType


-- | 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 n -&gt; QDiagram b v n m -&gt; Result b v n
--   </pre>
--   
--   (omitting a few type class constraints). <tt>b</tt> represents the
--   backend type, <tt>v</tt> the vector space, <tt>n</tt> the numeric
--   field, 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>, <tt>v ~ V2</tt>, and <tt>n ~ Double</tt>, we have
--   
--   <pre>
--   data family Options Cairo V2 Double = CairoOptions
--            { _cairoFileName     :: String             -- ^ The name of the file you want generated
--            , _cairoSizeSpec     :: SizeSpec V2 Double -- ^ 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 V2 Double = (IO (), <a>Render</a> ())
--   </pre>
--   
--   So the type of <a>renderDia</a> resolves to
--   
--   <pre>
--   renderDia :: Cairo -&gt; Options Cairo V2 Double -&gt; QQDiagram Cairo V2 Double Any m -&gt; (IO (), <a>Render</a> ())
--   </pre>
--   
--   which you could call like so:
--   
--   <pre>
--   renderDia Cairo (CairoOptions "foo.png" (Width 250) PNG False) (myDiagram :: QDiagram Cairo V2 Double Any)
--   </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 =
--   QDiagram b (V b) (N b) Any</tt> to fix <tt>m = Any</tt> and fix
--   <tt>v</tt> and <tt>n</tt> to backend specific types.
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 -> SizeSpec V2 Double -> QDiagram Cairo V2 Double Any -> 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
type B = Cairo


-- | 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 -> Format -> QDiagram Cairo V2 Double Any -> IO (Ptr Word8)

-- | Like <a>renderPtr</a> but automatically garbage collected by Haskell.
renderForeignPtr :: Int -> Int -> QDiagram Cairo V2 Double Any -> IO (ForeignPtr Word8)
renderForeignPtrOpaque :: Int -> Int -> QDiagram Cairo V2 Double Any -> 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 -> QDiagram Cairo V2 Double Any -> IO [[AlphaColour a]]


-- | 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>
--   <li><a>gifMain</a> creates an executable to generate an animated
--   GIF.</li>
--   <li><a>mainWith</a> is a generic form that does all of the above but
--   with a slightly scarier type. See <a>Diagrams.Backend.CmdLine</a>.
--   This form can also take a function type that has a suitable final
--   result (any of arguments to the above types) and <a>Parseable</a>
--   arguments.</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>Use a function with <a>mainWith</a>. This may require making
--   <a>Parseable</a> instances for custom argument types.</li>
--   <li>Make a new <a>Mainable</a> instance. This may require a newtype
--   wrapper on your diagram type to avoid the existing instances. This
--   gives you more control over argument parsing, intervening steps, and
--   diagram creation.</li>
--   <li>Build option records and pass them along with a diagram to
--   <a>mainRender</a> from <a>Diagrams.Backend.CmdLine</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>
--   
--   For a tutorial on command-line diagram creation see
--   <a>https://diagrams.github.io/doc/cmdline.html</a>.
module Diagrams.Backend.Cairo.CmdLine

-- | Main entry point for command-line diagram creation. This is the method
--   that users will call from their program <tt>main</tt>. For instance an
--   expected user program would take the following form.
--   
--   <pre>
--   import Diagrams.Prelude
--   import Diagrams.Backend.TheBestBackend.CmdLine
--   
--   d :: Diagram B R2
--   d = ...
--   
--   main = mainWith d
--   </pre>
--   
--   Most backends should be able to use the default implementation. A
--   different implementation should be used to handle more complex
--   interactions with the user.
mainWith :: Mainable d => d -> IO ()
defaultMain :: QDiagram Cairo V2 Double Any -> IO ()
multiMain :: [(String, QDiagram Cairo V2 Double Any)] -> 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 V2 Double -> IO ()

-- | <tt>gifMain</tt> takes a list of diagram and delay time pairs and
--   produces a command line program to generate an animated GIF, with
--   options <tt>GifOpts</tt>. "Delay times are in 1/100ths of a second."
--   
--   Example usage:
--   
--   <pre>
--   $ ghc --make GifTest
--   [1 of 1] Compiling Main             ( GifTest.hs, GifTest.o )
--   Linking GifTest ...
--   ./GifTest --help
--   GifTest
--   
--   Usage: GifTest [-w|--width WIDTH] [-h|--height HEIGHT] [-o|--output OUTPUT]
--   [--dither] [--looping-off] [--loop-repeat ARG]
--   Command-line diagram generation.
--   
--   Available options:
--    -?,--help                Show this help text
--    -w,--width WIDTH         Desired WIDTH of the output image
--    -h,--height HEIGHT       Desired HEIGHT of the output image
--    -o,--output OUTPUT       OUTPUT file
--    --dither                 Turn on dithering.
--    --looping-off            Turn looping off
--    --loop-repeat ARG        Number of times to repeat
--   </pre>
gifMain :: [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO ()

-- | Extra options for animated GIFs.
data GifOpts
GifOpts :: Bool -> Bool -> Maybe Int -> GifOpts
[_dither] :: GifOpts -> Bool
[_noLooping] :: GifOpts -> Bool
[_loopRepeat] :: GifOpts -> Maybe Int
gifRender :: (DiagramOpts, GifOpts) -> [(QDiagram Cairo V2 Double Any, GifDelay)] -> 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
type B = Cairo
instance Diagrams.Backend.CmdLine.Mainable (Diagrams.Animation.Animation Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double)
instance Diagrams.Backend.CmdLine.Mainable [(GHC.Internal.Base.String, Diagrams.Core.Types.QDiagram Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double GHC.Internal.Data.Semigroup.Internal.Any)]
instance Diagrams.Backend.CmdLine.Mainable [(Diagrams.Core.Types.QDiagram Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double GHC.Internal.Data.Semigroup.Internal.Any, Codec.Picture.Gif.GifDelay)]
instance Diagrams.Backend.CmdLine.Mainable (Diagrams.Core.Types.QDiagram Diagrams.Backend.Cairo.Internal.Cairo Linear.V2.V2 GHC.Types.Double GHC.Internal.Data.Semigroup.Internal.Any)
instance Diagrams.Backend.CmdLine.Parseable Diagrams.Backend.Cairo.CmdLine.GifOpts


-- | 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 <tt>textLineBounded</tt>, <a>textLineBoundedIO</a>,
--   <tt>textVisualBounded</tt>, or <a>textVisualBoundedIO</a>.
--   
--   Many of these functions take a <a>Style</a> <a>V2</a> <a>Double</a>
--   parameter, determining the style to apply to the text before rendering
--   / querying information about the text. These <a>Style</a> <a>V2</a>
--   <a>Double</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>, <a>fontSlant</a>, and
--   <a>fontWeight</a> 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 (<tt>textLineBounded</tt> style)</tt> stacks
--   them in the way that the font designer intended. Pango refers to this
--   as logical extents.
textLineBoundedIO :: Style V2 Double -> Text Double -> IO (Diagram Cairo)

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

-- | 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
