Cairo
Thin FFI bindings over the Cairo 2D graphics library.
The goal of this module is to expose Cairo's C API with Carp-friendly naming (kebab-case, grouped under Cairo), without adding a higher-level wrapper on top. Higher-level sketching primitives live in anima.carp.
Installation
Cairo must be installed on the system and discoverable via pkg-config:
brew install cairo # macOS
apt install libcairo2-dev # Debian / Ubuntu
Example
(load "git@github.com:carpentry-org/cairo.carp@0.2.0")
(defn main []
(let-do [surf (Cairo.image-surface-create Cairo.format-argb32 200 200)
cr (Cairo.create surf)]
(Cairo.set-source-rgb cr 1.0 1.0 1.0)
(Cairo.paint cr)
(Cairo.set-source-rgb cr 0.0 0.0 0.0)
(Cairo.set-line-width cr 4.0)
(Cairo.move-to cr 20.0 20.0)
(Cairo.line-to cr 180.0 180.0)
(Cairo.stroke cr)
(ignore (Cairo.surface-write-to-png surf (cstr "out.png")))
(Cairo.destroy cr)
(Cairo.surface-destroy surf)))
Memory management
Cairo uses reference counting internally; this binding does not manage
lifetimes for you. Every Cairo.create must be paired with a Cairo.destroy,
and every *-surface-create with a Cairo.surface-destroy. See the Cairo
manual for details.
=
(Fn [CairoStatus, CairoStatus] Bool)
(= a b)
Equality on status codes, implemented by converting to Int first.
arc
(Fn [(Ptr CairoContext), Double, Double, Double, Double, Double] ())
Add a circular arc centered at (xc yc) with radius, sweeping from angle1 to angle2 radians (positive = clockwise in Cairo's default orientation).
create
(Fn [(Ptr CairoSurface)] (Ptr CairoContext))
Create a drawing context targeting the given surface. Must be paired with destroy.
curve-to
(Fn [(Ptr CairoContext), Double, Double, Double, Double, Double, Double] ())
Append a cubic Bézier spline through (x1 y1), (x2 y2), (x3 y3).
fill-extents
(Fn [(Ptr CairoContext)] CairoExtents)
Compute the bounding box of the area that would be affected by fill.
font-extents
(Fn [(Ptr CairoContext)] CairoFontExtents)
Return a CairoFontExtents for the current font (ascent, descent, height, max advances).
format-argb32
CairoFormat
32-bit ARGB, native-endian. Matches SDL_PIXELFORMAT_ARGB8888 on little-endian.
get-current-point-x
(Fn [(Ptr CairoContext)] Double)
Return the x coordinate of the current point. Undefined if has-current-point? is false.
get-current-point-y
(Fn [(Ptr CairoContext)] Double)
Return the y coordinate of the current point. Undefined if has-current-point? is false.
get-dash
(Fn [(Ptr CairoContext)] (Array Double))
Return the current dash pattern as an array of doubles.
get-dash-count
(Fn [(Ptr CairoContext)] Int)
Return the number of dash segments in the current dash pattern (0 means solid).
get-dash-offset
(Fn [(Ptr CairoContext)] Double)
Return the offset into the dash pattern set by set-dash.
has-current-point?
(Fn [(Ptr CairoContext)] Bool)
Return true if the context has a current point (after move-to or drawing operations).
image-surface-create
(Fn [CairoFormat, Int, Int] (Ptr CairoSurface))
Create an in-memory image surface of the given format, width, and height.
image-surface-get-data
(Fn [(Ptr CairoSurface)] (Ptr Byte))
Return a raw pointer to the surface's pixel buffer. Must be preceded by surface-flush.
paint
(Fn [(Ptr CairoContext)] ())
Paint the current source everywhere within the current clip region.
path-extents
(Fn [(Ptr CairoContext)] CairoExtents)
Compute the bounding box enclosing the current path, ignoring stroke parameters.
pattern-add-color-stop-rgb
(Fn [(Ptr CairoPattern), Double, Double, Double, Double] ())
Add an opaque color stop at offset (0.0–1.0) to a gradient pattern.
pattern-add-color-stop-rgba
(Fn [(Ptr CairoPattern), Double, Double, Double, Double, Double] ())
Add a translucent color stop at offset (0.0–1.0) to a gradient pattern.
pattern-create-for-surface
(Fn [(Ptr CairoSurface)] (Ptr CairoPattern))
Create a pattern from a surface, useful for tiling or compositing.
pattern-create-linear
(Fn [Double, Double, Double, Double] (Ptr CairoPattern))
Create a linear gradient pattern along the line from (x0 y0) to (x1 y1).
pattern-create-radial
(Fn [Double, Double, Double, Double, Double, Double] (Ptr CairoPattern))
Create a radial gradient between two circles: center (cx0 cy0) radius r0 and center (cx1 cy1) radius r1.
pattern-destroy
(Fn [(Ptr CairoPattern)] ())
Destroy a pattern created by pattern-create-*. Must be called after the pattern is no longer needed.
pdf-surface-create
(Fn [(Ptr CChar), Double, Double] (Ptr CairoSurface))
Create a PDF surface writing to filename with dimensions in points (1 point = 1/72 inch).
restore
(Fn [(Ptr CairoContext)] ())
Pop the top drawing state off the stack and make it current.
rotate
(Fn [(Ptr CairoContext), Double] ())
Rotate the current transformation by angle radians.
save
(Fn [(Ptr CairoContext)] ())
Push a copy of the current drawing state onto an internal stack.
select-font-face
(Fn [(Ptr CairoContext), (Ptr CChar), CairoFontSlant, CairoFontWeight] ())
Select a font face by family name, slant, and weight. Uses Cairo's built-in toy text API.
set-dash
(Fn [(Ptr CairoContext), (Ref (Array Double) a), Double] ())
Set the dash pattern. dashes is an array of on/off lengths; offset shifts the pattern start.
set-source
(Fn [(Ptr CairoContext), (Ptr CairoPattern)] ())
Set the pattern as the source for subsequent drawing operations.
set-source-surface
(Fn [(Ptr CairoContext), (Ptr CairoSurface), Double, Double] ())
Set a surface as the source pattern, translated to (x y).
stroke-extents
(Fn [(Ptr CairoContext)] CairoExtents)
Compute the bounding box of the area that would be affected by stroke.
success?
(Fn [CairoStatus] Bool)
(success? s)
Returns true if the given status equals status-success.
surface-flush
(Fn [(Ptr CairoSurface)] ())
Ensure pending drawing for the surface has been applied. Required before reading pixels directly.
surface-write-to-png
(Fn [(Ptr CairoSurface), (Ptr CChar)] CairoStatus)
Write the contents of an image surface to a PNG file. Returns a CairoStatus.
svg-surface-create
(Fn [(Ptr CChar), Double, Double] (Ptr CairoSurface))
Create an SVG surface writing to filename with dimensions in points.
text-extents
(Fn [(Ptr CairoContext), (Ptr CChar)] CairoTextExtents)
Measure text and return a CairoTextExtents with bearing, size, and advance fields.