TurboJPEG Plugin

Provides TurboJPEGDecoder and TurboJPEGEncoder.

About

This plugin uses Java 22's new Foreign Function & Memory API ("Panama") to call into the TurboJPEG library. TurboJPEG is essentially a high-level wrapper API around libjpeg that is included with libjpeg-turbo.

The advantages of this plugin over Galia's built-in JPEG functionality (which employs the standard JDK Image I/O JPEG plugins) are that it is both faster and more lenient when reading malformed JPEGs, JPEGs with mismatching color profiles, and other quirky files.

The libjpeg-turbo distribution also includes a JNI binding, which brings the high-level TurboJPEG API directly into Java. We have opted not to use this because it requires libjpeg-turbo be compiled with the binding explicitly enabled, which is an additional hassle for most users.

libjpeg-turbo is not included with this plugin and must be provided separately. Most OS package managers should provide it. The minimum required version is 3.0. Newer versions in the 3.x series should work as well, but may not have been tested. It is a goal to support all 3.x versions fully, so if you encounter any problems, please contact us.

Once libjpeg-turbo has been installed, its containing directory must be present on the Java library path. You can either change your library path to include it (by adding the -Djava.library.path VM argument to your config/jvm.options file), or move the library files to one of the directories on that path. Galia logs the Java library path at startup.

Installation

Step 1: Install the plugin

Use the plugin installer:

bin/install_plugin.sh galia-plugin-turbojpeg

Alternatively, download the plugin directly and extract it into Galia's plugins directory.

Step 2: Enable TurboJPEGDecoder (optional)

If you'd like to use TurboJPEGDecoder to read JPEGs, you must assign it to the JPEG source format in your application configuration:

decoder.formats:
  jpg: TurboJPEGDecoder

Without this, the application won't know whether to use it or the built-in JPEGDecoder, and will return an error.

Step 3: Enable TurboJPEGEncoder (optional)

If you'd like to use TurboJPEGEncoder to generate JPEGs, you must assign it to the JPEG output format in your application configuration:

encoder.formats:
  jpg: TurboJPEGEncoder

Without this, the application won't know whether to use it or the built-in JPEGEncoder, and will return an error.

Step 4: Configure the decoder and encoder (optional)

If you'd like to override any of the default settings used by TurboJPEGDecoder or TurboJPEGEncoder, copy the keys from config.yml.sample into your application configuration file and edit them there.