White Paper

   

Java 2D API Data Sheet | Java 2D API Home Page


Enhanced Graphics and Imaging for the Java Platform

The Java 2D Application Programming Interface (API) provides a powerful, flexible framework for using device- and resolution-independent graphics in Java programs. The Java 2D API extends the graphics and imaging classes defined by java.awt , while maintaining compatibility for existing programs. The Java 2D API enables developers to easily incorporate high-quality 2D graphics, text, and images in Java applications and applets.

Authored primarily by Sun and Adobe Systems Incorporated, the Java 2D API provides a two-dimensional imaging model for line art, text, and images that uniformly addresses color, spatial transformations, and compositing. With the Java 2D API, you use the same imaging model for both screen and print, which provides a highly WYSIWYG (What You See Is What You Get) experience for the user.

This paper covers the design goals for the Java 2D API, the benefits the API provides, and a technical overview. An expanded version of this paper is available online that contains code samples and a more detailed description of the Java 2D API. For more information, see: here

Design Goals

Along with the other Java Media APIs, the Java 2D API was architected to empower developers to create applications that incorporate advanced user interfaces. The design goals for the Java 2D API include:

  •  

  • Supporting high-quality, platform-independent graphics, text, and images
  •  

  • Delivering a simple and compact 2D graphics and imaging solution
  •  

  • Leveraging Java's "Write Once, Run Anywhere" paradigm in order to provide consistent access to 2D graphics across major Java platforms
  •  

  • Complementing other Java technologies, thus providing an integrated media solution for the Java platform

Features

The table below summarizes the features provided by the Java 2D API. Innovative features include extensive support for image compositing, alpha channel capability, accurate color-space definition and conversion, and a set of display-oriented imaging operators.

 

Graphics Antialiased rendering
Bezier paths
Transforms
Compositing
Richer rendering attributes
Arbitrary fill styles
Stroking parameters for lines and curves
Transparency
Text Extended font support
Advanced text layout
Images Flexible in-memory image layouts
Extended imaging operations, such as convolution,
lookup tables, and affine transformations
Devices Hooks for supporting arbitrary graphics devices
such as printers and screens
Color Management ICC profile support
Color conversion from different color spaces
Arbitrary color spaces
Benefits for Developers

The Java 2D API provides many benefits to developers who want to incorporate graphics, text, and images into their applications and applets- in other words, the Java 2D API benefits virtually all Java developers. By enabling the incorporation of sophisticated graphics and text, the Java 2D API makes it possible to create Java programs that provide a richer end-user experience. With the Java 2D API, you have the necessary support to create real-world applications that meet the expectations of today's user for font, graphics, and image capabilities.

The Java 2D API is part of a set of class libraries that are designed to enable you to develop full-featured Java programs. With these libraries, developers have the essential tools to build applications that meet market needs. They make it possible to reach a broad audience running applications on any Java enabled platform.

Building on Java Technology's Strengths

Java has rapidly established itself as a platform for building portable Internet and intranet applications. The Java 2D API extends Java's strengths by allowing developers to incorporate high-quality graphics into their applications and applets.

The Java platform provides many advantages to developers who need high-quality graphics support:

  •  

  • Portable platform. The language, APIs, and virtual machine are available for a wide variety of hardware platforms and operating systems and are supported by all the major Web browsers.
  •  

  • Powerful and compact environment. The Java Platform provides developers with a powerful object-oriented language while eliminating much of the complexity and overhead associated with other languages and programming environments.
  •  

  • Network aware and secure. From its inception, the Java platform has been network-aware and has included security mechanisms that provide users with protection from untrusted applets.

2D Graphics and Imaging and AWT

The Java 2D API will become part of the java.awt and java.awt.image core class libraries. By extending the existing classes, the Java 2D API maintains compatibility for existing programs and allows programs to seamlessly integrate the features provided by java.awt and the Java 2D API.

2D Graphics and Imaging and Java Media

Java Media comprises a set of class libraries that enhance and expand the media and communications capabilities within the Java environment. The Java 2D API is closely integrated with the Java Media APIs. Both the Java Animation API and Java Media Framework will leverage the 2D graphics features provided by the Java 2D API.

Java 2D API Fundamentals

The Java 2D API handles arbitrary shapes, text, and images and provides a uniform mechanism for performing transformations such as rotation and scaling. The Java 2D API also provides comprehensive font and color support.

Comprehensive Drawing Model

The Java 2D API uses the drawing model defined by the java.awt package for drawing to the screen: each Component object implements a paint method that is invoked automatically whenever something needs to be drawn. When paint is invoked, it is passed a Graphics object that knows how to draw into the component. The Java 2D API simply provides a subclass of Graphics, Graphics2D , with additional features for specifying fancy paint styles, defining complex shapes, and controlling the rendering process. The Java 2D API treats paths, text, and images uniformly; they can all be rotated, scaled, skewed, and composited using the methods introduced in the following sections.

The basic drawing process is the same for any component:

  1. Specify the appropriate attributes for the graphics you want to draw by setting the drawing attributes in the Graphics2D object.
  2. Define the shape, text, or image that you want to draw.
  3. Use the Graphics2D object to render the shape, text, or image by calling one of the Graphics2D rendering methods.

Coordinate Spaces

The Java 2D API defines two coordinate spaces: the User Coordinate Space and the Device Coordinate Space. The origin of the Device Coordinate Space lies in the upper left-hand corner with x-coordinate values increasing to the right and y-coordinate values increasing downward.

x y coordinate graphic
Figure 1. Device Coordinate Space and default User Coordinate Space

All graphics objects are described in the device-independent User Coordinate Space until they are rendered on a device such as a screen or printer. The rendering state of a Graphics2D object associated with the target device includes a Transform object that converts the graphics object's User Space coordinates to the Device Space coordinates. The default Transform results in a default User Coordinate Space with the same orientation as the Device Coordinate Space.

Paths

The Java 2D API provides an implementation of the Path interface that can be used to define complex shapes. This class, BezierPath, allows you to describe a shape using a combination of lines and Bezier curves. Using BezierPath to define an object's shape allows you to control the location of the object (in User Coordinate Space) as well as its shape. The shape can be transformed to a different position, size, and orientation in Device Coordinate Space using the Graphics2D Transform.

Text

The Java 2D API classes provide text handling support that ranges from the simple use of fonts to professional-quality management of character layout and font features.

Text is treated as a first-class citizen. It can be drawn, transformed, used as a clipping path, and composited just like any other graphic element.

Fonts

The Java 2D API defines a Font class that provides greater control over fonts than the java.awt. Font class. It also allows you to retrievemore information about a font, such as the Bezier paths of individual character glyphs.

When you display text with the Java 2D API Font class you can specify detailed information, such as the Transform to apply to the font. This allows you to scale the font to any size you choose.

The information that describes a font, such as its name and style parameters, is contained in Font attributes and in FontFeature objects. Every Font object contains an array of FontFeatures describing the particular Font, as well as attributes for font name, size, and transform. The Font class defines several convenience methods that allow you to access this data directly.

The Font class also provides access to font metrics. Every font object contains the detailed metrics for the font. Font allows you to access metric and outline information through getDesignMetrics, getGlyphMetrics, and getGlyphOutline.

Layout

Before a piece of text can be displayed, it is necessary to determine exactly where each character should be placed. Most clients leave this layout process up to the system, which supplies a set of algorithms that compute the layout based on information contained in the font (such as the font metrics) and provided by the client (such as the text itself and the requested point size).

The Java 2D API provides text layout facilities that handle most common cases, including text strings with mixed fonts, mixed languages, and bi-directional text.

Advanced clients might want to compute the text layout themselves so that they can exercise detailed control over what glyphs are used and where they are placed. Using information such as glyph sizes, kerning tables, and ligature information, advanced clients can use their own algorithms to compute the text layout, bypassing the system's layout mechanism.

Images

The Java 2D API provides a full range of features for handling images by supplementing the image-handling classes in java.awt and java.awt.image with several new classes, including: BufferedImage, Tile, Channel, ComponentColorModel and ColorSpace.

These classes give advanced Java programmers greater control over images. They allow you to create images in color spaces other than RGB and characterize colors for accurate reproduction. The Java 2D API BufferedImage class allows you to specify exactly how pixels are laid out in an in-memory image.

Like all other graphic elements, images are transformed by the Transform object associated with the Graphics2D object when they are drawn. This means that images can be scaled, rotated, skewed, or otherwise transformed just like text and paths. However, images maintain their own color information, represented by a color model for interpreting color data, rather than using the current color. Images can also be used as the rendering target of a Graphics2D.

Rendering

The Java 2D API allows you to control how graphics primitives are rendered through a comprehensive set of attributes associated with the Graphics2D state. This allows you to specify characteristics such as the stroke width, join types, and color and texture fills, and also specify how the graphics are blended to the screen and whether or not they are antialiased.

Rendering Process

The rendering process can be broken down into four stages. (Note that this process can be compressed to optimize rendering performance.)

 

  1. The graphics object being rendered is converted to graphics primitives and transformed into the Device Space using the transform from the Graphics2D object associated with the target device. This determines where the graphics object should be rendered.

    When a path is rendered it is converted to a BezierPath object. If the path is to be stroked, the stroke attributes are used to convert the path to a stroked path. This BezierPath is transformed into device coordinates using the transform associated with the target device.

    When a text string is rendered, the layout of the glyphs is determined using the information in the fonts used by the string. The glyphs are then converted to outlines that are described by BezierPath objects. These BezierPath objects are transformed into device coordinates using the transform associated with the target device.

    When an image is rendered, its bounding box (in user coordinates) is transformed into device coordinates using the transform associated with the target device.

  2.  

  3. The current clip is used to constrain the rendering operation. The clip can be any shape that can be described by a Path object.
  4.  

  5. The color to be rendered is determined. For image operations, the color is taken from the data of the image. For all other operations, the current Paint object in the Graphics2D is queried for the color.
  6.  

  7. The color is applied to the drawing surface using the current Composite object.

Complex Fills

Like the classes in java.awt, the Java 2D API classes can fill a shape with simple colors, but they also support more complex fills such as gradients and patterns. To facilitate the use of complex fills, the API defines a new interface called Paint and a Graphics2D method called setPaint. These features eliminate the time-consuming task of creating complex fills using simple solid-color paints.

A plad fill and a graduated fill
Figure 2. Complex paint styles

Conceptually, all drawing is done with a Paint object. A Color object can be thought of as a very simple type of Paint object, and the setColor method as a special case of setPaint. In effect, setColor installs a Paint object for you that paints with a single color. You can even pass a Color to the setPaint method, because Color implements the Paint interface and is just another type of Paint object.

Once you call setPaint, everything you draw (such as text and paths) is painted using the specified Paint object.

Strokes

When a Path object is drawn, it is first converted to an equivalent BezierPath. In the Java 2D API, all Graphics2D objects know how to stroke and fill a BezierPath. Stroking a BezierPath object is equivalent to running a logical pen along the segments of the BezierPath. The Stroke object encapsulates the characteristics of the mark drawn by the pen. The Java 2D API provides a BasicStroke class that contains characteristics such as the line width, end-cap style, segment join style, and the dashing pattern. The end-cap styles are chopped, round, and squared. The join styles are bevel, miter, and round.

Transformations

Objects are processed by a Transform associated with the Graphics2D object before they are drawn. A Transform object takes a point or a path and transforms it to a new point or path. The default Transform object created when the Graphics2D object is constructed performs simple scaling to device space. To get effects such as rotation, translation, or custom scaling, you create Transform objects and apply them to the Graphics2D object. The most commonly used Transform is the AffineTransform, which performs simple transformations such as translation, rotation, scaling, and skewing. The effects of consecutive transforms are cumulative:

Translation and rotation of a rectangle's coordinates
Figure 3. Transformation effects

The Transform interface can easily be implemented to provide other types of transformations, such as a non-linear perspective transformation.

Compositing

When you combine images by blending or overlaying them, you must define how the colors of the images are blended. To do this with the Java 2D API, you create a Composite object that defines a transfer mode. The transfer mode specifies how the colors are blended.

The AlphaComposite class implements the Composite interface to support the most common composition styles. The most commonly used transfer mode supported by AlphaComposite is SRC_OVER . When AlphaComposite.SRC_OVER is applied, it indicates that the new color (the source color) should be blended over the existing color (the destination color). The alpha value indicates the transparency of the new color, as a percentage, indicating how much of the existing color should show through the new color. The alpha value can be derived from an instance of Color, Paint, or Image, depending on the rendering operation that is being performed. In addition, an AlphaComposite object can increase the transparency of everything that is drawn. To make all objects 50% more transparent, an AlphaComposite object could be created with an alpha value of 0.5. The alpha value of the Composite object is combined with the alpha value of the graphics object being drawn, decreasing the alpha of the graphics object by 50%. The first image in Figure 4-4 shows two overlapping rectangles drawn with an AlphaComposite.SRC_OVER object applied before the blue rectangle is drawn. In the second image, the text is drawn before the Composite object is created so that it is totally opaque. Then a AlphaComposite.SRC_OVER object is created that sets the transparency to 50% and the two overlapping rectangles are drawn.

Two rectangles and text composited at varying levels of transparency
Figure 4.Compositing

Note that the red rectangle that used to be completely opaque is now partially transparent and the blue rectangle is even more transparent than before. This additional layer of transparency provided by the AlphaComposite class can be useful in a number of circumstances. New composition styles can be created by implementing the Composite and CompositeContext interfaces. A Composite object, once initiated, provides a CompositeContext object that actually holds the state and does the compositing work. Multiple CompositeContext objects can be created from one Composite object for the purpose of maintaining the separate states in a multi-threaded environment.

Transfer modes are implemented procedurally; methods are implemented to blend colors. Implementing transfer modes procedurally rather than declaratively allows new modes to be added simply by adding new code.

Transparency and Images

Images can carry transparency information for each pixel in the image. This information, often called an alpha channel, is used in conjunction with the current Composite object to blend the image with an existing drawing. Figure 4-5 contains three images with different transparency information. In each case, the image is displayed over a blue rectangle. This example assumes that an AlphaComposite object is installed that uses SRC_OVER as its transfer mode for compositing.

A picture of a dog and a blue square demonstrating transparency
Figure 5. Transparency and images

In the first image, all pixels are fully opaque (the dog's body) or fully transparent (the background). You often see this effect used on web pages. The second image is rendered with uniform, non-opaque transparency for the dog's body. The third image has opaque values around the dog's face and increasingly transparent values as the distance from the dog's face increases.

Conclusion

The Java 2D API provides a standard, cross-platform interface for handling complex shapes, text, and images. Using the Java 2D API, developers will be able to easily incorporate high-quality 2D graphics, text, and images in their Java applications and applets. The Java 2D API:

  •  

  • Enables high-quality device- and resolution-independent graphics.
  •  

  • Enhances font and text handling support.
  •  

  • Provides a single, comprehensive rendering model.
  •  

  • Protects investment in existing programs by extending the java.awt and java.awt.image packages.
Left Curve
Java SDKs and Tools
Right Curve
Left Curve
Java Resources
Right Curve
JavaOne Banner
Java 8 banner (182)