System Properties
for Java 2DTM Technology

 2D Contents

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' (UNIX 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.


System Properties for Microsoft Windows Platforms

accthreshold

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

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

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

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

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

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

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:

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 (added in 1.5) 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


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

Copyright © 1995-2004 Sun Microsystems, Inc. All Rights Reserved.

Please send comments using the Java 2D Feedback page. 		Sun Microsystems, Inc
Java Software