github.com/LWJGLX/lwjgl3-awt @main

This library allows for using OpenGL and Vulkan LWJGL 3 surfaces in AWT (and by extension, Swing) frames. Works with macOS, Windows, and Linux.

What does it get me?

Support for OpenGL: - creating OpenGL 3.0 and 3.2 core/compatibility contexts (including debug/forward compatible) - OpenGL ES contexts - floating-point and sRGB pixel formats - multisampled framebuffers (also with different number of color samples - Nvidia only) - v-sync/swap control - context flush control - robust buffer access (with application/share-group isolation) - sync'ing buffer swaps over multiple windows and cards - Nvidia only - delay before swap - Nvidia only

Support for Vulkan: - Vulkan 1.0, 1.1, 1.2, 1.3, 1.4 - MoltenVK support

Note about compatibility: The minimum macOS version for OpenGL is 10.5, and the minimum for Vulkan is 10.11, since Vulkan runs on top of the Metal API introduced in that version.

On Linux, Wayland sessions use EGL with the X11 window exposed by AWT under XWayland, matching LWJGL's default context API selection. Set Configuration.OPENGL_CONTEXT_API to native before LWJGL initializes OpenGL to force the GLX backend. This does not provide a native Wayland AWT surface.

macOS compositor screenshot tests

The end-to-end screenshot tests use java.awt.Robot, which requires Screen & System Audio Recording permission on macOS. They are disabled there by default so unattended builds never open macOS privacy UI. On a logged-in Mac where the process already has permission, require and run them with:

./mvnw -Pmacos-robot-screenshots test

The profile checks the normal screen-capture permission without requesting it and fails before attempting capture when it is unavailable. On macOS 15 and later, Apple's separate private-window-picker bypass authorization must also have been allowed already; macOS exposes no API that can preflight that authorization. Ordinary framebuffer-based screenshot tests continue to run on macOS without this profile.

How to use

Full code samples: - AWTTest - AWTThreadTest - Core32Test - SimpleDemo (Vulkan)

OpenGL

In order to create the highest available OpenGL core profile context that is at least 3.3, with 4 sample MSAA, use:

JFrame frame = new JFrame("AWT test");
frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
frame.setLayout(new BorderLayout());
GLData data = new GLData();
data.majorVersion = 3;
data.minorVersion = 3;
data.profile = GLData.Profile.CORE;
data.versionPolicy = GLData.VersionPolicy.AT_LEAST;
data.samples = 4;
frame.add(new AWTGLCanvas(data) {
  public void initGL() {
  }
  public void paintGL() {
  }
});

EXACT is the default version policy and preserves the traditional single-version request. HIGHEST ignores the configured version fields and requests the highest profile-compatible version without setting a minimum. The version actually selected by the platform is available through the canvas's effective.majorVersion and effective.minorVersion fields.

Vulkan

if (!AWTVK.isPlatformSupported()) {
    throw new RuntimeException("Platform not supported.");
}

JFrame frame = new JFrame("AWT test");
frame.setDefaultCloseOperation(JFrame.DISPOSE_ON_CLOSE);
frame.setLayout(new BorderLayout());
frame.setPreferredSize(new Dimension(600, 600));
Canvas canvas = new Canvas();
frame.add(canvas, BorderLayout.CENTER);
frame.pack(); // Packing causes the canvas to be lockable, and is the earliest time it can be used

long surface = AWTVK.create(canvas, instance);

// Do things with the surface

frame.setVisible(true);
frame.addWindowListener(new WindowAdapter() {
    @Override
    public void windowClosing(WindowEvent e) {
        super.windowClosing(e);

        // Destroy the surface to prevent leaks and errors
        KHRSurface.vkDestroySurfaceKHR(instance, surface, null);
}});