System Properties for Java 2D Technology

This document describes several unsupported properties that you can use to customize how the 2D painting system operates. You might use these properties to improve performance, fix incorrect rendering, or avoid system crashes under certain configurations. For example, on a small set of Microsoft Windows computers with bad DirectDraw or Direct3D drivers, the use of hardware-accelerated rendering might cause system crashes. You can use properties to specify that on these computers, the Java 2D system shouldn't use DirectDraw or Direct3D.

Warning: Take care when using these properties. Some of them are unsupported for very practical reasons. For example, some behaviors are disabled by default due to driver instabilities; enabling such behaviors could cause system instabilities on some configurations.

Since these properties have the sole purpose of enabling or disabling implementation-specific behaviors, they are subject to change or removal without notification. Some properties might work only on the exact product releases for which they are documented.

2D properties have the prefix sun.java2d.. To specify them, you can use either command-line flags or the _JAVA_OPTIONS environment variable. For example, you can specify the 2D trace property with a flag when running an application, like this:

java -Dsun.java2d.trace=log SomeApp

Or you can specify it by setting _JAVA_OPTIONS before running the application, like this:

export _JAVA_OPTIONS='-Dsun.java2d.trace=log' (Solaris, Linux, or Mac OS X bash shell)
java SomeApp

Some system properties are also settable using environment variables. For example, the d3d property has the equivalent environment variable J2D_D3D. The property description lists the equivalent environment variable, if one exists.

Note: See the High Performance Graphics White Paper for explanations of terms used in property descriptions.

This document lists the following properties:

System Properties for All Platforms
- opengl
- trace
- awt.useSystemAAFontSettings
System Properties for Microsoft Windows Platforms
System Properties for Linux and Solaris Platforms

System Properties for All Platforms

`opengl`

Intended use: To enable the OpenGL-based pipeline, which provides hardware acceleration.
Introduced: 1.5 Beta 1 (Solaris/Linux); 1.5 Beta 2 (Microsoft Windows)
Default value: false
How to use: To silently enable the OpenGL-based pipeline, set this property to true:

-Dsun.java2d.opengl=true

To receive verbose console output about whether the OpenGL-based pipeline is initialized successfully for a particular screen, set this property to True (note the uppercase T):

-Dsun.java2d.opengl=True

An OpenGL-based pipeline for Java 2D was introduced in 1.5 Beta 1 for Solaris/Linux and 1.5 Beta 2 for Microsoft Windows platforms. This pipeline is currently disabled by default. It provides hardware acceleration for simple rendering operations (text, images, lines, and filled primitives) as well as those that involve complex transforms, paints, composites, and clips.

For more information: The OpenGL section of New Java 2D Features in the Java 2 SDK, v1.5.

`trace`

Intended use: To help determine the source of less-than-desirable graphics performance.
Introduced: 1.4
How to use: If your application is experiencing less-than-desirable performance, the trace runtime flag can help you determine the source of the problem. The flag is specified with a list of options:

    -Dsun.java2d.trace=[log[,timestamp]],[count],[out:<filename>],[help],[verbose]

The options are:

log: print out the name of each primitive as it is executed
timestamp: precede each log entry with the currentTimeMillis()
count: at exit, print out a count of each primitive used
out:<filename>: send output (logging and counts) to the indicated file
help: print out a short usage statement
verbose: print out a summary of the options chosen for this run

If you use the log option, the Java runtime will print the executed primitives' names, most of which will be in this format:

    <classname>.<methodname>(<src>,<composite>,<dst>)

The methodname represents the basic graphics operation that is used to do the actual rendering work of a Graphics method invocation. These method names will not necessarily map directly to methods on the Graphics object, nor will the number of calls made on the Graphics object map directly to the number of primitive operations performed.

The src and dst represent the type of surfaces or source data involved in the operation.

The composite names match the names in the AlphaComposite class fairly closely with the suffix "NoEa" meaning that the AlphaComposite instance had an "extra alpha" attribute of 1.0. The "SrcNoEa" type is the most commonly used composite type and represents the simplest way of transferring pixels with no blending required. "SrcNoEa" is often used behind the scenes even though the default composite is "SrcOver" when opaque colors and images are rendered because the two operations are indistinguishable for opaque source pixels.

Platform rendering pipelines are sometimes used for doing opaque operations on surfaces accessible by a platform renderer, such as X11, GDI, or DirectDraw. Their names currently use a simplified naming format, which has a prefix for the platform renderer and the name of the operation but without any classname or operand type list. Examples are "X11DrawLine", "GDIFillOval", and "DXFillRect". In the future these names should more closely approximate the names of the other primitives.

`awt.useSystemAAFontSettings`

Intended use:To override what text anti-aliasing settings are identified as being "desktop settings".
Introduced: 1.6
Default value:true.
How to use:Set on the command line or in a webstart jnlp file as one of the specified values below to control rendering hints used by Swing text.

Strictly this flag doesn't control Java 2D but is documented here because the values all directly map to Java 2D text antialiasing rendering hints values.

What the flag really does is override what the JRE reads from the user's desktop settings as the user's desktop antialiased text preferences. Swing instructs Java 2D to render Swing text to match that preference, so by overriding it you can control Swing text. This applies to standard Swing components (like JTextArea, JButton) in the Metal L&F (aka Java L&F) and native (Windows, GTK) Swing L&Fs. It should also apply to any custom component or L&F which picks up the same property.

For information on the desktop setting this overrides see AWT Desktop Properties

There aren't many reasons for you to specify this property but a couple are

The desktop setting you want isn't supported on your desktop (eg you want LCD text on Windows 2000)
JRE doesn't recognise your desktop setting (eg KDE)
You are automating testing under each of these conditions

System Property Value   | java.awt.RenderingHint value
"off"|"false"|"default" : VALUE_TEXT_ANTIALIAS_DEFAULT
"on"                    : VALUE_TEXT_ANTIALIAS_ON
"gasp"                  : VALUE_TEXT_ANTIALIAS_GASP
"lcd"|"lcd_hrgb"        : VALUE_TEXT_ANTIALIAS_LCD_HRGB
"lcd_hbgr"              : VALUE_TEXT_ANTIALIAS_LCD_HBGR
"lcd_vrgb"              : VALUE_TEXT_ANTIALIAS_LCD_VRGB
"lcd_vbgr"              : VALUE_TEXT_ANTIALIAS_LCD_VBGR

System Properties for Microsoft Windows Platforms

`accthreshold`

Obsoleted in: Java SE 6 Update 10
Intended use: To determine how many copies from managed images will occur before a VRAM version of the image is automatically created.
Introduced: 1.4.1_02
Default value: 1
How to use: To force accelerated surfaces to be created during image initialization, set the value to 0, as follows:

-Dsun.java2d.accthreshold=0

This property can be used to eliminate the initial delay in rendering when the images are being copied to the VRAM after the first few copies. Instead, the delay is effectively shifted to the image creation time.

This could be useful behavior when you know that your application will be able to take advantage of image management; just get the overhead of the copy over with at the start instead of incurring some number of slower copies to begin with and then having the copy overhead at some later time.

`d3d`

Intended use: To turn off the Java 2D system's use of Direct3D.
Introduced: 1.4.1_02
Equivalent environment variable: J2D_D3D
How to use: On a small subset of Windows 2000 systems with buggy Direct3D drivers, the use of Direct3D can cause a system crash. To turn off the use of Direct3D, set this property to false:

-Dsun.java2d.d3d=false

If problems persist, try setting the ddoffscreen property to false. If that doesn't solve the problems, try setting noddraw to true.

`d3dtexbpp`

Obsoleted in: Java SE 6 Update 10
Intended use: To specify that accelerated surfaces for managed or translucent images should be in 16-bit (4444) format, which saves VRAM and system memory but at the cost of decreased quality.
Introduced: 1.4.1_02
Default value: 32
How to use: To turn on 4444 format, set this property to 16:

-Dsun.java2d.d3dtexbpp=16

Note: The d3dtexbpp property has no effect if the OpenGL pipeline is in use.

When this property is set to 16, it forces the accelerated surfaces for managed images (created with GraphicsConfiguration.createCompatibleImage(w,h, TRANSLUCENT)) or translucent images loaded with Toolkit.getImage to be in 4444 format. The system memory surface for these images will be in 4444 format as well.

This option is useful when you have lots of images to be stored in VRAM. The downside is poorer quality.

This option is also useful for computers with video boards (such as 3dfx Voodoo3) that don't support 32-bit textures. When the Java 2D system uses 32-bit textures, as it does by default, then when it encounters a card without 32-bit texture support it disables support for accelerated translucent images. If you want acceleration of translucent images on a video board that doesn't support 32-bit textures, set the d3dtexbpp property to 16.

`ddforcevram`

Obsoleted in: Java SE 6 Update 10
Intended use: To specify whether VolatileImages should be kept in VRAM.
Introduced: 1.4.1_02
Default value: false in 1.4; as of 1.5 Beta 1, true if translaccel is true, and otherwise false
How to use: Normally, if the 2D system is using the DirectDraw/Direct3D pipeline and detects that an image in video memory is being read from too often (an expensive operation), it punts it to a system memory surface, which is faster to read from. Later, if the system detects that the user is copying from this surface to an accelerated surface again, it promotes it to the video memory. Setting this property to true disables the punting mechanism and always keeps the image in video memory.

Note: The ddforcevram property has no effect if the OpenGL pipeline is in use.

Although this property is often used with the translaccel property, it can be used separately. To set this property to true, either set translaccel to true in a 1.5 release, or set it separately:

-Dsun.java2d.ddforcevram=true

`ddoffscreen`

Obsoleted in: Java SE 6 Update 10, which contains a new implementation of D3D support. Setting sun.java2d.ddoffscreen=false is now interpreted exactly the same as disabling that via sun.java2d.d3d=false.
Intended use: To turn off the Java 2D system's use of DirectDraw and Direct3D for offscreen surfaces such as the Swing back buffer.
Introduced: 1.4
Default value: true
How to use: Setting this flag to false turns off DirectDraw offscreen surfaces acceleration.

`ddscale`

Obsoleted in: Java SE 6 Update 10
Intended use: To turn on hardware-accelerated scaling when the DirectDraw/Direct3D pipeline is in use.
Introduced: 1.2
Default value: false
How to use: Setting this flag to true enables hardware-accelerated scaling if the DirectDraw/Direct3D pipeline is in use. DirectDraw/Direct3D hardware scaling is disabled by default to avoid rendering artifacts in existing applications. These rendering artifacts are caused by possible inconsistencies between the scale method that the software scaling operation uses (nearest neighbor) and the different scale methods that video cards use. Certain events that occur while an application is running might cause a scaled image to be rendered partially with hardware scaling operations and partially with software scaling operations, resulting in an inconsistent appearance. For now, you can enable acceleration by setting the ddscale flag to true.

Note: The ddscale property has no effect if the OpenGL pipeline is in use.

For more information: High Performance Graphics White Paper

`noddraw`

Obsoleted in: Java SE 6 Update 10, which contains a new implementation of D3D support. Setting sun.java2d.noddraw=true is now interpreted exactly the same as disabling that via sun.java2d.d3d=false.
Intended use: To turn off the Java 2D system's use of DirectDraw and Direct3D completely.
Introduced: 1.2
Default value: false
How to use: Setting this flag to true turns off DirectDraw usage, which sometimes helps to get rid of rendering problems on Win32.

`translaccel`

Obsoleted in: Java SE 6 Update 10
Intended use: To specify whether translucent images should be hardware-accelerated when the DirectDraw/Direct3D pipeline is in use.
Introduced: 1.4.1_02
Default value: false
How to use: When the DirectDraw/Direct3D pipeline is being used, both translaccel and ddforcevram must be true for translucent images to be accelerated.

Note: The translaccel property has no effect if the OpenGL pipeline is in use.

To turn on acceleration of translucent images in 1.4 and 1.5:

-Dsun.java2d.translaccel=true
-Dsun.java2d.ddforcevram=true //unnecessary as of 1.5 Beta 1

When both these properties are true, the Java 2D system attempts to put translucent images into VRAM and use Direct3D for rendering (compositing) them to the screen or to a VolatileImage. Only translation transforms are supported (no rotation, scaling, and so on). Before 1.5, to be accelerated a translucent image had to be created in one of the following ways:

GraphicsConfiguration.createCompatibleImage(w,h, Transparency.TRANSLUCENT)
Images loaded with Toolkit.getImage() that have a translucent color model

As of 1.5, translucent images created with a BufferedImage constructor can also be accelerated. To find out whether an image can be accelerated on a particular device, you can use the Image getCapabilities method to get an ImageCapabilities object, which you can query using the isAccelerated method. Note that a managed image gets accelerated only after a certain number of copies to the screen or to another accelerated surface.

The following code fragment illustrates the use of accelerated images. The fragment assumes that back buffer is a VolatileImage. BufferStrategy can be used as well.

Image translucentImage = gc.createCompatibleImage(w, h, Transparency.TRANSLUCENT);
//...
Graphics2D g2 = (Grahics2D)backBuffer.getGraphics();
g2.drawImage(translucentImage, x, y, null);

Compositing with extra alpha with SRC_OVER rule (which is the default Graphics2D compositing rule) is accelerated, so the following code will allow the use of hardware for compositing: Code:

Image translucentImage = gc.createCompatibleImage(w, h, Transparency.TRANSLUCENT);
// ...
float ea = 0.5;
Graphics2D g2 = (Grahics2D)backBuffer.getGraphics();
g2.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, ea));
g2.drawImage(translucentImage, x, y, null);

System Properties for Linux and Solaris Platforms

`NO_J2D_DGA`

Intended use: To turn off DGA support and hardware acceleration on Solaris Sparc, which sometimes helps to reduce rendering artifacts.
Introduced: 1.2
Default value: (unset)
How to use: This property is settable only as an environment variable; it has no command-line flag equivalent. To turn off DGA support and hardware acceleration on Solaris Sparc, define the variable:

setenv NO_J2D_DGA

Setting this variable automatically enables the use of pixmaps, in effect setting pmoffscreen to true. The reverse, however, is not true: setting pmoffscreen to true doesn't disable DGA.

`J2D_PIXMAPS`

Intended use: To determine whether the 2D system uses shared memory pixmaps in the local display environment for storing images that experience frequent reads.
Introduced: 1.4 Beta 3
Default value: (unset)
How to use: This property is settable only as an environment variable; it has no command-line flag equivalent. As of 1.4 Beta 3, Java 2D starts out using normal pixmaps to store images, but changes the storage of frequently read images to use Shared Memory Pixmaps in the local display environment. You can override this default behavior, and force only one type of pixmap to be used, with J2D_PIXMAPS environment flag:

    setenv J2D_PIXMAPS=shared
    setenv J2D_PIXMAPS=server

If you set this flag to shared, all images are stored in Shared Memory Pixmaps if you are working in a local display environment. Conversely, if you set this flag to server, all images are stored in normal pixmaps, not Shared Memory Pixmaps; the normal pixmaps can be stored in VRAM at the discretion of the device driver.

For more information: High Performance Graphics White Paper

`xrender`

Intended use: To enable the XRender-based Java 2D rendering pipeline for modern X11-based desktops, offering improved graphics performance.
Introduced: Java SE 7
Default value: false
How to use: The pipeline is disabled by default, but may be enabled by setting the command line property -Dsun.java2d.xrender=true. Older X11 configurations may not be able to support XRender. The verbose form, -Dsun.java2d.xrender=True, can be used to enable a message to stdout indicating whether the pipeline was actually enabled.

`pmoffscreen`

Intended use: To determine whether Java 2D stores images in pixmaps by default when DGA is not available.
Introduced: 1.4 Beta 3
Default value: (unset)
How to use: As of 1.4 Beta 3, Java 2D stores images in pixmaps by default when DGA is not available, whether you are working in a local or remote display environment. You can override this behavior with the pmoffscreen flag:

    -Dsun.java2d.pmoffscreen=true
    -Dsun.java2d.pmoffscreen=false

Setting this flag to false disables offscreen pixmap support, which can solve some rendering problems. When the flag is true, offscreen pixmap support is enabled even if DGA is available.

For more information: High Performance Graphics White Paper