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 2D^TM 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 2D^TM API.

• Dynamic font loading

  The new method Font.createFont(int, InputStream) provides the ability to add fonts to the Java^TM 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 TrueType^TM 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 Java^TM 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 Java^TM 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