FAQs

General questions

Q: What is Java 2D?

Java 2D handles arbitrary shapes, text, and images and provides a uniform mechanism for performing transformations, such as rotation and scaling, on these objects. With Java 2D, application developers can render to display devices, discover and render to printer devices, read and write in many image formats. There is comprehensive text and font handling and color space support and various rendering techniques and effects are offered.

Q: Who needs Java 2D?

Q: Where can I go for more information about Java 2D?

Q: Are there any news groups or mailing lists dedicated to Java 2D?

This mailing list is also linked to the Java 2D forum at java.net: http://forums.java.net/jive/forum.jspa?forumID=69

A few Sun engineers also participate in the Java 2D forums at javagaming.org, which is a great resource for game developers and other performance hungry individuals: http://www.javagaming.org/forums/index.php?board=15.0

Programming, Debugging and Performance questions

Q: What's the difference between Graphics and Graphics2D?

Q: Is there a list of the various runtime flags that Java2D uses?

Q: What kinds of graphics hardware acceleration does Java2D use?

• What release you are running (we are constantly improving our hardware acceleration renderers, so each release has more to offer)
• What OS you are running (our story on Windows is different from our story on Linux which is again different from our story on Solaris ... and the Apple folks have their own story for their platform)
• What kind of hardware you have (your graphics card capabilities can be the single most important factor in enabling Java2D hardware acceleration).

• OpenGL: Here is an article about our OpenGL support in J2SE 5.0: http://today.java.net/pub/a/today/2004/11/12/graphics2d.html
• VolatileImage: here are two blogs about VolatileImage objects: http://weblogs.java.net/blog/chet/archive/2003/09/volatileimage_n.html and http://weblogs.java.net/blog/chet/archive/2003/09/volatileimage_q.html.
• Windows/Direct3D: Here is a blog about some of the hardware acceleration improvements in Windows in the Java SE 6 release: http://weblogs.java.net/blog/chet/archive/2005/05/graphics_accele.html.

Q: How can I get better performance for my Java2D application?

• All of the articles listed for the "hardware acceleration" Q&A above
• An article on using Intermediate Images to accelerate repeated renderings of complex operations: http://java.sun.com/developer/technicalArticles/Media/intimages.
• Online chat transcripts and interviews on performance: http://java.sun.com/developer/community/chat/JavaLive/2005/jl0215.html and http://www.javahispano.org/text.viewer.action?file=chet_en.
• The gamers on http://javagaming.org are highly sensitive to performance and that web site has several good discussions about performance issues.

Q: Are there any tracing facilities in Java2D to help me track down performance issues in my application?

    -Dsun.java2d.trace=[log[,timestamp]],[count],[out:<filename>],[help],[verbose]

For more information on this tracing facility, refer to the following documentation:
http://java.sun.com/j2se/1.5.0/docs/guide/2d/flags.html#trace

Image questions

Q: What image-file formats does Java 2D support?

Q: Which ColorModel should I use if I need optimum performance?

Q: What image types should I use to get the best performance?

Q: How do I create a resized copy of an image?

BufferedImage createResizedCopy(Image originalImage, 
                                int scaledWidth, int scaledHeight, 
                                boolean preserveAlpha)
{
    int imageType = preserveAlpha ? BufferedImage.TYPE_INT_RGB : BufferedImage.TYPE_INT_ARGB;
    BufferedImage scaledBI = new BufferedImage(scaledWidth, scaledHeight, imageType);
    Graphics2D g = scaledBI.createGraphics();
    if (preserveAlpha) {
       g.setComposite(AlphaComposite.Src);
    }
    g.drawImage(originalImage, 0, 0, scaledWidth, scaledHeight, null); 
    g.dispose();
    return scaledBI;
}

g.setRenderingHint(RenderingHints.KEY_INTERPOLATION,
                   RenderingHints.VALUE_INTERPOLATION_[NEAREST_NEIGHBOR
                                                       BILINEAR
                                                       BICUBIC]); 

Q: There are several types of images in Java2D; how do I know which one is appropriate in a particular situation?

Q: Can I use Java2D to generate dynamic images from my servlet (or other server-side Java application)?

Here is a simple example of a servlet that generates a smiley face using Java2D, and then writes a JPEG image that can be viewed in a browser:

import java.awt.*;
import java.awt.image.*;
import javax.imageio.*;
import javax.servlet.*;
import javax.servlet.http.*;

public class ImageServlet extends HttpServlet {

    public void doGet(HttpServletRequest request,
                      HttpServletResponse response)
        throws ServletException, IOException
    {
        response.setContentType("image/jpeg");

        // Create image
        int width=200, height=200;
        BufferedImage image =
            new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB);

        // Get drawing context
        Graphics2D g2d = image.createGraphics();

        // Fill background with white
        g2d.setColor(Color.WHITE);
        g2d.fillRect(0, 0, width, height);

        // Draw a smiley face
        g2d.setColor(Color.YELLOW);
        g2d.fillOval(10, 10, 180, 180);
        g2d.setColor(Color.BLACK);
        g2d.fillOval(40, 40, 40, 40);
        g2d.fillOval(120, 40, 40, 40);
        g2d.fillRect(50, 150, 100, 10);

        // Dispose context
        g2d.dispose();

        // Write image to the output stream
        ServletOutputStream os = response.getOutputStream();        

        ImageIO.write(bi, "jpeg", os);
    }
}

Q: I have an application that reads, writes, and processes images (but does not display them) using Java2D. When I run my application on Solaris or Linux, it complains that X11 is not available. What can I do to make my application work in this environment?

Although many image operations using the Image I/O APIs or the JAI optional package might not have any obvious need for display, they often invoke code that needs an AWT resource. For example, calling getGraphics() on a BufferedImage initializes AWT and causes these error messages seen by developers. There is no way to say that a particular API does or does not have this problem; it depends on what particular operations are being invoked, and might also depend on what the application does with the images that is not strictly related to any of the APIs cited above.

There are two possible solutions. As of J2SE 1.4 (and above), the preferred solution is to use the "headless AWT toolkit". This feature allows you to use the Java2D API in a server-side application without the need for a display environment. To specify the headless environment, run your application with the following system property:

    -Djava.awt.headless=true

For releases prior to J2SE 1.4 you can provide a "pseudo X-server" to emulate a display environment. One of these Xserver emulators is Xvfb, available for download at http://www.x.org. Another possibility is to start a VNC server (http://www.realvnc.com) and then run your application in that environment.

Xvfb does still have one possible use in J2SE 1.4: A server application may need to display to an Xserver, but requires no user interaction. The headless toolkit won't support this situation, but xvfb will. This is a completely hypothetical scenario and it is not clear if any real world application exhibits such a behavior.

Font and Text questions

Q: What are the capabilities of the Java 2D text rendering system?

A: These include:

• Antialiased and sub-pixel (aka LCD) text display
• Transformed text
• Text as shapes that can be filled with colours, gradient paints etc.
• Rendering complex text scripts (eg Indic), Bidi text etc
• APIs to locate and use platform fonts
• APIs to directly load and register fonts from files and network resources.

These capabilities are all uniformly supported across platforms both for on-screen display and for printing.

Q: What are the different ways that text can be rendered using Java 2D?

A:

• java.awt.Graphics2D.drawString() draws a String of text using the current font and other rendering attributes. This is the most

• java.awt.font.TextLayout object allows you to implement text editing yourself: it includes mixed styles, BIDI text layout, carets, highlighting, hit testing and many other features.

• java.awt.font.GlyphVector can be used to accomplish

• Using Swing text components : since Swing is based upon Java 2D JTextField, JTextArea, and JEditorPane, which supports editing and multiple fonts and styles, all utilise the above Java 2D APIs. Many developers will therefore not directly use the 2D text APIs but will use the UI-oriented Swing interfaces.

Q. What font types does Java 2D support?

A. The primary and preferred font format is the TrueType font format. Java 2D also supports Opentype layout tables within TrueType fonts for complex text rendering (Arabic, Indic etc). In addition Java 2D supports Postscript Type1 fonts.

Q: Are any fonts bundled with Java 2D?

Q: How can I list all available fonts?

A: You may get a list of all available font family names using java.awt.GraphicsEnvironment.getAvailableFontFamilyNames() or may list all the font instances using java.awt.GraphicsEnvironment.getAllFonts() In each case the returned list will include the logical fonts such as "Dialog". java.awt.GraphicsEnvironment. getAvailableFontFamilyNames() is typically the most useful for presenting a menu of fonts to a user as a particular style (eg Bold) can requested for a font by specifying it in the style field of the Font constructor.

For sample code, see the implementation of the Font2DTest demo shipped with the JDK (demo/jfc/Font2DTest/src)

Q: How can I make my custom font available to my Java application?

If you don't want other applications to use your font then there are two other options

• If you ship a private JRE with your application you can copy your fonts to $JAVAHOME/jre/lib/fonts since they will be available only to java applications executed by that JRE and will be visible via Java's font enumeration APIs.

• You may also load custom fonts dynamically - by using java.awt.Font.createFont() to instantiate your fonts from files or network streams.

Fonts instantiated via createFont() offer even more flexibility in limiting the visibility of the font. Font instances using such custom fonts cannot normally be constructed. Instead you must use Font.deriveFont() on the instance returned from the Font.createFont() method. Therefore only code to which you provide a references to the Font can use it. Note that each call to createFont from the same source (file) will create a new distinct Font which will be GC'd only when it is no longer referenced. So if you expect to need to use the created Font in many places simultaneously cache a single copy to derive from rather than re-creating from the source file.

As of Java SE 6, there is a method : GraphicsEnvironment.registerFont() which gives you the ability to make a "created" font available to Font constructors and to be listed via Font enumeration APIs. Font.createFont() and this method combine to provide a way to "install" a Font into the running JRE so it is available just as O/S installed fonts are. However this Font does not persist across JRE invocations.

Q: Why does (eg) a 10 pt font in Java applications appear to have a different size from the same font at 10pt in a native application?

A: Conversion from the size in points into device pixels depends on device resolution as reported by the platform APIs. Java 2D defaults to assuming 72 dpi. Platform defaults vary. Mac OS also uses 72 dpi. Linux desktops based on GTK (Gnome) or Qt (KDE) typically default to 96 dpi and let the end-user customise what they want to use. Windows defaults to 96 dpi (VGA resolution) and also offers 120 dpi (large fonts size) and lets users further specify a custom resolution. So a couple of things can now be seen

• The DPI reported by platform APIs likely has no correspondence to the true DPI

• Its unlikely that Java 2D's default matches the platform default.

So a typical results is that for Window's default 96 DPI that a 10 pt font in a Java application is 72/96 of the size of the native counterpart.

Note that Swing's Windows and GTK L&Fs do scale fonts based on the system DPI to match the desktop. If you want to do the same in your application you can call java.awt.Toolkit.getScreenResolution() and use this to apply a simple scale to the size you specify for fonts.

Q: How to I find if I use a font to display Cyrillic, or Hindi etc?

A: Use Font.canDisplay() to find out if there is a glyph matching a given Unicode character in a given font.

Q. How can I specify the text antialiasing/font smoothing settings to be used by Swing in applications on Java SE 6?

A. This is generally is a question from users of KDE (on Linux or other Unix) or Windows 2000 who would like to use LCD subpixel text. There's no programmatic way to do it in Java SE 6 (but see http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6274842 to see if that has changed since this was written). However if you know what you want you can set a system property :

java -Dawt.useSystemAAFontSettings=lcd

• "false" corresponds to disabling font smoothing on the desktop.
• "on" corresponds to Gnome Best shapes/Best contrast (no equivalent Windows desktop setting)
• "gasp" corresponds to Windows "Standard" font smoothing [see note (*) below] (no equivalent Gnome desktop setting)
• "lcd" corresponds to Gnome's "subpixel smoothing" and Windows "ClearType"

The full details are documented in the 2D Flags Guide at http://java.sun.com/javase/6/docs/guide/2d/flags.html#aaFonts

(*) Something that surprises people is that Windows "Standard" font smoothing does not mean always smooth/AA. In fact at typical GUI sizes most text is black and white. It uses information in a TrueType font (the gasp table) which specifies whether to use hinted B&W or greyscale smoothing. So if you expected the JDK to do AA at all sizes with this setting, don't be surprised when it doesn't. If you look closely you'll see windows native apps are behaving similarly. See http://www.microsoft.com/typography/SmoothFonts.mspx.

Q: How do I obtain font metrics?

A: You may obtain a Fontmetrics instance by calling java.awt.Graphics.getFontMetrics(Font) This will decribe the font-wide metrics using the current FontRenderContext of the Graphics instance.

Font wide metrics are not specific to a particular piece of text. It is based on data in the font specified by the font designer to reflect the overall design of the font. Do not expect that, for example, the reported "ascent" of the font will be as high as the highest ascent of any glyph in the font.

If you are looking for accurate bounds for string of text - please look at the next question.

FontMetrics are widely used in helping to layout GUIs. They are also cheap to obtain.

Q. What is the difference between logical, visual and pixel bounds?

* Font.getStringBounds(...)
* TextLayout.getAscent()
* TextLayout.getDescent()
* TextLayout.getLeading()
* TextLayout.getAdvance()
* GlyphVector.getLogicalBounds(...)

  * GlyphVector.getVisualBounds(...)
  * TextLayout.getBounds()

  * GlyphVector.getPixelBounds(...)
  * TextLayout.getPixelBounds(...) (new in Java SE 6)

Q. What are fractional metrics? What are the consequences of setting the fractional metrics rendering hint on text performance, readability etc? When should I use it?

A. In short fractional metrics doesn't affect performance. Principally it affects the spacing between glyphs (characters) which on low resolution (screen) devices can degrade the overall legibility of the text. Understanding this requires some explanation of the topic.

"Fractional metrics" is sometimes called "Printer matching" on other platforms. It refers to the fact that characters in a font are optimized for particular font size and output device resolution to improve legibility of text. These optimizations involve rounding to the pixel grid and therefore may affect overall widths of individual glyphs as well as distances between them.

The text display system can either choose to round these "advance widths" to an integer so that the text will have consistent spacing, or it can accumulate the positions of the characters using the unrounded, or fractional, values.

If it uses the fractional values then the sequence "wi" may not have consistent spacing between the "w" and the "i" at different points along the line. That variation in spacing creates visual noise which is disruptive to the reading process and so is not preferred as the default on the screen. Note that it is only the inter-glyph spacing which changes, not the glyph images,

If it uses the rounded values then the inter-character spacings are much more uniform, but each character's rounded spacing introduces some error and over a long string that error accumulates with each character displayed in succession. The result may be either a longer or a shorter overall string compared with factional metrics. That error is also dependent on the resolution at which the text is being displayed such that the relative lengths of strings will vary as you change the zoom factor or the resolution of the output device. As a result, such rounded widths are considered "not matched to the final printed output" or "not Printermatched". They also complicate layout if you want to view the same text at different sizes or magnifications - you have to customize the layout for each zoom level or expect the strings to start overrunning or underrunning their static positioning.

Since non-fractional (integer) metrics are required for best screen readibility, that is why integer metrics is the default for Java 2D.

The principal reason for turning on fractional metrics is then to closely approximate the layout at high-device resolution when formatting output to a printer, or for displaying a "print preview".

The simplest way to look at it is that "Fractional metrics" improve WYSIWYG on the printer at the expense of legibility on low DPI screens.

Printing questions

Q:What are the differences between the various printing APIs I see in the JDK?

A. These are the printing APIs in the JDK:

1.1 (aka AWT) printing - java.awt.PrintJob

• A UI component-oriented printing API
• Can print only the 1.1 "Graphics" API, not "Graphics2D" extensions

2D printing - java.awt.print.PrinterJob

• A more flexible API for printing documents
• Can print all of Java 2D.
• Callback printing model
• Integrates with javax.print

Java Printing Service - javax.print packages

• Adds discovery of printers and capabilities
• Adds ability to specify job behaviour through attributes
• Adds ability to install custom print services

In summary 1.1/AWT printing can be used for many basic cases but has largely been superseded by 2D printing (as of J2SE 1.2), and when the javax.print package was added in J2SE 1.4 it was made largely complementary to 2D printing and integrated with it for ease of us. So most applications which are focused on rendering to a printer will find it more natural to centre around PrinterJob.

So the presently recommended way to print for most applications is to use java.awt.print.PrinterJob which has methods which leverage javax.print to enumerate printers, and can accept printing attributes from javax.print which define job printing behaviour such as duplex printing.

Q Why is it so hard to print from Swing?

A. In most cases what this turns out to mean is:

• "how can I print all a JTable?"
• "how can I just ask Swing to print the contents of a text component (rather than

These have now been addressed: J2SE 5.0 added direct printing support on JTable, see: http://java.sun.com/j2se/1.5.0/docs/api/javax/swing/JTable.html#print()

In addition, Java SE adds the same capability with javax.swing.JTextComponent.print().

Q: What are the causes of large spool files from java.awt.print.PrinterJob and how can I avoid them?

A: This was much more of a problem in earlier releases but as of J2SE 5.0 most applications should not see a problem. Some of it is platform specific and in general things are better on Windows than Solaris and Linux.

Printing using non opaque colours, gradient paints, and custom paints can cause individual pages (not the whole print job) to be generated as a raster at device resolution. This can be mitigated in a few ways:

• the application printing code could avoid using these.
• the application could render a selected area which uses these to an offscreen opaque BufferedImage and then draw that BufferedImage to the printer graphics.
• the application could lower the device resolution of the print job which may be higher than needed, using the PrinterResolution attribute.

Printing Text on Solaris with non-Postscript standard fonts. In many cases the font requested by an application cannot be expected to be available to a Postscript printer, and the JDK has no way to determine the capabilities of the destination Postscript printer anyway. So often the JDK will generate text as stroked and filled outlines. This is particularly a problem in locales where there is no standard Postscript font support.

For English locales however, Latin text in the standard logical fonts such as Dialog, SansSerif, Serif are mapped directly to Postscript printer fonts and should generate compact Postscript. The same happens in the Japanese locale. Also fonts which are "compatible" such as the TrueType font "Times New Roman" which can be mapped to the Postscript "Times Roman" font will be OK. But keeping to the "logical" fonts is usually the simplest way of getting the most compact output.

Q: When printing using java.awt.PrinterJob, why does it print each page at least twice (and sometimes much more than that)?

A: The root of this is that Java 2D printing needs to be able to print everything that Java 2D can render to the screen, and that includes translucent colours, images etc which cannot always be printed directly in Postscript or GDI except when printing everything as one big image, so the implementation tries to avoid this by calling first to discover the rendering that needs to be done for the page. If its simple opaque rendering then only one more call is needed to render the page. If there are translucent colours then multiple calls are done for "bands" down the page to limit the size of the image being generated and hence constrain peak memory usage.

Q How do I keep the information from getting cut off from the top and left sides of the page when I print using the Java 2D printing API?

Because many printers cannot print on the entire paper surface, the PageFormat specifies the imageable area of the page: this is the portion of the page in which it's safe to render. The specification of the imageable area does not alter the coordinate system; it is provided so that the contents of the page can be rendered so that they don't extend into the area where the printer can't print. If you find that information is clipped from your page, you might need to translate the information to the imageable area of the page, as shown in this sample:

    public int print(Graphics g, PageFormat pf, int pageIndex) 
        throws PrinterException
    {
        Graphics2D g2 = (Graphics2D)g;
        g2.translate(pf.getImageableX(), 
        pf.getImageableY() + 72);
        ...
    }

Q: Why are my 1-pixel wide lines repositioned when I print them? How do I correct this?

A: For horizontal or vertical 1-pixel wide line fills, it is generally better to use fillRect rather than drawLine. The rounding of the drawLine method moves lines by half a device pixel, which make the lines appear more consistent whether or not antialiasing is applied. Therefore, if you have a 1-pixel wide line, the line is moved by half of its width. Because this adjustment occurs at the device-space level, your lines can move by half of a line width on printouts from high-resolution printers.

Q: How do I trouble shoot printing problems in Windows?

First, make sure that you have the latest printer driver. It is advisable to use the printer vendor's version of the driver and you can generally do this by downloading it online at their website. If you have the latest driver and are still having problems, sometimes a simple change in the printer's setting or Window's advanced spool options will fix your problem. You can also go to http://java.sun.com and search the bug archive for similar problem. A workaround may be available there. If not, please file a bug.

Q: How do I scale an image to fit a page?

Here is a sample code that uses the page's imageable width and height to scale an image.

public int print(Graphics graphics, PageFormat pageFormat, int
 pageIndex) throws PrinterException
 {
 if(pageIndex > 0)
    return Printable.NO_SUCH_PAGE;
 Graphics2D g2d = (Graphics2D) graphics;

 //Set us to the upper left corner
 g2d.translate(pageFormat.getImageableX(), pageFormat.getImageableY());
 AffineTransform at = new AffineTransform();
 at.translate(0,0);

 //We need to scale the image properly so that it fits on one page.
 double xScale = pageFormat.getImageableWidth() / m_image.getWidth();
 double yScale = pageFormat.getImageableHeight() / m_image.getHeight();
 // Maintain the aspect ratio by taking the min of those 2 factors and
 using it to scale both dimensions.
 double aspectScale = Math.min(xScale, yScale);

 g2d.drawRenderedImage(m_image, at);
 return Printable.PAGE_EXISTS;
 }

Q: When I print using PDF or HTML using the corresponding DocFlavor, how come it is printed as garbage or plain text?

First, do not assume that any of the defined DocFlavors are supported. Use the PrintService's isDocFlavorSupported to find out which flavors are supported. If you find out that it is not supported but know that your printer can handle this then you may go ahead and print it using the DocFlavor.xxx.AUTOSENSE. This is equivalent to printing a raw data. If on the other hand your printer does not support it you need to write your own PrintService which handles the conversion from PDF/HTML to the printer language e.g. PostScript.

Q: Why is Java unable to print to my CUPS 1.2 printers ?

Networking
/Domain Sockets;/
CUPS now supports the much faster UNIX  domain sockets for local printing

• localhost:631 via a TCP/IP socket connection - this is the same as in

• a unix domain socket at /var/run/cups/cups.sock

So far so good, except that the unix domain socket is now the default and the CUPS API call cupsServer() now returns the unix domain socket pat /var/run/cups/cups.sock instead of "localhost".

This can be an incompatible change for any pre-1.2 aware client which retrieves that name and expects to be able to use to open a TCP/IP connection.

In particular this breaks Sun's JDK (aka Java/aka Java SE, aka JRE) versions 1.5 and Java SE 6. ie all releases to date (Dec 2006) which connects to the CUPS IPP server to provide access to platform printing support. The symptom may be no printers found, or printers 'not accepting jobs'. This will be patched in the next available minor update releases of each of JDK 1.5 and JDK6. The Sun bug to track this can be viewed at http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6500903 and the updated releases in which this is fixed will then be viewable there. The expectation is that this will be fixed in JDK6 update 1 (1.6.0_01) and JDK 1.5 update 12 (1.5.0_12).

Until then there are several workaround options for configuring CUPS 1.2 to work with JDK

1. System-wide :

• Edit the cups configuration file, usually /etc/cups/cupsd.conf, and locate

# Listen /var/run/cups/cups.sock

• Ensure the line to listen on TCP/IP port 631 is present and UNcommented :

• Finally save the file and restart cups

sh /etc/init.d/cups restart

2. Per-user workaround #1 Add a ~/.cups/client.conf file with a "ServerName localhost" line. This will make the CUPS API library prefer localhost as the server to report

3. Per-user workaround #2 Set the CUPS_SERVER environment variable to localhost so that the CUPS API library will use and report that : CUPS_SERVER=localhost; export CUPS_SERVER

This approach could if necessary be set only in the environment in which your Java printing application is run and its effects confined to that.

There is one additional step to the workaround for at least some systems. JDK looks for"libcups.so". This is usually a symlink to the specific version, eg "libcups.so.2" but on systems without a developer package it may not exist. The solution is to locate the cup library on your system and if necessary create a symbolic link. For example

cd /usr/lib
ln -s libcups.so.2 libcups.so

Rendering questions

Q: What is the Rendering Process?

A Rendering is the process of taking a collection of shapes, text, and images and figuring out what colors the pixels should be on a screen or printer. In the Java 2D API, the Graphics2D class is the rendering engine: the Graphics2D object contains state attributes, such as color, and applies these attributes to the primitives when rendering them to various output devices.

The seven different attributes are:

• paint, which represents the color or pattern rendered to the destination for the text and shape draw and fill methods.
• stroke, which describes the line style of the outline of shapes which are rendered using the shape draw (but not fill) methods.
• font, which is the font of the text to be rendered in the text draw methods.
• rendering hint, which suggests optional algorithms for how a primitive should be rendered, such as whether a faster or more accurate algorithm should be used.
• transform, which represents the mapping from user space to device space and additional coordinate transforms, such as rotate and scale, to be applied to all primitives.
• composite, which defines how the paint colors should replace or be mixed or blended with the colors already in the destination for all primitives.
• clip, which identifies a subset of the pixels in the destination which are allowed to be changed. Pixels which fall outside the clip should never be modified by any primitive.

The following figure illustrates the rendering process:
 

Q: What kinds of shapes can I draw using Java 2D?

A: The Java 2D API provides classes for drawing basic shapes like rectangles and circles but also allows you to draw any arbitrary shape. The following table lists the classes that represent predetermined shapes.
 

In addition to these classes that allow you to create common shapes, the Java 2D API provides two other classes that allow you to define odd shapes: GeneralPath and Area. Shapes created with GeneralPath must be created segment by segment, but this means that you can combine straight lines and curved lines into a single shape.  The Area class supports constructive area geometry, which allows you to combine two shapes to create another shape, either by adding or intersecting the shapes, subtracting one shape from another, or by subtracting the intersection of the shapes. To see Java 2D and CAG in action, go to
Constructing Complex Shapes from Geometry Primitives in the Java Tutorial.

You can also create a Shape object from a String by calling getOutline on a TextLayout object.  After creating the Shape, you can perform operations such as filling and transforming on the Shape.

For more information on working with shapes in Java 2D, see the 2D Graphics tutorial.

Q: How do I draw on an image?

A: If your image is an external image in a format such as JPG then first you load it into a BufferedImage using the javax.imageio.ImageIO class Then you can obtain a Graphics2D for rendering to the in-memory copy of the image. Here's a sample that does this:

    BufferedImage bi = null;
    try {
        bi = ImageIO.read(new File("images/bld.jpg"));
    } catch (IOException ioe) {
    }
    Graphics2D g2d = bi.createGraphics();
    g2d.drawLine(10, 10, 20, 20);  // draw a line on the image
    ...
    g2d.dispose();

Q: I have a shape whose outline intersects itself. How do I control the filling of the shape?

A: You can control the filling of an arbitrary shape by setting the winding rule. The winding rule specifies which part of a shape is considered the inside of the shape. If you have an arbitrary shape with an outline that intersects itself, you might get different filling results depending on which winding rule you choose.  Because the GeneralPath class is used to represent such arbitrary shapes, any Shape objects that are instances of GeneralPath can use the setWindingRule(int) method to set the winding rule to either WIND_NON_ZERO or WIND_EVEN_ODD. See the GeneralPath class comments for a description of each winding rule.

Note that any given Shape can only have a single winding rule that applies for its entire outline. If you have a complex combination of shapes that overlap and intersect with each other in many places, it may be easier to use the Area class to combine the shapes with explicit intersection, union, subtraction and exclusive or operations rather than to try to control the action of the multiple overlapping sections with a single winding rule.

Q: What does it mean to flatten a Shape?

A: Flattening is the process of converting the curved lines of a Shape into straight line segments. During rasterization, flattening is often performed on all curved path segments before they are stroked or filled because rendering calculations are much faster for straight lines than for curves. Shape objects provide a getPathIterator(aT, flatness) method which returns a PathIterator object that iterates through the path with only straight line segments that approximate the original path of the Shape. The flatness parameter must be a double value greater than or equal to 0.0 which controls how closely the straight lines approximate the curve. The smaller the number, the closer the straight lines will approximate the curve. The original Shape object is not modified by this method as the flattening is done on the fly as the path is iterated.

Q: How do I draw a quadratic arrow-headed curves?

A: There is no direct API for doing this. However, the following sample code can be used to achieve this effect.

        ...
        GeneralPath path = new GeneralPath();
        float p1x = 10, p1y = 10;   // P1
        float p2x = 100, p2y = 10;  // P2
        float cx = 55, cy = 50;     // Control point of the curve
        float arrSize = 5;          // Size of the arrow segments

        float adjSize = (float)(arrSize/Math.sqrt(2));
        float ex = p2x - cx;
        float ey = p2y - cy;
        float abs_e = (float)Math.sqrt(ex*ex + ey*ey);
        ex /= abs_e;
        ey /= abs_e;


        // Creating quad arrow
        path.moveTo(p1x, p1y);
        path.quadTo(cx, cy, p2x, p2y);
        path.lineTo(p2x + (ey-ex)*adjSize, p2y - (ex + ey)*adjSize);
        path.moveTo(p2x, p2y);
        path.lineTo(p2x - (ey + ex)*adjSize, p2y + (ex - ey)*adjSize);
        ...

Q: Why do I get unexpected results when I use the setTransform method of Graphics2D to perform transformations?

A: Because the setTransform method is not intended for adding new coordinate transformations onto an existing transform. In fact, when you use setTransform, you are overwriting the Graphics2D object's current transform, which might be needed for other purposes, such as applying a scaling transformation to adjust for printer resolution. The setTransform method should ONLY be used to restore the Graphics2D transform to an earlier saved state after performing some temporarily transformed rendering.

To perform transformations, use these steps:

1. Use getTransform to get the current transform:

   AffineTransform aT = g2.getTransform();

2. Use the transform, translate, scale, shear, or rotate methods to concatenate a transform:

   g2.transform(...);

3. Perform the rendering:

   g2.draw(...);

4. Restore the original transform using setTransform:

   g2.setTransform(aT);