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

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.