Documentation Contents
Java Platform, Standard Edition Troubleshooting Guide
Contents Previous Next

# 11.1 Oracle Solaris and Linux: X11 Pipeline

On Unix platforms the default pipeline is the X11 pipeline. This pipeline uses the X protocol for rendering to the screen or to certain types of offscreen images, such as `VolatileImages`, or "compatible" images (images that are created with the `GraphicsConfiguration.createCompatibleImage()` method). Such types of images can be put into X11 pixmaps for improved performance, especially in the case of the Remote X server.

In addition, in certain cases Java 2D uses X server extensions, for example, the MIT X shared memory extension, or Direct Graphics Access extension, Double-buffer extension for double-buffering when using the `BufferStrategy` API.

An additional pipeline, the OpenGL pipeline, might offer greater performance in some configurations.

The following are X11 pipeline properties to troubleshoot.

- X11 Pipeline Pixmaps Properties

- X11 Pipeline MIT Shared Memory Extension

- Oracle Solaris on SPARC: DGA Support

- Oracle Solaris on SPARC - Change Java 2D Default Visual

## 11.1.1 X11 Pipeline Pixmaps Properties

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.

The following are two cases to disable the use of X11 pipeline.

1. Disable X11 pipeline pixmaps:

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

2. Disable X11 pipeline shared memory pixmaps:

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

## 11.1.2 X11 Pipeline MIT Shared Memory Extension

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.

The following are two ways to improve the performance of Java application.

- Increase X Server and Java 2D shared memory:

  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 shown in Example 11-1. Note: This is not needed on Oracle Solaris 9 and newer.

  Example 11-1 System File Settings

      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.

- Disable X11 pipeline shared memory extension:

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

## 11.1.3 Oracle Solaris on SPARC: DGA Support

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.

The following are use cases that describe how to detect DGA extension support and disable/enable DGA.

- DGA extension for rending:

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

  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.

- Enable or Disable DGA:

  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.

  Sometimes, 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`.

## 11.1.4 Oracle Solaris on SPARC - Change Java 2D Default Visual

On certain video boards on the SPARC platform, more than one visual can be available from the X server. By default Java 2D tries to select the best visual, where "best" is typically a higher-bit depth visual. For example, on some Oracle Solaris operating system releases the default X11 visual is 8-bit PseudoColor, although 24-bit visual is also available. In such cases Java 2D will select a 24-bit TrueColor visual as the default for Java windows.

While it is possible to create a Java top-level window with a `GraphicsConfiguration` object corresponding to a different visual, in some cases it is necessary to make Java use a different default visual instead. This can be done by setting the `FORCEDEFVIS` environment variable. It can be set to `true` to force the use of the default X server visual (even if it is not the best one), or it can be set to a hexadecimal number corresponding to the visual ID as reported by tools like `xdpyinfo`.

To determine your X server default visual, execute the `xdpyinfo` command and look at the `default visual id` field.

Contents Previous Next

Copyright © 1993, 2026, Oracle and/or its affiliates. All rights reserved.
Contact Us