Java 2D Pipeline Rendering Selection and Properties

12 Java 2D Pipeline Rendering Selection and Properties

Java 2D provides a set of pipelines, which can be roughly defined as different ways of rendering graphics primitives to a platform surface.

Because the JDK use platform-specific APIs to render graphics, the available pipelines vary by platform.

To select a pipeline, use the following command-line option:

-Dsun.java2d.<pipeline_name>=True|true|false

The variable <pipeline_name> is the name of the pipeline; see the following sections for possible pipeline names.
The capitalized value True enables verbose mode that prints a message that indicates whether the pipeline is enabled or not. Note that verbose mode won't be enabled if you select two pipelines (which is not recommended) and the chosen one has not been enabled with the verbose option.
The uncapitalized value true selects the pipeline, but doesn't enable verbose mode.
The value false means that this pipeline should not be chosen. However, one pipeline must always be enabled. This means that if you specify false to every pipeline, then one pipeline will be chosen. In addition, on some platforms, some pipelines cannot be "selected." You can deselect other pipelines only.

Every platform has a preferred default pipeline, which is automatically selected if it can be enabled. If not, a more basic pipeline is selected if it exists. If no pipeline can be enabled, then no windows can be created; this is called headless mode. Note that this shouldn't happen on a supported platform provided that the JDK is running in an environment with a display and has permissions to access it.

Topics

Linux Pipelines

There are three pipelines available

x11: This uses core X11 primitives for rendering where possible. However, if anti-aliased rendering is required, then most actual drawing is done in an MIT-Shared Memory Extensions pixmap, which is then blitted (which is the process of combining bitmaps into one with a boolean function) to the screen.
xrender: An X11 extension that allows much more direct rendering onto the X surface. This is better in most cases; in particular, it especially improve the performance of anti-aliased rendering on remote X displays.
opengl: This uses the OpenGL fixed function pipeline. This can improve performance if accelerated drivers are available.

The default pipeline is xrender. If all pipelines are disabled, then xrender is selected. If all pipelines are enabled, then the following is the order of preference: opengl, xrender, and then x11.

Windows Pipelines

There are three pipelines available:

gdi: This is essentially a software-only pipeline that uses basic Windows graphics device interface (GDI) bitmap blitting only. This pipeline is "unnamed," which means that it can't be selected or deselected by using its name.
d3d: The name of this pipleline is short for Direct3D. It's preferred where available; however this is disabled on Intel graphics cards due to rendering issues. In addition, this pipeline uses Direct3D version 9, which is a relatively old version.
opengl: This uses the OpenGL fixed-function pipeline. This pipeline isn't recommended except for completely controlled hardware and software environments because of rendering artifacts due to OpenGL drivers.

The default pipeline is d3d. If all pipelines are disabled, then gdi (the unnamed pipeline) is selected. If all pipelines are enabled, then the following is the order of preference: opengl, d3d, and then gdi.

System Properties Related to Windows Pipelines

To disable the d3d pipeline, set the system property sun.java2d.d3d to false as described in Java 2D Properties on Windows:

-Dsun.java2d.d3d=false

If you can't set system properties on the command line, then you can implictly disable the d3d pipeline by setting the environment variable J2D_D3D to false. Note that explicitly requesting the d3d will not always enable it if the detected graphics card is on a disabled list. To bypass this and force the d3d to be selected, set the environment variable J2D_D3D_NO_HWCHECK to true. Note that you might encounter rendering artifacts in this case.

macOS Pipelines

There are two pipelines available:

metal: This uses Apple's replacement for OpenGL.
opengl: This uses the OpenGL fixed function pipeline.

The default pipeline is metal. If all pipelines are disabled, then metal is selected. If all pipelines are enabled, then the following is the order of preference: metal and then opengl. Consequently the following two command line options select the opengl pipeline on macOS:

-Dsun.java2d.opengl=true
-Dsun.java2d.metal=false

Java 2D Pipeline Cross-Platform Diagnostics

Obtain detailed information about the startup procedures of the accelerated pipelines (D3D, OpenGL, and Metal) by setting a value between 1 and 5 for the J2D_TRACE_LEVEL environment variable; a value of 5 provides the most detailed information. This diagnostic is for the startup procedure only.

OpenGL Pipeline in Linux and Windows

The OpenGL pipeline is available on Linux and Windows.

This alternate pipeline uses the hardware-accelerated, cross-platform OpenGL API when rendering to VolatileImages, to back buffers created with BufferStrategy API, and to the screen.

This pipeline can offer great performance advantages over the default (X11 or GDI/DirectDraw) pipelines for certain applications. Consider enabling the pipeline for your application if it heavily uses of rendering operations like alpha compositing, antialiasing, and transforms.

The following are use cases for troubleshooting problems in OpenGL pipeline.

Enable OpenGL Pipeline

The OpenGL pipeline is disabled by default.

To attempt to enable the OpenGL pipeline, provide the following option to the JVM:

-Dsun.java2d.opengl=True

To receive verbose console output about whether the OpenGL pipeline is initialized successfully for a particular screen, set the option to True (note the uppercase T).

Minimum Requirements

The OpenGL pipeline will not be enabled if the hardware or drivers do not meet the minimum requirements.

If one of the following requirements is not met, Java 2D will fall back and use the default pipeline (X11 on Linux or GDI/DirectDraw on Windows), which means your application will continue to work correctly, but without the OpenGL acceleration.

The minimum requirements for the Linux operating system are the following:

Hardware accelerated OpenGL/GLX libraries installed and configured properly
OpenGL version 1.2 or higher
GLX version 1.3 or higher
At least one TrueColor visual with an available depth buffer

The minimum requirements for Windows OS are the following:

Hardware accelerated drivers supporting the extensions WGL_ARB_pbuffer, WGL_ARB_render_texture, and WGL_ARB_pixel_format
OpenGL version 1.2 or higher
At least one pixel format with an available depth buffer

Diagnose Startup Issues

You can get detailed information about the startup procedures of the OpenGL-based Java 2D pipeline by using the J2D_TRACE_LEVEL environment variable.

As previously mentioned, the OpenGL pipeline might not be enabled on certain machines for various reasons. For example, the drivers might not be properly installed and might report an insufficient version number. Alternatively, your machine might have an older graphics card that does not support the appropriate OpenGL version or extensions.

You can get detailed information about the startup procedures of the OpenGL-based Java 2D pipeline by using the J2D_TRACE_LEVEL environment variable, as shown in the following examples.

Set the J2D_TRACE_LEVEL environment variable on Windows.

# set J2D_TRACE_LEVEL=4
# java -Dsun.java2d.opengl=True YourApp

Set the J2D_TRACE_LEVEL environment variable on Linux.

# export J2D_TRACE_LEVEL=4
# java -Dsun.java2d.opengl=True YourApp

The output will be different depending on your platform and the installed graphics hardware, but it can give you some insight into the reasons why the OpenGL pipeline is not being successfully enabled for your configuration.

Note:

This output is especially useful when filing bug reports intended for the Java 2D team.

Diagnose Rendering and Performance Issues

Because the OpenGL pipeline relies so heavily on the underlying graphics hardware and drivers, it might sometimes be difficult to determine whether rendering or performance issues are being caused by Java 2D or by the OpenGL drivers.

The GL_EXT_framebuffer_object extension provides better performance for rendering and reduced VRAM consumption when using VolatileImages. This "FBO" code path is enabled by default when the OpenGL pipeline is enabled, but only if your graphics hardware and driver support this OpenGL extension. This extension is generally available on Nvidia GeForce/Quadro FX series and later, and on ATI Radeon 9500 and later. If you suspect that the "FBO" code path is causing problems in your application, then you can disable it by setting the following system property:

-Dsun.java2d.opengl.fbobject=false

Setting this property will cause Java 2D to fall back on the older pbuffer-based code path.

If you find that a certain Java 2D operation causes different visual results with the OpenGL pipeline enabled than without, then it probably indicates a graphics driver bug. Similarly, if the performance of Java 2D rendering is significantly worse with the OpenGL pipeline enabled than without, then it is most likely caused by a driver or hardware problem.

In either case, file a detailed bug report through the normal bug reporting channels. See Submit a Bug Report. When filing bug reports, be as detailed as possible, and include the following information:

Operating system (for example, Ubuntu Linux 6.06, Windows XP SP2)
Name of graphics hardware manufacturer and device (for example, Nvidia GeForce 2 MX 440)
Exact driver version (for example, ATI Catalyst 6.8, Nvidia 91.33)
Output when J2D_TRACE_LEVEL=4 is specified on the command line (as described in the previous section)
The output of the glxinfo command if you are on Linux

Latest OpenGL Drivers

Because the OpenGL pipeline relies heavily on the OpenGL API and the underlying graphics hardware and drivers, it is very important to ensure that you have the latest graphics drivers installed on your machine. Drivers can be downloaded from your graphics card manufacturer's web site, as shown in the following table.

Manufacturer	Platforms	Cards Known to Work
AMD/ATI	Linux, Windows	Radeon 8500 and later, FireGL series
Nvidia	Linux, Windows	GeForce 2 series and later, Quadro FX series and later
Xi Graphics	Linux	Various (check with Xi Graphics)