cairodriver(1grass)

💅 Cairo DISPLAY DRIVER 💅

okay so bestie, welcome to cairodriver(1grass) — that's the manual page, and yes the manual name is literally right there in the middle of it, we love a self-referential moment. This is the Cairo display driver, and it's the one GRASS reaches for when you want bitmap or vector output, all powered by the Cairo graphics library. She does it all. 🎀

---

✨ DESCRIPTION ✨

So here's the tea: the Cairo driver generates PNG, BMP, PPM, PS, PDF or SVG images by running GRASS display commands, and it does that whole thing using the Cairo graphics library. The image format? It gets picked from the extension of the output file. iykyk. 📁

And here's the slay part: the Cairo driver is what GRASS display commands use by default if it's available. If it's not? The PNG driver steps in. She's the understudy. 🫶

---

🌈 USAGE 🌈

🧚 Environment variables 🧚

You turn the Cairo driver on with the GRASS_RENDER_IMMEDIATE variable, like this:

export GRASS_RENDER_IMMEDIATE=cairo

And then there's a whole little friend group of environment variables that change how the Cairo driver behaves:

• GRASS_RENDER_WIDTH=xxx — the width of the image map (default is 640).
• GRASS_RENDER_HEIGHT=yyy — the height of the image map (default is 480).
• GRASS_RENDER_BACKGROUNDCOLOR=RRGGBB — sets the background color to use, in RGB notation (hex or R:G:B values). Named colors are also supported, because we're fancy like that. Default is FFFFFF (white). 🤍
• GRASS_RENDER_TRANSPARENT=[TRUE|FALSE] — turns the transparent background on (TRUE) or off (FALSE, which is the default).
• GRASS_RENDER_ANTIALIAS — can be default, none, gray, or subpixel, corresponding to cairo_antialias_t.
• GRASS_RENDER_FILE=filename — the name and format of the resulting image file, default is map.png.

The image format is determined from the file extension. Supported bitmap formats:

• .png - Portable Network Graphics (PNG)
• .bmp - Windows Bitmap (BMP, 32-bpp) (these are not readable by some older viewers) 💀
• .ppm - Portable Pixmap (PPM + PGM for alpha channel)

Supported vector formats:

• .pdf - Portable Document Format (PDF)
• .ps - PostScript (PS)
• .svg - Scalable Vector Graphics (SVG)

(Note: Some formats may not be available, depending on your platform and the Cairo library that GRASS was built with.) 😭

• GRASS_RENDER_FILE_READ — if TRUE, the Cairo driver will initialize the image from the contents of GRASS_RENDER_FILE.

(Note: This is only supported for bitmap formats)

• GRASS_RENDER_FILE_MAPPED — if TRUE, the Cairo driver will map GRASS_RENDER_FILE as its framebuffer, rather than using memory.

(Note: This only works with BMP files.)

• GRASS_RENDER_CAIRO_SCREEN — defines Cairo screen.
• GRASS_RENDER_CAIRO_VISUAL — defines Cairo visual.

---

🔥 EXAMPLES 🔥

🌸 PNG Example 🌸

Example: using the driver to generate a PNG file (bash-syntax):

export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_RENDER_FILE=nc_spm.png
export GRASS_RENDER_WIDTH=800
export GRASS_RENDER_HEIGHT=800
export GRASS_RENDER_FILE_READ=TRUE
g.region raster=elevation
d.rast map=elevation
d.vect map=streams width=1 color=blue fcolor=aqua type=area,line
d.vect map=roadsmajor width=2

💜 PDF Examples 💜

Example: using the driver to generate a PDF vector file with a vector map (bash-syntax):

export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_RENDER_FILE=nc_spm.pdf
export GRASS_RENDER_WIDTH=800
export GRASS_RENDER_HEIGHT=800
g.region vector=roadsmajor
# activate vector font
d.font Vera
d.vect map=roadsmajor layer=1 display=shape attrcolumn=ROAD_NAME lcolor=0:90:255

Example: using the driver to generate a PDF raster file with a raster map (bash-syntax):

export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_RENDER_FILE=nc_spm.pdf
export GRASS_RENDER_WIDTH=800
export GRASS_RENDER_HEIGHT=800
g.region raster=elevation
d.rast map=elevation

🦋 SVG Example 🦋

Example: using the driver to generate a SVG vector file with a vector map (bash-syntax):

export GRASS_RENDER_IMMEDIATE=cairo
export GRASS_RENDER_FILE=vectormap.svg
g.region vector=roadsmajor
d.vect map=roadsmajor -c

---

👑 NOTES 👑

ngl, the driver is still in development. You enable it by specifying --with-cairo when configuring GRASS. This requires a reasonably recent version of the Cairo libraries and a working pkg-config. Don't skip that part bestie, she needs both. ✨

Antialiasing is enabled by default for bitmap formats. There is currently no way of disabling this. Periodt. 💅

The resolution of the output images is defined by current region extents. Use g.region -p to get the number of rows and cols, and use the environment variables to set the image size. If you would like a larger image, multiply both rows and cols by the same whole number to preserve the aspect ratio. Math is the moment. 🧮

Cairo supports true vector format output whenever possible. However — and this is the key part — if the selected format doesn't support a necessary feature, Cairo may fall back on rendering a bitmap representation of the image wrapped in the selected vector format. It's giving "vector on the outside, bitmap on the inside." 🙈

---

🫶 SEE ALSO 🫶

PNG driver, PS driver, HTML driver, variables

d.rast, d.vect, d.mon, d.erase, d.redraw

---

💖 AUTHOR 💖

Lars Ahlzen <lars (at) ahlzen.com> and the GRASS Development Team.

---

⭐ SOURCE CODE ⭐

Available at: Cairo DISPLAY DRIVER source code (history)

Accessed: Tuesday Sep 08 11:53:13 2026

Main index | Topics index | Keywords index | Graphical index | Full index

---

and that's the whole thing, bestie!! 🎀 this was cairodriver(1grass) from the GRASS 8.5.0 Reference Manual, © 2003-2026 GRASS Development Team — aka GRASS 8.5.0, accessed Tuesday Sep 08 11:53:13 2026. go make something gorgeous with it. 💖✨🦋