13 Java 2D

This chapter provides information and guidance for troubleshooting some of the most common issues that might be found in the Java 2D API.

This chapter contains the following sections:

• Generic Performance Issues

• Text-Related Issues

For a summary of Java 2D properties, see Java 2D Properties.

Generic Performance Issues

There could be many causes for poor rendering performance. The following topics identify the cause for your applications poor rendering performance and suggests some approaches to improve performance of software-only rendering.

This topic contains the following subsections:

• Hardware-Accelerated Rendering Primitives

• Primitive Tracing to Detect and Avoid Non-Accelerated Rendering

• Causes of Poor Rendering Performance

• Improve Performance of Software-only Rendering

Hardware-Accelerated Rendering Primitives

In order to better understand what could be causing performance problems, take a look at what hardware acceleration means.

In general, hardware-accelerated rendering could be divided into two categories.

• Hardware-accelerated rendering to an "accelerated" destination. Examples of rendering destinations that can be hardware-accelerated are VolatileImage, screen and BufferStrategy. If a destination is accelerated, then rendering goes to a surface may be performed by video hardware. So, if you issue a drawRect call, Java 2D redirects this call to the underlying native API (such as GDI, DirectDraw, Direct3D or OpenGL, or X11), which performs the operation using hardware.

• Caching images in accelerated memory (video memory or pixmaps) so that they can be copied very fast to another accelerated surface. These images are known as managed images.

Ideally, all operations performed on an accelerated surface are hardware-accelerated. In this case, the application takes full advantage of what is offered by the platform.

Unfortunately in many cases the default pipelines are not able to use the hardware for rendering. This can happen due to the pipeline limitations, or the underlying native API. For example, most X servers do not support rendering antialiased primitives, or alpha compositing.

One cause of performance issues is when operations performed are not hardware-accelerated. Even in cases when a destination surface is accelerated, some primitives may not be.

It is important to know how to detect the cases when hardware acceleration is not being used. Knowing this may help in improving performance.

Primitive Tracing to Detect and Avoid Non-Accelerated Rendering

To detect a non-accelerated rendering, you can use Java 2D primitive tracing.

Run your application with -Dsun.java2d.trace=count. When the application exits, a list of primitives and their counts is printed to the console.

Any time you see a MaskBlit or any of the General* primitives, it typically means that some of your rendering is going through software loops. Here is the output from performing drawImage on a translucent BufferedImage to a VolatileImage on Linux:

sun.java2d.loops.Blit$GeneralMaskBlit::Blit(IntArgb, SrcOverNoEa, "Integer BGR Pixmap")sun.java2d.loops.MaskBlit::MaskBlit(IntArgb, SrcOver, IntBgr)

Here are some of the common non-accelerated primitives in the default pipelines, and their signatures in the tracing output.

Note:

Most of this tracing was taken on Linux; you may see some differences depending on your platform and configuration.

• Translucent images (images with ColorModel.getTranslucency() returnTranslucency.TRANSLUCENT), or images with AlphaCompositing. Sample primitive tracing output:

  sun.java2d.loops.Blit$GeneralMaskBlit::Blit(IntArgb,SrcOverNoEa, "Integer BGR Pixmap")sun.java2d.loops.MaskBlit::MaskBlit(IntArgb, SrcOver, IntBgr)
  

• Use of antialiasing (by setting the antialiasing hint). Sample primitive tracing output:

  sun.java2d.loops.MaskFill::MaskFill(AnyColor, Src, IntBgr)
  

• Rendering antialiased text (setting the text antialising hint). Sample output can be one of the following:

  • sun.java2d.loops.DrawGlyphListAA::DrawGlyphListAA(OpaqueColor, SrcNoEa, AnyInt)
    

  • sun.java2d.loops.DrawGlyphListLCD::DrawGlyphListLCD(AnyColor, SrcNoEa, IntBgr)
    

• Alpha compositing, either by rendering with translucent color (a color with an alpha value that is not 0xff) or by setting a non-default AlphaCompositing mode with Graphics2D.setComposite():

  sun.java2d.loops.Blit$GeneralMaskBlit::Blit(IntArgb, SrcOver, IntRgb)sun.java2d.loops.MaskBlit::MaskBlit(IntArgb, SrcOver, IntRgb)
  ]

• Non-trivial transforms (if the transform is more than only translation). Rendering a transformed opaque image to a VolatileImage:

  sun.java2d.loops.TransformHelper::TransformHelper(IntBgr, SrcNoEa, IntArgbPre)
  

• Rendering a rotated line:

  sun.java2d.loops.DrawPath::DrawPath(AnyColor, SrcNoEa, AnyInt)
  

  Run your application with tracing and ensure that you do not use unaccelerated primitives unless they are needed.

Causes of Poor Rendering Performance

Some of the possible causes of poor rendering performance and possible alternatives are described as follows:

• Mixing accelerated and non-accelerated rendering:

  A situation when only part of the primitives rendered by an application could be accelerated by the particular pipeline when rendering to an accelerated surface can cause thrashing, because the pipelines will be constantly trying to adjust for better rendering performance but with possibly little success.

  If it is known beforehand that most of the rendering primitives will not be accelerated, then it could be better to either render to a BufferedImage and then copy it to the back buffer or the screen, or switch to a non-hardware accelerated pipeline using one of the flags discussed.

  Note:

  This approach may limit your application's ability to take advantage of future improvements in Java 2D's use of hardware acceleration.

  For example, if your application is often used in remote X server cases, but it heavily uses antialiasing, alpha compositing, and so forth, then the performance can be severely degraded. To avoid this, disable the use of pixmaps by setting the -Dsun.java2d.pmoffscreen=false property either by passing it to the Java runtime, or by setting it programmatically using the System.setProperty() API. The default Xrender pipeline supports anti-aliased text and standard compositing modes even over remote X11, so depending on your application, pixmaps may still perform better. You must test this to verify.

  Note:

  This property must be set before any GUI-related operations because it is read only once.
• Non-optimal rendering primitives:

  It is preferable to use the simplest primitive possible to achieve the desired visual effect.

  For example, use Graphics.drawLine() instead of new Line2D().draw(). The result looks the same. However, the second operation is much more computationally intensive because it is rendered as a generic shape, which is typically much more expensive to render. Shapes show up in different ways in the primitive tracing, depending on antialiasing settings and the specific pipeline, but most likely they will show up as many *FillSpans or DrawPath primitives.

  Another example of complicated attributes is GradientPaint. Although it may be hardware accelerated by some of the non-default pipelines (such as OpenGL), it is not hardware accelerated by the default pipelines. Therefore, you can restrict the use of GradientPaint if it causes performance problems.

• Heap-based destination surface BufferedImage:

  Rendering to a BufferedImage almost always uses software loops.

  To ensure that the rendering has the opportunity of being hardware accelerated, choose a BufferStrategy or a VolatileImage object as the rendering destination.

• Defeat built-in acceleration mechanism:

  Java 2D attempts to accelerate certain types of images. The contents of images can be cached in video memory for faster copying to accelerated destinations such as VolatileImages. These mechanisms can be unknowingly defeated by the application.

• Get direct access to pixels with getDataBuffer():

  If an application gets access to BufferedImage pixels by using the getRaster().getDataBuffer() API, then 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 this type of image.

  To avoid this, do not call getDataBuffer(). Instead, work with WriteableRaster, which can be obtained with the BufferedImage.getRaster() method.

  If you need to modify the pixels directly, then 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.

• Render to a sprite before every copy:

  If an application renders to an image before copying it to an accelerated surface (VolatileImage, BufferStrategy), then the image cannot take advantage of being cached in accelerated memory. This is because the cached copy must 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.

• Exhausted accelerated memory resources:

  If the application uses many images, then it can exhaust the available accelerated memory. If this is the cause of performance issues for your application, then 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 by not holding 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.

  You can also 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.

Improve Performance of Software-only Rendering

If your application relies on software-only rendering (by only rendering to a BufferedImage, or changing the default pipeline to an unaccelerated one), or even if it does mixed rendering, then the following are certain approaches to improving performance:

1. Image types or operations with optimized support:

   Due to overall platform size constraints, Java 2D has a limited number of optimized routines for converting from one image format to another. In situations where an optimized direct loop can not be found, Java 2D will do the conversion through an intermediate image format (IntArgb). This results in performance degradation.

   Java 2D primitive tracing can be used for detecting such situations.

   For each drawImage call there will be two primitives: the first one converting the image from the source format to an intermediate IntArgb format and the second one converting from intermediate IntArgb to the destination format.

   Here are two ways to avoid such situations:

   • Use a different image format if possible.

   • Convert your image to an intermediate image of one of the better-supported formats, such as INT_RGB or INT_ARGB. In this way the conversion from the custom image format will happen only once instead of on every copy.

2. Transparency vs translucency:

   Consider using 1-bit transparent (BITMASK) images for your sprites as opposed to images with full translucency (such as INT_ARGB) if possible.

   Processing images with full alpha is more CPU-intensive.

   You can get a 1-bit transparent image using a call to GraphicsConfiguration.createCompatibleImage(w,h, Transparency.BITMASK).

Text-Related Issues

This section describes possible issues and crashes that are related to text rendering and describes tips to overcome such issues.

This section contains the following subsections:

• Tracing Font Loading

• Differences in Text Appearance

• Font Metrics

Tracing Font Loading

Setting the -Dsun.java2d.debugfonts=true property generates information about the fonts loaded by Java 2D. You can see what fonts Java 2D finds, infer which ones it uses, and see information about fonts that it rejects. This property generates output similar to the following:

INFO: Registered file C:\WINDOWS\Fonts\WINGDING.TTF as font ** TrueType Font: Family=Wingdings
 Name=Wingdings style=0 fileName=C:\WINDOWS\Fonts\WINGDING.TTF rank=2
Aug 16, 2006 10:59:06 PM sun.font.FontManager initialiseDeferredFont
INFO: Opening deferred font file SYMBOL.TTF
Aug 16, 2006 10:59:06 PM sun.font.FontManager addToFontList
INFO: Add to Family Symbol, Font Symbol rank=2
Aug 16, 2006 10:59:06 PM sun.font.FontManager registerFontFile
INFO: Registered file C:\WINDOWS\Fonts\SYMBOL.TTF as font ** TrueType Font: Family=Symbol
 Name=Symbol style=0 fileName=C:\WINDOWS\Fonts\SYMBOL.TTF rank=2
Aug 16, 2006 10:59:06 PM sun.font.FontManager findFont2D
INFO: Search for font: Dialog
Aug 16, 2006 10:59:06 PM sun.font.FontManager initialiseDeferredFont
INFO: Opening deferred font file ARIALBD.TTF
Aug 16, 2006 10:59:06 PM sun.font.FontManager addToFontList
INFO: Add to Family Arial, Font Arial Bold rank=2
Aug 16, 2006 10:59:06 PM sun.font.FontManager registerFontFile
INFO: Registered file C:\WINDOWS\Fonts\ARIALBD.TTF as font ** TrueType Font: Family=Arial
 Name=Arial Bold style=1 fileName=C:\WINDOWS\Fonts\ARIALBD.TTF rank=2
Aug 16, 2006 10:59:06 PM sun.font.FontManager initialiseDeferredFont
INFO: Opening deferred font file WINGDING.TTF
Aug 16, 2006 10:59:06 PM sun.font.FontManager initialiseDeferredFont
INFO: Opening deferred font file SYMBOL.TTF
Aug 16, 2006 10:59:06 PM sun.font.FontManager findFont2D
INFO: Search for font: Dialog
Aug 16, 2006 10:59:06 PM sun.font.FontManager initialiseDeferredFont
INFO: Opening deferred font file ARIAL.TTF
Aug 16, 2006 10:59:06 PM sun.font.FontManager addToFontList
INFO: Add to Family Arial, Font Arial rank=2
Aug 16, 2006 10:59:06 PM sun.font.FontManager registerFontFile
INFO: Registered file C:\WINDOWS\Fonts\ARIAL.TTF as font ** TrueType Font: Family=Arial
 Name=Arial style=0 fileName=C:\WINDOWS\Fonts\ARIAL.TTF rank=2
Aug 16, 2006 10:59:06 PM sun.font.FontManager initialiseDeferredFont
INFO: Opening deferred font file WINGDING.TTF
Aug 16, 2006 10:59:06 PM sun.font.FontManager initialiseDeferredFont
INFO: Opening deferred font file SYMBOL.TTF

Differences in Text Appearance

Differences in text appearance in Java applications compared to native applications can be due to different font rasterizers being used. Java applications typically use the operating system's font rasterizer, the same one that native applications use. However, Java applications may use FreeType, a software library to render fonts, which has been installed or included in an operating system. For example, FreeType may be used on Windows for grayscale text or on macOS for Type 1 fonts that aren't supported by the macOS font rasterizer. However, note that Windows has multiple font rasterizers. Consequently, text rendering can vary between native applications. In addition, all platforms have some degree of configurability in platform rasterization which can lead to small differences in text appearance.

Other sources of difference include:

• Whether subpixel positioning is in use as this affects the precise positioning of glyphs; see java.awt.RenderingHints.KEY_FRACTIONALMETRICS.
• On Linux, Swing might choose different anti-aliasing settings.

There are several likely reasons for this behavior:

• Antialiasing over a remote X11 connection is not enabled by default for performance reasons.

• CJK fonts that use embedded bitmaps may render using the bitmaps instead of subpixel text.

• Some variants of unsupported desktops do not report their font smoothing settings properly. For example, KDE is unsupported but should generally work; however, some problem seems to prevent JDK from picking up the setting.

The size of the font in the Java language is always expressed with 72 dpi. A native OS can use a different screen dpi, and therefore an adjustment must be made. Matching Java font size can be calculated as Toolkit.getScreenResolution() divided by 72 multiplied by the size of the native font.

In all native Swing look-and-feel, such as the Windows look-and-feel or the GTK look-and-feel for the Linux operating system, Swing components perform this adjustment automatically.

On operating systems other than Windows, the general recommendation is to use TrueType fonts instead of Type1 fonts. The easiest way to figure out the type of font is to look at the file extension: extensions pfa and pfb indicate Type1 fonts, and ttf, ttc, and tte represent TrueType fonts.

Font Metrics

If you find that text bounds are different from what you expect, then ensure that you are using the appropriate way to calculate them. For example, the height obtained from a FontMetrics is not specific to a particular piece of text, and the stringWidth indicates logical advance, which is not the same thing as wide. For more details, see the Font and Text questions in the Java 2D FAQ.