How to Use

Supported Java versions

The Marlin-renderer has been tested so far on:

• Oracle JDK 6 ~ 10 (see builds)
• OpenJDK 6 ~ 23+
• Azul Zulu 7 ~ 17+ (OpenJDK builds are available for Windows, Linux, and macOS, see zulu.org)

Tested OS's:

• Windows 10 - 11 (64-bit)
• Ubuntu 16 - 22 (64-bit)
• macOS 12 - 14 (64-bit)

If you test it on other platforms (e.g., PowerPC, 32-bit OS's, etc.) or other JDK vendors, let us know how it works.

How to Use (basic)

JDK 11+

1. Download the Marlin release for JDK 11+: marlin-X.Y.Z-Unsafe-OpenJDK11.jar (RenderingEngine only)
2. Edit your java command line to patch the java.desktop module with the Marlin JAR:

java --patch-module java.desktop=${PATH_TO_MARLIN}/marlin-X.Y.Z-Unsafe-OpenJDK11.jar \
     ...

JDK 8 (0.9.4.5+)

1. Download the Marlin release: marlin-X.Y.Z-Unsafe.jar (RenderingEngine only)
2. Edit your java command line to add the Marlin JAR to the bootstrap classpath (prepend to override sun.java2d.marlin package) and set the system property sun.java2d.renderer:

java -Xbootclasspath/p:${PATH_TO_MARLIN}/marlin-X.Y.Z-Unsafe.jar \
     -Dsun.java2d.renderer=sun.java2d.marlin.DMarlinRenderingEngine \
     ...

JDK 6 ~ 8 (before 0.9.4.5)

1. Download the Marlin release: marlin-X.Y.Z-Unsafe.jar (RenderingEngine only)
2. Edit your java command line to add the Marlin JAR to the bootstrap classpath (append) and set the system property sun.java2d.renderer:

java -Xbootclasspath/a:${PATH_TO_MARLIN}/marlin-X.Y.Z-Unsafe.jar \
     -Dsun.java2d.renderer=org.marlin.pisces.DMarlinRenderingEngine \
     ...

If your application is a web server (with hundreds of threads), consider setting also the system property sun.java2d.renderer.useThreadLocal to false (see Tuning-options)

Finally, run your Java application and you should see following logs (System.out or in log files):

INFO: ===============================================================================
INFO: Marlin software rasterizer           = ENABLED
INFO: Version                              = [marlin-X.Y.Z-Unsafe]
INFO: sun.java2d.renderer                  = sun.java2d.marlin.DMarlinRenderingEngine
...

Squeezing Out Every Ounce of Performance (JDK-8 only)

The above usage of the Marlin renderer plugs it into JDK 8 using a well supported mechanism. However, it is possible to gain a bit more performance by replacing some of JDK's built-in classes with optimized versions contained in the marlin-X.Y-sun-java2d.jar file. This can be done by including the following extra parameter on the java command line to prepend the classes to the bootstrap classpath:

java -Xbootclasspath/p:${PATH_TO_MARLIN}/marlin-X.Y.Z-Unsafe-sun-java2d.jar

There is, however, a catch. According to the Oracle documentation, using the bootclasspath:p option violates the Oracle binary license agreement, as such, the above should be used only for experimental purposes. This restriction applies to the Oracle JDK builds ONLY and does NOT apply to OpenJDK builds since they are licensed under GPLv2.

Enjoy!

Feedback and bug reports are welcome!