| # New Java 2DTM Features in the JavaTM 2 SDK, v1.3 | Documentation Contents

> Although the Java 2 SDK, v1.3 is an upgrade release, several significant features have been added to the Java 2DTM API in this release, including:

> > Multiple monitor support | Palette entry validity checking
> > PNG support | Access to a ColorModel's transfer type
> > Dynamic font loading | New ICC Profile Tags
> > `BasicStroke` pixel-adjustment hint | Improved paragraph balancing and hyphenation
> > Equation-solving methods | Precise bounding box calculations

> - Multiple Monitor Support

>   > You can now render on multiple screens by creating `Frame`, `JFrame`, `Window`, or `JWindow` objects with the `GraphicsConfiguration` of the target `GraphicsDevice`.

>   > The new `Frame` constructor, `Frame(GraphicsConfiguration)`, enables creation of a `Frame` object on a different screen device.

>   > The new `Window` constructor, `Window(Window, GraphicsConfiguration)`, constructs a new invisible window with the specified window as its owner and the `GraphicsConfiguration` of a screen device.

>   > The new `GraphicsConfiguration` `getBounds` method returns the bounds of the `GraphicsConfiguration` in device coordinates. If you have a virtual device, then the device coordinates returned from `getBounds` are virtual device coordinates.

>   > Finally, the new `Component` `getGraphicsConfiguration` method returns the `GraphicsConfiguration` with which the `Component` was created.

>   > In a virtual device configuration consisting of more than one physical screen device, the `GraphicsConfiguration` objects' coordinates are relative to the virtual coordinate system. For this reason, virtual coordinates must be used when calling the `setLocation` method of a `Frame` or `Window`. Similarly, calling `getBounds` of a `GraphicsConfiguration` in a virtual device environment returns virtual device coordinates.

>   > The following code sample creates a `JFrame` object for each `GraphicsConfiguration` on each screen device in the `GraphicsEnvironment`. It offsets the coordinates of the intended location of the `JFrame` with the bounds of the `GraphicsConfiguration` to ensure that the `JFrame` appears on the screen of the specified `GraphicsConfiguration`.

>   >             GraphicsEnvironment ge = GraphicsEnvironment.
>   >                                      getLocalGraphicsEnvironment();
>   >             GraphicsDevice[] gs = ge.getScreenDevices();
>   >             for (int j = 0; j < gs.length; j++) {
>   >                 GraphicsDevice gd = gs[j];
>   >                 GraphicsConfiguration[] gc = gd.getConfigurations();
>   >                 for (int i=0; i < gc.length; i++) {
>   >                         JFrame f = new JFrame(gs[j].getDefaultConfiguration());
>   >                         Canvas c = new Canvas(gc[i]);
>   >                         Rectangle gcBounds = gc[i].getBounds();
>   >                         int xoffs = gcBounds.x;
>   >                         int yoffs = gcBounds.y;
>   >                         f.getContentPane().add(c);
>   >                         f.setSize(300, 150);
>   >                         f.setLocation((i*50)+xoffs, (i*60)+yoffs);
>   >                         f.show();
>   >     	    }
>   >     	}

>   > If the bounds of a `GraphicsConfiguration` is not taken into account in this sample, a `JFrame` would appear at location (i*50, i*60) on the primary screen, which might be different than the screen of the specified `GraphicsConfiguration`.

>   > For more information on how the Java 2D API supports multi-screen environments, see Rendering in a Multi-Screen Environment in the Programmer's Guide to the Java 2D API.

> - PNG Support

>   > The PNG (Portable Network Graphics) format is a flexible, extensible, non-proprietary file format that represents lossless and portable storage of raster images. PNG supports grayscale, indexed-color, and truecolor images and an optional alpha channel.

>   > PNG images are loaded and drawn the same way as GIF and JPEG images in the Java 2DTM API.

> - Dynamic font loading

>   > The new method `Font.createFont(int, InputStream)` provides the ability to add fonts to the JavaTM 2 Virtual Machine* (JVM) at runtime. This font is not persistent upon termination of the JVM and is only available to the creator of the `Font`. At this time, only TrueTypeTM fonts can be created at runtime.

>   > The following code sample illustrates how to dynamically load the TrueType font Arial from a file:

>   >     	File file = new File("Arial.ttf");
>   >     	FileInputStream fis = new FileInputStream(file);
>   >     	Font font = Font.createFont(Font.TRUETYPE_FONT, fis);

>   > Similarly, to load the font from a URL:

>   >     	URL url = new URL("Arial.ttf");
>   >     	InputStream is = url.openStream();
>   >     	Font font = Font.createFont(Font.TRUETYPE_FONT, is);

> - `BasicStroke` pixel-adjustment hint

>   > In some releases of the JavaTM 2 SDK, v 1.2, the `BasicStroke` object automatically translated any lines drawn with it by (0.5, 0.5) in user space coordinates. This translation was performed so that the line would be centered on the pixels and exactly cover whole pixels. By completely covering whole pixels, the line would look the same whether or not antialiasing was applied. The translation bias also ensured the output to a screen and a printer was consistent.

>   > Unfortunately, the translation bias produced unexpected results in some cases. For example, when the coordinate system was scaled up significantly, a stroked line that enclosed a filled shape would not be exactly centered on the edge of the shape, as you might expect.

>   > Although this feature was included in some beta releases of the Java 2 SDK, v 1.2, it was not implemented in the FCS release.

>   > In the Beta release of the Java 2 SDK, v1.3, three new `BasicStroke` constructors allowed programmers to specify the translation bias. These constructors have since been removed because of a backwards compatibility problem.

>   > For the FCS release of the Java 2 SDK, v1.3, these constructors are replaced with a set of hints in the `RenderingHints` class that are used to perform stroke normalization:

>   > The KEY_STROKE_CONTROL hint key and these hint values:
>   > VALUE_STROKE_NORMALIZE
>   > VALUE_STROKE_DEFAULT
>   > VALUE_STROKE_PURE

>   > The `VALUE_STROKE_NORMALIZE` hint indicates that normalization is performed. Normalization improves the consistency of the appearance of a stroke whether or not antialiasing is applied to it and wherever the stoke is rendered on the pixel grid.

>   > The `VALUE_STROKE_PURE` hint indicates that no normalization is performed. Use this hint when you prefer that the rendering of your geometry is accurate rather than visually consistent.

>   > Use the `VALUE_STROKE_DEFAULT` hint if you have no preference whether or not a stroke is normalized.

>   > To normalize a stroke for consistency, call the setRenderingHint(Key, Object) method of the `Graphics2D` class with the `KEY_STROKE_CONTROL` hint key and the `VALUE_STROKE_NORMALIZE` hint value:

>   >     	Graphics2D g2 = (Graphics2D) g;
>   >     	g2.setRenderingHint(RenderingHints.KEY_STROKE_CONTROL,
>   >     		RenderingHints.VALUE_STROKE_NORMALIZE);

>   > See the Java 2D-Interest list posting, Basic Stroke offset and change of plans, for more information about this new API and why it has replaced the `BasicStroke` constructors added with the Beta release of the Java 2 SDK, v1.3.

> - Palette Entry Validity Checking

>   > When you create an off-screen image for an 8-bit display on X Windows, the palette of available colors contained in the returned `IndexColorModel` object could have invalid color entries. The invalid entries are filled with transparent black. Before the Java 2 SDK, v1.3, there was no way to determine which entries in the palette were valid. Two new methods and one new constructor enable you to determine the validity of the indices in the lookup table:

>   > - `IndexColorModel(int, int, int[], int, int, BigInteger)` is a constructor that allows you to specify the validity of each pixel in the `cmap` array.
>   > - `isValid(int pixel)` determines the validity of a single pixel.
>   > - `getValidPixels` returns a `BigInteger` indicating the valid and invalid pixels in the colormap.

> - Access to a ColorModel's Transfer Type

>   > The new `ColorModel` `getTransferType` method allows you to retrieve the `transferType` of the current `ColorModel`. The `transferType` is the data type of the array that is used to represent pixel values. Since `transferType` is a protected field, you need to get the `transferType` of the current `ColorModel` if you want to create a new `ColorModel` object identical to the current one except for a few parameters.

> - New ICC Profile tags

>   > The `ICC_Profile` class has three new profile tags that bring the Java 2D API into compliance with the latest International Color Consortium profile specification, ICC.1:1998-09, and addendum, ICC.1A:1999-04:

>   > - `icSigDeviceSettingsTag`
>   > - `icSigOutputResponseTag`
>   > - `icSigChromaticityTag`

> - Improved paragraph balancing and hyphenation

>   > The `TextMeasurer` class enables more precise control over line breaking than the `LineBreakMeasurer` class. With `TextMeasurer`, you can determine where to break a line of text and perform paragraph balancing and hyphenation.

> - Equation-solving methods

>   > Two new methods have been added to the Java 2D API that solve algebraic equations given an array containing the coefficients and store the results of the solution into a separate array.

>   > In the JavaTM 2 SDK, version 1.2.2, there are only methods that return the results of these equations in the same array that contained the coefficients. The new methods preserve the coefficients array by storing the results in a separate array.

>   > The `solveQuadratic(double[], double[])` method of `QuadCurve2D` solves quadratic equations.

>   > The `solveCubic(double[], double[])` method of `CubicCurve2D` solves cubic equations.

> - Precise bounding box calculations

>   > New implementation has been added to the `getBounds` and `getBounds2D` methods of the `Area` class that calculates a tighter bounding box of a shape.

>   > The bounding box returned from these methods in the Java 2 SDK, version 1.2.2 is a looser bounding box because the control points are taken into account when the bounds of the geometry is calculated. The new `getBounds` and `getBounds2D` methods do not factor in the control points to the bounds calculation.

*As used on this web site, the terms "Java Virtual Machine" or "JVM" mean a virtual machine for the Java platform.

Copyright © 1995-99 Sun Microsystems, Inc. All Rights Reserved. Please send comments to: java2d-comments@sun.com | Java Software