libghc-cairo-doc 0.13.3.1-1 / usr / share / doc / libghc-cairo-doc / html / cairo.txt

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


-- | Binding to the Cairo library.
--   
--   Cairo is a library to render high quality vector graphics. There exist
--   various backends that allows rendering to Gtk windows, PDF, PS, PNG
--   and SVG documents, amongst others.
@package cairo
@version 0.13.3.1


-- | Matrix math
module Graphics.Rendering.Cairo.Matrix

-- | Representation of a 2-D affine transformation.
--   
--   The Matrix type represents a 2x2 transformation matrix along with a
--   translation vector. <tt>Matrix a1 a2 b1 b2 c1 c2</tt> describes the
--   transformation of a point with coordinates x,y that is defined by
--   
--   <pre>
--   / x' \  =  / a1 b1 \  / x \  + / c1 \
--   \ y' /     \ a2 b2 /  \ y /    \ c2 /
--   </pre>
--   
--   or
--   
--   <pre>
--   x' =  a1 * x + b1 * y + c1
--   y' =  a2 * x + b2 * y + c2
--   </pre>
data Matrix
Matrix :: !Double -> !Double -> !Double -> !Double -> !Double -> !Double -> Matrix
type MatrixPtr = Ptr (Matrix)
identity :: Matrix
translate :: Double -> Double -> Matrix -> Matrix
scale :: Double -> Double -> Matrix -> Matrix
rotate :: Double -> Matrix -> Matrix
transformDistance :: Matrix -> (Double, Double) -> (Double, Double)
transformPoint :: Matrix -> (Double, Double) -> (Double, Double)
scalarMultiply :: Double -> Matrix -> Matrix
adjoint :: Matrix -> Matrix
invert :: Matrix -> Matrix
instance GHC.Classes.Eq Graphics.Rendering.Cairo.Matrix.Matrix
instance GHC.Show.Show Graphics.Rendering.Cairo.Matrix.Matrix
instance Foreign.Storable.Storable Graphics.Rendering.Cairo.Matrix.Matrix
instance GHC.Num.Num Graphics.Rendering.Cairo.Matrix.Matrix


-- | The Cairo 2D graphics library.
--   
--   Cairo is a 2D graphics library with support for multiple output
--   devices. Currently supported output targets include the X Window
--   System, win32, and image buffers. Experimental backends include OpenGL
--   (through glitz), Quartz, XCB, PostScript and PDF file output.
--   
--   Cairo is designed to produce consistent output on all output media
--   while taking advantage of display hardware acceleration when available
--   (eg. through the X Render Extension).
--   
--   The cairo API provides operations similar to the drawing operators of
--   PostScript and PDF. Operations in cairo including stroking and filling
--   cubic Bezier splines, transforming and compositing translucent images,
--   and antialiased text rendering. All drawing operations can be
--   transformed by any affine transformation (scale, rotation, shear,
--   etc.)
--   
--   Cairo is free software and is available to be redistributed and/or
--   modified under the terms of either the GNU Lesser General Public
--   License (LGPL) version 2.1 or the Mozilla Public License (MPL) version
--   1.1.
--   
--   For more information see <a>http://cairographics.org</a>
--   
--   <ul>
--   <li>Note the Haskell bindings do not support all the possible cairo
--   backends because it would require bindings for the associated
--   technology (eg X11, glitz, etc) however bindings to other backends may
--   be implemented externally. For example, Gtk2Hs provides a binding to
--   the backend for X11 (and win32 on Windows).</li>
--   </ul>
module Graphics.Rendering.Cairo

-- | Creates a new Render context with all graphics state parameters set to
--   default values and with the given surface as a target surface. The
--   target surface should be constructed with a backend-specific function
--   such as <a>withImageSurface</a> (or any other
--   with&lt;backend&gt;Surface variant).
renderWith :: (MonadIO m) => Surface -> Render a -> m a

-- | Makes a copy of the current state and saves it on an internal stack of
--   saved states. When <a>restore</a> is called, the saved state is
--   restored. Multiple calls to <a>save</a> and <a>restore</a> can be
--   nested; each call to <a>restore</a> restores the state from the
--   matching paired <a>save</a>.
save :: Render ()

-- | Restores to the state saved by a preceding call to <a>save</a> and
--   removes that state from the stack of saved states.
restore :: Render ()

-- | Ask for the status of the current <a>Render</a> monad.
status :: Render Status

-- | Gets the target surface for the Render context as passed to
--   <a>renderWith</a>.
withTargetSurface :: (Surface -> Render a) -> Render a

-- | Like <tt>pushGroupWithContent ContentColorAlpha</tt>, but more
--   convenient.
pushGroup :: Render ()

-- | Temporarily redirects drawing to an intermediate surface known as a
--   group. The redirection lasts until the group is completed by a call to
--   <a>withGroupPattern</a> or <a>popGroupToSource</a>. These calls
--   provide the result of any drawing to the group as a pattern (either as
--   an explicit object, or set as the source pattern). This group
--   functionality can be convenient for performing intermediate
--   compositing. One common use of a group is to render objects as opaque
--   within the group (so that they occlude each other), and then blend the
--   result with translucence onto the destination.
--   
--   Groups can be nested arbitrarily deeply by making balanced calls to
--   <a>pushGroupWithContent</a> and <a>withGroupPattern</a>. As a side
--   effect, <a>pushGroupWithContent</a> calls <a>save</a> and
--   <a>withGroupPattern</a> calls <a>restore</a>, so that any changes to
--   the graphics state will not be visible outside the group.
--   
--   As an example, here is how one might fill and stroke a path with
--   translucence, but without any portion of the fill being visible under
--   the stroke:
--   
--   <pre>
--   pushGroup
--   setSource fillPattern
--   fillPreserve
--   setSource strokePattern
--   stroke
--   popGroupToSource
--   paintWithAlpha alpha
--   </pre>
pushGroupWithContent :: Content -> Render ()

-- | Like <tt>withGroupPattern setSource</tt>, but more convenient.
popGroupToSource :: Render ()

-- | Sets the source pattern within the context to an opaque color. This
--   opaque color will then be used for any subsequent drawing operation
--   until a new source pattern is set.
--   
--   The color components are floating point numbers in the range 0 to 1.
--   If the values passed in are outside that range, they will be clamped.
setSourceRGB :: Double -> Double -> Double -> Render ()

-- | Sets the source pattern within the context to a translucent color.
--   This color will then be used for any subsequent drawing operation
--   until a new source pattern is set.
--   
--   The color and alpha components are floating point numbers in the range
--   0 to 1. If the values passed in are outside that range, they will be
--   clamped.
setSourceRGBA :: Double -> Double -> Double -> Double -> Render ()

-- | Sets the source pattern within the context to source. This pattern
--   will then be used for any subsequent drawing operation until a new
--   source pattern is set.
--   
--   Note: The pattern's transformation matrix will be locked to the user
--   space in effect at the time of <a>setSource</a>. This means that
--   further modifications of the current transformation matrix will not
--   affect the source pattern. See <a>setMatrix</a>.
setSource :: Pattern -> Render ()

-- | This is a convenience function for creating a pattern from surface and
--   setting it as the source in the context with <a>setSource</a>.
--   
--   The x and y parameters give the user-space coordinate at which the
--   surface origin should appear. (The surface origin is its upper-left
--   corner before any transformation has been applied.) The x and y
--   patterns are negated and then set as translation values in the pattern
--   matrix.
--   
--   Other than the initial translation pattern matrix, as described above,
--   all other pattern attributes, (such as its extend mode), are set to
--   the default values as in <tt>patternCreateForSurface</tt>. The
--   resulting pattern can be queried with <a>getSource</a> so that these
--   attributes can be modified if desired, (eg. to create a repeating
--   pattern with <tt>patternSetExtent</tt>.
setSourceSurface :: Surface -> Double -> Double -> Render ()

-- | Gets the current source pattern.
getSource :: Render Pattern

-- | Set the antialiasing mode of the rasterizer used for drawing shapes.
--   This value is a hint, and a particular backend may or may not support
--   a particular value. At the current time, no backend supports
--   <a>AntialiasSubpixel</a> when drawing shapes.
--   
--   Note that this option does not affect text rendering, instead see
--   <tt>fontOptionsSetAntilias</tt>.
setAntialias :: Antialias -> Render ()

-- | Sets the dash pattern to be used by <a>stroke</a>. A dash pattern is
--   specified by dashes, a list of positive values. Each value provides
--   the user-space length of altenate "on" and "off" portions of the
--   stroke. The offset specifies an offset into the pattern at which the
--   stroke begins.
--   
--   If <tt>dashes</tt> is <tt>[]</tt> then dashing is disabled.
setDash :: [Double] -> Double -> Render ()

-- | Set the current fill rule within the cairo context. The fill rule is
--   used to determine which regions are inside or outside a complex
--   (potentially self-intersecting) path. The current fill rule affects
--   both <a>fill</a> and <a>clip</a>. See <a>FillRule</a> for details on
--   the semantics of each available fill rule.
setFillRule :: FillRule -> Render ()

-- | Gets the current fill rule, as set by <tt>setFillrule</tt>.
getFillRule :: Render FillRule

-- | Sets the current line cap style within the cairo context. See
--   <a>LineCap</a> for details about how the available line cap styles are
--   drawn.
--   
--   As with the other stroke parameters, the current line cap style is
--   examined by <a>stroke</a>, <a>strokeExtents</a>, and
--   <tt>strokeToPath</tt>, but does not have any effect during path
--   construction.
setLineCap :: LineCap -> Render ()

-- | Gets the current line cap style, as set by <a>setLineCap</a>.
getLineCap :: Render LineCap

-- | Sets the current line join style within the cairo context. See
--   <a>LineJoin</a> for details about how the available line join styles
--   are drawn.
--   
--   As with the other stroke parameters, the current line join style is
--   examined by <a>stroke</a>, <a>strokeExtents</a>, and
--   <tt>strokeToPath</tt>, but does not have any effect during path
--   construction.
setLineJoin :: LineJoin -> Render ()

-- | Gets the current line join style, as set by <a>setLineJoin</a>.
getLineJoin :: Render LineJoin

-- | Sets the current line width within the cairo context. The line width
--   specifies the diameter of a pen that is circular in user-space.
--   
--   As with the other stroke parameters, the current line cap style is
--   examined by <a>stroke</a>, <a>strokeExtents</a>, and
--   <tt>strokeToPath</tt>, but does not have any effect during path
--   construction.
setLineWidth :: Double -> Render ()

-- | Gets the current line width, as set by <a>setLineWidth</a>.
getLineWidth :: Render Double
setMiterLimit :: Double -> Render ()

-- | Gets the current miter limit, as set by <a>setMiterLimit</a>.
getMiterLimit :: Render Double

-- | Sets the compositing operator to be used for all drawing operations.
--   See <a>Operator</a> for details on the semantics of each available
--   compositing operator.
setOperator :: Operator -> Render ()

-- | Gets the current compositing operator for a cairo context.
getOperator :: Render Operator

-- | Sets the tolerance used when converting paths into trapezoids. Curved
--   segments of the path will be subdivided until the maximum deviation
--   between the original path and the polygonal approximation is less than
--   tolerance. The default value is 0.1. A larger value will give better
--   performance, a smaller value, better appearance. (Reducing the value
--   from the default value of 0.1 is unlikely to improve appearance
--   significantly.)
setTolerance :: Double -> Render ()

-- | Gets the current tolerance value, as set by <a>setTolerance</a>.
getTolerance :: Render Double

-- | Establishes a new clip region by intersecting the current clip region
--   with the current path as it would be filled by <a>fill</a> and
--   according to the current fill rule (see <a>setFillRule</a>).
--   
--   After <a>clip</a>, the current path will be cleared from the cairo
--   context.
--   
--   The current clip region affects all drawing operations by effectively
--   masking out any changes to the surface that are outside the current
--   clip region.
--   
--   Calling <a>clip</a> can only make the clip region smaller, never
--   larger. But the current clip is part of the graphics state, so a
--   temporary restriction of the clip region can be achieved by calling
--   <a>clip</a> within a 'save'/'restore' pair. The only other means of
--   increasing the size of the clip region is <a>resetClip</a>.
clip :: Render ()

-- | Establishes a new clip region by intersecting the current clip region
--   with the current path as it would be filled by <a>fill</a> and
--   according to the current fill rule (see <a>setFillRule</a>).
--   
--   Unlike <a>clip</a>, cairoClipPreserve preserves the path within the
--   cairo context.
--   
--   The current clip region affects all drawing operations by effectively
--   masking out any changes to the surface that are outside the current
--   clip region.
--   
--   Calling <a>clip</a> can only make the clip region smaller, never
--   larger. But the current clip is part of the graphics state, so a
--   temporary restriction of the clip region can be achieved by calling
--   <a>clip</a> within a 'save'/'restore' pair. The only other means of
--   increasing the size of the clip region is <a>resetClip</a>.
clipPreserve :: Render ()

-- | Computes a bounding box in user coordinates covering the area inside
--   the current clip.
clipExtents :: Render (Double, Double, Double, Double)

-- | Reset the current clip region to its original, unrestricted state.
--   That is, set the clip region to an infinitely large shape containing
--   the target surface. Equivalently, if infinity is too hard to grasp,
--   one can imagine the clip region being reset to the exact bounds of the
--   target surface.
--   
--   Note that code meant to be reusable should not call <a>resetClip</a>
--   as it will cause results unexpected by higher-level code which calls
--   <a>clip</a>. Consider using <a>save</a> and <a>restore</a> around
--   <a>clip</a> as a more robust means of temporarily restricting the clip
--   region.
resetClip :: Render ()

-- | A drawing operator that fills the current path according to the
--   current fill rule, (each sub-path is implicitly closed before being
--   filled). After <a>fill</a>, the current path will be cleared from the
--   cairo context.
--   
--   See <a>setFillRule</a> and <a>fillPreserve</a>.
fill :: Render ()

-- | A drawing operator that fills the current path according to the
--   current fill rule, (each sub-path is implicitly closed before being
--   filled). Unlike <a>fill</a>, <a>fillPreserve</a> preserves the path
--   within the cairo context.
--   
--   See <a>setFillRule</a> and <a>fill</a>.
fillPreserve :: Render ()
fillExtents :: Render (Double, Double, Double, Double)
inFill :: Double -> Double -> Render Bool

-- | A drawing operator that paints the current source using the alpha
--   channel of pattern as a mask. (Opaque areas of mask are painted with
--   the source, transparent areas are not painted.)
mask :: Pattern -> Render ()

-- | A drawing operator that paints the current source using the alpha
--   channel of surface as a mask. (Opaque areas of surface are painted
--   with the source, transparent areas are not painted.)
maskSurface :: Surface -> Double -> Double -> Render ()

-- | A drawing operator that paints the current source everywhere within
--   the current clip region.
paint :: Render ()

-- | A drawing operator that paints the current source everywhere within
--   the current clip region using a mask of constant alpha value alpha.
--   The effect is similar to <a>paint</a>, but the drawing is faded out
--   using the alpha value.
paintWithAlpha :: Double -> Render ()

-- | A drawing operator that strokes the current path according to the
--   current line width, line join, line cap, and dash settings. After
--   issuing <a>stroke</a>, the current path will be cleared from the
--   <a>Render</a> monad.
--   
--   See <a>setLineWidth</a>, <a>setLineJoin</a>, <a>setLineCap</a>,
--   <a>setDash</a>, and <a>strokePreserve</a>.
stroke :: Render ()

-- | A drawing operator that strokes the current path according to the
--   current line width, line join, line cap, and dash settings. Unlike
--   <a>stroke</a>, <a>strokePreserve</a> preserves the path within the
--   <a>Render</a> monad.
--   
--   See <a>setLineWidth</a>, <a>setLineJoin</a>, <a>setLineCap</a>,
--   <a>setDash</a>, and <a>strokePreserve</a>.
strokePreserve :: Render ()
strokeExtents :: Render (Double, Double, Double, Double)
inStroke :: Double -> Double -> Render Bool
copyPage :: Render ()
showPage :: Render ()

-- | Gets the current point of the current path, which is conceptually the
--   final point reached by the path so far.
--   
--   The current point is returned in the user-space coordinate system. If
--   there is no defined current point then x and y will both be set to
--   0.0.
--   
--   Most path construction functions alter the current point. See the
--   following for details on how they affect the current point:
--   <a>newPath</a>, <a>moveTo</a>, <a>lineTo</a>, <a>curveTo</a>,
--   <a>arc</a>, <a>relMoveTo</a>, <a>relLineTo</a>, <a>relCurveTo</a>,
--   <a>arcNegative</a>, <a>textPath</a>, <tt>strokeToPath</tt>.
getCurrentPoint :: Render (Double, Double)

-- | Clears the current path. After this call there will be no current
--   point.
newPath :: Render ()

-- | Adds a line segment to the path from the current point to the
--   beginning of the current subpath, (the most recent point passed to
--   <a>moveTo</a>), and closes this subpath.
--   
--   The behavior of <a>closePath</a> is distinct from simply calling
--   <a>lineTo</a> with the equivalent coordinate in the case of stroking.
--   When a closed subpath is stroked, there are no caps on the ends of the
--   subpath. Instead, their is a line join connecting the final and
--   initial segments of the subpath.
closePath :: Render ()

-- | Adds a circular arc of the given radius to the current path. The arc
--   is centered at (<tt>xc</tt>, <tt>yc</tt>), begins at <tt>angle1</tt>
--   and proceeds in the direction of increasing angles to end at
--   <tt>angle2</tt>. If <tt>angle2</tt> is less than <tt>angle1</tt> it
--   will be progressively increased by <tt>2*pi</tt> until it is greater
--   than <tt>angle1</tt>.
--   
--   If there is a current point, an initial line segment will be added to
--   the path to connect the current point to the beginning of the arc.
--   
--   Angles are measured in radians. An angle of 0 is in the direction of
--   the positive X axis (in user-space). An angle of <tt>pi/2</tt> radians
--   (90 degrees) is in the direction of the positive Y axis (in
--   user-space). Angles increase in the direction from the positive X axis
--   toward the positive Y axis. So with the default transformation matrix,
--   angles increase in a clockwise direction.
--   
--   (To convert from degrees to radians, use <tt>degrees * (pi /
--   180)</tt>.)
--   
--   This function gives the arc in the direction of increasing angles; see
--   <a>arcNegative</a> to get the arc in the direction of decreasing
--   angles.
--   
--   The arc is circular in user-space. To achieve an elliptical arc, you
--   can scale the current transformation matrix by different amounts in
--   the X and Y directions. For example, to draw an ellipse in the box
--   given by x, y, width, height:
--   
--   <pre>
--   save
--   translate (x + width / 2) (y + height / 2)
--   scale (1 / (height / 2.)) (1 / (width / 2))
--   arc 0 0 1 0 (2 * pi)
--   restore
--   </pre>
arc :: Double -> Double -> Double -> Double -> Double -> Render ()

-- | Adds a circular arc of the given radius to the current path. The arc
--   is centered at (<tt>xc</tt>, <tt>yc</tt>), begins at <tt>angle1</tt>
--   and proceeds in the direction of decreasing angles to end at
--   <tt>angle2</tt>. If <tt>angle2</tt> is greater than <tt>angle1</tt> it
--   will be progressively decreased by 2*<tt>pi</tt> until it is greater
--   than <tt>angle1</tt>.
--   
--   See <a>arc</a> for more details. This function differs only in the
--   direction of the arc between the two angles.
arcNegative :: Double -> Double -> Double -> Double -> Double -> Render ()

-- | Adds a cubic Bezier spline to the path from the current point to
--   position (<tt>x3</tt>, <tt>y3</tt>) in user-space coordinates, using
--   (<tt>x1</tt>, <tt>y1</tt>) and (<tt>x2</tt>, <tt>y2</tt>) as the
--   control points. After this call the current point will be
--   (<tt>x3</tt>, <tt>y3</tt>).
curveTo :: Double -> Double -> Double -> Double -> Double -> Double -> Render ()

-- | Adds a line to the path from the current point to position
--   (<tt>x</tt>, <tt>y</tt>) in user-space coordinates. After this call
--   the current point will be (<tt>x</tt>, <tt>y</tt>).
lineTo :: Double -> Double -> Render ()

-- | If the current subpath is not empty, begin a new subpath. After this
--   call the current point will be (<tt>x</tt>, <tt>y</tt>).
moveTo :: Double -> Double -> Render ()

-- | Adds a closed-subpath rectangle of the given size to the current path
--   at position (<tt>x</tt>, <tt>y</tt>) in user-space coordinates.
rectangle :: Double -> Double -> Double -> Double -> Render ()

-- | Render text at the current path.
--   
--   <ul>
--   <li>See <a>showText</a> for why you should use Gtk functions.</li>
--   </ul>
textPath :: CairoString string => string -> Render ()

-- | Relative-coordinate version of <a>curveTo</a>. All offsets are
--   relative to the current point. Adds a cubic Bezier spline to the path
--   from the current point to a point offset from the current point by
--   (<tt>dx3</tt>, <tt>dy3</tt>), using points offset by (<tt>dx1</tt>,
--   <tt>dy1</tt>) and (<tt>dx2</tt>, <tt>dy2</tt>) as the control points.
--   After this call the current point will be offset by (<tt>dx3</tt>,
--   <tt>dy3</tt>).
--   
--   Given a current point of (x, y), relCurveTo <tt>dx1</tt> <tt>dy1</tt>
--   <tt>dx2</tt> <tt>dy2</tt> <tt>dx3</tt> <tt>dy3</tt> is logically
--   equivalent to curveTo (x + <tt>dx1</tt>) (y + <tt>dy1</tt>) (x +
--   <tt>dx2</tt>) (y + <tt>dy2</tt>) (x + <tt>dx3</tt>) (y +
--   <tt>dy3</tt>).
relCurveTo :: Double -> Double -> Double -> Double -> Double -> Double -> Render ()

-- | Relative-coordinate version of <a>lineTo</a>. Adds a line to the path
--   from the current point to a point that is offset from the current
--   point by (<tt>dx</tt>, <tt>dy</tt>) in user space. After this call the
--   current point will be offset by (<tt>dx</tt>, <tt>dy</tt>).
--   
--   Given a current point of (x, y), relLineTo <tt>dx</tt> <tt>dy</tt> is
--   logically equivalent to lineTo (x + <tt>dx</tt>) (y + <tt>dy</tt>).
relLineTo :: Double -> Double -> Render ()

-- | If the current subpath is not empty, begin a new subpath. After this
--   call the current point will offset by (x, y).
--   
--   Given a current point of (x, y), relMoveTo <tt>dx</tt> <tt>dy</tt> is
--   logically equivalent to moveTo (x + <tt>dx</tt>) (y + <tt>dy</tt>)
relMoveTo :: Double -> Double -> Render ()

-- | Creates a new <a>Pattern</a> corresponding to an opaque color. The
--   color components are floating point numbers in the range 0 to 1. If
--   the values passed in are outside that range, they will be clamped.
--   
--   For example to create a solid red pattern:
--   
--   <pre>
--   withRBGPattern 1 0 0 $ do
--     ...
--     ...
--   </pre>
withRGBPattern :: Double -> Double -> Double -> (Pattern -> Render a) -> Render a

-- | Creates a new <a>Pattern</a> corresponding to a translucent color. The
--   color components are floating point numbers in the range 0 to 1. If
--   the values passed in are outside that range, they will be clamped.
--   
--   For example to create a solid red pattern at 50% transparency:
--   
--   <pre>
--   withRBGPattern 1 0 0 0.5 $ do
--     ...
--     ...
--   </pre>
withRGBAPattern :: Double -> Double -> Double -> Double -> (Pattern -> Render a) -> Render a

-- | Create a new <a>Pattern</a> for the given surface.
withPatternForSurface :: Surface -> (Pattern -> Render a) -> Render a

-- | Pop the current group from the group stack and use it as a pattern.
--   The group should be populated first by calling <a>pushGroup</a> or
--   <a>pushGroupWithContent</a> and doing some drawing operations. This
--   also calls <a>restore</a> to balance the <a>save</a> called in
--   <a>pushGroup</a>.
withGroupPattern :: (Pattern -> Render a) -> Render a

-- | Create a new linear gradient <a>Pattern</a> along the line defined by
--   <tt>(x0, y0)</tt> and <tt>(x1, y1)</tt>. Before using the gradient
--   pattern, a number of color stops should be defined using
--   <a>patternAddColorStopRGB</a> and <a>patternAddColorStopRGBA</a>.
--   
--   <ul>
--   <li>Note: The coordinates here are in pattern space. For a new
--   pattern, pattern space is identical to user space, but the
--   relationship between the spaces can be changed with
--   <a>patternSetMatrix</a>.</li>
--   </ul>
withLinearPattern :: Double -> Double -> Double -> Double -> (Pattern -> Render a) -> Render a

-- | Creates a new radial gradient <a>Pattern</a> between the two circles
--   defined by <tt>(x0, y0, c0)</tt> and <tt>(x1, y1, c0)</tt>. Before
--   using the gradient pattern, a number of color stops should be defined
--   using <a>patternAddColorStopRGB</a> or <a>patternAddColorStopRGBA</a>.
--   
--   <ul>
--   <li>Note: The coordinates here are in pattern space. For a new
--   pattern, pattern space is identical to user space, but the
--   relationship between the spaces can be changed with
--   <a>patternSetMatrix</a>.</li>
--   </ul>
withRadialPattern :: Double -> Double -> Double -> Double -> Double -> Double -> (Pattern -> Render a) -> Render a

-- | Adds an opaque color stop to a gradient pattern. The offset specifies
--   the location along the gradient's control vector. For example, a
--   linear gradient's control vector is from (x0,y0) to (x1,y1) while a
--   radial gradient's control vector is from any point on the start circle
--   to the corresponding point on the end circle.
--   
--   The color is specified in the same way as in <a>setSourceRGB</a>.
--   
--   Note: If the pattern is not a gradient pattern, (eg. a linear or
--   radial pattern), then the pattern will be put into an error status
--   with a status of <a>StatusPatternTypeMismatch</a>.
patternAddColorStopRGB :: MonadIO m => Pattern -> Double -> Double -> Double -> Double -> m ()

-- | Adds a translucent color stop to a gradient pattern. The offset
--   specifies the location along the gradient's control vector. For
--   example, a linear gradient's control vector is from (x0,y0) to (x1,y1)
--   while a radial gradient's control vector is from any point on the
--   start circle to the corresponding point on the end circle.
--   
--   The color is specified in the same way as in setSourceRGBA.
--   
--   Note: If the pattern is not a gradient pattern, (eg. a linear or
--   radial pattern), then the pattern will be put into an error status
--   with a status of <a>StatusPatternTypeMismatch</a>.
patternAddColorStopRGBA :: MonadIO m => Pattern -> Double -> Double -> Double -> Double -> Double -> m ()

-- | Sets the pattern's transformation matrix to matrix. This matrix is a
--   transformation from user space to pattern space.
--   
--   When a pattern is first created it always has the identity matrix for
--   its transformation matrix, which means that pattern space is initially
--   identical to user space.
--   
--   Important: Please note that the direction of this transformation
--   matrix is from user space to pattern space. This means that if you
--   imagine the flow from a pattern to user space (and on to device
--   space), then coordinates in that flow will be transformed by the
--   inverse of the pattern matrix.
--   
--   Also, please note the discussion of the user-space locking semantics
--   of <a>setSource</a>.
patternSetMatrix :: MonadIO m => Pattern -> Matrix -> m ()

-- | Get the pattern's transformation matrix.
patternGetMatrix :: MonadIO m => Pattern -> m Matrix
patternSetExtend :: MonadIO m => Pattern -> Extend -> m ()
patternGetExtend :: MonadIO m => Pattern -> m Extend
patternSetFilter :: MonadIO m => Pattern -> Filter -> m ()
patternGetFilter :: MonadIO m => Pattern -> m Filter

-- | Modifies the current transformation matrix (CTM) by translating the
--   user-space origin by <tt>(tx, ty)</tt>. This offset is interpreted as
--   a user-space coordinate according to the CTM in place before the new
--   call to <a>translate</a>. In other words, the translation of the
--   user-space origin takes place after any existing transformation.
translate :: Double -> Double -> Render ()

-- | Modifies the current transformation matrix (CTM) by scaling the X and
--   Y user-space axes by sx and sy respectively. The scaling of the axes
--   takes place after any existing transformation of user space.
scale :: Double -> Double -> Render ()

-- | Modifies the current transformation matrix (CTM) by rotating the
--   user-space axes by <tt>angle</tt> radians. The rotation of the axes
--   takes places after any existing transformation of user space. The
--   rotation direction for positive angles is from the positive X axis
--   toward the positive Y axis.
rotate :: Double -> Render ()

-- | Modifies the current transformation matrix (CTM) by applying matrix as
--   an additional transformation. The new transformation of user space
--   takes place after any existing transformation.
transform :: Matrix -> Render ()

-- | Modifies the current transformation matrix (CTM) by setting it equal
--   to <tt>matrix</tt>.
setMatrix :: Matrix -> Render ()

-- | Gets the current transformation matrix, as set by <a>setMatrix</a>.
getMatrix :: Render Matrix

-- | Resets the current transformation matrix (CTM) by setting it equal to
--   the identity matrix. That is, the user-space and device-space axes
--   will be aligned and one user-space unit will transform to one
--   device-space unit.
identityMatrix :: Render ()

-- | Transform a coordinate from user space to device space by multiplying
--   the given point by the current transformation matrix (CTM).
userToDevice :: Double -> Double -> Render (Double, Double)

-- | Transform a distance vector from user space to device space. This
--   function is similar to <a>userToDevice</a> except that the translation
--   components of the CTM will be ignored when transforming
--   <tt>(dx,dy)</tt>.
userToDeviceDistance :: Double -> Double -> Render (Double, Double)

-- | Transform a coordinate from device space to user space by multiplying
--   the given point by the inverse of the current transformation matrix
--   (CTM).
deviceToUser :: Double -> Double -> Render (Double, Double)

-- | Transform a distance vector from device space to user space. This
--   function is similar to <a>deviceToUser</a> except that the translation
--   components of the inverse CTM will be ignored when transforming
--   <tt>(dx,dy)</tt>.
deviceToUserDistance :: Double -> Double -> Render (Double, Double)

-- | Selects a family and style of font from a simplified description as a
--   <tt>family</tt> name, <tt>slant</tt> and <tt>weight</tt>. This
--   function is meant to be used only for applications with simple font
--   needs: Cairo doesn't provide for operations such as listing all
--   available fonts on the system, and it is expected that most
--   applications will need to use a more comprehensive font handling and
--   text layout library in addition to cairo.
selectFontFace :: CairoString string => string -> FontSlant -> FontWeight -> Render ()

-- | Sets the current font matrix to a scale by a factor of <tt>size</tt>,
--   replacing any font matrix previously set with <a>setFontSize</a> or
--   <a>setFontMatrix</a>. This results in a font size of size user space
--   units. (More precisely, this matrix will result in the font's
--   em-square being a size by size square in user space.)
setFontSize :: Double -> Render ()

-- | Sets the current font matrix to <tt>matrix</tt>. The font matrix gives
--   a transformation from the design space of the font (in this space, the
--   em-square is 1 unit by 1 unit) to user space. Normally, a simple scale
--   is used (see <a>setFontSize</a>), but a more complex font matrix can
--   be used to shear the font or stretch it unequally along the two axes.
setFontMatrix :: Matrix -> Render ()

-- | Gets the current font matrix, as set by <a>setFontMatrix</a>
getFontMatrix :: Render Matrix

-- | Sets a set of custom font rendering options. Rendering options are
--   derived by merging these options with the options derived from
--   underlying surface; if the value in <tt>options</tt> has a default
--   value (like <a>AntialiasDefault</a>), then the value from the surface
--   is used.
setFontOptions :: FontOptions -> Render ()

-- | A drawing operator that generates the shape from a string of Unicode
--   characters, rendered according to the current font face, font size
--   (font matrix), and font options.
--   
--   This function first computes a set of glyphs for the string of text.
--   The first glyph is placed so that its origin is at the current point.
--   The origin of each subsequent glyph is offset from that of the
--   previous glyph by the advance values of the previous glyph.
--   
--   After this call the current point is moved to the origin of where the
--   next glyph would be placed in this same progression. That is, the
--   current point will be at the origin of the final glyph offset by its
--   advance values. This allows for easy display of a single logical
--   string with multiple calls to <a>showText</a>.
--   
--   NOTE: The <a>showText</a> function call is part of what the cairo
--   designers call the "toy" text API. It is convenient for short demos
--   and simple programs, but it is not expected to be adequate for the
--   most serious of text-using applications.
showText :: CairoString string => string -> Render ()

-- | Gets the font extents for the currently selected font.
fontExtents :: Render FontExtents

-- | Gets the extents for a string of text. The extents describe a
--   user-space rectangle that encloses the "inked" portion of the text,
--   (as it would be drawn by <a>showText</a>). Additionally, the
--   <a>textExtentsXadvance</a> and <a>textExtentsYadvance</a> values
--   indicate the amount by which the current point would be advanced by
--   <a>showText</a>.
--   
--   Note that whitespace characters do not directly contribute to the size
--   of the rectangle (<a>textExtentsWidth</a> and
--   <a>textExtentsHeight</a>). They do contribute indirectly by changing
--   the position of non-whitespace characters. In particular, trailing
--   whitespace characters are likely to not affect the size of the
--   rectangle, though they will affect the <a>textExtentsXadvance</a> and
--   <a>textExtentsYadvance</a> values.
textExtents :: CairoString string => string -> Render TextExtents

-- | Allocates a new font options object with all options initialized to
--   default values.
fontOptionsCreate :: MonadIO m => m FontOptions

-- | Allocates a new font options object copying the option values from
--   <tt>original</tt>.
fontOptionsCopy :: MonadIO m => FontOptions -> m FontOptions

-- | Merges non-default options from <tt>other</tt> into <tt>options</tt>,
--   replacing existing values. This operation can be thought of as
--   somewhat similar to compositing <tt>other</tt> onto <tt>options</tt>
--   with the operation of <tt>OperationOver</tt>.
fontOptionsMerge :: MonadIO m => FontOptions -> FontOptions -> m ()

-- | Compute a hash for the font options object; this value will be useful
--   when storing an object containing a <a>FontOptions</a> in a hash
--   table.
fontOptionsHash :: MonadIO m => FontOptions -> m Int

-- | Compares two font options objects for equality.
fontOptionsEqual :: MonadIO m => FontOptions -> FontOptions -> m Bool

-- | Sets the antiliasing mode for the font options object. This specifies
--   the type of antialiasing to do when rendering text.
fontOptionsSetAntialias :: MonadIO m => FontOptions -> Antialias -> m ()

-- | Gets the antialising mode for the font options object.
fontOptionsGetAntialias :: MonadIO m => FontOptions -> m Antialias

-- | Sets the subpixel order for the font options object. The subpixel
--   order specifies the order of color elements within each pixel on the
--   display device when rendering with an antialiasing mode of
--   <a>AntialiasSubpixel</a>. See the documentation for
--   <a>SubpixelOrder</a> for full details.
fontOptionsSetSubpixelOrder :: MonadIO m => FontOptions -> SubpixelOrder -> m ()

-- | Gets the subpixel order for the font options object. See the
--   documentation for <a>SubpixelOrder</a> for full details.
fontOptionsGetSubpixelOrder :: MonadIO m => FontOptions -> m SubpixelOrder

-- | Sets the hint style for font outlines for the font options object.
--   This controls whether to fit font outlines to the pixel grid, and if
--   so, whether to optimize for fidelity or contrast. See the
--   documentation for <a>HintStyle</a> for full details.
fontOptionsSetHintStyle :: MonadIO m => FontOptions -> HintStyle -> m ()

-- | Gets the hint style for font outlines for the font options object. See
--   the documentation for <a>HintStyle</a> for full details.
fontOptionsGetHintStyle :: MonadIO m => FontOptions -> m HintStyle

-- | Sets the metrics hinting mode for the font options object. This
--   controls whether metrics are quantized to integer values in device
--   units. See the documentation for <a>HintMetrics</a> for full details.
fontOptionsSetHintMetrics :: MonadIO m => FontOptions -> HintMetrics -> m ()

-- | Gets the metrics hinting mode for the font options object. See the
--   documentation for <a>HintMetrics</a> for full details.
fontOptionsGetHintMetrics :: MonadIO m => FontOptions -> m HintMetrics

-- | Create a temporary surface that is as compatible as possible with an
--   existing surface. The new surface will use the same backend as other
--   unless that is not possible for some reason.
withSimilarSurface :: Surface -> Content -> Int -> Int -> (Surface -> IO a) -> IO a

-- | Like <a>withSimilarSurface</a> but creates a Surface that is managed
--   by the Haskell memory manager rather than only being temporaily
--   allocated. This is more flexible and allows you to create surfaces
--   that persist, which can be very useful, for example to cache static
--   elements in an animation.
--   
--   However you should be careful because surfaces can be expensive
--   resources and the Haskell memory manager cannot guarantee when it will
--   release them. You can manually release the resources used by a surface
--   with <a>surfaceFinish</a>.
createSimilarSurface :: Surface -> Content -> Int -> Int -> IO Surface

-- | Create a temporary surface that is compatible with the current target
--   surface (like a combination of <a>withTargetSurface</a> and
--   <a>withSimilarSurface</a>).
--   
--   This is useful for drawing to a temporary surface and then compositing
--   it into the main suface. For example, the following code draws to a
--   temporary surface and then uses that as a mask:
--   
--   <pre>
--   renderWithSimilarSurface ContentAlpha 200 200 $ \tmpSurface -&gt; do
--     renderWith tmpSurface $ do
--       ... -- draw onto the temporary surface
--   
--     -- use the temporary surface as a mask, filling it with the
--     -- current source which in this example is transparent red.
--     setSourceRGBA 1 0 0 0.5
--     setOperator Operator{something} -- think of something clever to do
--     maskSurface tmpSurface 0 0)
--   </pre>
renderWithSimilarSurface :: Content -> Int -> Int -> (Surface -> Render a) -> Render a

-- | Retrieves the default font rendering options for the surface. This
--   allows display surfaces to report the correct subpixel order for
--   rendering on them, print surfaces to disable hinting of metrics and so
--   forth. The result can then be used with <tt>scaledFontCreate</tt>.
surfaceGetFontOptions :: Surface -> Render FontOptions

-- | This function finishes the surface and drops all references to
--   external resources. For example, for the Xlib backend it means that
--   cairo will no longer access the drawable, which can be freed. After
--   calling <a>surfaceFinish</a> the only valid operations on a surface
--   are getting and setting user data and referencing and destroying it.
--   Further drawing to the surface will not affect the surface but will
--   instead trigger a <a>StatusSurfaceFinished</a> error.
--   
--   When the last call to <tt>surfaceDestroy</tt> decreases the reference
--   count to zero, cairo will call <a>surfaceFinish</a> if it hasn't been
--   called already, before freeing the resources associated with the
--   surface.
surfaceFinish :: MonadIO m => Surface -> m ()

-- | Do any pending drawing for the surface and also restore any temporary
--   modification's cairo has made to the surface's state. This function
--   must be called before switching from drawing on the surface with cairo
--   to drawing on it directly with native APIs. If the surface doesn't
--   support direct access, then this function does nothing.
surfaceFlush :: MonadIO m => Surface -> m ()

-- | Tells cairo that drawing has been done to surface using means other
--   than cairo, and that cairo should reread any cached areas. Note that
--   you must call <a>surfaceFlush</a> before doing such drawing.
surfaceMarkDirty :: MonadIO m => Surface -> m ()

-- | Like <a>surfaceMarkDirty</a>, but drawing has been done only to the
--   specified rectangle, so that cairo can retain cached contents for
--   other parts of the surface.
surfaceMarkDirtyRectangle :: MonadIO m => Surface -> Int -> Int -> Int -> Int -> m ()

-- | Sets an offset that is added to the device coordinates determined by
--   the CTM when drawing to surface. One use case for this function is
--   when we want to create a <a>Surface</a> that redirects drawing for a
--   portion of an onscreen surface to an offscreen surface in a way that
--   is completely invisible to the user of the cairo API. Setting a
--   transformation via <a>translate</a> isn't sufficient to do this, since
--   functions like <a>deviceToUser</a> will expose the hidden offset.
--   
--   Note that the offset only affects drawing to the surface, not using
--   the surface in a surface pattern.
surfaceSetDeviceOffset :: MonadIO m => Surface -> Double -> Double -> m ()

-- | Creates an image surface of the specified format and dimensions. The
--   initial contents of the surface is undefined; you must explicitely
--   clear the buffer, using, for example, <a>rectangle</a> and <a>fill</a>
--   if you want it cleared.
withImageSurface :: Format -> Int -> Int -> (Surface -> IO a) -> IO a

-- | Like <a>withImageSurface</a> but creating a surface to target external
--   data pointed to by <a>PixelData</a>.
withImageSurfaceForData :: PixelData -> Format -> Int -> Int -> Int -> (Surface -> IO a) -> IO a

-- | This function provides a stride value that will respect all alignment
--   requirements of the accelerated image-rendering code within cairo.
formatStrideForWidth :: Format -> Int -> Int

-- | Like <a>createImageSurface</a> but creating a surface to target
--   external data pointed to by <a>PixelData</a>.
createImageSurfaceForData :: PixelData -> Format -> Int -> Int -> Int -> IO Surface

-- | Like <a>withImageSurface</a> but creates a Surface that is managed by
--   the Haskell memory manager rather than only being temporaily
--   allocated. This is more flexible and allows you to create surfaces
--   that persist, which can be very useful, for example to cache static
--   elements in an animation.
--   
--   However you should be careful because surfaces can be expensive
--   resources and the Haskell memory manager cannot guarantee when it will
--   release them. You can manually release the resources used by a surface
--   with <a>surfaceFinish</a>.
createImageSurface :: Format -> Int -> Int -> IO Surface

-- | Get the width of the image surface in pixels.
imageSurfaceGetWidth :: MonadIO m => Surface -> m Int

-- | Get the height of the image surface in pixels.
imageSurfaceGetHeight :: MonadIO m => Surface -> m Int

-- | Get the format of the surface.
imageSurfaceGetFormat :: MonadIO m => Surface -> m Format

-- | Get the number of bytes from the start of one row to the start of the
--   next. If the image data contains no padding, then this is equal to the
--   pixel depth * the width.
imageSurfaceGetStride :: MonadIO m => Surface -> m Int

-- | Return a ByteString of the image data for a surface. In order to
--   remain safe the returned ByteString is a copy of the data. This is a
--   little slower than returning a pointer into the image surface object
--   itself, but much safer
imageSurfaceGetData :: Surface -> IO ByteString

-- | An array that stores the raw pixel data of an image <a>Surface</a>.
data SurfaceData i e

-- | Retrieve the internal array of raw image data.
--   
--   <ul>
--   <li>Image data in an image surface is stored in memory in
--   uncompressed, packed format. Rows in the image are stored top to
--   bottom, and in each row pixels are stored from left to right. There
--   may be padding at the end of a row. The value returned by
--   <a>imageSurfaceGetStride</a> indicates the number of bytes between
--   rows.</li>
--   <li>The returned array is a flat representation of a three dimensional
--   array: x-coordiante, y-coordinate and several channels for each color.
--   The format depends on the <a>Format</a> of the surface:</li>
--   </ul>
--   
--   <a>FormatARGB32</a>: each pixel is 32 bits with alpha in the upper 8
--   bits, followed by 8 bits for red, green and blue. Pre-multiplied alpha
--   is used. (That is, 50% transparent red is 0x80800000, not 0x80ff0000.)
--   
--   <a>FormatRGB24</a>: each pixel is 32 bits with the upper 8 bits being
--   unused, followed by 8 bits for red, green and blue.
--   
--   <a>FormatA8</a>: each pixel is 8 bits holding an alpha value
--   
--   <a>FormatA1</a>: each pixel is one bit where pixels are packed into 32
--   bit quantities. The ordering depends on the endianes of the platform.
--   On a big-endian machine, the first pixel is in the uppermost bit, on a
--   little-endian machine the first pixel is in the least-significant bit.
--   
--   <ul>
--   <li>To read or write a specific pixel (and assuming
--   <a>FormatARGB32</a> or <a>FormatRGB24</a>), use the formula: <tt>p = y
--   * (rowstride <a>div</a> 4) + x</tt> for the pixel and force the array
--   to have 32-bit words or integers.</li>
--   <li>Calling this function without explicitly giving it a type will
--   often lead to a compiler error since the type parameter <tt>e</tt> is
--   underspecified. If this happens the function can be explicitly typed:
--   <tt>surData &lt;- (imageSurfaceGetPixels pb :: IO (SurfaceData Int
--   Word32))</tt></li>
--   <li>If modifying an image through Haskell's array interface is not
--   fast enough, it is possible to use <a>unsafeRead</a> and
--   <a>unsafeWrite</a> which have the same type signatures as
--   <tt>readArray</tt> and <tt>writeArray</tt>. Note that these are
--   internal functions that might change with GHC.</li>
--   <li>After each write access to the array, you need to inform Cairo
--   about the area that has changed using <a>surfaceMarkDirty</a>.</li>
--   <li>The function will return an error if the surface is not an image
--   surface or if <a>surfaceFinish</a> has been called on the
--   surface.</li>
--   </ul>
imageSurfaceGetPixels :: Storable e => Surface -> IO (SurfaceData Int e)

-- | Creates a new image surface and initializes the contents to the given
--   PNG file.
withImageSurfaceFromPNG :: FilePath -> (Surface -> IO a) -> IO a
imageSurfaceCreateFromPNG :: FilePath -> IO Surface

-- | Writes the contents of surface to a new file <tt>filename</tt> as a
--   PNG image.
surfaceWriteToPNG :: Surface -> FilePath -> IO ()

-- | Creates a PostScript surface of the specified size in points to be
--   written to <tt>filename</tt>.
--   
--   Note that the size of individual pages of the PostScript output can
--   vary. See <a>psSurfaceSetSize</a>.
withPDFSurface :: FilePath -> Double -> Double -> (Surface -> IO a) -> IO a

-- | Changes the size of a PDF surface for the current (and subsequent)
--   pages.
--   
--   This function should only be called before any drawing operations have
--   been performed on the current page. The simplest way to do this is to
--   call this function immediately after creating the surface or
--   immediately after completing a page with either <a>showPage</a> or
--   <a>copyPage</a>.
pdfSurfaceSetSize :: MonadIO m => Surface -> Double -> Double -> m ()

-- | Creates a PostScript surface of the specified size in points to be
--   written to <tt>filename</tt>.
--   
--   Note that the size of individual pages of the PostScript output can
--   vary. See <a>psSurfaceSetSize</a>.
withPSSurface :: FilePath -> Double -> Double -> (Surface -> IO a) -> IO a

-- | Changes the size of a PostScript surface for the current (and
--   subsequent) pages.
--   
--   This function should only be called before any drawing operations have
--   been performed on the current page. The simplest way to do this is to
--   call this function immediately after creating the surface or
--   immediately after completing a page with either <a>showPage</a> or
--   <a>copyPage</a>.
psSurfaceSetSize :: MonadIO m => Surface -> Double -> Double -> m ()

-- | Creates a SVG surface of the specified size in points be written to
--   <tt>filename</tt>.
withSVGSurface :: FilePath -> Double -> Double -> (Surface -> IO a) -> IO a

-- | Allocates a new empty region object.
regionCreate :: MonadIO m => m Region

-- | Allocates a new region object containing <tt>rectangle</tt>.
regionCreateRectangle :: MonadIO m => RectangleInt -> m Region

-- | Allocates a new region object containing the union of all given
--   <tt>rects</tt>.
regionCreateRectangles :: MonadIO m => [RectangleInt] -> m Region

-- | Allocates a new region object copying the area from <tt>original</tt>.
regionCopy :: MonadIO m => Region -> m Region

-- | Gets the bounding rectangle of <tt>region</tt> as a RectanglInt.
regionGetExtents :: MonadIO m => Region -> m RectangleInt

-- | Returns the number of rectangles contained in <tt>region</tt>.
regionNumRectangles :: MonadIO m => Region -> m Int

-- | Gets the <tt>nth</tt> rectangle from the <tt>region</tt>.
regionGetRectangle :: MonadIO m => Region -> Int -> m RectangleInt

-- | Checks whether <tt>region</tt> is empty.
regionIsEmpty :: MonadIO m => Region -> m Bool

-- | Checks whether (<tt>x</tt>, <tt>y</tt>) is contained in
--   <tt>region</tt>.
regionContainsPoint :: MonadIO m => Region -> Int -> Int -> m Bool

-- | Checks whether <tt>rectangle</tt> is inside, outside or partially
--   contained in <tt>region</tt>.
regionContainsRectangle :: MonadIO m => Region -> RectangleInt -> m RegionOverlap

-- | Compares whether <tt>region_a</tt> is equivalent to <tt>region_b</tt>.
regionEqual :: MonadIO m => Region -> Region -> m Bool

-- | Translates <tt>region</tt> by (<tt>dx</tt>, <tt>dy</tt>).
regionTranslate :: MonadIO m => Region -> Int -> Int -> m ()

-- | Computes the intersection of <tt>dst</tt> with <tt>other</tt> and
--   places the result in <tt>dst</tt>.
regionIntersect :: MonadIO m => Region -> Region -> m ()

-- | Computes the intersection of <tt>dst</tt> with <tt>rectangle</tt> and
--   places the result in <tt>dst</tt>.
regionIntersectRectangle :: MonadIO m => Region -> RectangleInt -> m ()

-- | Subtracts <tt>other</tt> from <tt>dst</tt> and places the result in
--   <tt>dst</tt>.
regionSubtract :: MonadIO m => Region -> Region -> m ()

-- | Subtracts <tt>rectangle</tt> from <tt>dst</tt> and places the result
--   in <tt>dst</tt>.
regionSubtractRectangle :: MonadIO m => Region -> RectangleInt -> m ()

-- | Computes the union of <tt>dst</tt> with <tt>other</tt> and places the
--   result in <tt>dst</tt>.
regionUnion :: MonadIO m => Region -> Region -> m ()

-- | Computes the union of <tt>dst</tt> with <tt>rectangle</tt> and places
--   the result in <tt>dst</tt>.
regionUnionRectangle :: MonadIO m => Region -> RectangleInt -> m ()

-- | Computes the exclusive difference of <tt>dst</tt> with <tt>other</tt>
--   and places the result in <tt>dst</tt>. That is, <tt>dst</tt> will be
--   set to contain all areas that are either in <tt>dst</tt> or in
--   <tt>other</tt>, but not in both.
regionXor :: MonadIO m => Region -> Region -> m ()

-- | Computes the exclusive difference of <tt>dst</tt> with
--   <tt>rectangle</tt> and places the result in <tt>dst</tt>. That is,
--   <tt>dst</tt> will be set to contain all areas that are either in
--   <tt>dst</tt> or in <tt>rectangle</tt>, but not in both
regionXorRectangle :: MonadIO m => Region -> RectangleInt -> m ()

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => forall a. IO a -> m a

-- | Returns the version of the cairo library encoded in a single integer.
version :: Int

-- | Returns the version of the cairo library as a human-readable string of
--   the form "X.Y.Z".
versionString :: String
class CairoString s

-- | The Render monad. All drawing operations take place in a Render
--   context. You can obtain a Render context for a <a>Surface</a> using
--   <tt>renderWith</tt>.
data Render m

-- | Representation of a 2-D affine transformation.
--   
--   The Matrix type represents a 2x2 transformation matrix along with a
--   translation vector. <tt>Matrix a1 a2 b1 b2 c1 c2</tt> describes the
--   transformation of a point with coordinates x,y that is defined by
--   
--   <pre>
--   / x' \  =  / a1 b1 \  / x \  + / c1 \
--   \ y' /     \ a2 b2 /  \ y /    \ c2 /
--   </pre>
--   
--   or
--   
--   <pre>
--   x' =  a1 * x + b1 * y + c1
--   y' =  a2 * x + b2 * y + c2
--   </pre>
data Matrix

-- | The medium to draw on.
data Surface

-- | Patterns can be simple solid colors, various kinds of gradients or
--   bitmaps. The current pattern for a <tt>Render</tt> context is used by
--   the <tt>stroke</tt>, <tt>fill</tt> and paint operations. These
--   operations composite the current pattern with the target surface using
--   the currently selected <a>Operator</a>.
data Pattern

-- | Cairo status.
--   
--   <ul>
--   <li><a>Status</a> is used to indicate errors that can occur when using
--   Cairo. In some cases it is returned directly by functions. When using
--   <a>Render</a>, the last error, if any, is stored in the monad and can
--   be retrieved with <a>status</a>.</li>
--   </ul>
data Status
StatusSuccess :: Status
StatusNoMemory :: Status
StatusInvalidRestore :: Status
StatusInvalidPopGroup :: Status
StatusNoCurrentPoint :: Status
StatusInvalidMatrix :: Status
StatusInvalidStatus :: Status
StatusNullPointer :: Status
StatusInvalidString :: Status
StatusInvalidPathData :: Status
StatusReadError :: Status
StatusWriteError :: Status
StatusSurfaceFinished :: Status
StatusSurfaceTypeMismatch :: Status
StatusPatternTypeMismatch :: Status
StatusInvalidContent :: Status
StatusInvalidFormat :: Status
StatusInvalidVisual :: Status
StatusFileNotFound :: Status
StatusInvalidDash :: Status
StatusInvalidDscComment :: Status
StatusInvalidIndex :: Status
StatusClipNotRepresentable :: Status
StatusTempFileError :: Status
StatusInvalidStride :: Status
StatusFontTypeMismatch :: Status
StatusUserFontImmutable :: Status
StatusUserFontError :: Status
StatusNegativeCount :: Status
StatusInvalidClusters :: Status
StatusInvalidSlant :: Status
StatusInvalidWeight :: Status
StatusInvalidSize :: Status
StatusUserFontNotImplemented :: Status
StatusDeviceTypeMismatch :: Status
StatusDeviceError :: Status
StatusInvalidMeshConstruction :: Status
StatusDeviceFinished :: Status
StatusJbig2GlobalMissing :: Status
StatusLastStatus :: Status

-- | Composition operator for all drawing operations.
data Operator
OperatorClear :: Operator
OperatorSource :: Operator
OperatorOver :: Operator
OperatorIn :: Operator
OperatorOut :: Operator
OperatorAtop :: Operator
OperatorDest :: Operator
OperatorDestOver :: Operator
OperatorDestIn :: Operator
OperatorDestOut :: Operator
OperatorDestAtop :: Operator
OperatorXor :: Operator
OperatorAdd :: Operator
OperatorSaturate :: Operator
OperatorMultiply :: Operator
OperatorScreen :: Operator
OperatorOverlay :: Operator
OperatorDarken :: Operator
OperatorLighten :: Operator
OperatorColorDodge :: Operator
OperatorColorBurn :: Operator
OperatorHardLight :: Operator
OperatorSoftLight :: Operator
OperatorDifference :: Operator
OperatorExclusion :: Operator
OperatorHslHue :: Operator
OperatorHslSaturation :: Operator
OperatorHslColor :: Operator
OperatorHslLuminosity :: Operator

-- | Specifies the type of antialiasing to do when rendering text or shapes
--   
--   <ul>
--   <li><i><a>AntialiasDefault</a></i> Use the default antialiasing for
--   the subsystem and target device.</li>
--   <li><i><a>AntialiasNone</a></i> Use a bilevel alpha mask.</li>
--   <li><i><a>AntialiasGray</a></i> Perform single-color antialiasing
--   (using shades of gray for black text on a white background, for
--   example).</li>
--   <li><i><a>AntialiasSubpixel</a></i> Perform antialiasing by taking
--   advantage of the order of subpixel elements on devices such as LCD
--   panels.</li>
--   </ul>
data Antialias
AntialiasDefault :: Antialias
AntialiasNone :: Antialias
AntialiasGray :: Antialias
AntialiasSubpixel :: Antialias
AntialiasFast :: Antialias
AntialiasGood :: Antialias
AntialiasBest :: Antialias

-- | Specify how paths are filled.
--   
--   <ul>
--   <li>For both fill rules, whether or not a point is included in the
--   fill is determined by taking a ray from that point to infinity and
--   looking at intersections with the path. The ray can be in any
--   direction, as long as it doesn't pass through the end point of a
--   segment or have a tricky intersection such as intersecting tangent to
--   the path. (Note that filling is not actually implemented in this way.
--   This is just a description of the rule that is applied.)</li>
--   </ul>
--   
--   <ul>
--   <li><i><a>FillRuleWinding</a></i> If the path crosses the ray from
--   left-to-right, counts +1. If the path crosses the ray from right to
--   left, counts -1. (Left and right are determined from the perspective
--   of looking along the ray from the starting point.) If the total count
--   is non-zero, the point will be filled.</li>
--   <li><i><a>FillRuleEvenOdd</a></i> Counts the total number of
--   intersections, without regard to the orientation of the contour. If
--   the total number of intersections is odd, the point will be
--   filled.</li>
--   </ul>
data FillRule
FillRuleWinding :: FillRule
FillRuleEvenOdd :: FillRule

-- | Specify line endings.
--   
--   <ul>
--   <li><i><a>LineCapButt</a></i> Start(stop) the line exactly at the
--   start(end) point.</li>
--   <li><i><a>LineCapRound</a></i> Use a round ending, the center of the
--   circle is the end point.</li>
--   <li><i><a>LineCapSquare</a></i> Use squared ending, the center of the
--   square is the end point</li>
--   </ul>
data LineCap
LineCapButt :: LineCap
LineCapRound :: LineCap
LineCapSquare :: LineCap

-- | Specify how lines join.
data LineJoin
LineJoinMiter :: LineJoin
LineJoinRound :: LineJoin
LineJoinBevel :: LineJoin
data ScaledFont
data FontFace
data Glyph

-- | Specify the extents of a text.
data TextExtents
TextExtents :: Double -> Double -> Double -> Double -> Double -> Double -> TextExtents
[textExtentsXbearing] :: TextExtents -> Double
[textExtentsYbearing] :: TextExtents -> Double
[textExtentsWidth] :: TextExtents -> Double
[textExtentsHeight] :: TextExtents -> Double
[textExtentsXadvance] :: TextExtents -> Double
[textExtentsYadvance] :: TextExtents -> Double

-- | Result of querying the font extents.
data FontExtents
FontExtents :: Double -> Double -> Double -> Double -> Double -> FontExtents
[fontExtentsAscent] :: FontExtents -> Double
[fontExtentsDescent] :: FontExtents -> Double
[fontExtentsHeight] :: FontExtents -> Double
[fontExtentsMaxXadvance] :: FontExtents -> Double
[fontExtentsMaxYadvance] :: FontExtents -> Double

-- | Specify font slant.
data FontSlant
FontSlantNormal :: FontSlant
FontSlantItalic :: FontSlant
FontSlantOblique :: FontSlant

-- | Specify font weight.
data FontWeight
FontWeightNormal :: FontWeight
FontWeightBold :: FontWeight

-- | The subpixel order specifies the order of color elements within each
--   pixel on the display device when rendering with an antialiasing mode
--   of <a>AntialiasSubpixel</a>.
--   
--   <ul>
--   <li><i><a>SubpixelOrderDefault</a></i> Use the default subpixel order
--   for for the target device</li>
--   <li><i><a>SubpixelOrderRgb</a></i> Subpixel elements are arranged
--   horizontally with red at the left</li>
--   <li><i><a>SubpixelOrderBgr</a></i> Subpixel elements are arranged
--   horizontally with blue at the left</li>
--   <li><i><a>SubpixelOrderVrgb</a></i> Subpixel elements are arranged
--   vertically with red at the top</li>
--   <li><i><a>SubpixelOrderVbgr</a></i> Subpixel elements are arranged
--   vertically with blue at the top</li>
--   </ul>
data SubpixelOrder
SubpixelOrderDefault :: SubpixelOrder
SubpixelOrderRgb :: SubpixelOrder
SubpixelOrderBgr :: SubpixelOrder
SubpixelOrderVrgb :: SubpixelOrder
SubpixelOrderVbgr :: SubpixelOrder

-- | Specifies the type of hinting to do on font outlines.
--   
--   Hinting is the process of fitting outlines to the pixel grid in order
--   to improve the appearance of the result. Since hinting outlines
--   involves distorting them, it also reduces the faithfulness to the
--   original outline shapes. Not all of the outline hinting styles are
--   supported by all font backends.
--   
--   <ul>
--   <li><i><a>HintStyleDefault</a></i> Use the default hint style for for
--   font backend and target device</li>
--   <li><i><a>HintStyleNone</a></i> Do not hint outlines</li>
--   <li><i><a>HintStyleSlight</a></i> Hint outlines slightly to improve
--   contrast while retaining good fidelity to the original shapes.</li>
--   <li><i><a>HintStyleMedium</a></i> Hint outlines with medium strength
--   giving a compromise between fidelity to the original shapes and
--   contrast</li>
--   <li><i><a>HintStyleFull</a></i> Hint outlines to maximize
--   contrast</li>
--   </ul>
data HintStyle
HintStyleDefault :: HintStyle
HintStyleNone :: HintStyle
HintStyleSlight :: HintStyle
HintStyleMedium :: HintStyle
HintStyleFull :: HintStyle

-- | Specifies whether to hint font metrics.
--   
--   Hinting font metrics means quantizing them so that they are integer
--   values in device space. Doing this improves the consistency of letter
--   and line spacing, however it also means that text will be laid out
--   differently at different zoom factors.
--   
--   <ul>
--   <li><i><a>HintMetricsDefault</a></i> Hint metrics in the default
--   manner for the font backend and target device</li>
--   <li><i><a>HintMetricsOff</a></i> Do not hint font metrics</li>
--   <li><i><a>HintMetricsOn</a></i> Hint font metrics</li>
--   </ul>
data HintMetrics
HintMetricsDefault :: HintMetrics
HintMetricsOff :: HintMetrics
HintMetricsOn :: HintMetrics

-- | Specifies how to render text.
data FontOptions

-- | A Cairo path.
--   
--   <ul>
--   <li>A path is a sequence of drawing operations that are accumulated
--   until <a>stroke</a> is called. Using a path is particularly useful
--   when drawing lines with special join styles and <a>closePath</a>.</li>
--   </ul>
data Path

-- | A data structure for holding a rectangle with integer coordinates.
data RectangleInt
RectangleInt :: Int -> Int -> Int -> Int -> RectangleInt
[x] :: RectangleInt -> Int
[y] :: RectangleInt -> Int
[width] :: RectangleInt -> Int
[height] :: RectangleInt -> Int

-- | Used as the return value for regionContainsRectangle.
data RegionOverlap
RegionOverlapIn :: RegionOverlap
RegionOverlapOut :: RegionOverlap
RegionOverlapPart :: RegionOverlap

-- | A Cairo region. Represents a set of integer-aligned rectangles.
--   
--   It allows set-theoretical operations like regionUnion and
--   regionIntersect to be performed on them.
data Region
data Content
ContentColor :: Content
ContentAlpha :: Content
ContentColorAlpha :: Content
data Format
FormatARGB32 :: Format
FormatRGB24 :: Format
FormatA8 :: Format
FormatA1 :: Format

-- | FIXME: We should find out about this.
data Extend
ExtendNone :: Extend
ExtendRepeat :: Extend
ExtendReflect :: Extend
ExtendPad :: Extend

-- | Specify how filtering is done.
data Filter
FilterFast :: Filter
FilterGood :: Filter
FilterBest :: Filter
FilterNearest :: Filter
FilterBilinear :: Filter
FilterGaussian :: Filter
instance Foreign.Storable.Storable e => Data.Array.Base.MArray Graphics.Rendering.Cairo.SurfaceData e GHC.Types.IO