Graphics.Rendering.Cairo.Canvas

This module defines the Canvas monad, which is a convenience wrapper around the underlying Cairo rendering and can be used with the same textures. You can also mix both APIs, if the need arises.

The Canvas API imitates most of the drawing functions of the Processing language. See http://processing.org/reference for comparison. While having the Processing spirit, this module does not aim for a perfect mapping and deviates where necessary or appropriate. Nevertheless most Processing examples should be trivial to port to the Canvas API. Example:

{-# LANGUAGE OverloadedStrings #-}
import SDL
import SDL.Cairo
import Linear.V2 (V2(..))
import Graphics.Rendering.Cairo.Canvas

main :: IO ()
main = do
  initializeAll
  window <- createWindow "cairo-canvas using SDL2" defaultWindow
  renderer <- createRenderer window (-1) defaultRenderer
  texture <- createCairoTexture' renderer window

  withCairoTexture' texture $ runCanvas $ do
    background $ gray 102
    fill $ red 255 !@ 128
    noStroke
    rect $ D 200 200 100 100
    stroke $ green 255 !@ 128
    fill $ blue 255 !@ 128
    rect $ D 250 250 100 100
    triangle (V2 400 300) (V2 350 400) (V2 400 400)

  copy renderer texture Nothing Nothing
  present renderer
  delay 5000

Entry point

type Canvas = RenderWrapper Render

wrapper around the Cairo Render monad, providing a Processing-style API

runCanvas :: Canvas a -> Surface -> IO a

draw on a Cairo surface using the Canvas monad

withRenderer

Arguments

:: (forall a. Render a -> IO a)

the renderer to use (e.g. renderWith surface)

-> V2 Double

reported canvas size

-> Canvas a

-> IO a

draw on a Cairo surface using the Canvas monad

getCanvasSize :: Canvas (V2 Double)

get size of the canvas (Processing: width(), height())

Color and Style

type Color = V4 Byte

RGBA Color is just a byte vector. Colors can be added, subtracted, etc.

type Byte = Word8

For values from 0 to 255

gray :: Byte -> Color

create opaque gray color

red :: Byte -> Color

create opaque red color

green :: Byte -> Color

create opaque green color

blue :: Byte -> Color

create opaque blue color

rgb :: Byte -> Byte -> Byte -> Color

create opaque mixed color

(!@) :: Color -> Byte -> Color

set transparency of color (half red would be: red 255 !@ 128)

stroke :: Color -> Canvas ()

set current stroke color

fill :: Color -> Canvas ()

set current fill color

noStroke :: Canvas ()

disable stroke (-> shapes without borders!), reenabled by using stroke

noFill :: Canvas ()

disable fill (-> shapes are not filled!), reenabled by using fill

strokeWeight :: Double -> Canvas ()

set line width for shape borders etc.

strokeJoin :: LineJoin -> Canvas ()

set the style of connections between lines of shapes

strokeCap :: LineCap -> Canvas ()

set the style of the line caps

Coordinates

data Dim

position (canonically, top-left corner) and size representation (X Y W H)

Constructors

D Double Double Double Double

Instances

Eq Dim

Methods

(==) :: Dim -> Dim -> Bool

(/=) :: Dim -> Dim -> Bool

Show Dim

Methods

showsPrec :: Int -> Dim -> ShowS

show :: Dim -> String

showList :: [Dim] -> ShowS

toD :: V2 Double -> V2 Double -> Dim

create dimensions from position and size vector

dimPos :: Dim -> V2 Double

get position vector from dimensions

dimSize :: Dim -> V2 Double

get size vector from dimensions

data Anchor

indicates where a position coordinate is located in a rectangle

Constructors

NW

N

NE

E

SE

S

SW

W

Center

Baseline

Instances

Eq Anchor

Methods

(==) :: Anchor -> Anchor -> Bool

(/=) :: Anchor -> Anchor -> Bool

Show Anchor

Methods

showsPrec :: Int -> Anchor -> ShowS

show :: Anchor -> String

showList :: [Anchor] -> ShowS

aligned :: Anchor -> Dim -> Dim

takes dimensions with non-standard position coordinate, returns dimensions normalized to top-left corner coordinate

centered :: Dim -> Dim

takes dimensions with centered position, returns normalized (top-left corner)

corners :: Dim -> Dim

takes dimensions with bottom-right corner instead of size, returns normalized (with size)

Primitives

background :: Color -> Canvas ()

clear the canvas with given color

point :: V2 Double -> Canvas ()

draw a point with stroke color (cairo emulates this with 1x1 rects!)

line :: V2 Double -> V2 Double -> Canvas ()

draw a line between two points with stroke color

triangle :: V2 Double -> V2 Double -> V2 Double -> Canvas ()

draw a triangle connecting three points

rect :: Dim -> Canvas ()

draw a rectangle

polygon :: [V2 Double] -> Canvas ()

draw a polygon connecting given points (equivalent to shape (ShapeRegular True))

shape :: ShapeMode -> [V2 Double] -> Canvas ()

draw shape along a given path using given ShapeMode. (Processing: beginShape(),vertex(),endShape())

data ShapeMode

Shape mode to use

Constructors

ShapeRegular Bool

regular path. flag decides whether the first and last point are connected

ShapePoints

just draw the points, no lines

ShapeLines

interpret points as pairs, draw lines

ShapeTriangles

interpret points as triples, draw triangles

ShapeTriangleStrip

draw triangle for every neighborhood of 3 points

ShapeTriangleFan

fix first point, draw triangles with every neighboring pair and first point

Instances

Eq ShapeMode

Methods

(==) :: ShapeMode -> ShapeMode -> Bool

(/=) :: ShapeMode -> ShapeMode -> Bool

Show ShapeMode

Methods

showsPrec :: Int -> ShapeMode -> ShowS

show :: ShapeMode -> String

showList :: [ShapeMode] -> ShowS

Arcs and Curves

circle :: V2 Double -> Double -> Canvas ()

draw circle: circle leftCorner diameter

circle' :: V2 Double -> Double -> Canvas ()

draw circle: circle centerPoint diameter

arc :: Dim -> Double -> Double -> Canvas ()

draw arc: arc dimensions startAngle endAngle

ellipse :: Dim -> Canvas ()

draw ellipse

bezier :: V2 Double -> V2 Double -> V2 Double -> V2 Double -> Canvas ()

draw cubic bezier spline: bezier fstAnchor fstControl sndControl sndAnchor

bezierQ :: V2 Double -> V2 Double -> V2 Double -> Canvas ()

draw quadratic bezier spline: bezier fstAnchor control sndAnchor

Transformations

resetMatrix :: Canvas ()

replace current matrix with identity

pushMatrix :: Canvas ()

push current matrix onto the stack

popMatrix :: Canvas ()

pop a matrix

translate :: V2 Double -> Canvas ()

translate coordinate system

rotate :: Double -> Canvas ()

rotate coordinate system

scale :: V2 Double -> Canvas ()

scale coordinate system

Images

data Image

Stores an image surface with additional information

createImage :: V2 Int -> Canvas Image

create a new empty image of given size

loadImagePNG :: FilePath -> Canvas Image

load a PNG image from given path.

saveImagePNG :: Image -> FilePath -> Canvas ()

Save an image as PNG to given file path

image :: Image -> V2 Double -> Canvas ()

Render complete image on given coordinates

image' :: Image -> Dim -> Canvas ()

Render complete image inside given dimensions

blend :: Operator -> Image -> Dim -> Dim -> Canvas ()

Copy given part of image to given part of screen, using given blending operator and resizing when necessary. Use OperatorSource to copy without blending effects. (Processing: copy(),blend())

grab :: Dim -> Canvas Image

get a copy of the image from current window (Processing: get())

Text

data Font

Font definition

Constructors

Font

Fields

• fontFace :: String
• fontSize :: Double
• fontBold :: Bool
• fontItalic :: Bool

Instances

Eq Font

Methods

(==) :: Font -> Font -> Bool

(/=) :: Font -> Font -> Bool

Show Font

Methods

showsPrec :: Int -> Font -> ShowS

show :: Font -> String

showList :: [Font] -> ShowS

textFont :: Font -> Canvas ()

set current font for text rendering

textSize :: String -> Canvas (V2 Double)

get the size of the text when rendered in current font

textExtents :: String -> Canvas (Dim, V2 Double)

get information about given text when rendered in current font. returns tuple with location of top-left corner relative to the origin and size of rendered text in the first component, cursor advancement relative to origin in the second component (also see TextExtents).

text :: String -> V2 Double -> Canvas (V2 Double)

render text. returns cursor advancement (text = text' Baseline)

text' :: Anchor -> String -> V2 Double -> Canvas (V2 Double)

render text with specified alignment. returns cursor advancement

Math

mapRange :: Double -> (Double, Double) -> (Double, Double) -> Double

map a value from one range onto another

radians :: Double -> Double

convert degrees to radians

degrees :: Double -> Double

convert radians to degrees

Misc

randomSeed :: Int -> Canvas ()

set new random seed

random :: Random a => (a, a) -> Canvas a

get new random number

getTime :: IO Time

get current system time. Use the Time accessors for specific components. (Processing: year(),month(),day(),hour(),minute(),second())

data Time

date and time as returned by getTime

Constructors

Time

Fields

• year :: Int
• month :: Int
• day :: Int
• hour :: Int
• minute :: Int
• second :: Int

Instances

Eq Time

Methods

(==) :: Time -> Time -> Bool

(/=) :: Time -> Time -> Bool

Show Time

Methods

showsPrec :: Int -> Time -> ShowS

show :: Time -> String

showList :: [Time] -> ShowS

data LineCap :: *

Specify line endings.

LineCapButt

Start(stop) the line exactly at the start(end) point.

LineCapRound

Use a round ending, the center of the circle is the end point.

LineCapSquare

Use squared ending, the center of the square is the end point

Constructors

LineCapButt

LineCapRound

LineCapSquare

Instances

Enum LineCap

Methods

succ :: LineCap -> LineCap

pred :: LineCap -> LineCap

toEnum :: Int -> LineCap

fromEnum :: LineCap -> Int

enumFrom :: LineCap -> [LineCap]

enumFromThen :: LineCap -> LineCap -> [LineCap]

enumFromTo :: LineCap -> LineCap -> [LineCap]

enumFromThenTo :: LineCap -> LineCap -> LineCap -> [LineCap]

Eq LineCap

Methods

(==) :: LineCap -> LineCap -> Bool

(/=) :: LineCap -> LineCap -> Bool

Show LineCap

Methods

showsPrec :: Int -> LineCap -> ShowS

show :: LineCap -> String

showList :: [LineCap] -> ShowS

data LineJoin :: *

Specify how lines join.

Constructors

LineJoinMiter

LineJoinRound

LineJoinBevel

Instances

Enum LineJoin

Methods

succ :: LineJoin -> LineJoin

pred :: LineJoin -> LineJoin

toEnum :: Int -> LineJoin

fromEnum :: LineJoin -> Int

enumFrom :: LineJoin -> [LineJoin]

enumFromThen :: LineJoin -> LineJoin -> [LineJoin]

enumFromTo :: LineJoin -> LineJoin -> [LineJoin]

enumFromThenTo :: LineJoin -> LineJoin -> LineJoin -> [LineJoin]

Eq LineJoin

Methods

(==) :: LineJoin -> LineJoin -> Bool

(/=) :: LineJoin -> LineJoin -> Bool

Show LineJoin

Methods

showsPrec :: Int -> LineJoin -> ShowS

show :: LineJoin -> String

showList :: [LineJoin] -> ShowS