B Java 2D Properties

This appendix presents properties that can be useful in troubleshooting Java 2D.

This appendix contains the following sections:

Java 2D Properties Common to All Platforms

On high DPI displays, Java 2D API automatically scales to match the display as follows:

  • Windows: All windows scaling is applied exactly.
  • Linux (X11): Scaling is applied only if the desktop scale is 2 or greater, rounded down.
  • macOS: Scaling is applied if macOS detects that a retina display is in use (2× scaling) rounded down; note that on macOS, scaling only affects the off-screen buffer

Physical (real world inches and centimetres) window sizes aren't affected.

To disable high DPI scaling, specify the following property:

-Dsun.java2d.uiScale.enabled=false

Alternatively, specify the scaling factor (which is subject to plaftorm limitations):

-Dsun.java2d.uiScale=1.0

You can specify the scaling factor with an environment variable; for example, the following sets a scaling factor of 2:

J2D_UISCALE=2.0

Java 2D Properties on Linux

The following lists some useful Java 2D properties on Linux.

Note:

The default values for Java 2D properties on Linux usually result in the best performance. Change them only if required.

The Xrender pipeline is the default pipeline for Linux. Change this default as follows:

  • -Dsun.java2d.xrender=false – disable the Xrender pipeline and fallback to the basic X11 pipeline
  • -Dsun.java2d.opengl=true – attempt to enable the OpenGL pipeline

By default, when using an X11-based pipeline, the MIT Shared Memory Extension (MIT-SHM) is used if available. To not use MIT-SHM, set the following environment variable as follows:

set NO_J2D_MITSHM=true

To disable off-screen pixmaps in an X11 remote display, specify the following property:

-Dsun.java2d.pmoffscreen=false

Note:

This was important when using X11 as the pipeline; however, because Xrender (the default pipeline) can composite to a remote pixmap, this is likely not needed for most applications and might even be unhelpful.

Control the use of shared and server pixmaps by specifying the value of the environment variable J2D_PIXMAPS as follows:

  • J2D_PIXMAPS unset – use both types as appropriate
  • J2D_PIXMAPS=shared – use only shared memory pixmaps
  • J2D_PIXMAPS=server – use only server-side pixmaps

Note:

In general, setting any of the options related to pixmaps is a matter for careful experimentation and should only be adopted if there is a clear measured benefit.

Control the default X visual by specifying the value of the FORCEDEFVIS environment variable as follows:

  • FORCEDEFVIS unset – use the best visual available
  • FORCEDEFVIS <hexadecimal value> – use the valid visual whose ID is the hexadecimal value

Java 2D Properties on Windows

The following list some useful Java 2D properties on Windows.

The D3D pipeline is the default pipeline for Windows. Change this default by specifying a value of the system property sun.java2d.d3d or sun.java2d.opengl or the environment variable J2D_D3D or J2D_D3D_NO_HWCHECK:

  • -Dsun.java2d.d3d=false – disable the use of the Direct3D pipeline; GDI is used instead
  • -Dsun.java2d.opengl=true – attempt to enable the OpenGL pipeline
  • J2D_D3D=true – enable the use of the Direct3D pipeline (subject to hardware checks)
  • J2D_D3D=false – disable the use of the Direct3D pipeline
  • J2D_D3D_NO_HWCHECK=true – disable checking for graphics chips and D3D drivers with known problems

Note:

In JDK 8, you can set the sun.java2d.dpiaware system property to either true or false:
  • -Dsun.java2d.dpiaware=true – the JDK renders graphics based on the desktop's scale
  • -Dsun.java2d.dpiaware=false – the operating system renders graphics in Java applications based on the desktop's scale

By default, the JDK renders graphics if the desktop's scale is less than 150%; otherwise, Windows renders graphics in Java applications. This can result in fuzzy rendering if the desktop's scale is 150% or greater because the JDK will no longer render text, geometry, or multiresolution images at the ideal resolution. The JDK partially compensates for this case by using grayscale, not ClearType, text rendering in Swing applications.

If your application running in a JDK 8 environment is too fuzzy when the desktop's scale is 150% or greater and you would prefer clearer but smaller rendering, then set sun.java2d.dpiaware to true or alternatively change your desktop's scale to a lower value such as 100% or 125%.

However, in JDK 9 and later, setting the system property sun.java2d.dpiaware to false has no effect. The Java launcher and compiler (java.exe, javaw.exe) contains a high DPI manifest entry (<dpiAware>) that's set to true, which cannot be disabled from code. Only a custom native Java launcher that doesn't set this manifest entries can use this option.

Java 2D Properties on macOS

The following table describes some useful Java 2D properties on macOS.

Table B-1 Java 2D Properties on macOS

System Property Default Value Description
sun.java2d.metal JDK 19 and later: true

JDK 17 and 18: false

 If true, then Metal is the default Java 2D rendering pipeline.
sun.java2d.opengl JDK 19 and later: false

JDK 18 and earlier: true

If true, then OpenGL is the default Java 2D rendering pipeline.