{"id":31055332,"url":"https://github.com/jwharm/cairo-java-bindings","last_synced_at":"2025-09-15T04:43:48.259Z","repository":{"id":170127194,"uuid":"646243072","full_name":"jwharm/cairo-java-bindings","owner":"jwharm","description":"Java language bindings for the Cairo graphics library using the JEP-454 Panama FFI","archived":false,"fork":false,"pushed_at":"2025-05-12T19:19:13.000Z","size":764,"stargazers_count":12,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-12T20:39:35.649Z","etag":null,"topics":["bindings","cairo-drawing","java","jep-454"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jwharm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-27T18:42:59.000Z","updated_at":"2025-05-12T19:19:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"7815f937-6149-436f-83b5-cc4e233e9dd6","html_url":"https://github.com/jwharm/cairo-java-bindings","commit_stats":null,"previous_names":["jwharm/cairo-java-bindings"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/jwharm/cairo-java-bindings","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fcairo-java-bindings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fcairo-java-bindings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fcairo-java-bindings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fcairo-java-bindings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jwharm","download_url":"https://codeload.github.com/jwharm/cairo-java-bindings/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jwharm%2Fcairo-java-bindings/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275207640,"owners_count":25423895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-15T02:00:09.272Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bindings","cairo-drawing","java","jep-454"],"created_at":"2025-09-15T04:43:41.155Z","updated_at":"2025-09-15T04:43:48.246Z","avatar_url":"https://github.com/jwharm.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cairo Java bindings\nJava language bindings for the [cairo](https://www.cairographics.org) graphics library using the \nnew JEP-454 Foreign Function \u0026 Memory API. The bindings are based on **cairo 1.18.0** and work with **JDK 22** and newer.\n\nI created these language bindings primarily as a companion to the GObject-Introspection-based Java \nlanguage bindings for Gtk and GStreamer generated with [Java-GI](https://github.com/jwharm/java-gi), but they can also be used independently.\n\n## Overview\n\n### Java API\n\nIn general, the Java bindings match the cairo C API, but with a Java \"coding style\". C structs like \n`cairo_t`, `cairo_surface_t` and `cairo_matrix_t` are modeled with Java proxy \nclasses like `Context`, `Surface` and `Matrix`, and all flags and enumerations are \navailable as Java enums. The proxy classes inherit when applicable: `RadialGradient` extends \n`Gradient`, which extends `Pattern`, and `ImageSurface` extends `Surface`. Types, \nfunctions and parameters follow Java (camel case) naming practices, so \n`cairo_move_to(*cr, x, y)` becomes `cr.moveTo(x, y)`. Out-parameters in the C API \nare mapped to return values in Java. Multiple out parameters (like coordinates) are mapped to a \n`Point`, `Circle`, `Rect` or `RGBA` return type in Java.\n\n### Resource allocation and disposal\n\nMost resources are allocated and deallocated automatically, so there is no need to manually dispose \ncairo resources in Java as would be the case in C with the various `cairo_..._destroy()` functions.\nHowever, please be aware that the disposal of these objects (like Context) is initiated by the Java \ngarbage collector, which does not know about the native resources, and might wait an indefinite \namount of time before the objects are effectively disposed. Therefore, manual calls to `destroy()` \nare still possible in case the automatic cleanup during GC is not sufficient to prevent resource \nexhaustion.\n\nSome data types (like Matrix and TextExtents) must be allocated by the client; the `create()` \nmethods for these classes have an `Arena` parameter. Consult the JDK documentation to choose the \noptimal type of Arena for your use case.\n\nThe `Surface` and `Device` classes implement `AutoCloseable` and are preferably used in \ntry-with-resources blocks. (The `close()` method calls the C `cairo_..._finish()` function.)\n\n### Error handling\n\nCairo status codes are checked in the language binding, and throw exceptions \n(IllegalStateException, IllegalArgumentException or IOException) with the detailed status \ndescription (from `cairo_status_to_string()`). The exceptions are documented in the \nJavadoc, except for the `CAIRO_STATUS_NO_MEMORY` status, which is not documented and will \nthrow a RuntimeException if it occurs. If your application consumes a lot of memory, add try-catch \nblocks for this situation where applicable.\n\n### Other notable features\n\nSome other features that the language bindings offer:\n\n* In the `Context`, `Surface` and `Pattern` classes (like `Mesh`), methods that return \n  `void` in the C API, return `this` in Java, to allow method chaining.\n\n* The `Path` class is iterable, and path traversal is implemented with `PathElement` \n  objects. The `PathElement` type is a sealed interface implemented by a record type for every \n  path operation. They can be iterated and processed with record patterns (JEP 440). See the \n  `Path` class javadoc for example code.\n\n* I/O operations in cairo that are designed to work with streams accept Java `InputStream` and \n  `OutputStream` parameters.\n  \n* The cairo Script surface has been split into a `Script` class that inherits from \n  `Device`, and a `ScriptSurface` class that inherits from `Surface`.\n\n* The functions for reading and comparing cairo version information are available in Java as static \n  methods in the `Cairo` class.\n\n* Basic functionality is included to load fonts with FreeType2 for use with cairo.\n\n## API Documentation\n\nAll API documentation is available as Javadoc, and has been reworked to use Javadoc syntax and \ncross-reference between Java classes and methods. You can \n[lookup the Javadoc online](https://jwharm.github.io/cairo-java-bindings/javadoc/), or download \nthe javadoc or sources jar to use in your IDE.\n\n## License\n\nThe bindings are available to be redistributed and/or modified under the terms of  the GNU Lesser \nGeneral Public License (LGPL) version 2.1 (which is also one of the licenses of cairo itself.)\n\n## Usage\n\nThe library is available on Maven Central. Include it in your `gradle.build` or `pom.xml` file:\n\n```\ndependencies {\n  implementation 'io.github.jwharm.cairobindings:cairo:1.18.4.2'\n}\n```\n\nFurthermore, you obviously need to have the cairo library version 1.18 installed on your system, \nor else the Java bindings have nothing to bind to. You also need to use JDK 22 or newer.\n\nNow, you can start developing with cairo in Java. Have fun! This is a simple example to get started, \nported from [the first sample on this page](https://www.cairographics.org/samples/):\n\n```java\nimport org.freedesktop.cairo.*;\nimport java.io.IOException;\n\npublic class CairoExample {\n\n    public static void main(String[] args) throws IOException {\n        // Create surface\n        try (var surface = ImageSurface.create(Format.ARGB32, 300, 300)) {\n\n            // Create drawing context\n            var cr = Context.create(surface);\n\n            double x = 128.0;\n            double y = 128.0;\n            double radius = 100.0;\n            double angle1 = 45.0 * (Math.PI / 180.0);  // angles are specified\n            double angle2 = 180.0 * (Math.PI / 180.0); // in radians\n\n            // Draw shapes\n            cr.setLineWidth(10.0)\n              .arc(x, y, radius, angle1, angle2)\n              .stroke();\n\n            cr.setSourceRGBA(1.0, 0.2, 0.2, 0.6)\n              .setLineWidth(6.0)\n              .arc(x, y, 10.0, 0.0, 2 * Math.PI)\n              .fill();\n\n            cr.arc(x, y, radius, angle1, angle1)\n              .lineTo(x, y)\n              .arc(x, y, radius, angle2, angle2)\n              .lineTo(x, y)\n              .stroke();\n\n            // Write image to png file\n            surface.writeToPNG(\"example.png\");\n        }\n    }\n}\n```\n\nWhen compiling and running the application, suppress warnings about unsafe native \naccess with the command-line parameter `--enable-native-access=org.freedesktop.cairo`.\n\n## Building and Contributing\n\nPlease contribute PRs or log issues on [GitHub](https://github.com/jwharm/cairo-java-bindings).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwharm%2Fcairo-java-bindings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjwharm%2Fcairo-java-bindings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjwharm%2Fcairo-java-bindings/lists"}