9 Java 2D

Properties Related to the Use of X11 Pixmaps

Java 2D by default uses X11 pixmaps for storing or caching certain types of offscreen images. Only the following types of images can be stored in pixmaps:

• Opaque images, in which case ColorModel.getTransparency() returns Transparency.OPAQUE

• 1-bit transparent images (also known as sprites, Transparency.BITMASK)

The advantage of using pixmaps for storing images is that they can be put into the framebuffer's Video memory at the driver's discretion, which improves the speed at which these pixmaps can be copied to the screen or another pixmap.

The use of pixmaps typically results in better performance. However, in certain cases, the opposite is true. Such cases typically involve the use of operations which cannot be performed using the X protocol, such as antialiasing, alpha compositing, and transforms that are more complex than simple translation transforms.

For these operations the X11 pipeline must do the rendering using the built-in software renderer. In most cases this includes reading the contents of the pixmap to a system memory (over the network in the case of remote X server), performing the rendering, and then sending the pixels back to the pixmap. Such operations could result in extremely poor performance, especially if the X server is remote.

Disabling the Use of Pixmaps by the X11 Pipeline

To disable the use of pixmaps by Java2D, pass the following property to the Java VM: -Dsun.java2d.pmoffscreen=false.

Disabling/Forcing the Use of Shared Memory Pixmaps by the X11 Pipeline

To minimize the effect of such operations requiring reading of pixels from a pixmap on overall performance, the X11 pipeline uses shared memory pixmaps for storing images which are often read from. Note that the shared memory pixmaps can only be used in the case of a local X server.

The advantage of using shared memory pixmaps is that the pipeline can get direct access to the pixels in the pipeline bypassing the X11 protocol, which results in better performance.

By default an image is stored in a normal X server pixmap, but it can be later moved to a shared memory pixmap if the pipeline detects excessive reading from such an image. The image can be moved back to a server pixmap if it is copied from often enough.

The pipeline allows two ways of controlling the use of shared memory pixmaps: either disabling them, or forcing all images to be always stored in shared memory pixmaps.

• To disable shared memory pixmaps, set the J2D_PIXMAPS environment variable to server. This is the default in remote X server case.

• To force all pixmaps to be created in shared memory, set J2D_PIXMAPS to shared.

First try forcing the shared memory pixmaps, as it often improves performance. However, with certain video board/driver configurations it may be necessary to disable the shared memory pixmaps to avoid rendering artifacts or crashes.

Use of MIT Shared Memory Extension by the X11 Pipeline

By default, the Java 2D X11 pipeline uses the MIT Shared Memory Extension (MIT SHM). This extension allows a faster exchange of data between the client (the Java application) and the X server, and this can significantly improve the performance of Java applications.

Increasing Shared Memory Available to X Server and Java 2D

On Oracle Solaris operating system releases 8 and earlier it was sometimes necessary to increase the amount of shared memory available to the system (and to X server in particular) as the default was too low, resulting in poor rendering performance. Increasing the amount of shared memory and shared memory segments can result in better performance.

To change the default settings on Oracle Solaris operating system, edit the /etc/system file, changing the shmsys:shminfo_* settings, as in the following example. Note that this is not needed on Oracle Solaris 9 and newer.

set shmsys:shminfo_shmmax=10000000
set shmsys:shminfo_shmni=200
set shmsys:shminfo_shminfo=150

On Linux this setting can be configured by editing the /proc/sys/kernel/shm* files.

Disabling Use of Shared Memory Extension by the X11 Pipeline

In case of problems (such as crashes, or rendering artifacts) with older X servers and Shared Memory Extension, it is useful to be able to disable the extension. To disable the use of MIT SHM, set the J2D_USE_MITSHM environment variable to false.

Oracle Solaris operating system on SPARC: Use of DGA in Certain Configurations

On SPARC hardware, if the framebuffer supports Sun's DGA (Direct Graphics Access) X server extension, and Java 2D has a corresponding module for accessing the framebuffer, DGA will be used for rendering to the screen.

All offscreen images will reside in Java heap memory, and Java 2D's software-only rendering pipeline is used for rendering to them. This is different from a typical UNIX configuration, where X11 pixmaps are used for offscreen images.

Detecting Use of DGA Extension for Rendering to Screen

To detect if the DGA extension is used for rendering to the screen, run any Java application which does some rendering or displays a GUI, and check if a /tmp/wg* file was created when the application started. Exit the application and verify that the file has been deleted. If this is the case, then on this system Java 2D is using DGA.

Typical Issues Caused by Use of DGA

Since DGA allows direct access to the framebuffer's video memory, the typical problems include corruption outside of window bounds, complete system, and X server lock-ups.

Controlling Use of DGA by Java 2D

If it is determined that DGA is being used, the first thing to try is to disable it. This can be done by setting the NO_J2D_DGA environment variable to true. This forces the default UNIX path to use only X11 for rendering to the screen, and pixmaps for accelerating offscreen images.

In some cases it could be beneficial to enable the use of pixmaps, while also using DGA for rendering to the screen. To force the use of pixmaps for accelerating offscreen images, set the following property when starting the application: -Dsun.java2d.pmoffscreen=true.

Disabling the Use of DirectDraw

When DirectDraw is disabled, all operations are performed with GDI. Provide the following flag to disable the use of DirectDraw: -Dsun.java2d.noddraw=true. In this case all offscreen images will be created in the Java heap, and rendered to with the default software pipeline. All onscreen rendering, as well as copies of offscreen images to the screen will be performed using GDI.

Forcing the Use of DirectDraw Pipeline

In case the pipeline was disabled by default for some reason, it can be enabled by providing the -Dsun.java2d.noddraw=false flag to the VM.

However, typically there was a reason why it was disabled in the first place, so it is better not to force it.

Disabling the Built-in Punting Mechanism

In general, the DirectDraw pipeline attempts to place the offscreen surfaces in the framebuffer's video memory, which provides fast copies from these surfaces to the screen or other accelerated surfaces, as well as hardware accelerated rendering of certain graphics operations.

However, if the pipeline cannot perform an operation using the DirectDraw API (operations using, for example, alpha compositing, or transforms, or antialiasing), the rendering is performed using the software pipeline. In some cases this means that the pixels of the destination surface, which resides in VRAM, need to be read into system memory, which is a very expensive operation.

To limit the impact of unaccelerated rendering to VRAM-based surfaces, there exists a punting mechanism, which moves the surface which is detected to be often read from to the system memory. If the surface is found to be copied from often enough, it may be promoted back to the video memory.

On certain video boards/drivers combinations the system-memory based DirectDraw surfaces are known to cause rendering artifacts and other issues. The DirectDraw pipeline provides a way to disable the punting mechanism so that the system memory surfaces are not used.

To defeat the built-in surface punting mechanism provide the following flag to the Java VM: -Dsun.java2d.ddforcevram=true.

Disabling the DirectDraw Blit Operations

In a blit operation (Bit Block Transfer), two bitmap patterns are combined. This operation basically corresponds to a call to the Graphics.drawImage() API.

In some cases it is possible to avoid rendering problems by disabling the DirectDraw blit operations. GDI blits will be used instead. Note that this might result in bad performance. Consider disabling the DirectDraw pipeline instead.

To disable the use of DirectDraw blit operations, pass the parameter -Dsun.java2d.ddblit=false to the Java VM.

Disabling the Direct3D Pipeline

Some older video boards/drivers combinations are known to cause issues (both rendering and performance) with the Direct3D pipeline. To disable the pipeline in such cases, with Java SE 5 and later releases, pass the parameter -Dsun.java2d.d3d=false to the Java VM, or set the J2D_D3D environment variable to false.

Forcing the Use of the Direct3D Pipeline

With Java SE 5 and later releases, to enable the Direct3D pipeline in both windowed and full-screen mode, use the parameter -Dsun.java2d.d3d=true, or set the J2D_D3D environment variable to true. Note that the pipeline is enabled only if the drivers support minimum required features.

Diagnosing Rendering Problems with Direct3D Pipeline

With the Java SE 6 release, some rendering issues (like missing pixels, garbled rendering) can be diagnosed by forcing different Direct3D rasterizers. Set the J2D_D3D_RASTERIZER environment variable to one of the following: ref, rgb, hal, or tnl.

Refer to Direct3D documentation for a description of these rasterizers. By default the best rasterizer is chosen based on its advertised capabilities. In particular, the ref rasterizer forces the use of the reference Direct3D rasterizer from Microsoft. If a rendering problem is not reproducible with this rasterizer, then it is very likely to be a video driver bug.

Enabling the OpenGL Pipeline

The OpenGL pipeline is currently disabled by default. To attempt to enable the OpenGL pipeline, provide the following option to the JVM:

-Dsun.java2d.opengl=true

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

-Dsun.java2d.opengl=True

Minimum Requirements

The OpenGL pipeline will not be enabled if the hardware or drivers do not meet the minimum requirements. If for some reason one of the following requirements is not met, Java 2D will fall back and use the default pipeline (X11 on Oracle Solaris/Linux, GDI/DirectDraw on Windows), which means your application will continue to work correctly, but without the OpenGL acceleration.

The minimum requirements for Oracle Solaris and Linux operating systems are the following:

• Hardware accelerated OpenGL/GLX libraries installed and configured properly

• OpenGL version 1.2 or higher

• GLX version 1.3 or higher

• At least one TrueColor visual with an available depth buffer

The minimum requirements for Windows OS are the following:

• Hardware accelerated drivers supporting the extensions WGL_ARB_pbuffer, WGL_ARB_render_texture, and WGL_ARB_pixel_format

• OpenGL version 1.2 or higher

• At least one pixel format with an available depth buffer

Latest OpenGL Drivers

Since the OpenGL pipeline relies heavily on the OpenGL API and the underlying graphics hardware and drivers, it is very important to ensure that you have the latest graphics drivers installed on your machine. Drivers can be downloaded from your graphics card manufacturer's web site, as shown in the following table.

Diagnosing Startup Issues

As mentioned above, the OpenGL pipeline might not be enabled on certain machines for various reasons. For example, the drivers might not be properly installed and might report an insufficient version number. Alternatively, your machine might have an older graphics card that does not support the appropriate OpenGL version or extensions.

In the Java SE 6 and later releases, you can get detailed information about the startup procedures of the OpenGL-based Java 2D pipeline by using the J2D_TRACE_LEVEL environment variable as follows.

On Windows:

# set J2D_TRACE_LEVEL=4
# java -Dsun.java2d.opengl=True YourApp

On Oracle Solaris and Linux:

# export J2D_TRACE_LEVEL=4
# java -Dsun.java2d.opengl=True YourApp

The output will be different depending on your platform and the installed graphics hardware, but it can give you some insight into the reasons why the OpenGL pipeline is not being successfully enabled for your configuration.

Diagnosing Rendering and Performance Issues

Since the OpenGL pipeline relies so heavily on the underlying graphics hardware and drivers, it might sometimes be difficult to determine whether rendering or performance issues are being caused by Java 2D or by the OpenGL drivers.

One feature new to the OpenGL pipeline in the Java SE 6 release is the use of the GL_EXT_framebuffer_object extension, which provides better performance for rendering and reduced VRAM consumption when using VolatileImages. This "FBO" codepath is enabled by default when the OpenGL pipeline is enabled, but only if your graphics hardware and driver support this OpenGL extension. This extension is generally available on Nvidia GeForce/Quadro FX series and newer, and on ATI Radeon 9500 and newer. If you suspect that the "FBO" codepath is causing problems in your application, you can disable it by setting the following system property:

-Dsun.java2d.opengl.fbobject=false

Setting this property will cause Java 2D to fall back on the older "pbuffer-based" codepath.

If you find that a certain Java 2D operation causes different visual results with the OpenGL pipeline enabled than without, it probably indicates a graphics driver bug. Similarly, if the performance of Java 2D rendering is significantly worse with the OpenGL pipeline enabled than without, it is most likely caused by a driver or hardware problem.

Using Heap-based Destination Surface (a BufferedImage)

Rendering to a BufferedImage almost always uses software loops.

Defeating Built-in Acceleration Mechanisms

Java 2D attempts to accelerate certain types of images. Contents of images may be cached in video memory for faster copying to accelerated destinations such as VolatileImages. These mechanisms can be unknowingly defeated by the application, for example, in the following cases:

Getting Direct Access to the Pixels with getDataBuffer()

If an application gets access to BufferedImage pixels by using the getRaster().getDataBuffer() API, Java 2D will not be able to guarantee that the data in the cache is up to date, so it will disable any acceleration attempts of such image.

There are two ways to avoid this problem:

• If possible, do not call getDataBuffer(). Instead, work with WriteableRaster, which can be obtained with the BufferedImage.getRaster() method.

• If you do need to modify the pixels directly, you can manually cache your image in video memory by maintaining the cached copy of your image in a VolatileImage, and updating the cached data when the original image is touched.

Rendering to a Sprite Before Every Copy

If an application renders to an image every time before copying it to an accelerated surface (VolatileImage, BufferStrategy), the image cannot take advantage of being cached in accelerated memory. This is because the cached copy has to be updated every time the original image is updated, and therefore only the default system-memory based surface is used, and this means no acceleration.

Exhausting Accelerated Memory Resources

If the application uses many images, it may exhaust the available accelerated memory. If this is indeed the cause of performance issues for your application, you might need to handle the resources.

The following API can be used to request the amount of available accelerated memory: GraphicsDevice.getAvailableAcceleratedMemory().

In addition, the following API can be used to determine if your image is being accelerated: Image.getCapabilities().

If you determined that your application is exhausting the resources, you can handle the problem in the following ways:

• Do not hold images you no longer need. For example, if your game advanced to the next level, release all images from the previous levels. You can also release accelerated resources associated with an image by using the Image.flush() API.

• Use the acceleration priority API Image.getAccelerationPriority() and setAccelerationPriority() to specify the acceleration priority for your images. It is a good idea to make sure that at least your back-buffer is accelerated, so create it first, and with acceleration priority of 1 (default). You can also prohibit certain images from being accelerated if needed by setting the acceleration priority to 0.0.

Figure 9-1 Sample Screen from Font2DTest Tool