Module org.freedesktop.cairo

Package org.freedesktop.cairo

package org.freedesktop.cairo
This package contains Java language bindings for the cairo graphics library using the JEP-454 Panama FFI. The bindings are based on cairo 1.18 and work with JDK 22 or later.

These language bindings were primarily created as a companion to the GObject-based language bindings for Gtk and GStreamer generated with Java-GI, but they can also be used independently. The dependency on io.github.jwharm.javagi:glib is optional. There are no other external dependencies.

Overview

Java API

In general, the Java bindings match the cairo C API, but with a Java "coding style". C structs like cairo_t, cairo_surface_t and cairo_matrix_t are modeled with Java Proxy classes like Context, Surface and Matrix, and all flags and enumerations are available as Java enums. The proxy classes inherit when applicable: RadialGradient extends Gradient, which extends Pattern, and ImageSurface extends Surface. Types, functions and parameters follow Java (camel case) naming practices, so cairo_move_to(*cr, x, y) becomes cr.moveTo(x, y). Out-parameters in the C API are mapped to return values in Java. Multiple out parameters (like coordinates) are mapped to a Point or Rectangle return type in Java.

Resource allocation and disposal

Resources are allocated and deallocated automatically, so there is no need to manually dispose cairo resources in Java. However, please be aware that the disposal of proxy objects (like Context, surfaces, matrices and patterns) is initiated by the Java garbage collector, which does not know about the native resources, and might wait an indefinite amount of time before the objects are effectively disposed. Therefore, manual calls to destroy() are still possible in case the normal cleanup during GC is not sufficient to prevent resource exhaustion.

Error handling

Cairo status codes are checked in the language binding, and throw exceptions (IllegalStateException, IllegalArgumentException or IOException) with the detailed status description (from cairo_status_to_string()). The exceptions are documented in the Javadoc, except for the CAIRO_STATUS_NO_MEMORY status, which is not documented and will throw a RuntimeException if it occurs. If your application consumes a lot of memory, add try-catch blocks for this situation where applicable.

Other notable features

Some other features that the language bindings offer:
  • In the Context, Surface and Pattern classes (like Mesh), methods that return void in the C API, return this in Java, to allow method chaining.
  • The Path class is iterable, and path traversal is implemented with PathElement objects. The PathElement type is a sealed interface implemented by a record type for every path operation. They can be iterated and processed with record patterns (JEP 440). See the Path class javadoc for example code.
  • The cairo_set_user_data() and cairo_get_user_data() functions (to attach custom data to a cairo struct) are available in Java, with a twist. You can call setUserData() to attach any Java object instance, and getUserData() to get it back. Objects that can be marshaled to a native memory segment (primitive types, memory segments, and other Proxy objects) will be attached to the native cairo struct. Other types will only be attached to the Java object and will not be passed to cairo itself.
  • I/O operations in cairo that are designed to work with streams accept Java InputStream and OutputStream parameters.
  • The Surface and Device classes implement AutoCloseable and can be used in try-with-resources blocks. (The close() method calls the C cairo_..._finish() function.)
  • The cairo Script surface has been split into a Script class that inherits from Device, and a ScriptSurface class that inherits from Surface.
  • The functions for reading and comparing cairo version information are available in Java as static methods in the Cairo class.