https://github.com/unascribed/jxljxl
Java Xtreme Library for JPEG-XL — a fluent and convenient frontend to all of libjxl's features
https://github.com/unascribed/jxljxl
java jpeg-xl jxl panama
Last synced: 6 months ago
JSON representation
Java Xtreme Library for JPEG-XL — a fluent and convenient frontend to all of libjxl's features
- Host: GitHub
- URL: https://github.com/unascribed/jxljxl
- Owner: unascribed
- License: mit
- Created: 2023-07-29T06:48:54.000Z (about 2 years ago)
- Default Branch: trunk
- Last Pushed: 2023-09-13T17:35:37.000Z (about 2 years ago)
- Last Synced: 2025-03-29T14:51:08.812Z (7 months ago)
- Topics: java, jpeg-xl, jxl, panama
- Language: Java
- Homepage:
- Size: 347 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# JXLJXL
**Warning**: JXLJXL is not complete. Currently, it only offers an encode API and has not been
thoroughly tested. It has encoded multiple files successfully, and v0.1 of it powers the JXL support
in [Visage](https://visage.surgeplay.com).
*The GitHub copy of this repository is a mirror. The authoritative copy is hosted on [Forgejo](https://git.sleeping.town/unascribed/JXLJXL)*
JXLJXL (jjxl or jxl^2 for short, the **J**ava **X**treme **L**ibrary for **J**PEG-**XL**) is a Java
library for low-level access to the libjxl encode/decode APIs. JXLJXL allows you to create JXL
files will all sorts of interesting topologies, with full support for multi-frame files, custom
boxes, extra channels, and names for both frames and channels.
The API is designed to feel nice to use within Java, having a fluent interface that resembles the
builder pattern. This design allows it to flex all the way from simple one-shot encoding of regular
files to building all manner of complex payloads.
The heart of the library is jxlpanama, a simple binding to libjxl via Project Panama, generated with
jextract. These bindings are… thorny, to say the least. Using a C adaptation of a C++ API from Java
isn't pretty. JXLJXL paves over the raw bindings, making advanced JXL use cases a breeze.
JXLJXL is designed for advanced use cases. If you don't need to handle encoding and have very simple
needs for decoding, the [jxlatte](https://github.com/Traneptora/jxlatte) project is a pure Java
implementation of a simple JXL decoder that I recommend using instead.
## Usage
JXLJXL is a modern Java 20 library that uses a preview feature — Project Panama, specifically the
Foreign Linker API, a modern and fast replacement for JNI. So, while including the dependency is as
easy as usual:
```gradle
repositories {
maven {
url 'https://repo.sleeping.town'
content.includeGroup 'com.unascribed'
}
}
dependencies {
implementation 'com.unascribed:jxljxl:0.2.1'
}
```
…you will also need to add these options to your Java invocation, in order to enable the Panama API
and give JXLJXL permission to invoke native code:
`--enable-preview --enable-native-access=com.unascribed.jxljxl`
If your project is not modular, then you will need this instead:
`--enable-preview --enable-native-access=ALL-UNNAMED`
JXLJXL does not currently bundle a copy of libjxl — that needs to be available on the target system.
Bundled libraries will be added later.
## API
The primary entrypoint to the encoding API is `JXLEncoder`, which can be used something like so:
```java
JXLEncoder.create()
.size(width, height)
.bitsPerSample(8)
.numChannels(3, 1)
.colorEncoding(JXLPredefinedColorEncoding.SRGB)
.newFrame()
.distance(1.5f)
.withModularEncoding()
.lossyPalette(true)
.done()
.brotliEffort(3)
.effort(1)
.keepInvisible(false)
.commit(bufferedImage)
.encodeToStream(out);
```
All the documentation from libjxl, plus some extras, are included as javadocs in the library. Take
a look around!
All operations are buffered in memory until the `encode` call is made, so the order isn't
particularly important. JXLJXL handles calling everything in the right order and making sense of the
mess.