JEP 382: New macOS Rendering Pipeline

OwnerPhilip Race
Componentclient-libs / 2d
Discussionlanai dash dev at openjdk dot java dot net
Reviewed byAjit Ghaisas, Alexey Ushakov, Iris Clark, Jayathirth D V, Kevin Rushforth, Sergey Bylokhov
Endorsed byKevin Rushforth
Created2020/01/31 21:40
Updated2021/01/21 22:07


Implement a Java 2D internal rendering pipeline for macOS using the Apple Metal API as alternative to the existing pipeline, which uses the deprecated Apple OpenGL API.




Two major factors motivate the introduction of a new Metal-based rendering pipeline on macOS:


Most graphical Java applications are written using the Swing UI toolkit, which renders via the Java 2D API. Internally, Java 2D can use software rendering plus a blit to the screen or it can use a platform-specific API, such as X11/Xrender on Linux, Direct3D on Windows, or OpenGL on macOS. These platform-specific APIs typically offer much better performance than software rendering and generally off-load the CPU. Metal is the new Apple platform API for such rendering, replacing the deprecated OpenGL API. (The name has nothing to do with the Swing “Metal” Look and Feel; that is just a coincidence.)

We will update existing internal JDK code and create new code to utilize the Metal framework in a similar way as we already utilize the other platform-specific APIs. We will also investigate opportunities to leverage new capabilities of the Metal framework, such as more concurrent rendering.

Refactoring outside of the OpenGL/Metal code is expected to be minimal.

This implementation of a new rendering pipeline will not introduce any new Java API. However, if necessary we will update the Java AWT Native Interface to provide access to a Metal native drawing surface. That is a native code interface, and thus does not affect Java language applications.

The Metal pipeline will co-exist with the OpenGL pipeline. When a graphical application starts up, one or the other will be chosen. For now, OpenGL will remain the default. Metal will be used only if it is specified on startup or if the initialization of OpenGL fails, as would happen in a future version of macOS with no OpenGL support.

Assuming that Apple provides some period of time before removing OpenGL support, after this JEP is integrated an application can opt-in to Metal by specifying -Dsun.java2d.metal=true on the java command line. The Metal rendering pipeline will be made the default in a later release.

Work on this JEP is being conducted in Project Lanai.


Testing the functionality of the new pipeline does not require new test development, since no Java 2D APIs will change. Existing tests and real-world applications will suffice. These include:

  1. JDK jtreg regression tests
  2. JCK Tests
  3. Java 2D and Swing Demos
  4. IDEs such as Intellij IDEA and Netbeans, as examples of large-scale real world applications

To test performance, we will use:

  1. J2DBench, a Java 2D benchmarking application included in JDK
  2. RenderPerfTest, a custom stress test that renders multiple objects of the same primitive type and measures frames per second (FPS) developed in Project Lanai
  3. IntelliJ IDEA IDE performance

These lists are subject to change as the work progresses.

Risks and Assumptions

Prototype work to date in Project Lanai suggests that we are well on the way to exceeding our goals and metrics. Until we are nearly finished, however, we cannot be sure that Metal will perform as well as expected in all cases. For example, so far no way has been discovered to efficiently implement the XOR operation which, although niche, is required.