CairoSharp

CairoSharp is a .NET 8+ wrapper for cairo.

cairo is a 2D graphics library with support for multiple output devices. Currently supported output targets include the X Window System (via both Xlib and XCB), Quartz, Win32, image buffers, PostScript, PDF, and SVG 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 Bézier splines, transforming and compositing translucent images, and antialiased text rendering. All drawing operations can be transformed by any affine transformation (scale, rotation, shear, etc.)

Documentation / Tutorials for cairo

Some / most of the documentation is for the C language or for Python. But cairo APIs are named everywhere quite similarly, so this shouldn't be a problem.

• official documentation
• Frequently Asked Questions
• Cooking with cairo
• ZetCode Cairo graphics tutorial
• Mono.Cairo which includes the Mono.Cairo Tutorial and the Mono.Cairo Cookbook
• cairo API documentation

Further there are some repositories which showcases the use of cairo or bear some nice tricks:

• cairo-demo repository
• Cairou -- A small library of useful, common Cairo routines.
• tests directory of the cairo repo -- as always, tests showcase how to use an API

cairo vs Skia

Both are (vector) graphic libraries, and the drawing model differs a bit. Naturally both have pros and cons, but -- experience in the drawing models aside -- I'd choose based on usage:

• UI rendering: Skia due it's capabilities to use GPU
• everything else: cairo, especially as with the same code you can write to different backends like PDF, SVG, PNG, PS

For UI rendering I also use cairo, but this is just simple animations in WinForms or GTK (4), and not very hardware demanding. The reason for this is just as I know cairo quite well and can keep the same drawing model for file / stream based backends and for UI.

License and history

The first official .NET wrapper for cairo lived in the Mono GTK-Sharp repository, and got licensed under the GNU LGPL. Later on a zwcloud/CairoSharp was created also under the GNU LGPL (I contributes quite a bit to that repository). Time passed by and the zwcloud-wrapper got outdated and not maintained anymore (no activity since 2020).

cairo got some updates in the meantime, so I started from scratch with a new wrapper for .NET. So this project here isn't a fork of some other wrapper, it's a new project with just some examples / demos taken over. The actual wrapper-code is completely new and based on modern .NET features.

As cairo and most other wrappers are licensed under the GNU LGPL, so does this project too. But this doesn't mean that using this project in your work brings copyleft-virality with it.

The license says

a larger work using the licensed work through interfaces provided by the licensed work may be distributed under different terms and without source code for the larger work

So graphically it will look like this:

--- config: class: hideEmptyMembersBox: true --- classDiagram direction LR Your App ..> CairoSharp: Interface CairoSharp ..> cairo: Interface

Thus your work is "decoupled" via an interface from the licensed work refered to in the license.

cairo features implemented

All features, functions, etc. as of cairo version 1.18.5 are implemented. Further the members in the .NET wrapper are documented (xml doc comments), so Intellisense works.

Supported platforms

This project only supports .NET 8 onwards. For older .NET targets please use https://github.com/zwcloud/CairoSharp, but note that lots of newer cairo APIs are missing there, and that there are no xml-doc comments available.

Operating system	cairo shipped with the package	manual installation
Linux	:x:	:heavy_check_mark: (see downloads)
Windows x64 / x86	:heavy_check_mark:	not needed
Mac OS	:x:	:heavy_check_mark: (see downloads)

• for Windows x64 / x86 the cairo DLL is bundled with the NuGet package, no further installation is needed

I don't have Mac OS, thus there are no stubs available, and I can't tell whether it will work or not.

Minimum cairo version is 1.17.2. For some newer cairo features (the ones added in 1.18 and newer) CairoSharp will throw a NotSupportedException if the installed cairo version is too old (1.17.2 was chosen as baseline, as many Windows cairo DLLs are this version -- but CairoSharp comes with it's own cairo DLL for Windows anyway).

Extensions

There is an accompanying project calls CairoSharp.Extensions.

Why another CairoSharp?

• the others are old, but cairo is still very handy and got recent updates
• others are missing doc comments for Intellisense
• new features like streaming APIs, PDF tags and other meta-data weren't available
• code didn't use features of modern .NET like Span<T> and others

So instead of polishing an old wrapper, I chose to start a fresh one. For the name I chose CairoSharp, because I'm so used to it, and I dislike names like NCairo, CairoDotNet, and so on.

The NuGet is named gfoidl.CairoSharp to have a distincition (and at the moment it's the only one for a .NET 8 and newer targets).

Building

Managed side (the actual wrapper)

Just like any other .NET project / solution. So either via dotnet build or via Visual Studio.

When a cairo shared library / DLL is available, that's all, and you can start drawing.

Windows native cairo build

For Windows it's hard to find a downloadable cairo DLL that is recent enough, and especially without any failures. There are quite some around where some features like PDF rendering just don't output anything. Maybe because of wrong set compiler flags -- I didn't investigate these further.

Luckily cairo switched their build system to a modern one. They use Meson, so it's quite easy to build cairo for Windows. See native build instructions.

Tests

cairo has a lot of unit tests which ideally should be ported also to see if the wrapper works as intended. But for most cairo function the wrapper is really thin, and for methods that require more logic they're touched in the demo / example code to see that they work as they should. Besides that, porting all the tests to this project would be quite an effort...