| Documentation Contents

# System Properties for Java 2DTM 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' (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`
>   - `trace`
>   - `awt.useSystemAAFontSettings`
> - System Properties for Microsoft Windows Platforms
>   - `accthreshold`
>   - `d3d`
>   - `d3dtexbpp`
>   - `ddforcevram`
>   - `ddoffscreen`
>   - `ddscale`
>   - `noddraw`
>   - `translaccel`
> - System Properties for Linux and Solaris Platforms
>   - `NO_J2D_DGA`
>   - `J2D_PIXMAPS`
>   - `pmoffscreen`

> ### 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`

> 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:

> - `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 (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-2010 Sun Microsystems, Inc. All Rights Reserved. Please send comments using this Feedback page. | Java Technology