System Properties
|
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 2Dtrace
property with a flag when running an application, like this:Or you can specify it by settingjava -Dsun.java2d.trace=log SomeApp_JAVA_OPTIONS
before running the application, like this:export _JAVA_OPTIONS='-Dsun.java2d.trace=log' (UNIX bash shell) java SomeAppSome system properties are also settable using environment variables. For example, the
d3d
property has the equivalent environment variableJ2D_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
- 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 totrue
:-Dsun.java2d.opengl=trueTo 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=TrueAn 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.
traceIntended 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, thetrace
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 aGraphics
method invocation. These method names will not necessarily map directly to methods on theGraphics
object, nor will the number of calls made on theGraphics
object map directly to the number of primitive operations performed.The
src
anddst
represent the type of surfaces or source data involved in the operation.The
composite
names match the names in theAlphaComposite
class fairly closely with the suffix "NoEa
" meaning that theAlphaComposite
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=0This 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:If problems persist, try setting the-Dsun.java2d.d3d=falseddoffscreen
property to false. If that doesn't solve the problems, try settingnoddraw
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: Thed3dtexbpp
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 withToolkit.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 whetherVolatileImages
should be kept in VRAM.
Introduced: 1.4.1_02
Default value: false in 1.4; as of 1.5 Beta 1, true iftranslaccel
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: Theddforcevram
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 settranslaccel
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 theddscale
flag to true.
Note: Theddscale
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, bothtranslaccel
andddforcevram
must be true for translucent images to be accelerated.
Note: Thetranslaccel
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 1When 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
GraphicsConfiguration.createCompatibleImage(w,h, Transparency.TRANSLUCENT)
- Images loaded with
Toolkit.getImage()
that have a translucent color modelBufferedImage
constructor can also be accelerated. To find out whether an image can be accelerated on a particular device, you can use theImage
getCapabilities
method (added in 1.5) to get anImageCapabilities
object, which you can query using theisAccelerated
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_DGASetting this variable automatically enables the use of pixmaps, in effect setting
pmoffscreen
to true. The reverse, however, is not true: settingpmoffscreen
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 withJ2D_PIXMAPS
environment flag:
setenv J2D_PIXMAPS=shared
setenv J2D_PIXMAPS=serverIf 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 toserver
, 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 thepmoffscreen
flag:
-Dsun.java2d.pmoffscreen=true
-Dsun.java2d.pmoffscreen=falseSetting 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.
Java Software