-- 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.11.0 -- | 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. Matrix a1 a2 b1 b2 c1 c2 describes the -- transformation of a point with coordinates x,y that is defined by -- -- 
--   / x' \  =  / a1 b1 \  / x \  + / c1 \
--   \ y' /     \ a2 b2 /  \ y /    \ c2 /
--
-- -- or -- -- 
--   x' =  a1 * x + b1 * y + c1
--   y' =  a2 * x + b2 * y + c2
--
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 Show Matrix instance Eq Matrix instance Num Matrix instance Storable 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 http://cairographics.org -- -- 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 withImageSurface (or any other -- with<backend>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 restore is called, the saved state is -- restored. Multiple calls to save and restore can be -- nested; each call to restore restores the state from the -- matching paired save. save :: Render () -- | Restores to the state saved by a preceding call to save and -- removes that state from the stack of saved states. restore :: Render () -- | Ask for the status of the current Render monad. status :: Render Status -- | Gets the target surface for the Render context as passed to -- renderWith. withTargetSurface :: (Surface -> Render a) -> Render a -- | 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 setSource. This means that -- further modifications of the current transformation matrix will not -- affect the source pattern. See setMatrix. setSource :: Pattern -> Render () -- | This is a convenience function for creating a pattern from surface and -- setting it as the source in the context with setSource. -- -- 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 patternCreateForSurface. The -- resulting pattern can be queried with getSource so that these -- attributes can be modified if desired, (eg. to create a repeating -- pattern with patternSetExtent. 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 -- AntialiasSubpixel when drawing shapes. -- -- Note that this option does not affect text rendering, instead see -- fontOptionsSetAntilias. setAntialias :: Antialias -> Render () -- | Sets the dash pattern to be used by stroke. 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 dashes is [] 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 fill and clip. See FillRule for details on -- the semantics of each available fill rule. setFillRule :: FillRule -> Render () -- | Gets the current fill rule, as set by setFillrule. getFillRule :: Render FillRule -- | Sets the current line cap style within the cairo context. See -- LineCap 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 stroke, strokeExtents, and -- strokeToPath, but does not have any effect during path -- construction. setLineCap :: LineCap -> Render () -- | Gets the current line cap style, as set by setLineCap. getLineCap :: Render LineCap -- | Sets the current line join style within the cairo context. See -- LineJoin 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 stroke, strokeExtents, and -- strokeToPath, but does not have any effect during path -- construction. setLineJoin :: LineJoin -> Render () -- | Gets the current line join style, as set by setLineJoin. 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 stroke, strokeExtents, and -- strokeToPath, but does not have any effect during path -- construction. setLineWidth :: Double -> Render () -- | Gets the current line width, as set by setLineWidth. getLineWidth :: Render Double setMiterLimit :: Double -> Render () -- | Gets the current miter limit, as set by setMiterLimit. getMiterLimit :: Render Double -- | Sets the compositing operator to be used for all drawing operations. -- See Operator 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 setTolerance. getTolerance :: Render Double -- | Establishes a new clip region by intersecting the current clip region -- with the current path as it would be filled by fill and -- according to the current fill rule (see setFillRule). -- -- After clip, 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 clip 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 -- clip within a 'save'/'restore' pair. The only other means of -- increasing the size of the clip region is resetClip. clip :: Render () -- | Establishes a new clip region by intersecting the current clip region -- with the current path as it would be filled by fill and -- according to the current fill rule (see setFillRule). -- -- Unlike clip, 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 clip 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 -- clip within a 'save'/'restore' pair. The only other means of -- increasing the size of the clip region is resetClip. clipPreserve :: Render () -- | 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 resetClip -- as it will cause results unexpected by higher-level code which calls -- clip. Consider using save and restore around -- clip 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 fill, the current path will be cleared from the -- cairo context. -- -- See setFillRule and fillPreserve. 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 fill, fillPreserve preserves the path -- within the cairo context. -- -- See setFillRule and fill. 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 paint, 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 stroke, the current path will be cleared from the -- Render monad. -- -- See setLineWidth, setLineJoin, setLineCap, -- setDash, and strokePreserve. stroke :: Render () -- | A drawing operator that strokes the current path according to the -- current line width, line join, line cap, and dash settings. Unlike -- stroke, strokePreserve preserves the path within the -- Render monad. -- -- See setLineWidth, setLineJoin, setLineCap, -- setDash, and strokePreserve. 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: -- newPath, moveTo, lineTo, curveTo, -- arc, relMoveTo, relLineTo, relCurveTo, -- arcNegative, textPath, strokeToPath. 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 -- moveTo), and closes this subpath. -- -- The behavior of closePath is distinct from simply calling -- lineTo 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 (xc, yc), begins at angle1 -- and proceeds in the direction of increasing angles to end at -- angle2. If angle2 is less than angle1 it -- will be progressively increased by 2*pi until it is greater -- than angle1. -- -- 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 pi 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 degrees * (pi / -- 180).) -- -- This function gives the arc in the direction of increasing angles; see -- arcNegative 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: -- -- 
--   save
--   translate (x + width / 2) (y + height / 2)
--   scale (1 / (height / 2.)) (1 / (width / 2))
--   arc 0 0 1 0 (2 * pi)
--   restore
--
arc :: Double -> Double -> Double -> Double -> Double -> Render () -- | Adds a circular arc of the given radius to the current path. The arc -- is centered at (xc, yc), begins at angle1 -- and proceeds in the direction of decreasing angles to end at -- angle2. If angle2 is greater than angle1 it -- will be progressively decreased by 2*pi until it is greater -- than angle1. -- -- See arc 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 (x3, y3) in user-space coordinates, using -- (x1, y1) and (x2, y2) as the -- control points. After this call the current point will be -- (x3, y3). curveTo :: Double -> Double -> Double -> Double -> Double -> Double -> Render () -- | Adds a line to the path from the current point to position -- (x, y) in user-space coordinates. After this call -- the current point will be (x, y). lineTo :: Double -> Double -> Render () -- | If the current subpath is not empty, begin a new subpath. After this -- call the current point will be (x, y). moveTo :: Double -> Double -> Render () -- | Adds a closed-subpath rectangle of the given size to the current path -- at position (x, y) in user-space coordinates. rectangle :: Double -> Double -> Double -> Double -> Render () -- | Render text at the current path. -- -- textPath :: String -> Render () -- | Relative-coordinate version of curveTo. 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 -- (dx3, dy3), using points offset by (dx1, -- dy1) and (dx2, dy2) as the control points. -- After this call the current point will be offset by (dx3, -- dy3). -- -- Given a current point of (x, y), relCurveTo dx1 dy1 -- dx2 dy2 dx3 dy3 is logically -- equivalent to curveTo (x + dx1) (y + dy1) (x + -- dx2) (y + dy2) (x + dx3) (y + -- dy3). relCurveTo :: Double -> Double -> Double -> Double -> Double -> Double -> Render () -- | Relative-coordinate version of lineTo. Adds a line to the path -- from the current point to a point that is offset from the current -- point by (dx, dy) in user space. After this call the -- current point will be offset by (dx, dy). -- -- Given a current point of (x, y), relLineTo dx dy is -- logically equivalent to lineTo (x + dx) (y + dy). 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 dx dy is -- logically equivalent to moveTo (x + dx) (y + dy) relMoveTo :: Double -> Double -> Render () -- | Creates a new Pattern 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: -- -- 
--   withRBGPattern 1 0 0 $ do
--     ...
--     ...
--
withRGBPattern :: Double -> Double -> Double -> (Pattern -> Render a) -> Render a -- | Creates a new Pattern 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: -- -- 
--   withRBGPattern 1 0 0 0.5 $ do
--     ...
--     ...
--
withRGBAPattern :: Double -> Double -> Double -> Double -> (Pattern -> Render a) -> Render a -- | Create a new Pattern for the given surface. withPatternForSurface :: Surface -> (Pattern -> Render a) -> Render a -- | Create a new linear gradient Pattern along the line defined by -- (x0, y0) and (x1, y1). Before using the gradient -- pattern, a number of color stops should be defined using -- patternAddColorStopRGB and patternAddColorStopRGBA. -- -- withLinearPattern :: Double -> Double -> Double -> Double -> (Pattern -> Render a) -> Render a -- | Creates a new radial gradient Pattern between the two circles -- defined by (x0, y0, c0) and (x1, y1, c0). Before -- using the gradient pattern, a number of color stops should be defined -- using patternAddColorStopRGB or patternAddColorStopRGBA. -- -- 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 setSourceRGB. -- -- 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 StatusPatternTypeMismatch. 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 StatusPatternTypeMismatch. 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 setSource. 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 (tx, ty). This offset is interpreted as -- a user-space coordinate according to the CTM in place before the new -- call to translate. 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 angle 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 matrix. setMatrix :: Matrix -> Render () -- | Gets the current transformation matrix, as set by setMatrix. 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 userToDevice except that the translation -- components of the CTM will be ignored when transforming -- (dx,dy). 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 deviceToUser except that the translation -- components of the inverse CTM will be ignored when transforming -- (dx,dy). deviceToUserDistance :: Double -> Double -> Render (Double, Double) -- | Selects a family and style of font from a simplified description as a -- family name, slant and weight. 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 :: String -> FontSlant -> FontWeight -> Render () -- | Sets the current font matrix to a scale by a factor of size, -- replacing any font matrix previously set with setFontSize or -- setFontMatrix. 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 matrix. 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 setFontSize), 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 setFontMatrix 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 options has a default -- value (like AntialiasDefault), 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 showText. -- -- NOTE: The showText 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 :: 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 showText). Additionally, the -- textExtentsXadvance and textExtentsYadvance values -- indicate the amount by which the current point would be advanced by -- showText. -- -- Note that whitespace characters do not directly contribute to the size -- of the rectangle (textExtentsWidth and -- textExtentsHeight). 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 textExtentsXadvance and -- textExtentsYadvance values. textExtents :: 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 -- original. fontOptionsCopy :: (MonadIO m) => FontOptions -> m FontOptions -- | Merges non-default options from other into options, -- replacing existing values. This operation can be thought of as -- somewhat similar to compositing other onto options -- with the operation of OperationOver. 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 FontOptions 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 -- AntialiasSubpixel. See the documentation for -- SubpixelOrder for full details. fontOptionsSetSubpixelOrder :: (MonadIO m) => FontOptions -> SubpixelOrder -> m () -- | Gets the subpixel order for the font options object. See the -- documentation for SubpixelOrder 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 HintStyle 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 HintStyle 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 HintMetrics for full details. fontOptionsSetHintMetrics :: (MonadIO m) => FontOptions -> HintMetrics -> m () -- | Gets the metrics hinting mode for the font options object. See the -- documentation for HintMetrics 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 withSimilarSurface 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 surfaceFinish. createSimilarSurface :: Surface -> Content -> Int -> Int -> IO Surface -- | Create a temporary surface that is compatible with the current target -- surface (like a combination of withTargetSurface and -- withSimilarSurface). -- -- 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: -- -- 
--   renderWithSimilarSurface ContentAlpha 200 200 $ \tmpSurface -> 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)
--
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 scaledFontCreate. 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 surfaceFinish 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 StatusSurfaceFinished error. -- -- When the last call to surfaceDestroy decreases the reference -- count to zero, cairo will call surfaceFinish 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 surfaceFlush before doing such drawing. surfaceMarkDirty :: (MonadIO m) => Surface -> m () -- | Like surfaceMarkDirty, 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 Surface 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 translate isn't sufficient to do this, since -- functions like deviceToUser 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, rectangle and fill -- if you want it cleared. withImageSurface :: Format -> 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 withImageSurface 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 surfaceFinish. 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 Surface. data (Ix i) => SurfaceData i e -- | Retrieve the internal array of raw image data. -- -- -- -- FormatARGB32: 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.) -- -- FormatRGB24: each pixel is 32 bits with the upper 8 bits being -- unused, followed by 8 bits for red, green and blue. -- -- FormatA8: each pixel is 8 bits holding an alpha value -- -- FormatA1: 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. -- -- 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 -- | Writes the contents of surface to a new file filename as a -- PNG image. surfaceWriteToPNG :: Surface -> FilePath -> IO () -- | Creates a PostScript surface of the specified size in points to be -- written to filename. -- -- Note that the size of individual pages of the PostScript output can -- vary. See psSurfaceSetSize. 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 showPage or -- copyPage. pdfSurfaceSetSize :: (MonadIO m) => Surface -> Double -> Double -> m () -- | Creates a PostScript surface of the specified size in points to be -- written to filename. -- -- Note that the size of individual pages of the PostScript output can -- vary. See psSurfaceSetSize. 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 showPage or -- copyPage. psSurfaceSetSize :: (MonadIO m) => Surface -> Double -> Double -> m () -- | Creates a SVG surface of the specified size in points be written to -- filename. withSVGSurface :: FilePath -> Double -> Double -> (Surface -> IO a) -> IO a 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 -- | The Render monad. All drawing operations take place in a Render -- context. You can obtain a Render context for a Surface using -- renderWith. data Render m -- | Representation of a 2-D affine transformation. -- -- The Matrix type represents a 2x2 transformation matrix along with a -- translation vector. Matrix a1 a2 b1 b2 c1 c2 describes the -- transformation of a point with coordinates x,y that is defined by -- -- 
--   / x' \  =  / a1 b1 \  / x \  + / c1 \
--   \ y' /     \ a2 b2 /  \ y /    \ c2 /
--
-- -- or -- -- 
--   x' =  a1 * x + b1 * y + c1
--   y' =  a2 * x + b2 * y + c2
--
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 Render context is used by -- the stroke, fill and paint operations. These -- operations composite the current pattern with the target surface using -- the currently selected Operator. data Pattern -- | Cairo status. -- -- 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 -- | 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 -- | Specifies the type of antialiasing to do when rendering text or shapes -- -- data Antialias AntialiasDefault :: Antialias AntialiasNone :: Antialias AntialiasGray :: Antialias AntialiasSubpixel :: Antialias data FillRule FillRuleWinding :: FillRule FillRuleEvenOdd :: FillRule -- | Specify line endings. -- -- 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 AntialiasSubpixel. -- -- 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. -- -- 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. -- -- data HintMetrics HintMetricsDefault :: HintMetrics HintMetricsOff :: HintMetrics HintMetricsOn :: HintMetrics -- | Specifies how to render text. data FontOptions -- | A Cairo path. -- -- data Path 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 (Storable e) => MArray SurfaceData e IO