<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Programmer's Guide to the Java 2D API</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- font size="-1" -->
CONTENTS | PREV | <a href="j2d-bookTOC.doc.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right></td>
</tr></table>
<hr>

<TABLE BORDER=0 WIDTH="100%">
<tr>
<td width=40></td>
<td width=40></td>
<td width=40></td>
<td width=40></td>
<td></td>
</tr>
<a name="997233"><!-- --></a>
<center><h1>Programmer's Guide to the Java<sup>TM</sup> 2D API</h1></center>
<hr><p><blockquote>
<a name="997295"><!-- --></a>
<center>
JDK<sup>TM</sup> 1.2 Version<p>
<a name="997302"><!-- --></a>
November 2, 1998<p>
</center>
<a name="997223"><!-- --></a>
<p>
<a name="997224"><!-- --></a>
<p>
<a name="997225"><!-- --></a>
<p>
<a name="997226"><!-- --></a>
<p>
</blockquote><a name="997236"><!-- --></a>
<b></b> &nbsp; 


<a name="997220"><!-- --></a>
<b></b> &nbsp; 


<a name="997221"><!-- --></a>
<b></b> &nbsp; 


<a name="997192"><!-- --></a>
<b></b> &nbsp; <br>
<p><center><img src="j2d-title.fm.anc.gif"></center>



</TABLE>

<!--
<hr>
<h3>Deborah Adair</h3>
-->

<br>
<hr>
<!-- font size="-1" -->
CONTENTS | PREV | <a href="j2d-bookTOC.doc.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:02 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm4.html">PREV</a>
 | <a href="j2d-awt.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 
<a name="70026"><!-- --></a>
<hr size="8" width="35%" align="left" noshade>

<table border=0>
<tr valign=bottom>
<td valign=bottom>
<br>
<U><B><FONT FACE="ARIAL,HELVETICA,TIMES ROMAN">CHAPTER</FONT> 
2 
</B></U>
</td>
</tr>
</table>

<a name="70028"><!-- --> </a>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td align="left">
<h1><FONT SIZE=+4>
Rendering with Graphics2D 
</font></h1>
</td>
</tr>
</table>
<blockquote>
<a name="70029"><!-- --></a>
<kbd>Graphics2D</kbd> extends <kbd>java.awt.Graphics </kbd>to provide more sophisticated control over the presentation of shapes, text, and images. The Java 2D rendering process is controlled through the <kbd>Graphics2D</kbd> object and its state attributes. <p>
<a name="68316"><!-- --></a>
The <kbd>Graphics2D</kbd> state attributes, such as line styles and transformations, are applied to graphic objects when they are rendered. The collection of state attributes associated with a <kbd>Graphics2D</kbd> is referred to as the <kbd>Graphics2D</kbd> context. To render text, shapes, or images, you set up the <kbd>Graphics2D</kbd> context and then call one of the <kbd>Graphics2D</kbd> rendering methods, such as <kbd>draw</kbd> or <kbd>fill</kbd>.<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm4.html">PREV</a>
 | <a href="j2d-awt.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:11 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm.html">PREV</a>
 | <a href="j2d-awt.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="68318"><i>2.1	</i> Interfaces and Classes
</a></h2>

<blockquote>
<a name="68838"><!-- --></a>
The following tables list the interfaces and classes used in conjunction with the <kbd>Graphics2D</kbd> context, including the classes that represent state attributes. Most of these classes are part of the <kbd>java.awt</kbd> package. <p>
<a name="65733"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="63965"><!-- --></a>
<blockquote><hr noshade size="1"><b>Interface</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="63967"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="63969"><!-- --></a>
<p><code>Composite</code>

</td><td><a name="63971"><!-- --></a>
<p>Defines methods to compose a draw primitive with the underlying graphics area. Implemented by <code>AlphaComposite</code>.

</td></tr>
<tr><td><a name="63973"><!-- --></a>
<p><code>CompositeContext</code>

</td><td><a name="63975"><!-- --></a>
<p>Defines the encapsulated and optimized environment for a composite operation. Used by programmers implementing custom compositing rules.

</td></tr>
<tr><td><a name="63977"><!-- --></a>
<p><code>Paint</code>

</td><td><a name="63979"><!-- --></a>
<p>Extends: <code>Transparency</code>

<a name="63980"><!-- --></a>
<p>Defines colors for a <code>draw</code> or <code>fill</code> operation. Implemented by <code>Color</code>, <code>GradientPaint</code> and <code>TexturePaint</code>. 

</td></tr>
<tr><td><a name="63982"><!-- --></a>
<p><code>PaintContext</code>

</td><td><a name="63984"><!-- --></a>
<p>Defines the encapsulated and optimized environment for a paint operation. Used by programmers implementing custom paint operations.

</td></tr>
<tr><td><a name="63990"><!-- --></a>
<p><code>Stroke</code>

</td><td><a name="63992"><!-- --></a>
<p>Generates a <code>Shape</code> that encloses the outline of the <code>Shape</code> to be rendered. Implemented by <code>BasicStroke</code>.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
<a name="65734"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="63345"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="63347"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="68194"><!-- --></a>
<p><code>AffineTransform</code>

<a name="68195"><!-- --></a>
<p><code>(java.awt.geom)</code>

</td><td><a name="68175"><!-- --></a>
<p>Represents a 2D affine transform, which performs a linear mapping from 2D coordinates to other 2D coordinates.

</td></tr>
<tr><td><a name="63404"><!-- --></a>
<p><code>AlphaComposite</code>

</td><td><a name="63467"><!-- --></a>
<p>Implements: <code>Composite</code> 

<a name="63468"><!-- --></a>
<p>Implements basic alpha composite rules for shapes, text, and images. 

</td></tr>
<tr><td><a name="63406"><!-- --></a>
<p><code>BasicStroke</code>

</td><td><a name="63472"><!-- --></a>
<p>Implements: <code>Stroke</code>

<a name="63473"><!-- --></a>
<p>Defines the &#34;pen style&#34; to be applied to the outline of a <code>Shape</code>.

</td></tr>
<tr><td><a name="69586"><!-- --></a>
<p>Color

</td><td><a name="69588"><!-- --></a>
<p>Implements: <code>Paint</code>

<a name="69596"><!-- --></a>
<p>Defines a solid color fill for a <code>Shape</code>. 

</td></tr>
<tr><td><a name="63412"><!-- --></a>
<p><code>GradientPaint</code>

</td><td><a name="69633"><!-- --></a>
<p>Implements: <code>Paint</code>

<a name="63488"><!-- --></a>
<p>Defines a linear color gradient fill pattern for a <code>Shape</code>. This fill pattern changes from color C1 at point P1 to color C2 at point P2.

</td></tr>
<tr><td><a name="63414"><!-- --></a>
<p><code>Graphics2D</code>

</td><td><a name="63492"><!-- --></a>
<p>Extends: <code>Graphics</code>

<a name="63493"><!-- --></a>
<p>Fundamental class for 2D rendering. Extends the original <code>java.awt.Graphics</code> class.

</td></tr>
<tr><td><a name="63426"><!-- --></a>
<p><code>TexturePaint</code>

</td><td><a name="63514"><!-- --></a>
<p>Implements: <code>Paint</code>

<a name="63515"><!-- --></a>
<p>Defines a texture or pattern fill for a <code>Shape</code>. The texture or pattern is generated from a <code>BufferedImage</code>.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm.html">PREV</a>
 | <a href="j2d-awt.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:11 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm1.html">PREV</a>
 | <a href="j2d-awt.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="63340"><i>2.2	</i> Rendering Concepts
</a></h2>

<blockquote>
<a name="67675"><!-- --></a>
To render a graphic object using the Java 2D API, you set up the <kbd>Graphics2D</kbd> context and pass the graphic object to one of the <kbd>Graphics2D</kbd> rendering methods. <p>
<a name="67676"><!-- --></a>
You can modify the state attributes that form the <kbd>Graphics2D</kbd> context to: <p>
</blockquote>
<blockquote>
<ul><li>
<a name="68359"><!-- --></a>
Vary the stroke width.
</li>
<li>
<a name="68360"><!-- --></a>
Change how strokes are joined together.
</li>
<li>
<a name="61830"><!-- --></a>
Set a clipping path to limit the area that is rendered.
</li>
<li>
<a name="68302"><!-- --></a>
Translate, rotate, scale, or shear objects when they are rendered.
</li>
<li>
<a name="68365"><!-- --></a>
Define colors and patterns to fill shapes with.
</li>
<li>
<a name="61834"><!-- --></a>
Specify how multiple graphics objects should be composed.
</li>
</ul>
</blockquote>
<blockquote>
<a name="67162"><!-- --></a>
<kbd>Graphics2D</kbd> defines several methods for adding and changing attributes in the graphics context. Most of these methods take an object that represents a particular attribute, such as a <kbd>Paint</kbd> or <kbd>Stroke</kbd> object. <p>
<a name="68341"><!-- --></a>
The <kbd>Graphics2D</kbd> context holds <em>references</em> to these attribute objects: they are not cloned. If you alter an attribute object that is part of the <kbd>Graphics2D</kbd> context, you need to call the appropriate <kbd>set</kbd> method to notify the context. Modifying an attribute object during a rendering operation will cause unpredictable and possibly unstable behavior. <p>
</blockquote>
<br>
<h3>
<a name="67506"><!-- --></a>
<i>2.2.1	</i> Rendering Process
</h3>

<blockquote>
<a name="67507"><!-- --></a>
When a graphic object is rendered, the geometry, image, and attribute information are combined to calculate which pixel values must be changed on the display. <p>
<a name="67528"><!-- --></a>
The rendering process for a <kbd>Shape</kbd> can be broken down into four steps:<p>
</blockquote><blockquote><ol>
<li>
<a name="67534"><!-- --></a>
If the <kbd>Shape</kbd> is to be stroked, the <kbd>Stroke</kbd> attribute in the <kbd>Graphics2D</kbd> context is used to generate a new <kbd>Shape</kbd> that encompasses the stroked path. 
</li>

<li>
<a name="68346"><!-- --></a>
The coordinates of the <kbd>Shape</kbd>&#39;s path are transformed from user space into device space according to the transform attribute in the <kbd>Graphics2D</kbd> context.
</li>

<li>
<a name="67511"><!-- --></a>
The <kbd>Shape</kbd>&#39;s path is clipped using the clip attribute in the <kbd>Graphics2D</kbd> context.
</li>

<li>
<a name="67512"><!-- --></a>
The remaining <kbd>Shape</kbd>, if any, is filled using the <kbd>Paint</kbd> and <kbd>Composite</kbd> attributes in the <kbd>Graphics2D</kbd> context.
</li>

</ol></blockquote>
<blockquote>
<a name="67513"><!-- --></a>
Rendering text is similar to rendering a <kbd>Shape</kbd>, since the text is rendered as individual glyphs and each glyph is a <kbd>Shape</kbd>. The only difference is that the Java 2D API must determine what <kbd>Font</kbd> to apply to the text and get the appropriate glyphs from the <kbd>Font</kbd> before rendering.<p>
<a name="67514"><!-- --></a>
Images are handled differently, transformations and clipping operations are performed on the image&#39;s bounding box. The color information is taken from the image itself and its alpha channel is used in conjunction with the current <kbd>Composite</kbd> attribute when the image pixels are composited onto the rendering surface.<p>
</blockquote>
<br>
<h3>
<a name="61856"><!-- --></a>
<i>2.2.2	</i> Controlling Rendering Quality
</h3>

<blockquote>
<a name="68861"><!-- --></a>
The Java 2D API lets you indicate whether you want objects to be rendered as quickly as possible, or whether you prefer that the rendering quality be as high as possible. Your preferences are specified as hints through the <kbd>RenderingHints</kbd> attribute in the <kbd>Graphics2D</kbd> context. Not all platforms support modification of the rendering mode so specifying rendering hints does not guarantee that they will be used.<p>
<a name="69745"><!-- --></a>
The <kbd>RenderingHints</kbd> class supports the following types of hints:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="69749"><!-- --></a>
Alpha interpolation&#45;&#45;can be set to default, quality, or speed. 
</li>
<li>
<a name="69750"><!-- --></a>
Antialiasing&#45;&#45;can be set to default, on, or off. 
</li>
<li>
<a name="69957"><!-- --></a>
Color Rendering&#45;can be set to default, quality, or speed.
</li>
<li>
<a name="69958"><!-- --></a>
Dithering&#45;&#45;can be set to default, disable, or enable. 
</li>
<li>
<a name="69959"><!-- --></a>
Fractional Metrics&#45;&#45;can be set to default, on, or off. 
</li>
<li>
<a name="69930"><!-- --></a>
Interpolation&#45;&#45;can be set to nearest-neighbor, bilinear, or bicubic.
</li>
<li>
<a name="69931"><!-- --></a>
Rendering&#45;&#45;can be set to default, quality, or speed.
</li>
<li>
<a name="69932"><!-- --></a>
Text antialiasing&#45;&#45;can be set to default, on, or off. 
</li>
</ul>
</blockquote>
<blockquote>
<a name="69990"><!-- --></a>
To set or change the <kbd>RenderingHints</kbd> attribute in the <kbd>Graphics2D</kbd> context, you call <kbd>setRenderingHints</kbd>. When a hint is set to default, the platform rendering default is used is used.<p>
<a name="70008"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="68882"><!-- --></a>
<blockquote><hr noshade size="1"><b>Antialiasing</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><blockquote>
<a name="69228"><!-- --></a>
When graphics primitives are rendered on raster-graphics display devices, their edges can appear jagged because of <em>aliasing</em>. Arcs and diagonal lines take on a jagged appearance because they are approximated by turning on the pixels that are closest to the path of the line or curve. This is particularly noticeable on low-resolution devices, where the jagged edges appear in stark contrast to the smooth edges of horizontal or vertical lines. <p>
<a name="69327"><!-- --></a>
<em>Antialiasing</em> is a technique used to render objects with smoother-appearing edges. Instead of simply turning on the pixel that is closest to the line or curve, the intensity of surrounding pixels is set in proportion to the amount of area covered by the geometry being rendered. This softens the edges and spreads the on-off transition over multiple pixels. However, antialiasing requires additional computing resources and can reduce rendering speed.<p><center><img src="j2d-awt.fm.anc.gif"></center><p>
</blockquote></td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>
<br>
<h3>
<a name="61854"><!-- --></a>
<i>2.2.3	</i> Stroke Attributes
</h3>

<blockquote>
<a name="67742"><!-- --></a>
Stroking a <kbd>Shape</kbd> such as a <kbd>GeneralPath</kbd> object is equivalent to running a logical pen along the segments of the <kbd>GeneralPath</kbd>. The <kbd>Graphics2D</kbd> <kbd>Stroke</kbd> attribute defines the characteristics of the mark drawn by the pen.<p>
<a name="67856"><!-- --></a>
<kbd>A BasicStroke</kbd> object is used to define the stroke attributes for a <kbd>Graphics2D</kbd> context. <kbd>BasicStroke</kbd> defines characteristics such as the line width, endcap style, segment join-style, and the dashing pattern. To set or change the <kbd>Stroke</kbd> attribute in the <kbd>Graphics2D</kbd> context, you call <kbd>setStroke</kbd>.<p>
<a name="69253"><!-- --></a>
<p><center><img src="j2d-awt.fm.anc4.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="69256"><!-- --></a>
<b>Figure 2-1	</b> endcap styles supported by <kbd>BasicStroke
</kbd>
</p>
</blockquote><blockquote>
<a name="65703"><!-- --></a>
<p><center><img src="j2d-awt.fm.anc9.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="69259"><!-- --></a>
<b>Figure 2-2	</b> Join styles supported by <kbd>BasicStroke</kbd>

</p>
</blockquote><blockquote>
<a name="63039"><!-- --></a>
For example, the first image in <a href="j2d-awt.fm2.html#61897">Figure&#160;2-3</a> uses the miter join-style; the second image uses a round join-style, a round endcap style, and a dashing pattern.<p>
<a name="61895"><!-- --></a>
<p><center><img src="j2d-awt.fm.anc1.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="61897"><!-- --></a>
<b>Figure 2-3	</b> Stroke Styles

</p>
</blockquote><blockquote>
<a name="68772"><!-- --></a>
The <kbd>Graphics2D</kbd> rendering methods that use the <kbd>Stroke</kbd> attribute are <kbd>draw</kbd>, <kbd>drawArc</kbd>, <kbd>drawLine</kbd>, <kbd>drawOval</kbd>, <kbd>drawPolygon</kbd>, <kbd>drawPolyline</kbd>, <kbd>drawRect</kbd>, and <kbd>drawRoundRect</kbd>.When one of these methods is called, the outline of the specified <kbd>Shape</kbd> is rendered. The <kbd>Stroke</kbd> attribute defines the line characteristics and the <kbd>Paint</kbd> attribute defines the color or pattern of the mark drawn by the pen. <p>
<a name="68775"><!-- --></a>
For example, when <kbd>draw(myRectangle)</kbd> is called:<p>
</blockquote><blockquote><ol>
<li>
<a name="68709"><!-- --></a>
The <kbd>Stroke</kbd> is applied to the rectangle&#39;s outline. 
</li>

<li>
<a name="68710"><!-- --></a>
The stroked outline is converted to a <kbd>Shape</kbd> object.
</li>

<li>
<a name="68711"><!-- --></a>
The <kbd>Paint</kbd> is applied to the pixels that lie within the contour of the outline <kbd>Shape</kbd>. 
</li>

</ol></blockquote>
<blockquote>
<a name="69350"><!-- --></a>
This process is illustrated in <a href="j2d-awt.fm2.html#68717">Figure&#160;2-4</a>:<p><center><img src="j2d-awt.fm.anc5.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="68717"><!-- --></a>
<b>Figure 2-4	</b> Stroking a Shape

</p>
</blockquote>
<br>
<h3>
<a name="70202"><!-- --></a>
<i>2.2.4	</i> Fill Attributes
</h3>

<blockquote>
<a name="70203"><!-- --></a>
The fill attribute in the <kbd>Graphics2D</kbd> context is represented by a <kbd>Paint</kbd> object. You add a <kbd>Paint</kbd> to the <kbd>Graphics2D</kbd> context by calling <kbd>setPaint</kbd>. <p>
<a name="70204"><!-- --></a>
When a <kbd>Shape</kbd> or glyph is drawn (<kbd>Graphics2D.draw</kbd>, <kbd>Graphics2D.drawString</kbd>), the <kbd>Paint</kbd> is applied to all of the pixels that lie inside of the <kbd>Shape</kbd> that represents the object&#39;s stroked outline. When a <kbd>Shape</kbd> is filled (<kbd>Graphics2D.fill</kbd>), the <kbd>Paint</kbd> is applied to all of the pixels that lie within the <kbd>Shape</kbd>&#39;<kbd>s</kbd> contour.<p>
<a name="70205"><!-- --></a>
Simple solid color fills can be set with the <kbd>setColor</kbd> method. <kbd>Color</kbd> is the simplest implementation of the <kbd>Paint</kbd> interface. <p>
<a name="70206"><!-- --></a>
To fill <kbd>Shapes</kbd> with more complex paint styles such as gradients and textures, you use the Java 2D <kbd>Paint</kbd> classes <kbd>GradientPaint</kbd> and <kbd>TexturePaint</kbd>. These classes eliminate the time-consuming task of creating complex fills using simple solid-color paints. <a href="j2d-awt.fm2.html#70216">Figure&#160;2-5</a> illustrates two fills that could easily be defined by <kbd>GradientPaint</kbd> and <kbd>TexturePaint</kbd>.<p>
<a name="70214"><!-- --></a>
<p><center><img src="j2d-awt.fm.anc2.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="70216"><!-- --></a>
<b>Figure 2-5	</b> Complex Fill Styles

</p>
</blockquote><blockquote>
<a name="70217"><!-- --></a>
When <kbd>fill</kbd> is called to render a <kbd>Shape</kbd>, the system:<p>
</blockquote><blockquote><ol>
<li>
<a name="70218"><!-- --></a>
Determines what pixels comprise the <kbd>Shape</kbd>.
</li>

<li>
<a name="70219"><!-- --></a>
Gets the color of each pixel from the <kbd>Paint</kbd> object.
</li>

<li>
<a name="70220"><!-- --></a>
Converts the color to an appropriate pixel value for the output device.
</li>

<li>
<a name="70221"><!-- --></a>
Writes the pixel to that device.
</li>

</ol></blockquote>
<blockquote>
<a name="70233"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="70224"><!-- --></a>
<blockquote><hr noshade size="1"><b>Batch Processing</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><blockquote>
<a name="70226"><!-- --></a>
To streamline the processing of pixels, the Java 2D API processes them in batches. A batch can be either a contiguous set of pixels on a given scanline or a block of pixels. This batch processing is done in two steps:<p>
</blockquote><blockquote><ol>
<li>
<a name="70227"><!-- --></a>
The <kbd>Paint</kbd> object&#39;s <kbd>createContext</kbd> method is called to create a <kbd>PaintContext</kbd>. The <kbd>PaintContext</kbd> stores the contextual information about the current rendering operation and the information necessary to generate the colors. The <kbd>createContext</kbd> method is passed the bounding boxes of the graphics object being filled in user space and in device space, the <kbd>ColorModel</kbd> in which the colors should be generated, and the transform used to map user space into device space. The <kbd>ColorModel</kbd> is treated as a hint because not all <kbd>Paint</kbd> objects can support an arbitrary <kbd>ColorModel</kbd>. (For more information about <kbd>ColorModels</kbd>, see <a href="j2d-color.fm.html#61757">&#34;Color&#34; on page&#160;89</a>.&#34;)
</li>

<li>
<a name="70231"><!-- --></a>
The <kbd>getColorModel</kbd> method is called to get the <kbd>ColorModel</kbd> of the generated paint color from the <kbd>PaintContext</kbd>. 
</li>

</ol></blockquote>
<blockquote>
<a name="70232"><!-- --></a>
The<kbd> getRaster </kbd>method is then called repeatedly to get the <kbd>Raster</kbd> that contains the actual color data for each batch. This information is passed to the next stage in the rendering pipeline, which draws the generated color using the current <kbd>Composite</kbd> object.<p>
</blockquote></td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>
<br>
<h3>
<a name="68462"><!-- --></a>
<i>2.2.5	</i> Clipping Paths
</h3>

<blockquote>
<a name="68463"><!-- --></a>
A <em>clipping path</em> identifies the portion of a <kbd>Shape</kbd> or <kbd>Image</kbd> that needs to be rendered. When a clipping path is part of the <kbd>Graphics2D</kbd> context, only those parts of a <kbd>Shape</kbd> or <kbd>Image</kbd> that lie within the path are rendered. <p>
<a name="68464"><!-- --></a>
To add a clipping path to the <kbd>Graphics2D</kbd> context, you call <kbd>setClip</kbd>. Any <kbd>Shape</kbd> can be used to define the clipping path. <p>
<a name="68778"><!-- --></a>
To change the clipping path, you can either use <kbd>setClip</kbd> to specify a new path or call <kbd>clip</kbd> to change the clipping path to the intersection of the old clipping path and a new <kbd>Shape</kbd>.<p>
</blockquote>
<br>
<h3>
<a name="68474"><!-- --></a>
<i>2.2.6	</i> Transformations
</h3>

<blockquote>
<a name="68950"><!-- --></a>
The <kbd>Graphics2D</kbd> context contains a transform that is used to transform objects from user space to device space during rendering. To perform additional transformations, such as rotation or scaling, you can add other transforms to the   <kbd>Graphics2D</kbd> context. These additional transforms become part of the pipeline of transformations applied during rendering. <p>
<a name="68965"><!-- --></a>
<kbd>Graphics2D</kbd> provides several different ways to modify the transform in the <kbd>Graphics2D</kbd> context. The simplest is to call one of the <kbd>Graphics2D</kbd> transformation methods: <kbd>rotate</kbd>, <kbd>scale</kbd>, <kbd>shear</kbd>, or <kbd>translate</kbd>. You specify the characteristics of the transform that you want to be applied during rendering, and <kbd>Graphics2D</kbd> automatically makes the appropriate changes.<p>
<a name="68966"><!-- --></a>
You can also explicitly <em>concatenate</em> an <kbd>AffineTransform</kbd> with the current <kbd>Graphics2D</kbd> transform. An <kbd>AffineTransform </kbd>performs a linear transformation such as translation, scaling, rotation, or shearing on a set of graphics primitives. When a transform is concatenated with an existing transform, the last transform specified is the <em>first</em> to be applied. To concatenate a transform with the current transform, you pass an <kbd>AffineTransform</kbd> to <kbd>Graphics2D.transform</kbd>. <p>
<a name="68967"><!-- --></a>
<kbd>Graphics2D</kbd> also provides a version of <kbd>drawImage</kbd> that takes an <kbd>AffineTransform</kbd> as a parameter. This enables you to apply a transformation to an image object when it is drawn without permanently modifying the transformation pipeline. The image is drawn as if you had concatenated the transform with the current transform in the <kbd>Graphics2D</kbd> context.<p>
<a name="70236"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="68984"><!-- --></a>
<blockquote><hr noshade size="1"><b>Affine Transforms</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><blockquote>
<a name="69003"><!-- --></a>
The Java 2D API provides one transform class, <kbd>AffineTransform</kbd>. <kbd>AffineTransforms</kbd> are used to transform text, shapes, and images when they are rendered. You can also apply transforms to <kbd>Font</kbd> objects to create new font derivations, as discussed in <a href="j2d-fonts.fm6.html#74065">&#34;Creating Font Derivations&#34; on page&#160;65</a>.<p>
<a name="69007"><!-- --></a>
An affine transformation performs a linear transformation on a set of graphics primitives. It always transforms straight lines into straight lines and parallel lines into parallel lines; however, the distance between points and the angles between nonparallel lines might be altered. <p>
<a name="69008"><!-- --></a>
Affine transformations are based on two-dimensional matrices of the following form:<p>
<a name="69009"></a>
<p><a name="69019"></a>
<p><center><img src="j2d-awt.fm.anc6.gif"></center>  where <p><center><img src="j2d-awt.fm.anc7.gif"></center> and <p><center><img src="j2d-awt.fm.anc8.gif"></center><p><a name="69020"></a>
<p><a name="69021"><!-- --></a>
Transforms can be combined, effectively creating a series or <em>pipeline</em> of transformations that can be applied to an object. This combination is referred to as <em>concatenation</em>. When a transform is concatenated with an existing transform, such as with <kbd>AffineTransform.concatenate</kbd>, the last transform specified is the <em>first</em> to be applied. A transform can also be <em>pre-concatenated</em> with an existing transform. In this case, the last transform specified is the <em>last</em> to be applied. <p>
<a name="68990"><!-- --></a>
Pre-concatenation is used to perform transformations relative to device space instead of user space. For example, you could use <kbd>AffineTransform.preConcatenate</kbd> to perform a translation relative to absolute pixel space.<p>
</blockquote></td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>
<br>
<a name="68556"><!-- --></a>
<h4><i>2.2.6.1	 Constructing an AffineTransform
</i></h4>

<blockquote>
<a name="68557"><!-- --></a>
<kbd>AffineTransform</kbd> provides a set of convenience methods for constructing <kbd>AffineTransform</kbd> objects: <p>
</blockquote>
<blockquote>
<ul><li>
<a name="68502"><!-- --></a>
<kbd>getTranslateInstance</kbd>
</li>
<li>
<a name="68503"><!-- --></a>
<kbd>getRotateInstance</kbd>
</li>
<li>
<a name="68504"><!-- --></a>
<kbd>getScaleInstance</kbd>
</li>
<li>
<a name="68505"><!-- --></a>
<kbd>getShearInstance</kbd>
</li>
</ul>
</blockquote>
<blockquote>
<a name="68506"><!-- --></a>
To use these methods, you specify the characteristics of the transform you want to create and <kbd>AffineTransform</kbd> generates the appropriate transform matrix. You can also construct an <kbd>AffineTransform</kbd> by directly specifying the elements of the transformation matrix.<p>
</blockquote>
<br>
<h3>
<a name="64398"><!-- --></a>
<i>2.2.7	</i> Composite Attributes
</h3>

<blockquote>
<a name="68322"><!-- --></a>
When two graphic objects overlap, it is necessary to determine what colors to render the overlapping pixels. For example, if a red rectangle and a blue rectangle overlap, the pixels that they share could be rendered red, blue, or some combination of the two. The color of the pixels in the overlapping area will determine which rectangle appears to be on top and how transparent it looks. The process of determining what color to render pixels shared by overlapping objects is called <em>compositing</em>.<p>
<a name="67997"><!-- --></a>
Two interfaces form the basis of the Java 2D compositing model: <kbd>Composite</kbd> and <kbd>CompositeContext</kbd>. <p>
<a name="68671"><!-- --></a>
To specify the compositing style that should be used, you add an <kbd>AlphaComposite</kbd> object to the <kbd>Graphics2D</kbd> context by calling <kbd>setComposite</kbd>. <kbd>AlphaComposite</kbd>, an implementation of the <kbd>Composite</kbd> interface, supports a number of different compositing styles. Instances of this class embody a compositing rule that describes how to blend a new color with an existing one. <p>
<a name="68680"><!-- --></a>
One of the most commonly used compositing rules in the <kbd>AlphaComposite</kbd> class is SRC_OVER, which indicates that the new color (the source color) should be blended over the existing color (the destination color). 

<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="68600"><!-- --></a>
<blockquote><hr noshade size="1"><b>AlphaComposite Composition Rule</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="68602"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="68604"><!-- --></a>
<blockquote><hr noshade size="1"><b>Example</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="68606"><!-- --></a>
<p>CLEAR

</td><td><a name="68608"><!-- --></a>
<p>Clear

</td><td><a name="68610"><!-- --></a>
<p>

</td></tr>
<tr><td><a name="68612"><!-- --></a>
<p>DEST_IN

</td><td><a name="68614"><!-- --></a>
<p>Destination In

</td><td><a name="68616"><!-- --></a>
<p>

</td></tr>
<tr><td><a name="68618"><!-- --></a>
<p>DEST_OUT

</td><td><a name="68620"><!-- --></a>
<p>Destination Out

</td><td><a name="68622"><!-- --></a>
<p>

</td></tr>
<tr><td><a name="68624"><!-- --></a>
<p>DEST_OVER

</td><td><a name="68626"><!-- --></a>
<p>Destination Over

</td><td><a name="68628"><!-- --></a>
<p>

</td></tr>
<tr><td><a name="68630"><!-- --></a>
<p>SRC

</td><td><a name="68632"><!-- --></a>
<p>Source

</td><td><a name="68634"><!-- --></a>
<p>

</td></tr>
<tr><td><a name="68636"><!-- --></a>
<p>SRC_IN

</td><td><a name="68638"><!-- --></a>
<p>Source In

</td><td><a name="68640"><!-- --></a>
<p>

</td></tr>
<tr><td><a name="68642"><!-- --></a>
<p>SRC_OUT

</td><td><a name="68644"><!-- --></a>
<p>Source Out

</td><td><a name="68646"><!-- --></a>
<p>

</td></tr>
<tr><td><a name="68648"><!-- --></a>
<p>SRC_OVER

</td><td><a name="68650"><!-- --></a>
<p>Source Over

</td><td><a name="68652"><!-- --></a>
<p>

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>
<br>
<a name="68654"><!-- --></a>
<h4><i>2.2.7.1	 Managing Transparency
</i></h4>

<blockquote>
<a name="69138"><!-- --></a>
A color&#39;s <em>alpha</em> value is a measure of its transparency: it indicates, as a percentage, how much of a previously rendered color should show through when colors overlap. Opaque colors (<kbd>alpha=1.0</kbd>) don&#39;t allow any of the underlying color to show through, while transparent colors (<kbd>alpha=0.0</kbd>) let all of it show through.<p>
<a name="69162"><!-- --></a>
When text and <kbd>Shapes</kbd> are rendered, the alpha<em> </em>value<em> </em>is derived from the <kbd>Paint </kbd>attribute in the <kbd>Graphics2D</kbd> context. When <kbd>Shapes</kbd> and text are antialiased, the alpha value from the <kbd>Paint</kbd> in the <kbd>Graphics2D</kbd> context is combined with pixel coverage information from the rasterized path. Images maintain their own alpha information&#45;&#45;see <a href="j2d-awt.fm2.html#64995">&#34;Transparency and Images&#34; on page&#160;26</a> for more information.<p>
<a name="64994"><!-- --></a>
When you construct an <kbd>AlphaComposite </kbd>object, you can specify an additional alpha value. When you add this <kbd>AlphaComposite</kbd> object to the <kbd>Graphics2D</kbd> context, this extra alpha value increases the transparency of any graphic objects that are rendered&#45;&#45;the alpha value of each graphic object is multiplied by the <kbd>AlphaComposite</kbd>&#39;s alpha value. <p>
</blockquote>
<br>
<a name="64995"><!-- --></a>
<h4><i>2.2.7.2	 Transparency and Images
</i></h4>

<blockquote>
<a name="62010"><!-- --></a>
Images can carry transparency information for each pixel in the image. This information, called an <em>alpha channel</em>, is used in conjunction with the <kbd>Composite</kbd> object in the <kbd>Graphics2D</kbd> context to blend the image with existing drawings. <p>
<a name="62014"><!-- --></a>
For example, <a href="j2d-awt.fm2.html#62022">Figure&#160;2-6</a> contains three images with different transparency information. In each case, the image is displayed over a blue rectangle. This example assumes that the <kbd>Graphics2D</kbd> context contains an <kbd>AlphaComposite</kbd> object that uses SRC_OVER as the compositing operation.<p>
<a name="62020"><!-- --></a>
<p><center><img src="j2d-awt.fm.anc3.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="62022"><!-- --></a>
<b>Figure 2-6	</b> Transparency and Images

</p>
</blockquote><blockquote>
<a name="62023"><!-- --></a>
In the first image, all of the pixels are either fully opaque (the dog&#39;s body) or fully transparent (the background). This effect is often used on Web pages. In the second image, all of the pixels in the dog&#39;s body are rendered using a uniform, non-opaque alpha value, allowing the blue background to show through. In the third image, the pixels around the dogs face are fully opaque (alpha=1.0), but as the distance from its face increases, the alpha values for the pixels decrease.<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm1.html">PREV</a>
 | <a href="j2d-awt.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:11 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm2.html">PREV</a>
 | <a href="j2d-awt.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="68374"><i>2.3	</i> Setting Up the Graphics2D Context
</a></h2>

<blockquote>
<a name="70032"><!-- --></a>
To configure the <kbd>Graphics2D</kbd> context for rendering, you use the <kbd>Graphics2D</kbd> set methods to specify attributes such as the <kbd>RenderingHints</kbd>, <kbd>Stroke</kbd>, <kbd>Paint</kbd>, clipping path, <kbd>Composite</kbd>, and <kbd>Transform</kbd>.<p>
</blockquote>
<br>
<h3>
<a name="65412"><!-- --></a>
<i>2.3.1	</i> Setting Rendering Hints
</h3>

<blockquote>
<a name="70103"><!-- --></a>
A <kbd>RenderingHints</kbd> object encapsulates all of your preferences concerning how an object is rendered. To set the rendering hints in the <kbd>Graphics2D</kbd> context, you create a <kbd>RenderingHints</kbd> object and pass it into <kbd>Graphics2D.setRenderingHints</kbd>.<p>
<a name="70042"><!-- --></a>
Setting a rendering hint does not guarantee that a particular rendering algorithm will be used: not all platforms support modification of the rendering mode.<p>
<a name="70057"><!-- --></a>
In the following example, antialiasing is enabled and the rendering preference is set to quality:<p>
</blockquote><pre><blockquote>qualityHints = new
               RenderingHints(RenderingHints.KEY_ANTIALIASING,
               RenderingHints.VALUE_ANTIALIAS_ON);
</blockquote></pre><pre><blockquote>qualityHints.put(RenderingHints.KEY_RENDERING,
               RenderingHints.VALUE_RENDER_QUALITY);
</blockquote></pre><pre><blockquote>g2.setRenderingHints(qualityHints);
</blockquote></pre>
<br>
<h3>
<a name="70111"><!-- --></a>
<i>2.3.2	</i> Specifying Stroke Attributes
</h3>

<blockquote>
<a name="70112"><!-- --></a>
A <kbd>BasicStroke</kbd> defines the characteristics applied to a <kbd>Shape</kbd>&#39;s outline, including its width and dashing pattern, how line segments are joined together, and the decoration (if any) applied to the end of a line. To set the stroke attributes in the <kbd>Graphics2D</kbd> context, you create a <kbd>BasicStroke</kbd> object and pass it into <kbd>setStroke</kbd>.<p>
</blockquote>
<br>
<a name="70121"><!-- --></a>
<h4><i>2.3.2.1	 Setting the Stroke Width
</i></h4>

<blockquote>
<a name="70123"><!-- --></a>
To set the stroke width, you create a <kbd>BasicStroke</kbd> object with the desired width and call <kbd>setStroke</kbd>. <p>
<a name="70136"><!-- --></a>
In the following example, the stroke width is set to twelve points and the defaults are used for the join and endcap decorations:<p>
</blockquote><pre><blockquote>wideStroke = new BasicStroke(12.0f);
g2.setStroke(wideStroke);
</blockquote></pre>
<br>
<a name="70122"><!-- --></a>
<h4><i>2.3.2.2	 Specifying Join and Endcap Styles
</i></h4>

<blockquote>
<a name="70193"><!-- --></a>
To set the join and endcap styles, you create a <kbd>BasicStroke</kbd> object with the desired attributes.<p>
<a name="70194"><!-- --></a>
In the following example, the stroke width is set to twelve points and the round join and endcap styles are used instead of the defaults:<p>
</blockquote><blockquote><pre>
roundStroke = new BasicStroke(4.0f, BasicStroke.CAP_ROUND,
              BasicStroke.JOIN_ROUND);
g2.setStroke(roundStroke);
</pre></blockquote>
<br>
<a name="68450"><!-- --></a>
<h4><i>2.3.2.3	 Setting the Dashing Pattern
</i></h4>

<blockquote>
<a name="64466"><!-- --></a>
Complex dashing patterns can easily be defined with a <kbd>BasicStroke</kbd> object. When you create a <kbd>BasicStroke</kbd> object, you can specify two parameters that control the dashing pattern:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="64469"><!-- --></a>
<kbd>dash</kbd>&#45;&#45;an array that represents the dashing pattern. Alternating elements in the array represent the dash size and the size of the space between dashes. Element 0 represents the first dash, element 1 represents the first space.
</li>
<li>
<a name="66367"><!-- --></a>
<kbd>dash_phase</kbd>&#45;&#45;an offset that defines where the dashing pattern starts.
</li>
</ul>
</blockquote>
<blockquote>
<a name="69382"><!-- --></a>
In the following example, two different dashing patterns are applied to a line. In the first, the size of the dashes and the space between them is constant. The second dashing pattern is more complex, using a six-element array to define the dashing pattern.<p>
</blockquote><pre><blockquote>
float dash1[] = {10.0f};
BasicStroke bs = new BasicStroke(5.0f, BasicStroke.CAP_BUTT, 
                 BasicStroke.JOIN_MITER, 10.0f, dash1, 0.0f);
g2.setStroke(bs);
Line2D line = new Line2D.Float(20.0f, 10.0f, 100.0f, 10.0f);
g2.draw(line);

float[] dash2 = {6.0f, 4.0f, 2.0f, 4.0f, 2.0f, 4.0f};
bs = new BasicStroke(5.0f, BasicStroke.CAP_BUTT, 
     BasicStroke.JOIN_MITER, 10.0f, dash2, 0.0f);
g2.setStroke(bs);
g2.draw(line);
</blockquote></pre><blockquote>
<a name="69394"><!-- --></a>
Both dashing patterns use a dash phase of zero, causing the dashes to be drawn starting at the beginning of the dashing pattern. The two dashing patterns are shown in Figure <a href="j2d-awt.fm3.html#69457">Figure&#160;2-7</a>.<p><center><img src="j2d-awt.fm.anc10.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="69457"><!-- --></a>
<b>Figure 2-7	</b> Dashing Patterns

</p>
</blockquote>
<br>
<h3>
<a name="68782"><!-- --></a>
<i>2.3.3	</i> Specifying Fill Attributes
</h3>

<blockquote>
<a name="69419"><!-- --></a>
The <kbd>Paint</kbd> attribute in the <kbd>Graphics2D</kbd> context determines the fill color or pattern that is used when text and <kbd>Shapes</kbd> are rendered.<p>
</blockquote>
<br>
<a name="68783"><!-- --></a>
<h4><i>2.3.3.1	 Filling a Shape with a Gradient
</i></h4>

<blockquote>
<a name="68784"><!-- --></a>
The <kbd>GradientPaint</kbd> class provides an easy way to fill a shape with a gradient of one color to another. When you create a <kbd>GradientPaint</kbd>, you specify a beginning position and color, and an ending position and color. The fill color changes proportionally from one color to the other along the line connecting the two positions, as shown in <a href="j2d-awt.fm3.html#68790">Figure&#160;2-8</a>. <p>
<a name="68788"><!-- --></a>
<p><center><img src="j2d-awt.fm.ancA9.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="68790"><!-- --></a>
<b>Figure 2-8	</b> Creating Gradient Fills

</p>
</blockquote><blockquote>
<a name="68794"><!-- --></a>
In the third star in <a href="j2d-awt.fm3.html#68790">Figure&#160;2-8</a>, both points lie within the shape. All of the points along the gradient line extending beyond P1 take the beginning color, and the points along the gradient line extending beyond P2 take the ending color. <p>
<a name="68795"><!-- --></a>
To fill a shape with a gradient of one color to another:<p>
</blockquote><blockquote><ol>
<li>
<a name="68796"><!-- --></a>
Create a <kbd>GradientPaint</kbd> object.
</li>

<li>
<a name="68797"><!-- --></a>
Call <kbd>Graphics2D.setPaint.</kbd>
</li>

<li>
<a name="68798"><!-- --></a>
Create the <kbd>Shape</kbd>.
</li>

<li>
<a name="68799"><!-- --></a>
Call <kbd>Graphics2D.fill(shape)</kbd>.
</li>

</ol></blockquote>
<blockquote>
<a name="68800"><!-- --></a>
In the following example, a rectangle is filled with a blue-green gradient.<p>
</blockquote><blockquote><pre>
GradientPaint gp = new GradientPaint(50.0f, 50.0f, Color.blue
                   50.0f, 250.0f, Color.green);
g2.setPaint(gp);
g2.fillRect(50, 50, 200, 200);
</pre></blockquote>
<br>
<a name="68805"><!-- --></a>
<h4><i>2.3.3.2	 Filling a Shape with a Texture
</i></h4>

<blockquote>
<a name="68806"><!-- --></a>
The <kbd>TexturePaint</kbd> class provides an easy way to fill a shape with a repeating pattern. When you create a <kbd>TexturePaint</kbd>, you specify a <kbd>BufferedImage</kbd> to use as the pattern. You also pass the constructor a rectangle to define the repetition frequency of the pattern, as shown in <a href="j2d-awt.fm3.html#68811">Figure&#160;2-9</a>.<p>
<a name="68810"><!-- --></a>
<p><center><img src="j2d-awt.fm.anc11.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="68811"><!-- --></a>
<b>Figure 2-9	</b> Creating Texture Paints

</p>
</blockquote><blockquote>
<a name="68812"><!-- --></a>
To fill a shape with a texture:<p>
</blockquote><blockquote><ol>
<li>
<a name="68813"><!-- --></a>
Create a <kbd>TexturePaint</kbd> object.
</li>

<li>
<a name="68814"><!-- --></a>
Call <kbd>Graphics2D.setPaint.</kbd>
</li>

<li>
<a name="68815"><!-- --></a>
Create the <kbd>Shape</kbd>.
</li>

<li>
<a name="68816"><!-- --></a>
Call <kbd>Graphics2D.fill(shape)</kbd>.
</li>

</ol></blockquote>
<blockquote>
<a name="68817"><!-- --></a>
In the following example, a rectangle is filled with a simple texture created from a buffered image.<p>
</blockquote><blockquote><pre>
// Create a buffered image texture patch of size 5x5
BufferedImage bi = new BufferedImage(5, 5,   
                       BufferedImage.TYPE_INT_RGB);
Graphics2D big = bi.createGraphics();
// Render into the BufferedImage graphics to create the texture
big.setColor(Color.green);
big.fillRect(0,0,5,5);
big.setColor(Color.lightGray);
big.fillOval(0,0,5,5);

// Create a texture paint from the buffered image
Rectangle r = new Rectangle(0,0,5,5);
TexturePaint tp = new 
TexturePaint(bi,r,TexturePaint.NEAREST_NEIGHBOR);

// Add the texture paint to the graphics context.
g2.setPaint(tp);

// Create and render a rectangle filled with the texture.
g2.fillRect(0,0,200,200);
}
</pre></blockquote>
<br>
<h3>
<a name="70241"><!-- --></a>
<i>2.3.4	</i> Setting the Clipping Path
</h3>

<blockquote>
<a name="70242"><!-- --></a>
To define a clipping path:<p>
</blockquote><blockquote><ol>
<li>
<a name="70243"><!-- --></a>
Create a <kbd>Shape</kbd> that represents the area you want to render.
</li>

<li>
<a name="70244"><!-- --></a>
Call <kbd>Graphics2D.setClip</kbd> to use the shape as the clipping path for the <kbd>Graphics2D</kbd> context.
</li>

</ol></blockquote>
<blockquote>
<a name="70245"><!-- --></a>
To shrink the clipping path:<p>
</blockquote><blockquote><ol>
<li>
<a name="70246"><!-- --></a>
Create a <kbd>Shape</kbd> that intersects the current clipping path.
</li>

<li>
<a name="70247"><!-- --></a>
Call <kbd>clip</kbd> to change the clipping path to the intersection of the current clipping path and the new <kbd>Shape</kbd>.
</li>

</ol></blockquote>
<blockquote>
<a name="70248"><!-- --></a>
In the following example, a clipping path is created from an ellipse and then modified by calling <kbd>clip</kbd>.<p>
</blockquote><blockquote><pre>
public void paint(Graphics g) {
  Graphics2D g2 = (Graphics2D) g;

// The width and height of the canvas
  int w = getSize().width;
  int h = getSize().height;
  // Create an ellipse and use it as the clipping path
  Ellipse2D e = new Ellipse2D.Float(w/4.0f,h/4.0f,
                                    w/2.0f,h/2.0f);
  g2.setClip(e);

  // Fill the canvas. Only the area within the clip is rendered
  g2.setColor(Color.cyan);
  g2.fillRect(0,0,w,h);

  // Change the clipping path, setting it to the intersection of 
  // the current clip and a new rectangle.
  Rectangle r = new Rectangle(w/4+10,h/4+10,w/2-20,h/2-20);
  g2.clip(r);

  // Fill the canvas. Only the area within the new clip 
  // is rendered
  g2.setColor(Color.magenta);
  g2.fillRect(0,0,w,h);
}
</pre></blockquote>
<br>
<h3>
<a name="68134"><!-- --></a>
<i>2.3.5	</i> Setting the Graphics2D Transform
</h3>

<blockquote>
<a name="68135"><!-- --></a>
To transform a <kbd>Shape,</kbd> text string, or <kbd>Image</kbd> you add a new <kbd>AffineTransform</kbd> to the transformation pipeline in the <kbd>Graphics2D</kbd> context before rendering. The transformation is applied when the graphic object is rendered.<p>
<a name="68136"><!-- --></a>
For example, to draw a rectangle that is rotated 45 degrees:<p>
</blockquote><blockquote><ol>
<li>
<a name="68137"><!-- --></a>
Get a rotation transform by calling <kbd>AffineTransform. getRotateInstance</kbd>. 
</li>

<li>
<a name="68138"><!-- --></a>
Call <kbd>Graphics2D.setTransform</kbd> to add the new transform to the transformation pipeline.
</li>

<li>
<a name="68139"><!-- --></a>
Create a <kbd>Rectangle2D.Float</kbd> object.
</li>

<li>
<a name="68140"><!-- --></a>
Call<kbd> Graphics2D.draw</kbd> to render the rectangle. 
</li>

</ol></blockquote>
<blockquote>
<a name="69431"><!-- --></a>
In the following example, an instance of <kbd>AffineTransform</kbd> is used to rotate a rectangle 45 degrees when it is rendered.<p>
</blockquote><blockquote><pre>
Rectangle2D rect = new Rectangle2D.Float(1.0,1.0,2.0,3.0);
AffineTransform rotate45 =   
  AffineTransform.getRotateInstance(Math.PI/4.0,0.0,0.0)
g2.setTransform(rotate45);
g2.draw(rect);
</pre></blockquote>
<a name="69496"><!-- --></a>
In this example, an <kbd>AffineTransform</kbd> is used to rotate a text string around a center point:<p>
</blockquote><blockquote><pre>
// Define the rendering transform
AffineTransform at = new AffineTransform();
// Apply a translation transform to make room for the
// rotated text.
at.setToTranslation(400.0, 400.0);
g2.transform(at);
// Create a rotation transform to rotate the text
at.setToRotation(Math.PI / 2.0);
// Render four copies of the string &#34;Java&#34; at 90 degree angles
for (int i = 0; i &lt; 4; i++) {
    g2.drawString(&#34;Java&#34;, 0.0f, 0.0f);
    g2.transform(at);
}
</pre></blockquote><blockquote>
<a name="69494"><!-- --></a>
You can transform an image in the same way&#45;&#45;the transform in the <kbd>Graphics2D </kbd>context<kbd> </kbd>is applied during rendering regardless of the type of graphic object being rendered. <p>
<a name="69540"><!-- --></a>
To apply a transform to an image <em>without</em> changing the transform in the <kbd>Graphics2D</kbd> context, you can pass an <kbd>AffineTransform</kbd> to <kbd>drawImage</kbd>:<p>
</blockquote><blockquote><pre>AffineTransform rotate45 =   
  AffineTransform.getRotateInstance(Math.PI/4.0,0.0,0.0)
g2.drawImage(myImage, rotate45);
</blockquote></pre><blockquote>
<a name="69464"><!-- --></a>
Transforms can also be applied to a <kbd>Font </kbd>to create a modified version of the<kbd> Font</kbd>, for more information see <a href="j2d-fonts.fm6.html#74065">&#34;Creating Font Derivations&#34; on page&#160;65</a>.<p>
</blockquote>
<br>
<h3>
<a name="68155"><!-- --></a>
<i>2.3.6	</i> Specifying a Composition Style
</h3>

<blockquote>
<a name="64024"><!-- --></a>
An <kbd>AlphaComposite</kbd> encapsulates composition rules that determine how colors should be rendered when one object overlaps another. To specify the composition style for the <kbd>Graphics2D</kbd> context, you create an <kbd>AlphaComposite</kbd> and pass it into <kbd>setComposite</kbd>. The most commonly used is composition style is <kbd>SRC_OVER</kbd>.<p>
</blockquote>
<br>
<a name="62986"><!-- --></a>
<h4><i>2.3.6.1	 Using the Source Over Compositing Rule
</i></h4>

<blockquote>
<a name="64129"><!-- --></a>
The <kbd>SRC_OVER</kbd> compositing rule composites the source pixel over the destination pixel such that the shared pixel takes the color of the source pixel. For example, if you render a blue rectangle and then render a red rectangle that partially overlaps it, the overlapping area will be red. In other words, the object that is rendered last will appear to be on top.<p>
<a name="64147"><!-- --></a>
To use the <kbd>SRC_OVER</kbd> composition rule:<p>
</blockquote><blockquote><ol>
<li>
<a name="64148"><!-- --></a>
Create an <kbd>AlphaComposite</kbd> object by calling <kbd>getInstance</kbd> and specifying the <kbd>SRC_OVER</kbd> rule.
</li>

</ol></blockquote>
<pre><blockquote>AlphaComposite ac = 
AlphaComposite.getInstance(AlphaComposite.SRC_OVER);
</blockquote></pre><blockquote><ol>
<li>
<a name="64163"><!-- --></a>
Call <kbd>setComposite</kbd> to add the <kbd>AlphaComposite</kbd> object to the <kbd>Graphics2D</kbd> context.
</li>

</ol></blockquote>
<pre><blockquote>g2.setComposite(ac);
</blockquote></pre><blockquote>
<a name="64153"><!-- --></a>
Once the composite object is set, overlapping objects will be rendered using the specified composition rule.<p>
</blockquote>
<br>
<a name="64058"><!-- --></a>
<h4><i>2.3.6.2	 Increasing the Transparency of Composited Objects
</i></h4>

<blockquote>
<a name="64061"><!-- --></a>
<kbd>AlphaComposite</kbd> allows you to specify an additional constant alpha value that is multiplied with the alpha of the source pixels to increase transparency. <p>
<a name="64070"><!-- --></a>
For example, to create an <kbd>AlphaComposite</kbd> object that renders the source object 50% transparent, specify an alpha of .5:<p>
</blockquote><pre><blockquote>AlphaComposite ac = 
AlphaComposite.getInstance(AlphaComposite.SRC_OVER, .5f);
</blockquote></pre><blockquote>
<a name="67498"><!-- --></a>
In the following example, a source over alpha composite object is created with an alpha of .5 and added to the graphics context, causing subsequent shapes to be rendered 50% transparent. <p>
</blockquote><blockquote><pre>
public void paint(Graphics g) {
  Graphics2D g2 = (Graphics2D) g;

  g2.setColor(Color.red);
  g2.translate(100,50);
  // radians=degree * pie / 180
  g2.rotate((45*java.lang.Math.PI)/180); 
  g2.fillRect(0,0,100,100);
  g2.setTransform(new AffineTransform());  // set to identity
  // Create a new alpha composite
  AlphaComposite ac =
      AlphaComposite.getInstance(AlphaComposite.SRC_OVER,0.5f);
  g2.setComposite(ac);
  g2.setColor(Color.green);
  g2.fillRect(50,0,100,100);
  g2.setColor(Color.blue);
  g2.fillRect(125,75,100,100);
  g2.setColor(Color.yellow);
  g2.fillRect(50,125,100,100);
  g2.setColor(Color.pink);
  g2.fillRect(-25,75,100,100);
}
</pre></blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm2.html">PREV</a>
 | <a href="j2d-awt.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:11 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm3.html">PREV</a>
 | <a href="j2d-awt.fm5.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="68381"><i>2.4	</i> Rendering Graphics Primitives
</a></h2>

<blockquote>
<a name="68382"><!-- --></a>
<kbd>Graphics2D</kbd> provides rendering methods for <kbd>Shapes</kbd>, <kbd>Text</kbd>, and <kbd>Images</kbd>:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="68383"><!-- --></a>
<kbd>draw</kbd>&#45;&#45;strokes a <kbd>Shape</kbd>&#39;s path using the <kbd>Stroke</kbd> and <kbd>Paint</kbd> objects in the <kbd>Graphics2D</kbd> context.
</li>
<li>
<a name="68384"><!-- --></a>
<kbd>fill</kbd>&#45;&#45;fills a <kbd>Shape</kbd> using the <kbd>Paint</kbd> in the <kbd>Graphics2D</kbd> context.
</li>
<li>
<a name="68385"><!-- --></a>
<kbd>drawString</kbd>&#45;&#45;renders the specified text string using the <kbd>Paint</kbd> in the <kbd>Graphics2D</kbd> context.
</li>
<li>
<a name="68386"><!-- --></a>
<kbd>drawImage</kbd>&#45;&#45;renders the specified image.
</li>
</ul>
</blockquote>
<blockquote>
<a name="68387"><!-- --></a>
To stroke and fill a shape, you must call both the <kbd>draw</kbd> and <kbd>fill</kbd> methods.<kbd></kbd><p>
<a name="68388"><!-- --></a>
<kbd>Graphics2D</kbd> also supports the draw and fill methods from previous versions of the JDK software, such as <kbd>drawOval</kbd> and <kbd>fillRect</kbd>.<p>
</blockquote>
<br>
<h3>
<a name="68389"><!-- --></a>
<i>2.4.1	</i> Drawing a Shape
</h3>

<blockquote>
<a name="68390"><!-- --></a>
The outline of any <kbd>Shape</kbd> can be rendered with the <kbd>Graphics2D.draw</kbd> method. The draw methods from previous versions of the JDK software are also supported: <kbd>drawLine</kbd>, <kbd>drawRect</kbd>, <kbd>drawRoundRect</kbd>, <kbd>drawOval</kbd>, <kbd>drawArc</kbd>, <kbd>drawPolyline</kbd>, <kbd>drawPolygon</kbd>, <kbd>draw3DRect</kbd>.<p>
<a name="68391"><!-- --></a>
When a <kbd>Shape</kbd> is drawn, its path is stroked with the <kbd>Stroke</kbd> object in the <kbd>Graphics2D</kbd> context. (See <a href="j2d-awt.fm2.html#61854">&#34;Stroke Attributes&#34; on page&#160;19</a> for more information.) By setting an appropriate <kbd>BasicStroke</kbd> object in the <kbd>Graphics2D</kbd> context, you can draw lines of any width or pattern. The <kbd>BasicStroke</kbd> object also defines the line&#39;s endcap and join attributes.<p>
<a name="68395"><!-- --></a>
To render shape&#39;s outline:<p>
</blockquote><blockquote><ol>
<li>
<a name="68396"><!-- --></a>
Create a <kbd>BasicStroke</kbd> object
</li>

<li>
<a name="68397"><!-- --></a>
Call <kbd>Graphics2D.setStroke</kbd>
</li>

<li>
<a name="68398"><!-- --></a>
Create the <kbd>Shape</kbd>.
</li>

<li>
<a name="68399"><!-- --></a>
Call <kbd>Graphics2D.draw(shape)</kbd>.
</li>

</ol></blockquote>
<blockquote>
<a name="68400"><!-- --></a>
In the following example, a <kbd>GeneralPath</kbd> object is used to define a star and a <kbd>BasicStroke</kbd> object is added to the <kbd>Graphics2D</kbd> context to define the star&#39;s line with and join attributes.<p>
</blockquote><blockquote><pre>
public void paint(Graphics g) {
  Graphics2D g2 = (Graphics2D) g;

  // create and set the stroke
  g2.setStroke(new BasicStroke(4.0f));

  // Create a star using a general path object
  GeneralPath p = new GeneralPath(GeneralPath.NON_ZERO);
  p.moveTo(- 100.0f, - 25.0f);
  p.lineTo(+ 100.0f, - 25.0f);
  p.lineTo(- 50.0f, + 100.0f);
  p.lineTo(+ 0.0f, - 100.0f);
  p.lineTo(+ 50.0f, + 100.0f);
  p.closePath();

  // translate origin towards center of canvas
  g2.translate(100.0f, 100.0f);

  // render the star's path
  g2.draw(p);
}
</pre></blockquote>
<br>
<h3>
<a name="68422"><!-- --></a>
<i>2.4.2	</i> Filling a Shape
</h3>

<blockquote>
<a name="68423"><!-- --></a>
The<kbd> Graphics2D.fill</kbd> method can be used to <em>fill</em> any <kbd>Shape</kbd>. When a <kbd>Shape</kbd> is filled, the area within its path is rendered with the <kbd>Graphics2D</kbd> context&#39;s current <kbd>Paint</kbd> attribute&#45;&#45;a <kbd>Color</kbd>, <kbd>TexturePaint</kbd>, or <kbd>GradientPaint</kbd>. <p>
<a name="68424"><!-- --></a>
The fill methods from previous versions of the JDK software are also supported: <kbd>fillRect</kbd>, <kbd>fill3DRect</kbd>, <kbd>fillRoundRect</kbd>, <kbd>fillOval</kbd>, <kbd>fillArc</kbd>, <kbd>fillPolygon</kbd>, <kbd>clearRect</kbd>.<p>
<a name="68425"><!-- --></a>
To fill a <kbd>Shape</kbd>:<p>
</blockquote><blockquote><ol>
<li>
<a name="68426"><!-- --></a>
Set the fill color or pattern on the graphics context using <br> <kbd>Graphics2D.setColor </kbd>or <kbd>Graphics2D.setPaint.</kbd>
</li>

<li>
<a name="68427"><!-- --></a>
Create the <kbd>Shape</kbd>.
</li>

<li>
<a name="68428"><!-- --></a>
Call <kbd>Graphics2D.fill</kbd> to render the <kbd>Shape</kbd>.
</li>

</ol></blockquote>
<blockquote>
<a name="68429"><!-- --></a>
In the following example, <kbd>setColor</kbd> is called to define a green fill for a <kbd>Rectangle2D</kbd>.<p>
</blockquote><blockquote><pre>
public void paint(Graphics g) {
  Graphics2D g2 = (Graphics2D) g;

  g2.setPaint(Color.green);
  Rectangle2D r2 = new Rectangle2D.Float(25,25,150,150);

  g2.fill(r2);
}
</pre></blockquote>
<br>
<h3>
<a name="68438"><!-- --></a>
<i>2.4.3	</i> Rendering Text
</h3>

<blockquote>
<a name="68439"><!-- --></a>
To render a text string, you call <kbd>Graphics2D.drawString</kbd>, passing in the string that you want to render. For more information about rendering text and selecting fonts, see <a href="j2d-fonts.fm.html#73059">&#34;Fonts and Text Layout&#34; on page&#160;45</a>.<p>
</blockquote>
<br>
<h3>
<a name="68443"><!-- --></a>
<i>2.4.4	</i> Rendering Images
</h3>

<blockquote>
<a name="68444"><!-- --></a>
To render an <kbd>Image</kbd>, you create the <kbd>Image</kbd> and call<kbd> Graphics2D.drawImage</kbd>. For more information about processing and rendering images, see <a href="j2d-image.fm.html#65661">&#34;Imaging&#34; on page&#160;67</a>.<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm3.html">PREV</a>
 | <a href="j2d-awt.fm5.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:11 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm4.html">PREV</a>
 | <a href="j2d-geom.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="67029"><i>2.5	</i> Defining Custom Composition Rules
</a></h2>

<blockquote>
<a name="62000"><!-- --></a>
You can create an entirely new type of compositing operation by implementing the <kbd>Composite</kbd> and <kbd>CompositeContext</kbd> interfaces. A <kbd>Composite</kbd> object provides a <kbd>CompositeContext</kbd> object that actually holds the state and performs the compositing work. Multiple <kbd>CompositeContext</kbd> objects can be created from one <kbd>Composite</kbd> object to maintain the separate states in a multithreaded environment. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm4.html">PREV</a>
 | <a href="j2d-geom.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:11 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm5.html">PREV</a>
 | <a href="j2d-awt.fm7.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="63773"><i>2.6	</i> Filling a Shape with a Texture
</a></h2>

<blockquote>
<a name="63890"><!-- --></a>
The <kbd>TexturePaint</kbd> class provides an easy way to fill a shape with a repeating pattern. When you create a <kbd>TexturePaint</kbd>, you specify a <kbd>BufferedImage</kbd> to use as the pattern. You also pass the constructor a rectangle to define the repetition frequency of the pattern. For example:<p>
<a name="63926"><!-- --></a>
<p><center><img src="j2d-awt.fm.anc8.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="63790"><!-- --></a>
<b>Figure 2-7	</b> Creating Texture Paints

</p>
</blockquote><blockquote>
<a name="63927"><!-- --></a>
To fill a shape with a texture:<p>
</blockquote><blockquote><ol>
<li>
<a name="63777"><!-- --></a>
Create a <kbd>TexturePaint</kbd> object.
</li>

<li>
<a name="63778"><!-- --></a>
Call <kbd>Graphics2D.setPaint.</kbd>
</li>

<li>
<a name="67238"><!-- --></a>
Create the <kbd>Shape</kbd>.
</li>

<li>
<a name="63779"><!-- --></a>
Call <kbd>Graphics2D.fill(shape)</kbd>.
</li>

</ol></blockquote>
<blockquote>
<a name="66489"><!-- --></a>
In the following example, a rectangle is filled with a simple texture created from a buffered image:<p>
</blockquote><pre><blockquote>// Create a buffered image texture patch of size 5x5
</blockquote></pre><pre><blockquote>BufferedImage bi = new BufferedImage(5, 5,   
</blockquote></pre><pre><blockquote>                       BufferedImage.TYPE_INT_RGB);
</blockquote></pre><pre><blockquote>Graphics2D big = bi.createGraphics();
</blockquote></pre><pre><blockquote>// Render into the BufferedImage graphics to create the texture
</blockquote></pre><pre><blockquote>big.setColor(Color.green);
</blockquote></pre><pre><blockquote>big.fillRect(0,0,5,5);
</blockquote></pre><pre><blockquote>big.setColor(Color.lightGray);
</blockquote></pre><pre><blockquote>big.fillOval(0,0,5,5);
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>// Create a texture paint from the buffered image
</blockquote></pre><pre><blockquote>Rectangle r = new Rectangle(0,0,5,5);
</blockquote></pre><pre><blockquote>TexturePaint tp = new 
TexturePaint(bi,r,TexturePaint.NEAREST_NEIGHBOR);
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>// Add the texture paint to the graphics context.
</blockquote></pre><pre><blockquote>g2.setPaint(tp);
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>// Create and render a rectangle filled with the texture.
</blockquote></pre><pre><blockquote>g2.fillRect(0,0,200,200);
</blockquote></pre><pre><blockquote>}
</blockquote></pre>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm5.html">PREV</a>
 | <a href="j2d-awt.fm7.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Tue Feb 24 10:24:05 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm6.html">PREV</a>
 | <a href="j2d-awt.fm8.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="66518"><i>2.7	</i> Setting the Clipping Path
</a></h2>

<blockquote>
<a name="64411"><!-- --></a>
To define a clipping path:<p>
</blockquote><blockquote><ol>
<li>
<a name="64412"><!-- --></a>
Create a <kbd>Shape</kbd> that represents the area you want to render.
</li>

<li>
<a name="64413"><!-- --></a>
Call <kbd>Graphics2D.setClip</kbd> to use the shape as the clipping path for the <kbd>Graphics2D</kbd> context.
</li>

</ol></blockquote>
<blockquote>
<a name="64414"><!-- --></a>
To shrink the clipping path:<p>
</blockquote><blockquote><ol>
<li>
<a name="64415"><!-- --></a>
Create a <kbd>Shape</kbd> that intersects the current clipping path.
</li>

<li>
<a name="64416"><!-- --></a>
Call <kbd>clip</kbd> to change the clipping path to the intersection of the current clipping path and the new <kbd>Shape</kbd>.
</li>

</ol></blockquote>
<blockquote>
<a name="66632"><!-- --></a>
In the following example, a clipping path is created from an ellipse and then modified by calling <kbd>clip</kbd>.<p>
</blockquote><pre><blockquote>public void paint(Graphics g) {
</blockquote></pre><pre><blockquote>  Graphics2D g2 = (Graphics2D) g;
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>// The width and height of the canvas
</blockquote></pre><pre><blockquote>  int w = getSize().width;
</blockquote></pre><pre><blockquote>  int h = getSize().height;
</blockquote></pre><pre><blockquote>  // Create an ellipse and use it as the clipping path
</blockquote></pre><pre><blockquote>  Ellipse2D e = new Ellipse2D.Float(w/4.0f,h/4.0f,
</blockquote></pre><pre><blockquote>                                    w/2.0f,h/2.0f);
</blockquote></pre><pre><blockquote>  g2.setClip(e);
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>  // Fill the canvas. Only the area within the clip is rendered
</blockquote></pre><pre><blockquote>  g2.setColor(Color.cyan);
</blockquote></pre><pre><blockquote>  g2.fillRect(0,0,w,h);
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>  // Change the clipping path, setting it to the intersection of 
</blockquote></pre><pre><blockquote>  // the current clip and a new rectangle.
</blockquote></pre><pre><blockquote>  Rectangle r = new Rectangle(w/4+10,h/4+10,w/2-20,h/2-20);
</blockquote></pre><pre><blockquote>  g2.clip(r);
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>  // Fill the canvas. Only the area within the new clip 
</blockquote></pre><pre><blockquote>  // is rendered
</blockquote></pre><pre><blockquote>  g2.setColor(Color.magenta);
</blockquote></pre><pre><blockquote>  g2.fillRect(0,0,w,h);
</blockquote></pre><pre><blockquote>}
</blockquote></pre>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm6.html">PREV</a>
 | <a href="j2d-awt.fm8.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Tue Feb 24 10:24:05 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm7.html">PREV</a>
 | <a href="j2d-awt.fm9.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="61882"><i>2.8	</i> Compositing Images
</a></h2>

<blockquote>
<a name="64024"><!-- --></a>
A <kbd>Graphics2D</kbd> context includes a <kbd>Composite</kbd> object that encapsulates the composition style to use if objects overlap. <kbd>AlphaComposite</kbd> implements a number of common composition rules that support blending and transparency effects. The most commonly used is <kbd>SRC_OVER</kbd>.<p>
</blockquote>
<br>
<h3>
<a name="62986"><!-- --></a>
<i>2.8.1	</i> Using the Source Over Composition Rule
</h3>

<blockquote>
<a name="64129"><!-- --></a>
The <kbd>SRC_OVER</kbd> composition rule composites the source pixel over the destination pixel so that the shared pixel takes the color of the source pixel. For example, if you render a blue rectangle and then render a red rectangle that partially overlaps it, the overlapping area will be red. In other words, the object that is rendered last will appear to be on top.<p>
<a name="64147"><!-- --></a>
To use the SRC_OVER composition rule:<p>
</blockquote><blockquote><ol>
<li>
<a name="64148"><!-- --></a>
Create an <kbd>AlphaComposite</kbd> object by calling <kbd>getInstance</kbd> and specifying the <kbd>SRC_OVER</kbd> rule.
</li>

</ol></blockquote>
<pre><blockquote>AlphaComposite ac = 
AlphaComposite.getInstance(AlphaComposite.SRC_OVER);
</blockquote></pre><blockquote><ol>
<li>
<a name="64163"><!-- --></a>
Call <kbd>setComposite</kbd> to add the <kbd>AlphaComposite</kbd> object to the <kbd>Graphics2D</kbd> context.
</li>

</ol></blockquote>
<pre><blockquote>g2.setComposite(ac);
</blockquote></pre><blockquote>
<a name="64153"><!-- --></a>
Once the composite object is set, overlapping objects will be rendered using the specified composition rule.<p>
</blockquote>
<br>
<h3>
<a name="64058"><!-- --></a>
<i>2.8.2	</i> Increasing the Transparency of Composited Objects
</h3>

<blockquote>
<a name="64061"><!-- --></a>
<kbd>AlphaComposite</kbd> allows you to specify an additional constant alpha value that is multiplied with the alpha of the source pixels to increase transparency. <p>
<a name="64070"><!-- --></a>
For example, to create an <kbd>AlphaComposite</kbd> object that renders the source object 50% transparent, specify an alpha of .5:<p>
</blockquote><pre><blockquote>AlphaComposite ac = 
AlphaComposite.getInstance(AlphaComposite.SRC_OVER, .5f);
</blockquote></pre><blockquote>
<a name="67498"><!-- --></a>
In the following example, a source over alpha composite object is created with an alpha of .5 and added to the graphics context, causing subsequent shapes to be rendered 50% transparent. <p>
</blockquote><pre><blockquote>public void paint(Graphics g) {
</blockquote></pre><pre><blockquote>  Graphics2D g2 = (Graphics2D) g;
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>  g2.setColor(Color.red);
</blockquote></pre><pre><blockquote>  g2.translate(100,50);
</blockquote></pre><pre><blockquote>  // radians=degree * pie / 180
</blockquote></pre><pre><blockquote>  g2.rotate((45*java.lang.Math.PI)/180); 
</blockquote></pre><pre><blockquote>  g2.fillRect(0,0,100,100);
</blockquote></pre><pre><blockquote>  g2.setTransform(new AffineTransform());  // set to identity
</blockquote></pre><pre><blockquote>  // Create a new alpha composite
</blockquote></pre><pre><blockquote>  AlphaComposite ac =
</blockquote></pre><pre><blockquote>      AlphaComposite.getInstance(AlphaComposite.SRC_OVER,0.5f);
</blockquote></pre><pre><blockquote>  g2.setComposite(ac);
</blockquote></pre><pre><blockquote>  g2.setColor(Color.green);
</blockquote></pre><pre><blockquote>  g2.fillRect(50,0,100,100);
</blockquote></pre><pre><blockquote>  g2.setColor(Color.blue);
</blockquote></pre><pre><blockquote>  g2.fillRect(125,75,100,100);
</blockquote></pre><pre><blockquote>  g2.setColor(Color.yellow);
</blockquote></pre><pre><blockquote>  g2.fillRect(50,125,100,100);
</blockquote></pre><pre><blockquote>  g2.setColor(Color.pink);
</blockquote></pre><pre><blockquote>  g2.fillRect(-25,75,100,100);
</blockquote></pre><pre><blockquote>}
</blockquote></pre>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm7.html">PREV</a>
 | <a href="j2d-awt.fm9.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Tue Feb 24 10:24:05 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm8.html">PREV</a>
 | <a href="j2d-geom.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="67029"><i>2.9	</i> Defining Custom Composition Rules
</a></h2>

<blockquote>
<a name="62000"><!-- --></a>
You can create an entirely new type of compositing operation by implementing the <kbd>Composite</kbd> and <kbd>CompositeContext</kbd> interfaces. A <kbd>Composite</kbd> object provides a <kbd>CompositeContext</kbd> object that actually holds the state and performs the compositing work. Multiple <kbd>CompositeContext</kbd> objects can be created from one <kbd>Composite</kbd> object to maintain the separate states in a multi-threaded environment. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm8.html">PREV</a>
 | <a href="j2d-geom.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Tue Feb 24 10:24:05 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-title.fm.html">PREV</a>
 | <a href="j2d-preface.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 
<H2>
	
<a href="j2d-intro.fm.html#62980">Java<sup>TM</sup> 2D API Overview		</a>
</H2>

<dl>
<dt></dt>
<dd><br>
<a href="j2d-intro.fm1.html">
<b><font size="+2">
 
Enhanced Graphics, Text, and Imaging</font></b></a>

<dd><br>
<a href="j2d-intro.fm2.html">
<b><font size="+2">
 
Rendering Model</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-intro.fm2.html#61857">Coordinate Systems</a>
</b>

<dd>
<b> 
<a href="j2d-intro.fm2.html#61888">Transforms</a>
</b>

<dd>
<b> 
<a href="j2d-intro.fm2.html#61894">Fonts</a>
</b>

<dd>
<b> 
<a href="j2d-intro.fm2.html#61906">Images</a>
</b>

<dd>
<b> 
<a href="j2d-intro.fm2.html#61939">Fills and Strokes</a>
</b>

<dd>
<b> 
<a href="j2d-intro.fm2.html#63573">Composites</a>
</b>

</dl>
<dd><br>
<a href="j2d-intro.fm3.html">
<b><font size="+2">
 
	Backward Compatibility and Platform Independence</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-intro.fm3.html#63962">Backward Compatibility</a>
</b>

<dd>
<b> 
<a href="j2d-intro.fm3.html#63963">Platform Independence</a>
</b>

</dl>
<dd><br>
<a href="j2d-intro.fm4.html">
<b><font size="+2">
 
The Java 2D API Packages</font></b></a>

</dl>
<H2>
	
<a href="j2d-awt.fm.html#70028">Rendering with Graphics2D		</a>
</H2>

<dl>
<dt></dt>
<dd><br>
<a href="j2d-awt.fm1.html">
<b><font size="+2">
 
Interfaces and Classes</font></b></a>

<dd><br>
<a href="j2d-awt.fm2.html">
<b><font size="+2">
 
Rendering Concepts</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-awt.fm2.html#67506">Rendering Process</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm2.html#61856">Controlling Rendering Quality</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm2.html#61854">Stroke Attributes</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm2.html#70202">Fill Attributes</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm2.html#68462">Clipping Paths</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm2.html#68474">Transformations</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm2.html#64398">Composite Attributes</a>
</b>

</dl>
<dd><br>
<a href="j2d-awt.fm3.html">
<b><font size="+2">
 
Setting Up the Graphics2D Context</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-awt.fm3.html#65412">Setting Rendering Hints</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm3.html#70111">Specifying Stroke Attributes</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm3.html#68782">Specifying Fill Attributes</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm3.html#70241">Setting the Clipping Path</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm3.html#68134">Setting the Graphics2D Transform</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm3.html#68155">Specifying a Composition Style</a>
</b>

</dl>
<dd><br>
<a href="j2d-awt.fm4.html">
<b><font size="+2">
 
Rendering Graphics Primitives</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-awt.fm4.html#68389">Drawing a Shape</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm4.html#68422">Filling a Shape</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm4.html#68438">Rendering Text</a>
</b>

<dd>
<b> 
<a href="j2d-awt.fm4.html#68443">Rendering Images</a>
</b>

</dl>
<dd><br>
<a href="j2d-awt.fm5.html">
<b><font size="+2">
 
Defining Custom Composition Rules</font></b></a>

</dl>
<H2>
	
<a href="j2d-geom.fm.html#61756">Geometries		</a>
</H2>

<dl>
<dt></dt>
<dd><br>
<a href="j2d-geom.fm1.html">
<b><font size="+2">
 
Interfaces and Classes</font></b></a>

<dd><br>
<a href="j2d-geom.fm2.html">
<b><font size="+2">
 
Geometry Concepts</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-geom.fm2.html#63798">Constructive Area Geometry</a>
</b>

<dd>
<b> 
<a href="j2d-geom.fm2.html#63262">Bounds and Hit Testing</a>
</b>

</dl>
<dd><br>
<a href="j2d-geom.fm3.html">
<b><font size="+2">
 
Combining Areas to Create New Shapes</font></b></a>

<dd><br>
<a href="j2d-geom.fm4.html">
<b><font size="+2">
 
Creating a Custom Shape</font></b></a>

</dl>
<H2>
	
<a href="j2d-fonts.fm.html#73059">Fonts and Text Layout		</a>
</H2>

<dl>
<dt></dt>
<dd><br>
<a href="j2d-fonts.fm1.html">
<b><font size="+2">
 
Interfaces and Classes</font></b></a>

<dd><br>
<a href="j2d-fonts.fm2.html">
<b><font size="+2">
 
Font Concepts</font></b></a>

<dd><br>
<a href="j2d-fonts.fm3.html">
<b><font size="+2">
 
Text Layout Concepts</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-fonts.fm3.html#74588">Shaping Text</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm3.html#73474">Ordering Text</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm3.html#63651">Measuring and Positioning Text</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm3.html#68590">Supporting Text Manipulation</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm3.html#74467">Performing Text Layout in a Java Application</a>
</b>

</dl>
<dd><br>
<a href="j2d-fonts.fm4.html">
<b><font size="+2">
 
Managing Text Layout</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-fonts.fm4.html#67652">Laying Out Text</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm4.html#63814">Displaying Dual Carets</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm4.html#74427">Moving the Caret</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm4.html#68373">Hit Testing</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm4.html#68115">Highlighting Selections</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm4.html#63976">Querying Layout Metrics</a>
</b>

<dd>
<b> 
<a href="j2d-fonts.fm4.html#64005">Drawing Text Across Multiple Lines</a>
</b>

</dl>
<dd><br>
<a href="j2d-fonts.fm5.html">
<b><font size="+2">
 
Implementing a Custom Text Layout Mechanism</font></b></a>

<dd><br>
<a href="j2d-fonts.fm6.html">
<b><font size="+2">
 
Creating Font Derivations</font></b></a>

</dl>
<H2>
	
<a href="j2d-image.fm.html#65661">Imaging		</a>
</H2>

<dl>
<dt></dt>
<dd><br>
<a href="j2d-image.fm1.html">
<b><font size="+2">
 
Interfaces and Classes</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-image.fm1.html#69751">Imaging Interfaces</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm1.html#64405">Image Data Classes</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm1.html#68832">Image Operation Classes</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm1.html#64487">Sample Model Classes</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm1.html#64040">Color Model Classes</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm1.html#68512">Exception Classes</a>
</b>

</dl>
<dd><br>
<a href="j2d-image.fm2.html">
<b><font size="+2">
 
Immediate Mode Imaging Concepts</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-image.fm2.html#65725">Terminology</a>
</b>

</dl>
<dd><br>
<a href="j2d-image.fm3.html">
<b><font size="+2">
 
Using BufferedImages</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-image.fm3.html#66509">Creating a BufferedImage</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm3.html#66525">Drawing in an Offscreen Buffer</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm3.html#67504">Manipulating BufferedImage Data Directly</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm3.html#66550">Filtering a BufferedImage</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm3.html#66557">Rendering a BufferedImage</a>
</b>

</dl>
<dd><br>
<a href="j2d-image.fm4.html">
<b><font size="+2">
 
Managing and Manipulating Rasters</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-image.fm4.html#67258">Creating a Raster</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm4.html#66680">Parent and Child Rasters</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm4.html#66687">Operations on a Raster</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm4.html#69484">The WritableRaster Subclass</a>
</b>

</dl>
<dd><br>
<a href="j2d-image.fm5.html">
<b><font size="+2">
 
Image Data and DataBuffers</font></b></a>

<dd><br>
<a href="j2d-image.fm6.html">
<b><font size="+2">
 
Extracting Pixel Data from a SampleModel</font></b></a>

<dd><br>
<a href="j2d-image.fm7.html">
<b><font size="+2">
 
ColorModels and Color Data</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-image.fm7.html#65329">Lookup Table</a>
</b>

</dl>
<dd><br>
<a href="j2d-image.fm8.html">
<b><font size="+2">
 
Image Processing and Enhancement</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-image.fm8.html#61900">Using an Image Processing Operation</a>
</b>

<dd>
<b> 
<a href="j2d-image.fm8.html#66496">Implementing an Image Processing Operation</a>
</b>

</dl>
</dl>
<H2>
	
<a href="j2d-color.fm.html#61757">Color		</a>
</H2>

<dl>
<dt></dt>
<dd><br>
<a href="j2d-color.fm1.html">
<b><font size="+2">
 
Classes</font></b></a>

<dd><br>
<a href="j2d-color.fm2.html">
<b><font size="+2">
 
Color Concepts</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-color.fm2.html#62455">Describing Colors</a>
</b>

<dd>
<b> 
<a href="j2d-color.fm2.html#61783">Mapping Colors through sRGB and CIEXYZ</a>
</b>

</dl>
</dl>
<H2>
	
<a href="j2d-print.fm.html#418231">Printing		</a>
</H2>

<dl>
<dt></dt>
<dd><br>
<a href="j2d-print.fm1.html">
<b><font size="+2">
 
Interfaces and Classes</font></b></a>

<dd><br>
<a href="j2d-print.fm2.html">
<b><font size="+2">
 
Printing Concepts</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-print.fm2.html#420680">Supporting Printing</a>
</b>

<dd>
<b> 
<a href="j2d-print.fm2.html#420933">Page Painters</a>
</b>

<dd>
<b> 
<a href="j2d-print.fm2.html#417961">Printable Jobs and Pageable Jobs</a>
</b>

<dd>
<b> 
<a href="j2d-print.fm2.html#420247">Typical Life-Cycle of a PrinterJob</a>
</b>

<dd>
<b> 
<a href="j2d-print.fm2.html#417988">Dialogs</a>
</b>

</dl>
<dd><br>
<a href="j2d-print.fm3.html">
<b><font size="+2">
 
Printing with Printables</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-print.fm3.html#418019">Using Graphics2D for Rendering</a>
</b>

</dl>
<dd><br>
<a href="j2d-print.fm4.html">
<b><font size="+2">
 
Printing with Pageables and Books</font></b></a>


<dl>
<dt></dt>
<dd>
<b> 
<a href="j2d-print.fm4.html#421072">Using a Pageable Job</a>
</b>

<dd>
<b> 
<a href="j2d-print.fm4.html#418048">Using Multiple Page Painters</a>
</b>

</dl>
</dl>


<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-title.fm.html">PREV</a>
 | <a href="j2d-preface.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:03 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm8.html">PREV</a>
 | <a href="j2d-color.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 
<a name="60754"><!-- --></a>
<hr size="8" width="35%" align="left" noshade>

<table border=0>
<tr valign=bottom>
<td valign=bottom>
<br>
<U><B><FONT FACE="ARIAL,HELVETICA,TIMES ROMAN">CHAPTER</FONT> 
6 
</B></U>
</td>
</tr>
</table>

<a name="61757"><!-- --> </a>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td align="left">
<h1><FONT SIZE=+4>
Color
</font></h1>
</td>
</tr>
</table>
<blockquote>
<a name="61777"><!-- --></a>
Color imaging is one of the fundamental components of any graphics system, and it is often a source of great complexity in the imaging model. The Java 2D API provides support for high-quality color output that is easy to use and allows advanced clients to make sophisticated use of color. <p>
<a name="62572"><!-- --></a>
The key color management classes in the Java 2D API are <kbd>ColorSpace, Color</kbd>, <kbd>ColorModel</kbd>:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="62615"><!-- --></a>
A<kbd> ColorSpace</kbd> represents a system for measuring colors, typically using three separate numerical values or components. The <kbd>ColorSpace</kbd> class contains methods for converting between the color space and two standard color spaces, <kbd>CIEXYZ</kbd> and RGB.
</li>
<li>
<a name="62573"><!-- --></a>
A<kbd> Color</kbd> is a fixed color, defined in terms of its components in a particular <kbd>ColorSpace</kbd>. To draw a <kbd>Shape</kbd> in a color, such as red, you pass a <kbd>Color</kbd> object representing that color to the <kbd>Graphics2D</kbd> context. <kbd>Color</kbd> is defined in the <kbd>java.awt package</kbd>. 
</li>
<li>
<a name="62602"><!-- --></a>
A<kbd> ColorModel</kbd> describes a particular way that pixel values are mapped to colors. A <kbd>ColorModel</kbd> is typically associated with an <kbd>Image</kbd> or <kbd>BufferedImage</kbd> and provides the information necessary to correctly interpret the pixel values. <kbd>ColorModel</kbd> is defined in the <kbd>java.awt.image package</kbd>. 
</li>
</ul>
</blockquote>


<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm8.html">PREV</a>
 | <a href="j2d-color.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:36 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-color.fm.html">PREV</a>
 | <a href="j2d-color.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62604"><i>6.1	</i> Classes
</a></h2>

<blockquote>
<a name="62467"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="62471"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="62473"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="62475"><!-- --></a>
<p><code>ColorSpace</code>

</td><td><a name="62527"><!-- --></a>
<p>Identifies the color space of a <code>Color</code> object, <code>Image</code>, <code>BufferedImage</code>, or <code>GraphicsDevice</code>. Has methods to transform between RGB and CIEXYZ color spaces.

</td></tr>
<tr><td><a name="62479"><!-- --></a>
<p><code>ICC_ColorSpace</code>

</td><td><a name="62531"><!-- --></a>
<p>Extends: <code>ColorSpace</code>

<a name="62532"><!-- --></a>
<p>Represents device-independent and device-dependent color spaces based on the ICC Profile Format Specification.

</td></tr>
<tr><td><a name="62483"><!-- --></a>
<p><code>ICC_Profile</code>

</td><td><a name="62536"><!-- --></a>
<p>A representation of color profile data for device independent and device dependent color spaces based on the ICC Profile Format Specification.

</td></tr>
<tr><td><a name="62487"><!-- --></a>
<p><code>ICC_ProfileGray</code>

</td><td><a name="62542"><!-- --></a>
<p>Extends: <code>ICC_Profile</code>

<a name="62543"><!-- --></a>
<p>A representation of color space type gray.

</td></tr>
<tr><td><a name="62491"><!-- --></a>
<p><code>ICC_ProfileRGB</code>

</td><td><a name="62547"><!-- --></a>
<p>Extends: <code>ICC_Profile</code>

<a name="62548"><!-- --></a>
<p>A representation of color space type RGB.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-color.fm.html">PREV</a>
 | <a href="j2d-color.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:36 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-color.fm1.html">PREV</a>
 | <a href="j2d-print.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62583"><i>6.2	</i> Color Concepts
</a></h2>

<blockquote>
<a name="62586"><!-- --></a>
A <kbd>ColorModel</kbd> is used to interpret pixel data in an image. This includes mapping components in the bands of an image to components of a particular color space. It might also involve extracting pixel components from packed pixel data, retrieving multiple components from a single band using masks, and converting pixel data through a lookup table. <p>
<a name="62297"><!-- --></a>
To determine the color value of a particular pixel in an image, you need to know how color information is encoded in each pixel. The <kbd>ColorModel</kbd> associated with an image encapsulates the data and methods necessary for translating a pixel value to and from its constituent color components. <p>
<a name="62298"><!-- --></a>
The Java 2D API provides two color models in addition to the <kbd>DirectColorModel</kbd> and <kbd>IndexColorModel</kbd> defined in the JDK 1.1 software release: <p>
</blockquote>
<blockquote>
<ul><li>
<a name="62299"><!-- --></a>
<kbd>ComponentColorModel</kbd> can handle an arbitrary <kbd>ColorSpace</kbd> and an array of color components to match the <kbd>ColorSpace</kbd>. This model can be used to represent most color models on most types of <kbd>GraphicsDevices</kbd>. 
</li>
<li>
<a name="62300"><!-- --></a>
<kbd>PackedColorModel</kbd> is a base class for models that represent pixel values that have their color components embedded directly in the bits of an integer pixel. A <kbd>PackedColorModel</kbd> stores the packing information that describes how color and alpha components are extracted from the channel.The <kbd>DirectColorModel</kbd> in the JDK 1.1 software release is a <kbd>PackedColorModel</kbd>. 
</li>
</ul>
</blockquote>

<br>
<a name="62302"><!-- --></a>
<h4><i>6.2.0.1	 ColorSpace
</i></h4>

<blockquote>
<a name="62303"><!-- --></a>
A <kbd>ColorSpace</kbd> object represents a system for measuring colors, typically using three separate numeric values. For example, RGB and CMYK are color spaces. A <kbd>ColorSpace</kbd> object serves as a colorspace tag that identifies the specific color space of a <kbd>Color</kbd> object or, through a <kbd>ColorModel</kbd> object, of an <kbd>Image</kbd>, <kbd>BufferedImage</kbd>, or <kbd>GraphicsConfiguration</kbd>. <kbd>ColorSpace</kbd> provides methods that transform <kbd>Colors</kbd> in a specific color space to and from <kbd>sRGB</kbd> and to and from a well-defined <kbd>CIEXYZ</kbd> color space.<p>
<a name="62304"><!-- --></a>
All <kbd>ColorSpace</kbd> objects must be able to map a color from the represented color space into <kbd>sRGB</kbd> and transform an <kbd>sRGB</kbd> color into the represented color space. Since every <kbd>Color</kbd> contains a <kbd>ColorSpace</kbd> object, set explicitly or by default, every <kbd>Color</kbd> can also be converted to <kbd>sRGB</kbd>. Every <kbd>GraphicsConfiguration</kbd> is associated with a <kbd>ColorSpace</kbd> object that in turn has an associated <kbd>ColorSpace</kbd>. A color specified in any color space can be displayed by any device by mapping it through <kbd>sRGB</kbd> as an intermediate color space.<p>
<a name="62305"><!-- --></a>
The methods used for this process are <kbd>toRGB</kbd> and <kbd>fromRGB:</kbd><p>
</blockquote>
<blockquote>
<ul><li>
<a name="62306"><!-- --></a>
<kbd>toRGB</kbd> transforms a <kbd>Color</kbd> in the represented color space to a <kbd>Color</kbd> in <kbd>sRGB</kbd>. 
</li>
<li>
<a name="62307"><!-- --></a>
<kbd>fromRGB</kbd> takes a <kbd>Color</kbd> in <kbd>sRGB</kbd> and transforms it into the represented color space.
</li>
</ul>
</blockquote>
<blockquote>
<a name="62308"><!-- --></a>
Though mapping through <kbd>sRGB</kbd> always works, it's not always the best solution. For one thing, <kbd>sRGB</kbd> cannot represent every color in the full gamut of <kbd>CIEXYZ</kbd> colors. If a color is specified in some space that has a different gamut (spectrum of representable colors) than <kbd>sRGB</kbd>, then using <kbd>sRGB</kbd> as an intermediate space results in a loss of information. To address this problem, the <kbd>ColorSpace</kbd> class can map colors to and from another color space, the &#34;conversion space&#34; <kbd>CIEXYZ</kbd>.<p>
<a name="62309"><!-- --></a>
The methods <kbd>toCIEXYZ</kbd> and <kbd>fromCIEXYZ</kbd> map color values from the represented color space to the conversion space. These methods support conversions between any two color spaces at a reasonably high degree of accuracy, one <kbd>Color</kbd> at a time. However, it is expected that Java 2D API implementations will support high-performance conversion based on underlying platform color-management systems, operating on entire images. (See <kbd>ColorConvertOp</kbd> in <a href="j2d-image.fm.html#65661">&#34;Imaging&#34; on page&#160;67</a>.)<p>
<a name="62319"><!-- --></a>
<a href="j2d-color.fm2.html#62371">Figure&#160;6-1</a> and <a href="j2d-color.fm2.html#62421">Figure&#160;6-2</a> illustrate the process of translating a color specified in a CMYK color space for display on an RGB color monitor. <a href="j2d-color.fm2.html#62371">Figure&#160;6-1</a> shows a mapping through <kbd>sRGB</kbd>. As this figure illustrates, the translation of the CMYK color to an RGB color is not exact because of a gamut mismatch. <a href="#62325"><sup>1</sup></a><p>
<a name="62369"><!-- --></a>
<p><center><img src="j2d-color.fm.anc1.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="62371"><!-- --></a>
<b>Figure 6-1	</b> Mapping Through sRGB

</p>
</blockquote><blockquote>
<a name="62375"><!-- --></a>
<a href="j2d-color.fm2.html#62421">Figure&#160;6-2</a> shows the same process using <kbd>CIEXYZ</kbd> as the conversion space. When <kbd>CIEXYZ</kbd> is used, the color is passed through accurately.<p>
<a name="62419"><!-- --></a>
<p><center><img src="j2d-color.fm.anc2.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="62421"><!-- --></a>
<b>Figure 6-2	</b> Mapping Through CIEXYZ

</p>
</blockquote>
<br>
<a name="62422"><!-- --></a>
<h4><i>6.2.0.2	 ICC_Profile and ICC_ColorSpace
</i></h4>

<blockquote>
<a name="62423"><!-- --></a>
<kbd>ColorSpace</kbd> is actually an abstract class. The Java 2D API provides one implementation, <kbd>ICC_ColorSpace</kbd>, which is based on ICC Profile data as represented by the <kbd>ICC_Profile</kbd> class. You can define your own subclasses to represent arbitrary color spaces, as long as the methods discussed above are implemented. However, most developers can simply use the default <kbd>sRGB</kbd> <kbd>ColorSpace</kbd> or color spaces that are represented by commonly available ICC Profiles, such as profiles for monitors and printers, or profiles embedded in image data.<p>
<a name="62427"><!-- --></a>
<a href="j2d-color.fm2.html#62302">&#34;ColorSpace&#34; on page&#160;90</a> describes how <kbd>ColorSpace</kbd> objects represent a color space and how colors in the represented space can be mapped to and from a conversion space. Color management systems are often used to handle the mapping between color spaces. A typical color management system (CMS) manages ICC profiles, which are similar to <kbd>ColorSpace</kbd> objects; ICC profiles describe an input space and a connection space, and define how to map between them. Color management systems are very good at figuring out how to map a color tagged with one profile into the color space of another profile.<p>
<a name="62428"><!-- --></a>
The Java 2D API defines a class called <kbd>ICC_Profile</kbd> that holds data for an arbitrary ICC Profile. <kbd>ICC_ColorSpace</kbd> is an implementation of the abstract <kbd>ColorSpace</kbd> class. <kbd>ICC_ColorSpace</kbd> objects can be constructed from <kbd>ICC_Profiles</kbd>. (There are some limitations&#45;&#45;not all ICC Profiles are appropriate for defining an <kbd>ICC_ColorSpace</kbd>). <p>
<a name="62429"><!-- --></a>
<kbd>ICC_Profile</kbd> has several subclasses that correspond to specific color space types, such as <kbd>ICC_ProfileRGB</kbd> and <kbd>ICC_ProfileGray</kbd>. Each subclass of <kbd>ICC_Profile</kbd> has a well-defined input space (such as an RGB space) and a well-defined connection space (like <kbd>CIEXYZ</kbd>). The Java 2D API can use a platform's CMS to access color profiles for various devices such as scanners, printers, and monitors. It can also use the CMS to find the best mapping between profiles.<p>
</blockquote>
<br>
<h3>
<a name="62455"><!-- --></a>
<i>6.2.1	</i> Describing Colors
</h3>

<blockquote>
<a name="62437"><!-- --></a>
The <kbd>Color</kbd> class provides a description of a color in a particular color space. An instance of <kbd>Color</kbd> contains the value of the color components and a <kbd>ColorSpace</kbd> object. Because a <kbd>ColorSpace</kbd> object can be specified in addition to the color components when a new instance of <kbd>Color</kbd> is created, the <kbd>Color</kbd> class can handle colors in any color space.<p>
<a name="62438"><!-- --></a>
The <kbd>Color</kbd> class has a number of methods that support a proposed standard RGB color space called <kbd>sRGB</kbd> (see <kbd>http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html</kbd>). <kbd>sRGB</kbd> is the default color space for the Java 2D API. Several constructors defined by the Color class omit the <kbd>ColorSpace</kbd> parameter. These constructors assume that the color's RGB values are defined in <kbd>sRGB</kbd>, and use a default instance of <kbd>ColorSpace</kbd> to represent that space.<p>
<a name="62439"><!-- --></a>
The Java 2D API uses <kbd>sRGB</kbd> as a convenience to application programmers, not as a reference color space for color conversion. Many applications are primarily concerned with RGB images and monitors, and defining a standard RGB color space makes writing such applications easier. The <kbd>ColorSpace</kbd> class defines the methods <kbd>toRGB</kbd> and <kbd>fromRGB</kbd> so that developers can easily retrieve colors in this standard space. These methods are not intended to be used for highly accurate color correction or conversions. See <a href="j2d-color.fm2.html#62302">&#34;ColorSpace&#34; on page&#160;90</a> for more information.<p>
<a name="62443"><!-- --></a>
To create a color in a color space other than <kbd>sRGB</kbd>, you use the <kbd>Color</kbd> constructor that takes a <kbd>ColorSpace</kbd> object and an array of floats that represent the color components appropriate to that space. The <kbd>ColorSpace</kbd> object identifies the color space.<p>
<a name="61780"><!-- --></a>
To display a rectangle of a certain color, such as the process color cyan, you need a way to describe this color to the system. There are a number of different ways to describe a color; for example, a color could be described as a set of red, green, and blue (RGB) components, or a set of cyan, magenta, yellow, and black (CMYK) components. These different techniques for specifying colors are called<em> color spaces</em>. <p>
<a name="61781"><!-- --></a>
As you probably know, colors on a computer screen are generated by blending different amounts of red, green, and blue light. Therefore, using an RGB color space is standard for imaging on computer monitors. Similarly, four-color process printing uses cyan, magenta, yellow, and black ink to produce color on a printed page; the printed colors are specified as percentages in a CMYK color space. <p>
<a name="61782"><!-- --></a>
Due to the prevalence of computer monitors and color printing, RGB and CMYK color spaces are both commonly used to describe colors. However, both types of color spaces have a fundamental drawback&#45;&#45;they are device-dependent. The cyan ink used by one printer might not exactly match the cyan ink used by another. Similarly, a color described as an RGB color might look blue on one monitor and purplish on another. <p>
</blockquote>
<br>
<h3>
<a name="61783"><!-- --></a>
<i>6.2.2	</i> Mapping Colors through sRGB and CIEXYZ
</h3>

<blockquote>
<a name="62282"><!-- --></a>
The Java 2D API refers to RGB and CMYK as color space types. A particular model of monitor with its particular phosphors defines its own RGB color space. Similarly, a particular model of printer has its own CMYK color space. Different RGB or CMYK color spaces can be related to each other through a device-independent color space.<p>
<a name="61784"><!-- --></a>
Standards for the device-independent specification of color have been defined by the International Commission on Illumination (CIE). The most commonly used device-independent color space is the three-component XYZ color space developed by CIE. When you specify a color using <kbd>CIEXYZ</kbd>, you are insulated from device dependencies.<p>
<a name="61785"><!-- --></a>
Unfortunately, it&#39;s not always practical to describe colors in the <kbd>CIEXYZ</kbd> color space&#45;&#45;there are valid reasons for representing colors in other color spaces. To obtain consistent results when a color is represented using a device-dependent color space such as a particular RGB space, it is necessary to show how that RGB&#160;space relates to a device-independent space like <kbd>CIEXYZ</kbd>.<p>
<a name="61786"><!-- --></a>
One way to map between color spaces is to attach information to the spaces that describes how the device-dependent space relates to the device-independent space. This additional information is called a <em>profile</em>. A commonly used type of color profile is the ICC Color Profile, as defined by the International Color Consortium. For details, see the ICC Profile Format Specification, version 3.4 available at <kbd>http://www.color.org</kbd>.<p>
<a name="61790"><!-- --></a>
<a href="j2d-color.fm2.html#61912">Figure&#160;6-3</a> illustrates how a solid color and a scanned image are passed to the Java 2D API, and how they are displayed by various output devices. As you can see in <a href="j2d-color.fm2.html#61912">Figure&#160;6-3</a>, both the input color and the image have profiles attached.<p>
</blockquote><a name="61910"><!-- --></a>
<p><p><center><img src="j2d-color.fm.anc.gif"></center>


<blockquote><p>
<a name="61912"><!-- --></a>
<b>Figure 6-3	</b> Using Profiles to Map Between Color Spaces

</p>
</blockquote>
<br>
<a name="61913"><!-- --></a>
<h4><i>6.2.2.1	 Color Matching 
</i></h4>

<blockquote>
<a name="62270"><!-- --></a>
Once the API has an accurately specified color, it must reproduce that color on an output device, such as a monitor or printer. These devices have imaging characteristics of their own that must be taken into account to make sure that they produce the correct results. Another profile is associated with each output device to describe how the colors need to be transformed to produce accurate results.<p>
<a name="62724"><!-- --></a>
Achieving consistent and accurate color requires that both input colors and output devices be profiled against a standard color space. For example, an input color could be mapped from its original color space into a standard device-independent space, and then mapped from that space to the output device&#39;s color space. In many respects, the transformation of colors mimics the transformation of graphical objects in an (<em>x</em>,&#160;<em>y</em>) coordinate space. In both cases, a transformation is used to specify coordinates in a &#34;standard&#34; space and then map those coordinates to a device-specific space for output.<p>
<a name="62729"><!-- --></a>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-color.fm1.html">PREV</a>
 | <a href="j2d-print.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:36 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-color.fm2.html">PREV</a>
 | <a href="j2d-print.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62459"><i>6.3	</i> Representing a New Color Space
</a></h2>



<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-color.fm2.html">PREV</a>
 | <a href="j2d-print.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Tue Feb 24 10:24:32 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm4.html">PREV</a>
 | <a href="j2d-fonts.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 
<a name="73057"><!-- --></a>
<hr size="8" width="35%" align="left" noshade>

<table border=0>
<tr valign=bottom>
<td valign=bottom>
<br>
<U><B><FONT FACE="ARIAL,HELVETICA,TIMES ROMAN">CHAPTER</FONT> 
4 
</B></U>
</td>
</tr>
</table>

<a name="73059"><!-- --> </a>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td align="left">
<h1><FONT SIZE=+4>
Fonts and Text Layout
</font></h1>
</td>
</tr>
</table>
<blockquote>
<a name="73060"><!-- --></a>
You can use the Java 2D API transformation and drawing mechanisms with text strings. In addition, the Java 2D API provides text-related classes that support fine-grain font control and sophisticated text layout. These include an enhanced <kbd>Font</kbd> class and the new <kbd>TextLayout</kbd> class.<p>
<a name="72736"><!-- --></a>
This chapter focuses on the new font and text layout capabilities supported through interfaces and classes in<kbd> java.awt</kbd>, and <kbd>java.awt.font</kbd>.
<b>For more information about using these features, see the 2D text Tutorial
that's available through the Java Developer Connection at 
<a href="http://developer.java.sun.com/developer/onlineTraining/Graphics/2DText/">http://developer.java.sun.com/developer/onlineTraining/Graphics/2DText/</a>.</b><p>
<a name="74367"><!-- --></a>
For information about text analysis and internationalization, refer to the <kbd>java.text</kbd> documentation and the &#34;Writing Global Programs&#34; track in the Java Tutorial. For information about using the text layout mechanisms implemented in Swing, see the <kbd>java.awt.swing.text</kbd> documentation and &#34;Using the JFC/Swing Packages&#34; in the Java Tutorial.<p>
<a name="67024"><!-- --></a>
<strong>Note</strong>: The information on international text layout contained in this chapter is based on the paper <em>International Text in JDK 1.2</em> by Mark Davis, Doug Felt, and John Raley, copyright 1997, Taligent, Inc. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm4.html">PREV</a>
 | <a href="j2d-fonts.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:22 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm.html">PREV</a>
 | <a href="j2d-fonts.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62190"><i>4.1	</i> Interfaces and Classes
</a></h2>

<blockquote>
<a name="68561"><!-- --></a>
The following tables list the key font and text layout interfaces and classes. Most of these interfaces and classes are part of the <kbd>java.awt.font</kbd> package. Some, like <kbd>Font</kbd>, are part of the <kbd>java.awt</kbd> package to maintain backward compatibility with earlier versions of the JDK.<p>
<a name="66739"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="62425"><!-- --></a>
<blockquote><hr noshade size="1"><b>Interface</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="62427"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="62429"><!-- --></a>
<p><code>MultipleMaster</code>

</td><td><a name="62542"><!-- --></a>
<p>Represents Type 1 Multiple Master fonts. Implemented by <kbd>Font</kbd> objects that are multiple master fonts to enable access to multiple master design controls.

</td></tr>
<tr><td><a name="62433"><!-- --></a>
<p><code>OpenType</code>

</td><td><a name="62546"><!-- --></a>
<p>Represents Open Type and True Type fonts. Implemented by <kbd>Font</kbd> objects that are Open Type or True Type fonts to enable access to the font&#39;s <kbd>sfnt</kbd> tables.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
<a name="66742"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="62935"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="62937"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="63043"><!-- --></a>
<p><code>Font</code>

</td><td><a name="63045"><!-- --></a>
<p>Represents an instance of a font face from the collection of font faces available on the host system. Supports the specification of detailed font information and provides access to information about the font and its glyphs. (In<kbd> </kbd><code>java.awt package</code>.)

</td></tr>
<tr><td><a name="73090"><!-- --></a>
<p>FontRenderContext

</td><td><a name="73092"><!-- --></a>
<p>Encapsulates the information necessary to correctly measure text.

</td></tr>
<tr><td><a name="63078"><!-- --></a>
<p><code>GlyphJustificationInfo</code>

</td><td><a name="63080"><!-- --></a>
<p>Represents information about the justification properties of a glyph, such as weight, priority, absorb, and limit.

</td></tr>
<tr><td><a name="63430"><!-- --></a>
<p><code>GlyphMetrics</code>

</td><td><a name="63432"><!-- --></a>
<p>Provides metrics for a single glyph.

</td></tr>
<tr><td><a name="62968"><!-- --></a>
<p><code>GlyphVector</code>

</td><td><a name="62970"><!-- --></a>
<p>A collection of glyphs and their positions. 

</td></tr>
<tr><td><a name="63442"><!-- --></a>
<p><code>GraphicAttribute</code>

</td><td><a name="63444"><!-- --></a>
<p>Base class for a <kbd>TextLayout</kbd> attribute that specifies a graphic to be embedded within text. Implemented by <kbd>ShapeGraphicAttribute</kbd> and <kbd>ImageGraphicAttribute</kbd>, which enable <kbd>Shapes</kbd> and <kbd>Images</kbd> to be embedded in a <kbd>TextLayout</kbd>. Can be subclassed to implement custom character replacement graphics.

</td></tr>
<tr><td><a name="63452"><!-- --></a>
<p><code>ImageGraphicAttribute</code>

</td><td><a name="63454"><!-- --></a>
<p>Extends: <code>GraphicAttribute</code>

<a name="66689"><!-- --></a>
<p>A <code>GraphicsAttribute</code> used to draw <code>Images</code> within a <code>TextLayout</code>.

</td></tr>
<tr><td><a name="63456"><!-- --></a>
<p><code>LineBreakMeasurer</code>

</td><td><a name="63458"><!-- --></a>
<p>Breaks a block of text that spans multiple lines into <br><kbd>TextLayout</kbd> objects that fit within a specified line length.

</td></tr>
<tr><td><a name="73120"><!-- --></a>
<p>LineMetrics

</td><td><a name="73122"><!-- --></a>
<p>Provides access to the font metrics needed to lay out characters along a line and to lay out a set of lines. These metrics include ascent, descent, leading, height, and baseline information.

</td></tr>
<tr><td><a name="63460"><!-- --></a>
<p><code>ShapeGraphicAttribute</code>

</td><td><a name="66688"><!-- --></a>
<p>Extends: <code>GraphicAttribute</code>

<a name="63462"><!-- --></a>
<p>A <code>GraphicsAttribute</code> used to draw <code>Shapes</code> within a <code>TextLayout</code>.

</td></tr>
<tr><td><a name="73072"><!-- --></a>
<p><code>TextAttribute</code>

</td><td><a name="73074"><!-- --></a>
<p>Defines attribute keys and values used for text rendering. 

</td></tr>
<tr><td><a name="62988"><!-- --></a>
<p><code>TextHitInfo</code>

</td><td><a name="62990"><!-- --></a>
<p>Represents hit test information for characters in a <code>TextLayout</code>.

</td></tr>
<tr><td><a name="63000"><!-- --></a>
<p><code>TextLayout</code>

</td><td><a name="63002"><!-- --></a>
<p>Implements: <code>Cloneable</code>

<a name="63003"><!-- --></a>
<p>Provides an immutable graphical representation of styled character data, including bidirectional text.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm.html">PREV</a>
 | <a href="j2d-fonts.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:22 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm1.html">PREV</a>
 | <a href="j2d-fonts.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62220"><i>4.2	</i> Font Concepts
</a></h2>

<blockquote>
<a name="72771"><!-- --></a>
The <kbd>Font</kbd> class has been enhanced to support the specification of detailed font information and enable the use of sophisticated typographic features.<p>
<a name="61786"><!-- --></a>
A <kbd>Font</kbd> object represents an instance of a font face from the collection of font faces available on the system. Examples of common font faces include <kbd>Helvetica Bold</kbd> and <kbd>Courier Bold Italic</kbd>.<p>
<a name="68534"><!-- --></a>
Three names are associated with a <kbd>Font</kbd>&#45;&#45;its logical name, family name, and font face name:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="68535"><!-- --></a>
A <kbd>Font</kbd> object&#39;s<em> logical name</em> is a name mapped onto one of the specific fonts available on the platform. The logical font name is the name used to specify a <kbd>Font</kbd> in JDK 1.1 and earlier releases. When specifying a <kbd>Font </kbd>in JDK 1.2, you should use the <em>font face name</em> instead of the logical name.You can get the logical name from the <kbd>Font</kbd> by calling <kbd>getName</kbd>. To get a list of the logical names that are mapped onto the specific fonts available on a platform, call <kbd>java.awt.Toolkit.getFontList</kbd>. 
</li>
<li>
<a name="68533"><!-- --></a>
A <kbd>Font</kbd> object&#39;s <em>family name</em> is the name of the font family that determines the typographic design across several faces, such as Helvetica. You retrieve the family name through the <kbd>getFamily</kbd> method. 
</li>
<li>
<a name="68536"><!-- --></a>
A <kbd>Font</kbd> objects&#39; <em>font face name</em> refers to an actual font installed on the system. This is the name you should use when specifying a font in JDK 1.2. It&#39;s often referred to as just the <em>font name</em>. You can retrieve the font name by calling <kbd>getFontName</kbd>. To determine which font faces are available on the system, you can call <kbd>GraphicsEnvironment.getAllFonts</kbd>. 
</li>
</ul>
</blockquote>
<blockquote>
<a name="73181"><!-- --></a>
You can access information about a<kbd> Font</kbd> through the <kbd>getAttributes</kbd> method. A <kbd>Font</kbd>&#39;s attributes include its name, size, transform, and font features such as weight and posture. <p>
<a name="73239"><!-- --></a>
A <kbd>LineMetrics</kbd> object encapsulates the measurement information associated with a <kbd>Font</kbd>, such as its ascent, descent, and leading:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="73240"><!-- --></a>
A<em>scent</em> is the distance from the baseline to the ascender line. This distance represents the typical height of capital letters, but some characters might extend above the ascender line.
</li>
<li>
<a name="69526"><!-- --></a>
<em>Descent</em> is the distance from the baseline to the descender line. The lowest point of most characters will fall within the descent, but some characters might extend below the descender line.
</li>
<li>
<a name="69531"><!-- --></a>
<em>Leading</em> is the recommended distance from the bottom of the descender line to the top of the next line.
</li>
</ul>
</blockquote>
<blockquote>
<a name="69518"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc5.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="69504"><!-- --></a>
<b>Figure 4-1	</b> Line Metrics

</p>
</blockquote><blockquote>
<a name="73260"><!-- --></a>
This information is used to properly position characters along a line, and to position lines relative to one another. You can access these line metrics through the <kbd>getAscent</kbd>, <kbd>getDescent</kbd>, and <kbd>getLeading</kbd> methods. You can also access information about a <kbd>Font</kbd>&#39;s height, baseline, and underline and strikethrough characteristics through <kbd>LineMetrics</kbd>.<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm1.html">PREV</a>
 | <a href="j2d-fonts.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:22 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm2.html">PREV</a>
 | <a href="j2d-fonts.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="73261"><i>4.3	</i> Text Layout Concepts
</a></h2>

<blockquote>
<a name="68804"><!-- --></a>
Before a piece of text can be displayed, it must be properly shaped and positioned using the appropriate glyphs and ligatures. This process is referred to as <em>text layout</em>. The text layout process involves:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="74549"><!-- --></a>
Shaping text using the appropriate glyphs and ligatures.
</li>
<li>
<a name="74550"><!-- --></a>
Properly ordering the text.
</li>
<li>
<a name="74551"><!-- --></a>
Measuring and positioning the text.
</li>
</ul>
</blockquote>
<blockquote>
<a name="74574"><!-- --></a>
The information used to lay out text is also necessary for performing text operations such as caret positioning, hit detection, and highlighting.<p>
<a name="74587"><!-- --></a>
To develop software that can be deployed in international markets, text must be laid out in different languages in a way that conforms to the rules of the appropriate writing system.   <p>
</blockquote>
<br>
<h3>
<a name="74588"><!-- --></a>
<i>4.3.1	</i> Shaping Text
</h3>

<blockquote>
<a name="73366"><!-- --></a>
A <em>glyph</em> is the visual representation of one or more characters. The shape, size, and position of a glyph is dependent on its context. Many different glyphs can be used to represent a single character or combination of characters, depending on the font and style.<p>
<a name="73367"><!-- --></a>
For example, in handwritten cursive text, a particular character can take on different shapes depending on how it is connected to adjacent characters.<p>
<a name="73368"><!-- --></a>
In some writing systems, particularly Arabic, the context of a glyph must always be taken into account. Unlike in English, cursive forms are mandatory in Arabic; it is unacceptable to present text without using cursive forms. <p>
<a name="73369"><!-- --></a>
Depending on the context, these cursive forms can differ radically in shape. For example, the Arabic letter <em>heh</em> has the four cursive forms shown in <a href="j2d-fonts.fm3.html#73395">Figure&#160;4-2</a>. <p>
<a name="73393"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc2.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="73395"><!-- --></a>
<b>Figure 4-2	</b> Cursive Forms in Arabic

</p>
</blockquote><blockquote>
<a name="73396"><!-- --></a>
Although these four forms are quite different from one another, such cursive shape-changing is not fundamentally different from cursive writing in English.<p>
<a name="73449"><!-- --></a>
In some contexts, two glyphs can change shape even more radically and merge to form a single glyph. This type of merged glyph is called a <em>ligature</em>. For example, most English fonts contain the ligature<em> fi</em> shown in <a href="j2d-fonts.fm3.html#73408">Figure&#160;4-3</a>. The merged glyph takes into account the overhang on the letter<em> f</em> and combines the characters in a natural-looking way, instead of simply letting the letters collide.<p>
<a name="73406"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc6.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="73408"><!-- --></a>
<b>Figure 4-3	</b> English Ligatures

</p>
</blockquote><blockquote>
<a name="73409"><!-- --></a>
Ligatures are also used in Arabic and the use of some ligatures is mandatory&#45;&#45;it is unacceptable to present certain character combinations without using the appropriate ligature. When ligatures are formed from Arabic characters, the shapes change even more radically than they do in English. For example, <a href="j2d-fonts.fm3.html#73421">Figure&#160;4-4</a> illustrates how two Arabic characters are combined into a single ligature when they appear together.<p>
<a name="73419"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc7.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="73421"><!-- --></a>
<b>Figure 4-4	</b> Arabic Ligatures

</p>
</blockquote>
<br>
<h3>
<a name="73474"><!-- --></a>
<i>4.3.2	</i> Ordering Text
</h3>

<blockquote>
<a name="73475"><!-- --></a>
In the Java programming language, text is encoded using Unicode character encoding. Text that uses Unicode character encoding is stored in memory in <em>logical order</em>. Logical order is the order in which characters and words are read and written. The logical order is not necessarily the same as the <em>visual order</em>, the order in which the corresponding glyphs are displayed.<p>
<a name="73476"><!-- --></a>
The visual order for glyphs in a particular writing system (script) is called the <em>script order</em>. For example, the script order for Roman text is left-to-right and the script order for Arabic and Hebrew is right-to-left. <p>
<a name="73477"><!-- --></a>
Some writing systems have rules in addition to script order for arranging glyphs and words on lines of text. For example, Arabic and Hebrew numbers run left to right, even though the letters run right to left. (This means that Arabic and Hebrew, even with no embedded English text, are truly bidirectional.)<p>
<a name="73478"><!-- --></a>
A writing system&#39;s visual order must be maintained even when languages are mixed together. This is illustrated in <a href="j2d-fonts.fm3.html#73488">Figure&#160;4-5</a>, which displays an Arabic phrase embedded in an English sentence. <p>
<a name="73482"><!-- --></a>
<strong>Note:</strong> In this and subsequent examples, Arabic and Hebrew text is represented by uppercase letters and spaces are represented by underscores. Each illustration contains two parts: a representation of the characters stored in memory (the characters in logical order) followed by a representation of how those characters are displayed (the characters in visual order). The numbers below the character boxes indicate the insertion offsets.<p>
<a name="73734"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc3.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="73488"><!-- --></a>
<b>Figure 4-5	</b> Bidirectional Text

</p>
</blockquote><blockquote>
<a name="73489"><!-- --></a>
Even though they are part of an English sentence, the Arabic words are displayed in the Arabic script order, right-to-left. Because the italicized Arabic word is logically after the Arabic in plain text, it is visually to the left of the plain text.<p>
<a name="73490"><!-- --></a>
When a line with a mixture of left-to-right and right-to-left text is displayed, the <em>base direction</em> is significant. The base direction is the script order of the predominant writing system. For example, if the text is primarily English with some embedded Arabic, then the base direction is left-to-right. If the text is primarily Arabic with some embedded English or numbers, then the base direction is right-to-left.<p>
<a name="73491"><!-- --></a>
The base direction determines the order in which segments of text with a common direction are displayed. In the example shown in <a href="j2d-fonts.fm3.html#73488">Figure&#160;4-5</a>, the base direction is left-to-right. There are three directional runs in this example: the English text at the beginning of the sentence runs left to right, the Arabic text runs right to left, and the period runs left to right. <p>
<a name="73495"><!-- --></a>
Graphics are often embedded in the flow of text. These inline graphics behave like glyphs in terms of how they affect the text flow and line wrapping. Such inline graphics need to be positioned using the same bidirectional layout algorithm so that they appear in the proper location in the flow of characters.<p>
<a name="73496"><!-- --></a>
For more information about the precise algorithm used to order glyphs within a line, see the description of the Bidirectional Algorithm in The Unicode Standard, Version 2.0, Section 3.11.<p>
</blockquote>
<br>
<h3>
<a name="63651"><!-- --></a>
<i>4.3.3	</i> Measuring and Positioning Text
</h3>

<blockquote>
<a name="63656"><!-- --></a>
Unless you are working with a monospace font, different characters in a font have different widths. This means that all positioning and measuring of text has to take into account exactly which characters are used, not just how many. For example, to right-align a column of numbers displayed in a proportional font, you can&#39;t simply use extra spaces to position the text. To properly align the column, you need to know the exact width of each number so that you can adjust accordingly. <p>
<a name="63660"><!-- --></a>
Text is often displayed using multiple fonts and styles, such as bold or italic. In this case, even the same character can have different shapes and widths, depending on how it is styled. To properly position, measure, and render text, you need to keep track of each individual character <em>and</em> the style applied to that character. Fortunately, <kbd>TextLayout</kbd> does this for you. <p>
<a name="63663"><!-- --></a>
To properly display text in languages such as Hebrew and Arabic, each individual character needs to be measured and positioned within the context of neighboring characters. Because the shapes and positions of the characters can change depending on the context, measuring and positioning such text without taking the context into account produces unacceptable results.<p>
</blockquote>
<br>
<h3>
<a name="68590"><!-- --></a>
<i>4.3.4	</i> Supporting Text Manipulation
</h3>

<blockquote>
<a name="69042"><!-- --></a>
To allow the user to edit the text that is displayed, you must be able to:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="69045"><!-- --></a>
Display a caret that indicates where new characters will be inserted when the user enters text.
</li>
<li>
<a name="69048"><!-- --></a>
Move the caret and insertion point in response to user input.
</li>
<li>
<a name="69058"><!-- --></a>
Detect user selections (hit detection).
</li>
<li>
<a name="69243"><!-- --></a>
Highlight selected text.
</li>
</ul>
</blockquote>

<br>
<a name="68895"><!-- --></a>
<h4><i>4.3.4.1	 Displaying Carets
</i></h4>

<blockquote>
<a name="68896"><!-- --></a>
In editable text, a <em>caret</em> is used to graphically represent the current insertion point, the position in the text where new characters will be inserted. Typically, a caret is shown as a blinking vertical bar between two glyphs. New characters are inserted and displayed at the caret's location. <p>
<a name="68897"><!-- --></a>
Calculating the caret position can be complicated, particularly for bidirectional text. Insertion offsets on directional boundaries have two possible caret positions because the two glyphs that correspond to the character offset are not displayed adjacent to one another. This is illustrated in <a href="j2d-fonts.fm3.html#68918">Figure&#160;4-6</a>. In this figure, the carets are shown as square brackets to indicate the glyph to which the caret corresponds.<p>
<a name="68916"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc8.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="68918"><!-- --></a>
<b>Figure 4-6	</b> Dual Carets

</p>
</blockquote><blockquote>
<a name="68919"><!-- --></a>
Character offset 8 corresponds to the location after the _ and before the <em>A</em>. If the user enters an Arabic character, its glyph is displayed to the right of (before) the <em>A</em>; if the user enters an English character, its glyph is displayed to the right of (after) the _. <p>
<a name="73866"><!-- --></a>
To handle this situation, some systems display dual carets, a strong (primary) caret and a weak (secondary) caret. The strong caret indicates where an inserted character will be displayed when that character's direction is the same as the base direction of the text. The weak caret shows where an inserted character will be displayed when the character's direction is the opposite of the base direction. <kbd>TextLayout</kbd> automatically supports dual carets; <kbd>JTextComponent</kbd> does not.<p>
<a name="68922"><!-- --></a>
When you&#39;re working with bidirectional text, you can&#39;t simply add the widths of the glyphs before a character offset to calculate the caret position. If you did, the caret would be drawn in the wrong place, as shown in <a href="j2d-fonts.fm3.html#68932">Figure&#160;4-7</a>. <p>
<a name="68930"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc9.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="68932"><!-- --></a>
<b>Figure 4-7	</b> Caret Drawn Incorrectly

</p>
</blockquote><blockquote>
<a name="69215"><!-- --></a>
For the caret to be properly positioned, the widths of the glyphs to the left of the offset need to be added and the current context taken into account. Unless the context is taken into account, the glyph metrics won&#39;t necessarily match the display. (The context can affect which glyphs are used.)<p>
</blockquote>
<br>
<a name="73930"><!-- --></a>
<h4><i>4.3.4.2	 Moving Carets
</i></h4>

<blockquote>
<a name="73931"><!-- --></a>
All text editors allow the user to move the caret with the arrow keys. Users expect the caret to move in the direction of the pressed arrow key. In left-to-right text, moving the insertion offset is simple: the right arrow key increases the insertion offset by one and the left arrow key decreases it by one. In bidirectional text or in text with ligatures, this behavior would cause the caret to jump across glyphs at direction boundaries and move in the reverse direction within different directional runs. <p>
<a name="68945"><!-- --></a>
To move the caret smoothly through bidirectional text, you need to take into account the direction of the text runs. You can&#39;t simply increment the insertion offset when the right arrow key is pressed and decrement it when the left arrow key is pressed. If the current insertion offset is within a run of right-to-left characters, the right arrow key should decrease the insertion offset, and the left arrow key should increase it. <p>
<a name="68949"><!-- --></a>
Moving the caret across a directional boundary is even more complicated. <a href="j2d-fonts.fm3.html#68955">Figure&#160;4-8</a> illustrates what happens when a directional boundary is crossed when the user is navigating with the arrow key. Stepping three positions to the right in the displayed text corresponds to moving to the character offsets 7, 19, then 18.<p>
<a name="68953"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc10.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="68955"><!-- --></a>
<b>Figure 4-8	</b> Caret Movement

</p>
</blockquote><blockquote>
<a name="68956"><!-- --></a>
Certain glyphs should never have a caret between them; instead, the caret should move as though the glyphs represented a single character. For example, there should never be a caret between an<em> o</em> and an umlaut if they are represented by two separate characters. (See The Unicode Standard, Version 2.0, Chapter 5, for more information.)<p>
<a name="73936"><!-- --></a>
<kbd>TextLayout </kbd>provides methods<kbd> (getNextRightHit</kbd> and <kbd>getNextLeftHit</kbd>) that enable you to easily move the caret smoothly through bidirectional text. <p>
</blockquote>
<br>
<a name="68966"><!-- --></a>
<h4><i>4.3.4.3	 Hit Testing
</i></h4>

<blockquote>
<a name="69108"><!-- --></a>
Often, a location in device space must be converted to a text offset. For example, when a user clicks the mouse on selectable text, the location of the mouse is converted to a text offset and used as one end of the selection range. Logically, this is the inverse of positioning a caret. <p>
<a name="69116"><!-- --></a>
When you&#39;re working with bidirectional text, a single visual location in the display can correspond to two different offsets in the source text, as shown in <a href="j2d-fonts.fm3.html#68981">Figure&#160;4-9</a>.<p>
<a name="68979"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc11.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="68981"><!-- --></a>
<b>Figure 4-9	</b> Hit Testing Bidirectional Text

</p>
</blockquote><blockquote>
<a name="69131"><!-- --></a>
Because a single visual location can correspond to two different offsets, hit testing bidirectional text isn&#39;t just a matter of measuring glyph widths until the glyph at the correct location is found and then mapping that position back to a character offset. Detecting the side that the hit was on helps distinguish between the two alternatives. <p>
<a name="73769"><!-- --></a>
You can perform hit testing using <kbd>TextLayout.hitTestChar</kbd>. Hit information is encapsulated in a <kbd>TextHitInfo</kbd> object and includes information about the side that the hit was on. <p>
</blockquote>
<br>
<a name="68983"><!-- --></a>
<h4><i>4.3.4.4	 Highlighting Selections
</i></h4>

<blockquote>
<a name="68984"><!-- --></a>
A selected range of characters is represented graphically by a highlight region, an area in which glyphs are displayed with inverse video or against a different background color. <p>
<a name="68991"><!-- --></a>
Highlight regions, like carets, are more complicated for bidirectional text than for monodirectional text. In bidirectional text, a contiguous range of characters might not have a contiguous highlight region when displayed. Conversely, a highlight region showing a visually contiguous range of glyphs might not correspond to a single, contiguous range of characters.<p>
<a name="68992"><!-- --></a>
This results in two strategies for highlighting selections in bidirectional text:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="68993"><!-- --></a>
<em>Logical highlighting</em> &#45;&#45;with logical highlighting, the selected characters are always contiguous in the text model, and the highlight region is allowed to be discontinuous. For an example of logical highlighting, see <a href="j2d-fonts.fm3.html#69006">Figure&#160;4-10</a>.
</li>
<li>
<a name="68997"><!-- --></a>
<em>Visual highlighting</em>&#45;&#45;with visual highlighting, there might be more than one range of selected characters, but the highlight region is always contiguous. For an example of visual highlighting, see <a href="j2d-fonts.fm3.html#69012">Figure&#160;4-11</a>.
</li>
</ul>
</blockquote>
<blockquote>
<a name="69004"><!-- --></a>
 <p><center><img src="j2d-fonts.fm.anc12.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="69006"><!-- --></a>
<b>Figure 4-10	</b> Logical Highlighting (contiguous characters)

</p>
</blockquote><blockquote>
<a name="69010"><!-- --></a>
 <p><center><img src="j2d-fonts.fm.anc13.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="69012"><!-- --></a>
<b>Figure 4-11	</b> Visual Highlighting (contiguous highlight region)

</p>
</blockquote><blockquote>
<a name="74466"><!-- --></a>
Logical highlighting is simpler to implement, since the selected characters are always contiguous in the text. <p>
</blockquote>
<br>
<h3>
<a name="74467"><!-- --></a>
<i>4.3.5	</i> Performing Text Layout in a Java Application 
</h3>

<blockquote>
<a name="74473"><!-- --></a>
Depending on which Java APIs you use, you can have as little or as much control over text layout as you need:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="74474"><!-- --></a>
If you just want to display a block of text or need an editable text control, you can use <kbd>JTextComponent</kbd>, which will perform the text layout for you. JTextComponent is designed to handle the needs of most international applications and supports bidirectional text For more information about <kbd>JTextComponent</kbd>, see &#34;Using the JFC/Swing Packages&#34; in the Java Tutorial.
</li>
<li>
<a name="74475"><!-- --></a>
If you want to display a simple text string, you can call <kbd>Graphics2D.drawString</kbd> and let Java 2D lay out the string for you. You can also use <kbd>drawString</kbd> to render styled strings and strings that contain bidirectional text. For more information about rendering text through <kbd>Graphics2D</kbd>, see <a href="j2d-awt.fm4.html#68381">&#34;Rendering Graphics Primitives&#34; on page&#160;36</a>.
</li>
<li>
<a name="74476"><!-- --></a>
If you want to implement your own text editing routines, you can use <kbd>TextLayout</kbd> to manage text layout, highlighting, and hit detection. The facilities provided by <kbd>TextLayout</kbd> handle most common cases, including text strings with mixed fonts, mixed languages, and bidirectional text. For more information about using TextLayout, see <a href="j2d-fonts.fm4.html#74623">&#34;Managing Text Layout&#34; on page&#160;58</a>.
</li>
<li>
<a name="74477"><!-- --></a>
If you want total control over how text is shaped and positioned, you can construct your own <kbd>GlyphVectors</kbd> using <kbd>Font</kbd> and then render them through <kbd>Graphics2D</kbd>. For more information about implementing your own text layout mechanism, see <a href="j2d-fonts.fm5.html#66677">&#34;Implementing a Custom Text Layout Mechanism&#34; on page&#160;64</a>.
</li>
</ul>
</blockquote>
<blockquote>
<a name="74620"><!-- --></a>
Generally, you do not need to perform text layout operations yourself. For most applications, <kbd>JTextComponent</kbd> is the best solution for displaying static and editable text. However, <kbd>JTextComponent</kbd> does not support the display of dual carets or discontinuous selections in bidirectional text. If your application requires these features, or you prefer to implement your own text editing routines, you can use the Java 2D text layout APIs.<p>
<a name="74633"><!-- --></a>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm2.html">PREV</a>
 | <a href="j2d-fonts.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:22 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm3.html">PREV</a>
 | <a href="j2d-fonts.fm5.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="74623"><i>4.4	</i> Managing Text Layout
</a></h2>

<blockquote>
<a name="67703"><!-- --></a>
The<kbd> TextLayout </kbd>class supports text that contains multiple styles and characters from different writing systems, including Arabic and Hebrew. (Arabic and Hebrew are particularly difficult to display because you must reshape and reorder the text to achieve an acceptable representation.)<p>
<a name="67659"><!-- --></a>
<kbd>TextLayout</kbd> simplifies the process of displaying and measuring text even if you are working with English-only text. By using <kbd>TextLayout</kbd>, you can achieve high-quality typography with no extra effort.

<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="67656"><!-- --></a>
<blockquote><hr noshade size="1"><b>Text Layout Performance</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="68644"><!-- --></a>
<p><kbd>TextLayout</kbd> is designed so that there is no significant performance impact when it&#39;s used to display simple, monodirectional text. There is some additional processing overhead when <kbd>TextLayout</kbd> is used to display Arabic or Hebrew text. However, it&#39;s typically on the order of microseconds per character and is dominated by the execution of normal drawing code.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
<a name="65533"><!-- --></a>
The <kbd>TextLayout</kbd> class manages the positioning and ordering of glyphs for you. You can use <kbd>TextLayout</kbd> to:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="65535"><!-- --></a>
Lay out monodirectional and bidirectional text
</li>
<li>
<a name="73543"><!-- --></a>
Display and move carets 
</li>
<li>
<a name="65524"><!-- --></a>
Perform hit testing on text
</li>
<li>
<a name="65525"><!-- --></a>
Highlight text selections
</li>
</ul>
</blockquote>
<blockquote>
<a name="67682"><!-- --></a>
In some situations, you might want to compute the text layout yourself, so that you can control exactly which glyphs are used and where they are placed. Using information such as glyph sizes, kerning tables, and ligature information, you can construct your own algorithms for computing the text layout, bypassing the system&#39;s layout mechanism. For more information, see <a href="j2d-fonts.fm5.html#66677">&#34;Implementing a Custom Text Layout Mechanism&#34; on page&#160;64</a>.<p>
</blockquote>
<br>
<h3>
<a name="67652"><!-- --></a>
<i>4.4.1	</i> Laying Out Text
</h3>

<blockquote>
<a name="67708"><!-- --></a>
<kbd>TextLayout</kbd> automatically lays out text, including bidirectional (BIDI) text, with the correct shaping and ordering. To correctly shape and order the glyphs representing a line of text, <kbd>TextLayout</kbd> must know the full context of the text:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="67714"><!-- --></a>
If the text fits on a single line, such as a single-word label for a button or a line in a dialog box, you can construct a <kbd>TextLayout</kbd> directly from the text. 
</li>
<li>
<a name="67715"><!-- --></a>
If you have more text than can fit on a single line or want to break text on a single line into tabbed segments, you cannot construct a <kbd>TextLayout</kbd> directly. You must use a <kbd>LineBreakMeasurer</kbd> to provide sufficient context.
</li>
</ul>
</blockquote>
<blockquote>
<a name="67814"><!-- --></a>
The base direction of the text is normally set by an attribute (style) on the text. If that attribute is missing, <kbd>TextLayout</kbd> follows the Unicode bidirectional algorithm and derives the base direction from the initial characters in the paragraph.<p>
</blockquote>
<br>
<h3>
<a name="63814"><!-- --></a>
<i>4.4.2	</i> Displaying Dual Carets
</h3>

<blockquote>
<a name="69369"><!-- --></a>
<kbd>TextLayout</kbd> maintains caret information such as the caret <kbd>Shape</kbd>, position, and angle. You can use this information to easily display carets in both monodirectional and bidirectional text. When you&#39;re drawing carets for bidirectional text, using <kbd>TextLayout</kbd> ensures that the carets will be positioned correctly. <p>
<a name="69399"><!-- --></a>
<kbd>TextLayout</kbd> provides default caret <kbd>Shapes</kbd> and automatically supports dual carets. For italic and oblique glyphs, <kbd>TextLayout</kbd> produces angled carets, as shown in <a href="j2d-fonts.fm4.html#69408">Figure&#160;4-12</a>. These caret positions are also used as the boundaries between glyphs for highlighting and hit testing, which helps produce a consistent user experience.<p>
<a name="69406"><!-- --></a>
<p><center><img src="j2d-fonts.fm.anc4.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="69408"><!-- --></a>
<b>Figure 4-12	</b> Angled Carets

</p>
</blockquote><blockquote>
<a name="67933"><!-- --></a>
Given an insertion offset, the <kbd>getCaretShapes</kbd> method returns a two-element array of <kbd>Shapes</kbd>: element 0 contains the strong caret and element 1 contains the weak caret, if one exists. To display dual carets, you simply draw both caret <kbd>Shapes</kbd>; the carets will be automatically be rendered in the correct positions. <p>
<a name="69421"><!-- --></a>
If you want to use custom caret <kbd>Shapes</kbd>, you can retrieve the position and angle of the carets from the <kbd>TextLayout </kbd>and draw them yourself.<p>
<a name="69356"><!-- --></a>
In the following example, the default strong and weak caret <kbd>Shapes</kbd> are drawn in different colors. This is a common way to differentiate dual carets.<p>
</blockquote><blockquote><pre>
Shape[] caretShapes = layout.getCaretShapes(hit);
g2.setColor(PRIMARY_CARET_COLOR); 
g2.draw(caretShapes[0]);
if (caretShapes[1] != null){  
  g2.setColor(SECONDARY_CARET_COLOR); 
  g2.draw(caretShapes[1]); 
}
</pre></blockquote>
<br>
<h3>
<a name="74427"><!-- --></a>
<i>4.4.3	</i> Moving the Caret
</h3>

<blockquote>
<a name="74429"><!-- --></a>
You can also use<kbd> TextLayout </kbd>to determine the resulting insertion offset when a user presses the left or right arrow key. Given a <kbd>TextHitInfo</kbd> object that represents the current insertion offset, the <kbd>getNextRightHit</kbd> method returns a <kbd>TextHitInfo</kbd> object that represents the correct insertion offset if the right arrow key is pressed. The <kbd>getNextLeftHit</kbd> method provides the same information for the left arrow key. <p>
<a name="68359"><!-- --></a>
In the following example, the current insertion offset is moved in response to a right arrow key. <p>
</blockquote><blockquote><pre>
TextHitInfo newInsertionOffset = 
            layout.getNextRightHit(insertionOffset); 
if (newInsertionOffset != null) { 
  Shape[] caretShapes =   
          layout.getCaretShapes(newInsertionOffset);
  // draw carets
  ...
  insertionOffset = newInsertionOffset;
}
</pre></blockquote>
<br>
<h3>
<a name="68373"><!-- --></a>
<i>4.4.4	</i> Hit Testing
</h3>

<blockquote>
<a name="68092"><!-- --></a>
<kbd>TextLayout </kbd>provides a simple mechanism for hit testing text. The <kbd>hitTestChar</kbd> method takes <em>x</em> and <em>y</em> coordinates from the mouse as arguments and returns a <kbd>TextHitInfo</kbd> object. The <kbd>TextHitInfo</kbd> contains the insertion offset for the specified position and the side that the hit was on. The insertion offset is the offset closest to the hit: if the hit is past the end of the line, the offset at the end of the line is returned.<p>
<a name="69476"><!-- --></a>
In the following example, <kbd>hitTestChar</kbd> is called on a <kbd>TextLayout</kbd> and then <kbd>getInsertionOffset</kbd> is used to retrieve the offset.<p>
</blockquote><blockquote><pre>
TextHitInfo hit = layout.hitTestChar(x, y);
int insertionOffset = hit.getInsertionOffset();
</pre></blockquote>
<br>
<h3>
<a name="68115"><!-- --></a>
<i>4.4.5	</i> Highlighting Selections
</h3>

<blockquote>
<a name="68159"><!-- --></a>
You can get a <kbd>Shape</kbd> that represents the highlight region from the <kbd>TextLayout</kbd>. <kbd>TextLayout</kbd> automatically takes the context into account when calculating the dimensions of the highlight region. <kbd>TextLayout</kbd> supports both logical and visual highlighting.<p>
<a name="68271"><!-- --></a>
In the following example, the highlight region is filled with the highlight color and then the <kbd>TextLayout</kbd> is drawn over the filled region. This is one simple way to display highlighted text.<p>
</blockquote><blockquote><pre>
Shape highlightRegion = layout.getLogicalHighlightShape(hit1,
      hit2); 
graphics.setColor(HIGHLIGHT_COLOR); 
graphics.fill(highlightRegion); 
graphics.drawString(layout, 0, 0);
</pre></blockquote>
<br>

<h3>
<a name="63976"><!-- --></a>
<i>4.4.6	</i> Querying Layout Metrics
</h3>

<blockquote>
<a name="63978"><!-- --></a>
<kbd>TextLayout</kbd> provides access to graphical metrics for the entire range of text it represents. Metrics available from <kbd>TextLayout</kbd> include the ascent, descent, leading, advance, visible advance, and the bounding rectangle.<p>
<a name="63985"><!-- --></a>
More than one <kbd>Font</kbd> can be associated with a <kbd>TextLayout</kbd>: different style runs can use different fonts. The ascent and descent values for a <kbd>TextLayout</kbd> are the maximum values of all of the fonts used in the <kbd>TextLayout</kbd>. The computation of the <kbd>TextLayout</kbd>'s leading is more complicated; it&#39;s not just the maximum leading value.<p>
<a name="63988"><!-- --></a>
The advance of a <kbd>TextLayout</kbd> is its length: the distance from the left edge of the leftmost glyph to the right edge of the rightmost glyph. The advance is sometimes referred to as the <em>total advance</em>. The <em>visible advance</em> is the length of the <kbd>TextLayout</kbd> without its trailing whitespace.<p>
<a name="66438"><!-- --></a>
The bounding box of a <kbd>TextLayout</kbd> encloses all of the text in the layout. It includes all the visible glyphs and the caret boundaries. (Some of these might hang over the origin or origin + advance). The bounding box is relative to the origin of the <kbd>TextLayout</kbd>, not to any particular screen position. <p>
<a name="66419"><!-- --></a>
In the following example, the text in a <kbd>TextLayout</kbd> is drawn within the layout&#39;s bounding box.<p>
</blockquote><blockquote><pre>
graphics.drawString(layout, 0, 0); 
Rectangle2D bounds = layout.getBounds(); 
graphics.drawRect(bounds.getX()-1, bounds.getY()-1, 
         bounds.getWidth()+2, bounds.getHeight()+2);
</pre></blockquote>
<br>
<h3>
<a name="64005"><!-- --></a>
<i>4.4.7	</i> Drawing Text Across Multiple Lines
</h3>

<blockquote>
<a name="64007"><!-- --></a>
<kbd>TextLayout</kbd> can also be used to display a piece of text that spans multiple lines. For example, you might take a paragraph of text, line-wrap the text to a certain width, and display the paragraph as multiple lines of text. <p>
<a name="66482"><!-- --></a>
To do this, you do not directly create the <kbd>TextLayouts</kbd> that represent each line of text&#45;&#45;<kbd>LineBreakMeasurer</kbd> generates them for you. Bidirectional ordering cannot always be performed correctly unless all of the text in a paragraph is available. <kbd>LineBreakMeasurer</kbd> encapsulates enough information about the context to produce correct <kbd>TextLayouts</kbd>.<p>
<a name="64011"><!-- --></a>
When text is displayed across multiple lines, the length of the lines is usually determined by the width of the display area. Line breaking (line wrapping) is the process of determining where lines begin and end, given a graphical width in which the lines must fit. <p>
<a name="66480"><!-- --></a>
The most common strategy is to place as many words on each line as will fit. This strategy is implemented in <kbd>LineBreakMeasurer</kbd>. Other more complex line break strategies use hyphenation, or attempt to minimize the differences in line length within paragraphs. The Java 2D API does not provide implementations of these strategies.<p>
<a name="64020"><!-- --></a>
To break a paragraph of text into lines, you construct a <kbd>LineBreakMeasurer</kbd> with the entire paragraph and then call <kbd>nextLayout</kbd> to step through the text and generate <kbd>TextLayouts</kbd> for each line. <p>
<a name="64022"><!-- --></a>
To do this,<kbd> LineBreakMeasurer</kbd> maintains an offset within the text. Initially, the offset is at the beginning of the text. Each call to <kbd>nextLayout</kbd> moves the offset by the character count of the <kbd>TextLayout</kbd> that was created. When this offset reaches the end of the text, <kbd>nextLayout</kbd> returns <kbd>null</kbd>.<p>
<a name="66620"><!-- --></a>
The visible advance of each <kbd>TextLayout </kbd>that the<kbd> LineBreakMeasurer </kbd>creates doesn&#39;t exceed the specified line width. By varying the width you specify when you call <kbd>nextLayout</kbd>, you can break text to fit complicated areas, such as an HTML page with images in fixed positions or tab-stop fields. You can also pass in a <kbd>BreakIterator</kbd> to tell <kbd>LineBreakMeasurer</kbd> where valid breakpoints are; if you don't supply one the <kbd>BreakIterator</kbd> for the default locale is used. <p>
<a name="66516"><!-- --></a>
In the following example, a bilingual text segment is drawn line by line. The lines are aligned to either to the left margin or right margin, depending on whether the base text direction is left-to-right or right-to-left.<p>
</blockquote><blockquote><pre>
Point2D pen = initialPosition; 
LineBreakMeasurer measurer = new LineBreakMeasurer(styledText, 
myBreakIterator);
while (true) {
  TextLayout layout = measurer.nextLayout(wrappingWidth);
  if (layout == null) break;
    pen.y += layout.getAscent(); 
    float dx = 0;
    if (layout.isLeftToRight())
      dx = wrappingWidth - layout.getAdvance(); 
    layout.draw(graphics, pen.x + dx, pen.y); 
    pen.y += layout.getDescent() + layout.getLeading();
}
</pre></blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm3.html">PREV</a>
 | <a href="j2d-fonts.fm5.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:22 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm4.html">PREV</a>
 | <a href="j2d-fonts.fm6.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="66677"><i>4.5	</i> Implementing a Custom Text Layout Mechanism
</a></h2>

<blockquote>
<a name="67334"><!-- --></a>
The <kbd>GlyphVector</kbd> class provides a way to display the results of custom layout mechanisms. A <kbd>GlyphVector</kbd> object can be thought of as the output of an algorithm that takes a string and computes exactly how the string should be displayed. The system has a built-in algorithm and the Java 2D API lets advanced clients define their own algorithms. <p>
<a name="72890"><!-- --></a>
A <kbd>GlyphVector</kbd> object is basically an array of glyphs and glyph locations. Glyphs are used instead of characters to provide total control over layout characteristics such as kerning and ligatures. For example, when displaying the string &#34;final&#34;, you might want to replace the leading fi substring with the ligature <em>fi.</em> In this case, the <kbd>GlyphVector</kbd> object will have fewer glyphs than the number of characters in the original string.   <p>
<a name="72925"><!-- --></a>
<a href="j2d-fonts.fm5.html#67409">Figure&#160;4-13</a> and <a href="j2d-fonts.fm5.html#67469">Figure&#160;4-14</a> illustrate how <kbd>GlyphVector</kbd> objects are used by layout mechanisms. <a href="j2d-fonts.fm5.html#67409">Figure&#160;4-13</a> shows the default layout mechanism. When <kbd>drawString</kbd> is called on a <kbd>String</kbd>, the built-in layout algorithm:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="72938"><!-- --></a>
Uses the current <kbd>Font</kbd> in the <kbd>Graphics2D</kbd> context to determine which glyphs to use.
</li>
<li>
<a name="72941"><!-- --></a>
Calculates where each glyph should be placed.
</li>
<li>
<a name="72944"><!-- --></a>
Stores the resulting glyph and position information in a <kbd>GlyphVector</kbd>.
</li>
<li>
<a name="72945"><!-- --></a>
Passes the <kbd>GlyphVector</kbd> to a glyph rendering routine that does the actual drawing.<p><center><img src="j2d-fonts.fm.anc.gif"></center>
</li>
</ul>
</blockquote>

<blockquote><p>
<a name="67409"><!-- --></a>
<b>Figure 4-13	</b> Using the Built-in Layout Algorithm

</p>
</blockquote><blockquote>
<a name="67413"><!-- --></a>
<a href="j2d-fonts.fm5.html#67469">Figure&#160;4-14</a> shows the process for using a custom layout algorithm. To use a custom layout algorithm, you must assemble all of the information necessary to lay out the text. The basic process is the same:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="72962"><!-- --></a>
Using the <kbd>Font</kbd>, determine which glyphs to use 
</li>
<li>
<a name="72965"><!-- --></a>
Determine where to place the glyphs 
</li>
<li>
<a name="72968"><!-- --></a>
Store this layout information in a <kbd>GlyphVector</kbd>
</li>
</ul>
</blockquote>
<blockquote>
<a name="72970"><!-- --></a>
To render the text, you pass the <kbd>GlyphVector</kbd> to <kbd>drawString</kbd>, which in turn passes it to the glyph renderer. In <a href="j2d-fonts.fm5.html#67469">Figure&#160;4-14</a>, the custom layout algorithm replaces the fi substring with the ligature <em>fi</em>. <p><center><img src="j2d-fonts.fm.anc1.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="67469"><!-- --></a>
<b>Figure 4-14	</b> Using a Custom Layout Algorithm

</p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm4.html">PREV</a>
 | <a href="j2d-fonts.fm6.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:22 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm5.html">PREV</a>
 | <a href="j2d-image.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="74065"><i>4.6	</i> Creating Font Derivations
</a></h2>

<blockquote>
<a name="74066"><!-- --></a>
Using the <kbd>Font.deriveFont</kbd> methods, you can create a new <kbd>Font</kbd> object with different attributes from an existing <kbd>Font</kbd> object. Often, a transform is applied to the existing <kbd>Font</kbd> to create a new derived <kbd>Font</kbd>. To do this, you:<p>
</blockquote><blockquote><ol>
<li>
<a name="74067"><!-- --></a>
Create a <kbd>Font</kbd> object., 
</li>

<li>
<a name="74068"><!-- --></a>
Create the <kbd>AffineTransform</kbd> you want to apply to the <kbd>Font</kbd>. 
</li>

<li>
<a name="74069"><!-- --></a>
Call <kbd>Font.deriveFont</kbd>, passing in the <kbd>AffineTransform</kbd>.
</li>

</ol></blockquote>
<blockquote>
<a name="74070"><!-- --></a>
In this way, you could easily create a <kbd>Font</kbd> in a custom size or a skewed version of an existing <kbd>Font</kbd>.<p>
<a name="74071"><!-- --></a>
In the following code excerpt, an <kbd>AffineTransform</kbd> is applied to create a skewed version of the font Helvetica. The new derived font is then used to render a string.<p>
</blockquote><blockquote><pre>
// Create a transformation for the font.
AffineTransform fontAT = new AffineTransform();
fontAT.setToShear(-1.2, 0.0);
// Create a Font Object.
Font theFont = new Font("Helvetica", Font.PLAIN, 1);
// Derive a new font using the shear transform
theDerivedFont = theFont.deriveFont(fontAT);
// Add the derived font to the Graphics2D context
g2.setFont(theDerivedFont);
// Render a string using the derived font
g2.drawString(&#34;Java&#34;, 0.0f, 0.0f);
</pre></blockquote>

<a name="74062"><!-- --></a>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm5.html">PREV</a>
 | <a href="j2d-image.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:22 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm6.html">PREV</a>
 | <a href="j2d-fonts.fm8.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="66676"><i>4.7	</i> Managing Multilingual Text Layout
</a></h2>



<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm6.html">PREV</a>
 | <a href="j2d-fonts.fm8.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Tue Feb 24 10:24:17 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm7.html">PREV</a>
 | <a href="j2d-image.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="66677"><i>4.8	</i> Implementing a Custom Text Layout Mechanism
</a></h2>



<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm7.html">PREV</a>
 | <a href="j2d-image.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Tue Feb 24 10:24:17 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm5.html">PREV</a>
 | <a href="j2d-geom.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 
<a name="60754"><!-- --></a>
<hr size="8" width="35%" align="left" noshade>

<table border=0>
<tr valign=bottom>
<td valign=bottom>
<br>
<U><B><FONT FACE="ARIAL,HELVETICA,TIMES ROMAN">CHAPTER</FONT> 
3 
</B></U>
</td>
</tr>
</table>

<a name="61756"><!-- --> </a>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td align="left">
<h1><FONT SIZE=+4>
Geometries
</font></h1>
</td>
</tr>
</table>
<blockquote>
<a name="62717"><!-- --></a>
The Java 2D API provides several classes that define common geometric objects, such as points, lines, curves, and rectangles. These new geometry classes are part of the<kbd> java.awt.geom</kbd> package. For backward compatibility, the geometry classes that existed in previous versions of the JDK software, such as <kbd>Rectangle</kbd>, <kbd>Point</kbd>, and <kbd>Polygon</kbd>, remain in the <kbd>java.awt </kbd>package. <p>
<a name="63622"><!-- --></a>
The Java 2D API geometries such as <kbd>GeneralPath</kbd>, <kbd>Arc2D</kbd>, and <kbd>Rectangle2D</kbd> implement the <kbd>Shape</kbd> interface defined in<kbd> java.awt</kbd>. <kbd>Shape</kbd> provides a common protocol for describing and inspecting geometric path objects. A new interface, <kbd>PathIterator</kbd>, defines methods for retrieving elements from a geometry.<p>
<a name="63691"><!-- --></a>
Using the geometry classes, you can easily define and manipulate virtually any two-dimensional object. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-awt.fm5.html">PREV</a>
 | <a href="j2d-geom.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:19 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm.html">PREV</a>
 | <a href="j2d-geom.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62744"><i>3.1	</i> Interfaces and Classes
</a></h2>

<blockquote>
<a name="64157"><!-- --></a>
The following tables list the key geometry interfaces and classes. Most of these interfaces and classes are part of the <kbd>java.awt.geom</kbd> package. Some, like <kbd>Shape</kbd>, are part of the <kbd>java.awt</kbd> package, primarily to maintain backward compatibility with earlier versions of the JDK software.<p>
<a name="62349"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="62240"><!-- --></a>
<blockquote><hr noshade size="1"><b>Interface</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="62242"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="62244"><!-- --></a>
<p><code>PathIterator</code>

</td><td><a name="62612"><!-- --></a>
<p>Defines methods for retrieving elements from a path.

</td></tr>
<tr><td><a name="64151"><!-- --></a>
<p><code>Shape</code>

<a name="64154"><!-- --></a>
<p>(java.awt)

</td><td><a name="64153"><!-- --></a>
<p>Provides a common set of methods for describing and inspecting geometric path objects. Implemented by <code>GeneralPath </code>and other geometry classes.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
 <p>
<a name="63427"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="62355"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="62357"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="62363"><!-- --></a>
<p><code>Arc2D</code>

<a name="64281"><!-- --></a>
<p><code>Arc2D.Double</code>

<a name="64286"><!-- --></a>
<p><code>Arc2D.Float</code>

</td><td><a name="62621"><!-- --></a>
<p>Extends: <code>RectangularShape</code>

<a name="62622"><!-- --></a>
<p>Represents an arc defined by a bounding rectangle, start angle, angular extent, and a closure type. Implemented to specify arcs in float and double precision: <code>Arc2D.Float</code> and <code>Arc2D.Double.</code>

</td></tr>
<tr><td><a name="62372"><!-- --></a>
<p><code>Area</code>

</td><td><a name="62627"><!-- --></a>
<p>Implements: <code>Shape, Cloneable </code>

<a name="63389"><!-- --></a>
<p>Represents an area geometry that supports boolean operations.

</td></tr>
<tr><td><a name="64311"><!-- --></a>
<p><code>CubicCurve2D<br>CubicCurve2D.Double</code>

<a name="64315"><!-- --></a>
<p><code>CubicCurve2D.Float</code>

<a name="62376"><!-- --></a>
<p><code></code>

</td><td><a name="62632"><!-- --></a>
<p>Implements: <code>Shape</code>

<a name="64321"><!-- --></a>
<p>Represents a cubic parametric curve segment in (w) coordinate space. Implemented to specify cubic curves in float and double precision: <code>CubicCurve2D.Float </code>and <code>CubicCurve2D.Double.</code>

</td></tr>
<tr><td><a name="62504"><!-- --></a>
<p><code>Dimension2D</code>

</td><td><a name="62642"><!-- --></a>
<p>Encapsulates a width and height dimension. Abstract superclass for all objects that store a 2D dimension.

</td></tr>
<tr><td><a name="64336"><!-- --></a>
<p><code>Ellipse2D</code>

<a name="64339"><!-- --></a>
<p><code>Ellipse2D.Double</code>

<a name="64341"><!-- --></a>
<p><code>Ellipse2D.Float</code>

</td><td><a name="64353"><!-- --></a>
<p>Extends: <code>RectangularShape</code>

<a name="64358"><!-- --></a>
<p>Represents an ellipse defined by a bounding rectangle. Implemented to specify ellipses in float and double precision: <code>Ellipse2D.Float </code>and <code>Ellipse2D.Double.</code> 

</td></tr>
<tr><td><a name="64525"><!-- --></a>
<p>FlatteningPathIterator

</td><td><a name="64529"><!-- --></a>
<p>Returns a flattened view of a <code>PathIterator</code> object.

<a name="64530"><!-- --></a>
<p>Can be used to provide flattening behavior for <code>Shapes</code> that don&#39;t perform the interpolation calculations themselves.

</td></tr>
<tr><td><a name="62435"><!-- --></a>
<p><code>GeneralPath</code>

</td><td><a name="62653"><!-- --></a>
<p>Implements: <code>Shape</code>

<a name="62654"><!-- --></a>
<p>Represents a geometric path constructed from lines and quadratic and cubic curves.

</td></tr>
<tr><td><a name="62443"><!-- --></a>
<p><code>Line2D</code>

<a name="64370"><!-- --></a>
<p><code>Line2D.Double</code>

<a name="64375"><!-- --></a>
<p><code>Line2D.Float</code>

</td><td><a name="64386"><!-- --></a>
<p>Implements: <code>Shape</code>

<a name="62445"><!-- --></a>
<p>Represents a line segment in (x, y) coordinate space. Implemented to specify lines in float and double precision: <code>Line2D.Float </code>and <code>Line2D.Double.</code>

</td></tr>
<tr><td><a name="62451"><!-- --></a>
<p><code>Point2D</code>

<a name="64413"><!-- --></a>
<p><code>Point2D.Double</code>

<a name="64420"><!-- --></a>
<p><code>Point2D.Float</code>

</td><td><a name="62669"><!-- --></a>
<p>A point representing a location in (x,y) coordinate space. Implemented to specify points in float and double precision: <code>Point2D.Float </code>and <code>Point2D.Double.</code>

</td></tr>
<tr><td><a name="62558"><!-- --></a>
<p><code>QuadCurve2D</code>

<a name="64442"><!-- --></a>
<p><code>QuadCurve2D.Double</code>

<a name="64449"><!-- --></a>
<p><code>QuadCurve2D.Float</code>

</td><td><a name="62677"><!-- --></a>
<p>Implements: <code>Shape</code>

<a name="62678"><!-- --></a>
<p>Represents a quadratic parametric curve segment in (x, y) coordinate space. Implemented to specify quadratic curves in float and double precision: <code>QuadCurve2D.Float </code>and <code>QuadCurve2D.Double.</code>

</td></tr>
<tr><td><a name="62550"><!-- --></a>
<p><code>Rectangle2D</code>

<a name="64471"><!-- --></a>
<p><code>Rectangle2D.Double</code>

<a name="64478"><!-- --></a>
<p><code>Rectangle2D.Float</code>

</td><td><a name="62683"><!-- --></a>
<p>Extends: <code>RectangularShape</code>

<a name="62684"><!-- --></a>
<p>Represents a rectangle defined by a location (x, y) and dimension (w x h). Implemented to specify rectangles in float and double precision: <code>Rectangle2D.Float </code>and <code>Rectangle2D.Double.</code>

</td></tr>
<tr><td><a name="62538"><!-- --></a>
<p><code>RectangularShape</code>

</td><td><a name="62692"><!-- --></a>
<p>Implements: <code>Shape</code>

<a name="62693"><!-- --></a>
<p>Provides common manipulation routines for operating on shapes that have rectangular bounds. 

</td></tr>
<tr><td><a name="62534"><!-- --></a>
<p><code>RoundRectangle2D</code>

<a name="64502"><!-- --></a>
<p><code>RoundRectangle2D.Double</code>

<a name="64507"><!-- --></a>
<p><code>RoundRectangle2D.Float</code>

</td><td><a name="62699"><!-- --></a>
<p>Extends: <code>RectangularShape</code>

<a name="62700"><!-- --></a>
<p>Represents a rectangle with rounded corners defined by a location (x, y), a dimension (w x h), and the width and height of the corner arc. Implemented to specify round rectangles in float and double precision: <code>RoundRectangle2D.Float </code>and <code>RoundRectangle2D.Double.</code>

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm.html">PREV</a>
 | <a href="j2d-geom.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:19 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm1.html">PREV</a>
 | <a href="j2d-geom.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="63719"><i>3.2	</i> Geometry Concepts
</a></h2>

<blockquote>
<a name="63720"><!-- --></a>
A <kbd>Shape</kbd> is an instance of any class that implements the <kbd>Shape</kbd> interface, such as <kbd>GeneralPath</kbd> or <kbd>Rectangle2D.Float</kbd>. A <kbd>Shape</kbd>&#39;s contour (outline) is referred to as its <em>path</em>. <p>
<a name="63732"><!-- --></a>
When a <kbd>Shape</kbd> is drawn, the pen style defined by the <kbd>Stroke</kbd> object in the <kbd>Graphics2D</kbd> context is applied to the <kbd>Shape</kbd>&#39;s path. When a <kbd>Shape</kbd> is filled, the <kbd>Paint</kbd> in the <kbd>Graphics2D</kbd> context is applied to the area within its path. For more information, see <a href="j2d-awt.fm.html#70028">&#34;Rendering with Graphics2D&#34; on page&#160;15</a>.<p>
<a name="62875"><!-- --></a>
A <kbd>Shape</kbd>&#39;s path can be also used to define a <em>clipping path</em>. A clipping path determines what pixels are rendered&#45;&#45;only those pixels that lie within the area defined by the clipping path are rendered. The clipping path is part of the <kbd>Graphics2D</kbd> context. For more information, see <a href="j2d-awt.fm3.html#70241">&#34;Setting the Clipping Path&#34; on page&#160;32</a>.<p>
<a name="63725"><!-- --></a>
A <kbd>GeneralPath</kbd> is a shape that can be used to represent any two-dimensional object that can be constructed from lines and quadratic or cubic curves. For convenience,<kbd> java.awt.geom</kbd> provides additional implementations of the <kbd>Shape</kbd> interface that represent common geometric objects such as rectangles, ellipses, arcs, and curves. The Java2D API also provides a special type of shape that supports constructive area geometry. <p>
</blockquote>
<br>
<h3>
<a name="63798"><!-- --></a>
<i>3.2.1	</i> Constructive Area Geometry
</h3>

<blockquote>
<a name="63799"><!-- --></a>
Constructive Area Geometry (CAG) is the process of creating new geometric objects by performing boolean operations on existing objects. In the Java 2D API, a special type of <kbd>Shape</kbd> called an <kbd>Area</kbd> supports boolean operations. You can construct an <kbd>Area</kbd> from any <kbd>Shape</kbd>. <p>
<a name="63800"><!-- --></a>
<kbd>Areas</kbd> support the following Boolean operations:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="63801"><!-- --></a>
Union
</li>
<li>
<a name="63802"><!-- --></a>
Intersection
</li>
<li>
<a name="63803"><!-- --></a>
Subtraction
</li>
<li>
<a name="64208"><!-- --></a>
Exclusive OR (XOR)
</li>
</ul>
</blockquote>
<blockquote>
<a name="64215"><!-- --></a>
These operations are illustrated in <a href="j2d-geom.fm2.html#64217">Figure&#160;3-1</a>.<p>
<a name="64221"><!-- --></a>
<p><center><img src="j2d-geom.fm.anc.gif"></center> <p>
</blockquote>
<blockquote><p>
<a name="64217"><!-- --></a>
<b>Figure 3-1	</b> Boolean Operations

</p>
</blockquote>
<br>
<h3>
<a name="63262"><!-- --></a>
<i>3.2.2	</i> Bounds and Hit Testing
</h3>

<blockquote>
<a name="63263"><!-- --></a>
A <em>bounding box</em> is a rectangle that fully encloses a shape&#39;s geometry. Bounding boxes are used to determine whether or not an object has been selected or &#34;hit&#34; by the user. <p>
<a name="63285"><!-- --></a>
The <kbd>Shape</kbd> interface defines two methods for retrieving a shape&#39;s bounding box, <kbd>getBounds</kbd> and <kbd>getBounds2D</kbd>. The <kbd>getBounds2D</kbd> method returns a <kbd>Rectangle2D</kbd> instead of a <kbd>Rectangle</kbd>, providing a higher-precision description of the shape&#39;s bounding box.<p>
<a name="63280"><!-- --></a>
<kbd>Shape</kbd> also provides methods for determining whether or not:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="63312"><!-- --></a>
A specified point lies within the bounds of the shape (<kbd>contains</kbd>)
</li>
<li>
<a name="63313"><!-- --></a>
A specified rectangle lies totally within the bounds of the shape (<kbd>contains</kbd>)
</li>
<li>
<a name="63314"><!-- --></a>
A specified rectangle intersects the shape (<kbd>intersects</kbd>)
</li>
</ul>
</blockquote>


<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm1.html">PREV</a>
 | <a href="j2d-geom.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:19 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm2.html">PREV</a>
 | <a href="j2d-geom.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="64138"><i>3.3	</i> Combining Areas to Create New Shapes
</a></h2>

<blockquote>
<a name="64222"><!-- --></a>
<kbd>Areas</kbd> can be used to quickly construct complex <kbd>Shapes</kbd> from simple shapes such as circles and squares. To create a new complex <kbd>Shape</kbd> by combining <kbd>Areas</kbd>:<p>
</blockquote><blockquote><ol>
<li>
<a name="64139"><!-- --></a>
Using <kbd>Shapes</kbd>, construct the <kbd>Areas</kbd> to be combined.
</li>

<a name="64136"></a>
Call the appropriate Boolean operators: <kbd>add</kbd>, <kbd>subtract</kbd>, <kbd>intersect</kbd>, <kbd>exclusiveOr</kbd>.<p></ol></blockquote>
<blockquote>
<a name="64223"><!-- --></a>
For example, CAG could be used to create a pear like that shown in <kbd><a href="j2d-geom.fm3.html#64235">Figure&#160;3-2</a>.</kbd><p>
<a name="64226"><!-- --></a>
<p><center><img src="j2d-geom.fm.anc1.gif"></center> <p>
</blockquote>
<blockquote><p>
<a name="64235"><!-- --></a>
<b>Figure 3-2	</b> Pear constructed from circles

</p>
</blockquote><blockquote>
<a name="61777"><!-- --></a>
The body of the pear is constructed by performing a union operation on two overlapping <kbd>Areas</kbd>: a circle and an oval. The leaves are each created by performing an intersection on two overlapping circles and then joined into a single <kbd>Shape</kbd> through a union operation. Overlapping circles are also used to construct the stem through two subtraction operations. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm2.html">PREV</a>
 | <a href="j2d-geom.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:19 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm3.html">PREV</a>
 | <a href="j2d-fonts.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="64250"><i>3.4	</i> Creating a Custom Shape
</a></h2>

<blockquote>
<a name="61818"><!-- --></a>
You can implement the <kbd>Shape</kbd> interface to create a class that defines a new type of shape. It doesn&#39;t matter how you represent the shape internally, as long as you can implement the <kbd>Shape</kbd> interface methods. The <kbd>Shape</kbd> must be able to generate a path that specifies its contour.<p>
<a name="63526"><!-- --></a>
For example, you could create a simple implementation of <kbd>Shape</kbd> that represents polygons as arrays of points. Once the polygon is built, it could be passed to <kbd>draw</kbd>, <kbd>setClip</kbd>, or any other method that expects a <kbd>Shape</kbd> object as an argument.<p>
<a name="61819"><!-- --></a>
The <kbd>PolygonPath</kbd> class must implement the <kbd>Shape</kbd> interface methods:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="61820"><!-- --></a>
<kbd>contains</kbd>
</li>
<li>
<a name="61821"><!-- --></a>
<kbd>getBounds</kbd>
</li>
<li>
<a name="61822"><!-- --></a>
<kbd>getBounds2D</kbd>
</li>
<li>
<a name="61823"><!-- --></a>
<kbd>getPathIterator</kbd>
</li>
<li>
<a name="61824"><!-- --></a>
<kbd>intersects</kbd>
</li>
</ul>
</blockquote>
<blockquote>
<a name="64684"><!-- --></a>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-geom.fm3.html">PREV</a>
 | <a href="j2d-fonts.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:19 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm6.html">PREV</a>
 | <a href="j2d-image.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 
<a name="65659"><!-- --></a>
<hr size="8" width="35%" align="left" noshade>

<table border=0>
<tr valign=bottom>
<td valign=bottom>
<br>
<U><B><FONT FACE="ARIAL,HELVETICA,TIMES ROMAN">CHAPTER</FONT> 
5 
</B></U>
</td>
</tr>
</table>

<a name="65661"><!-- --> </a>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td align="left">
<h1><FONT SIZE=+4>
Imaging 
</font></h1>
</td>
</tr>
</table>
<blockquote>
<a name="65671"><!-- --></a>
The Java 2D API supports three imaging models<p>
</blockquote>
<blockquote>
<ul><li>
<a name="68573"><!-- --></a>
The producer/consumer (push) model provided in previous versions of the JDK software.
</li>
<li>
<a name="68580"><!-- --></a>
The immediate mode model introduced in the JDK 1.2 software release.
</li>
<li>
<a name="68578"><!-- --></a>
The pipeline (pull) model compatible with the immediate mode model and that will be fully implemented in the forthcoming Java Advanced Imaging API. 
</li>
</ul>
</blockquote>
<blockquote>
<a name="69740"><!-- --></a>
The following table contrasts the features of each of these imaging models.<p>
<a name="69746"><!-- --></a>
<p><center><img src="j2d-image.fm.anc5.gif"></center><p>
<a name="65675"><!-- --></a>
This chapter focuses on the objects and techniques of the immediate mode imaging model.   The immediate mode imaging classes and interfaces of the Java 2D API provide techniques for dealing with pixel mapped images whose data is stored in memory. This API supports accessing image data in a variety of storage formats and manipulating image data through several types of filtering operations. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-fonts.fm6.html">PREV</a>
 | <a href="j2d-image.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Nov 02 12:33:41 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm.html">PREV</a>
 | <a href="j2d-image.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62520"><i>5.1	</i> Interfaces and Classes
</a></h2>

<blockquote>
<a name="69754"><!-- --></a>
The immediate mode imaging APIs in the Java 2D API can be grouped into six categories: interfaces, image data classes, image operation classes, sample model classes, color model classes, and exceptions.<p>
</blockquote>
<br>
<h3>
<a name="69751"><!-- --></a>
<i>5.1.1	</i> Imaging Interfaces
</h3>

<blockquote>
<a name="65180"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="62752"><!-- --></a>
<blockquote><hr noshade size="1"><b>Interface</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="62754"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="62784"><!-- --></a>
<p><code>BufferedImageOp</code>

</td><td><a name="62971"><!-- --></a>
<p>Describes single-input/single-output operations performed on <code>BufferedImage</code> objects. Implemented by <code>AffineTransformOp</code>, <code>ColorConvertOp</code>, <code>ConvolveOp</code>, <code>LookupOp</code>, and <code>RescaleOp</code>.

</td></tr>
<tr><td><a name="62916"><!-- --></a>
<p><code>RasterOp </code>

</td><td><a name="62975"><!-- --></a>
<p>Defines single-input/single-output operations performed on <code>Raster</code> objects. Implemented by <code>AffineTransformOp</code>, <code>BandCombineOp</code>, <code>ColorConvertOp</code>, <code>ConvolveOp</code>, <code>LookupOp</code>, and <code>RescaleOp</code>.

</td></tr>
<tr><td><a name="64598"><!-- --></a>
<p><code>RenderedImage </code>

</td><td><a name="64600"><!-- --></a>
<p>Defines a common protocol for objects that contain or can produce image data in the form of <code>Rasters</code>. 

</td></tr>
<tr><td><a name="64640"><!-- --></a>
<p><code>WritableRenderedImage </code>

</td><td><a name="64642"><!-- --></a>
<p>Extends: <code>RenderedImage</code>

<a name="64643"><!-- --></a>
<p>Defines a common protocol for objects that contain or can produce image data in the form of <code>Rasters</code> which can be modified.

</td></tr>
<tr><td><a name="64651"><!-- --></a>
<p><code>TileObserver </code>

</td><td><a name="64656"><!-- --></a>
<p>Defines a protocol for objects that want to be notified when the modification state of a <code>WritableRenderedImage</code> changes. 

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>
<br>
<h3>
<a name="64405"><!-- --></a>
<i>5.1.2	</i> Image Data Classes
</h3>

<blockquote>
<a name="68794"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><td><a name="68733"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</td><td><a name="68735"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</td></tr>
<tr><td><a name="68737"><!-- --></a>
<p><code>BufferedImage</code>

</td><td><a name="68739"><!-- --></a>
<p>Extends: <code>Image</code>

<a name="68740"><!-- --></a>
<p>Implements: <code>WriteableRenderedImage</code>

<a name="68741"><!-- --></a>
<p>An image with an accessible data buffer. A <code>BufferedImage</code> has a <code>ColorModel</code> and a <code>Raster</code> of image data.

</td></tr>
<tr><td><a name="68743"><!-- --></a>
<p><code>ByteLookupTable</code>

</td><td><a name="68745"><!-- --></a>
<p>Extends: <code>LookupTable</code>

<a name="68746"><!-- --></a>
<p>A <code>LookupTable</code> that contains byte data. 

</td></tr>
<tr><td><a name="68748"><!-- --></a>
<p><code>DataBuffer </code>

</td><td><a name="68750"><!-- --></a>
<p>Wraps one or more data arrays holding pixel data. Each data array is called a <em>bank</em>.

</td></tr>
<tr><td><a name="68752"><!-- --></a>
<p><code>DataBufferByte </code>

</td><td><a name="68754"><!-- --></a>
<p>Extends: <code>DataBuffer</code> (Final)

<a name="68755"><!-- --></a>
<p>A data buffer that stores bytes of data. (Used in Java Advanced Imaging API)

</td></tr>
<tr><td><a name="68757"><!-- --></a>
<p><code>DataBufferInt </code>

</td><td><a name="68759"><!-- --></a>
<p>Extends: <code>DataBuffer</code> (Final)<code>)</code>

<a name="68760"><!-- --></a>
<p>A data buffer that stores integer data.(Used in Java Advanced Imaging API)

</td></tr>
<tr><td><a name="68762"><!-- --></a>
<p><code>DataBufferShort </code>

</td><td><a name="68764"><!-- --></a>
<p>Extends: <code>DataBuffer</code> (Final)

<a name="68765"><!-- --></a>
<p>A data buffer that stores short data.(Used in Java Advanced Imaging API)

</td></tr>
<tr><td><a name="68767"><!-- --></a>
<p><code>DataBufferUShort </code>

</td><td><a name="68769"><!-- --></a>
<p>Extends: <code>DataBuffer </code>(Final)

<a name="68770"><!-- --></a>
<p>A data buffer that stores unsigned short data.

</td></tr>
<tr><td><a name="68772"><!-- --></a>
<p><code>Kernel</code>

</td><td><a name="68774"><!-- --></a>
<p>A matrix that describes how an input pixel and its surrounding pixels affect the value of an output pixel in a <code>ConvolveOp</code> filtering operation.

</td></tr>
<tr><td><a name="68776"><!-- --></a>
<p><code>LookupTable</code>

</td><td><a name="68778"><!-- --></a>
<p>Extends: <code>Object</code>

<a name="68779"><!-- --></a>
<p>A table that maps values from single-banded pixel data to color values. 

</td></tr>
<tr><td><a name="68781"><!-- --></a>
<p><code>Raster </code>

</td><td><a name="68783"><!-- --></a>
<p>A rectangular array of pixels from which you can retrieve image data. A <code>Raster</code> contains a <code>DataBuffer</code> and a <code>SampleModel</code>. 

</td></tr>
<tr><td><a name="68785"><!-- --></a>
<p><code>ShortLookupTable</code>

</td><td><a name="68787"><!-- --></a>
<p>Extends: <code>LookupTable</code>

<a name="68788"><!-- --></a>
<p>A lookup table that contains short data. 

</td></tr>
<tr><td><a name="68790"><!-- --></a>
<p><code>WritableRaster </code>

</td><td><a name="68792"><!-- --></a>
<p>Extends: <code>Raster</code>

<a name="68793"><!-- --></a>
<p>A <code>Raster</code> that you can modify.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>
<br>
<h3>
<a name="68832"><!-- --></a>
<i>5.1.3	</i> Image Operation Classes
</h3>

<blockquote>
<a name="65263"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="65265"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="65267"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="64417"><!-- --></a>
<p><code>AffineTransformOp</code>

</td><td><a name="64788"><!-- --></a>
<p>Implements: <code>BufferedImageOp</code>, <code>RasterOp</code>

<a name="64817"><!-- --></a>
<p>A class that defines an affine transform to perform a linear mapping from 2D coordinates in a source <code>Image</code> or <code>Raster</code> to 2D coordinates in the destination image or <code>Raster</code>. This class can perform either bilinear or nearest neighbor affine transform operations. 

</td></tr>
<tr><td><a name="64421"><!-- --></a>
<p><code>BandCombineOp</code>

</td><td><a name="64821"><!-- --></a>
<p>Implements: <code>RasterOp</code>

<a name="64825"><!-- --></a>
<p>Using a specified matrix, this operation performs an arbitrary linear combination of bands in a <code>Raster</code>.

</td></tr>
<tr><td><a name="68838"><!-- --></a>
<p><code>BufferedImageFilter</code>

</td><td><a name="68840"><!-- --></a>
<p>Extends: <code>ImageFilter</code>

<a name="68841"><!-- --></a>
<p>An <code>ImageFilter</code> that provides a simple means of using a <kbd>BufferedImageOp</kbd> (a single-source/single-destination image operator) to filter a <code>BufferedImage</code> or <code>Raster</code>.

</td></tr>
<tr><td><a name="64429"><!-- --></a>
<p><code>ColorConvertOp</code>

</td><td><a name="64848"><!-- --></a>
<p>Implements: <code>BufferedImageOp</code>, <code>RasterOp</code>

<a name="64850"><!-- --></a>
<p>Performs a pixel-by-pixel color conversion of the data in the source image.

</td></tr>
<tr><td><a name="64433"><!-- --></a>
<p><code>ConvolveOp</code>

</td><td><a name="68443"><!-- --></a>
<p>Implements: <code>BufferedImageOp</code>, <code>RasterOp</code>

<a name="64857"><!-- --></a>
<p>Uses a <code>Kernel</code> to perform a convolution on the source image. A convolution is a spatial operation where the pixels surrounding the input pixel are multiplied by a kernel value to generate the value of the output pixel. The <code>Kernel</code> mathematically defines the relationship between the pixels in the immediate neighborhood of the input pixel and the output pixel. 

</td></tr>
<tr><td><a name="64441"><!-- --></a>
<p><code>LookupOp</code>

</td><td><a name="64882"><!-- --></a>
<p>Implements: <code>BufferedImageOp</code>, <code>RasterOp</code>

<a name="64879"><!-- --></a>
<p>Performs a lookup operation from the source to the destination. For <code>Rasters</code>, the lookup operates on sample values. For <code>BufferedImages</code>, the lookup operates on color and alpha components. 

</td></tr>
<tr><td><a name="64449"><!-- --></a>
<p><code>RescaleOp</code>

</td><td><a name="64912"><!-- --></a>
<p>Implements: <code>BufferedImageOp</code>, <code>RasterOp</code>

<a name="64914"><!-- --></a>
<p>Performs a pixel-by-pixel rescaling of the data in the source image by multiplying each pixel value by a scale factor and then adding an offset. 

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>
<br>
<h3>
<a name="64487"><!-- --></a>
<i>5.1.4	</i> Sample Model Classes
</h3>

<blockquote>
<a name="65271"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="65273"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="65275"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="64468"><!-- --></a>
<p><code>BandedSampleModel </code>

</td><td><a name="64958"><!-- --></a>
<p>Extends: <code>ComponentSampleModel</code> (Final)

<a name="64963"><!-- --></a>
<p>Provides access to image data stored with like samples stored as bands in separate banks of a <kbd>DataBuffer</kbd>. A pixel consists of one sample from each band.

</td></tr>
<tr><td><a name="64472"><!-- --></a>
<p><code>ComponentSampleModel </code>

</td><td><a name="64982"><!-- --></a>
<p>Extends: <code>SampleModel</code>

<a name="64992"><!-- --></a>
<p>Provides access to image data stored with each sample of a pixel residing in a separate element of a <code>DataBuffer</code>. Different types of pixel interleaving are supported.

</td></tr>
<tr><td><a name="68449"><!-- --></a>
<p><code>MultiPixelPackedSampleModel </code>

</td><td><a name="68451"><!-- --></a>
<p>Extends: <code>SampleModel</code>

<a name="68452"><!-- --></a>
<p>Provides access to image data stored with multiple one-sample pixels packed into one element of a <code>DataBuffer</code>. 

</td></tr>
<tr><td><a name="64476"><!-- --></a>
<p><code>PixelInterleavedSampleModel </code>

</td><td><a name="64984"><!-- --></a>
<p>Extends: <code>ComponentSampleModel</code>

<a name="68568"><!-- --></a>
<p>Provides access to image data stored with the sample data for each pixel in adjacent elements of the data array, and all elements in a single bank of a <code>DataBuffer</code>. 

</td></tr>
<tr><td><a name="64480"><!-- --></a>
<p><code>SampleModel </code>

</td><td><a name="65042"><!-- --></a>
<p>An abstract class that defines a mechanism for extracting sample data from an image without knowing how the underlying data is stored in a <code>DataBuffer</code>.

</td></tr>
<tr><td><a name="64484"><!-- --></a>
<p><code>SinglePixelPackedSampleModel </code>

</td><td><a name="64988"><!-- --></a>
<p>Extends: <code>SampleModel</code>

<a name="68911"><!-- --></a>
<p>Provides access to image data stored with all the samples belonging to an individual pixel packed into one element of a <code>DataBuffer</code>. 

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>
<br>
<h3>
<a name="64040"><!-- --></a>
<i>5.1.5	</i> Color Model Classes
</h3>

<blockquote>
<a name="69804"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="65281"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="65283"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="64227"><!-- --></a>
<p><code>ColorModel</code>

</td><td><a name="64229"><!-- --></a>
<p>Implements: <code>Transparency</code>

<a name="65085"><!-- --></a>
<p>JDK1.1 class. An abstract class that defines methods for translating from image pixel values to color components such as red, green, and blue. 

</td></tr>
<tr><td><a name="64236"><!-- --></a>
<p><code>ComponentColorModel</code>

</td><td><a name="64238"><!-- --></a>
<p>Extends: <code>ColorModel</code>

<a name="65105"><!-- --></a>
<p>A <code>ColorModel</code> that can handle an arbitrary <code>ColorSpace</code> and an array of color components to match the <code>ColorSpace</code>. This class can be used to represent most color models on most types of <code>GraphicsDevices</code>. 

</td></tr>
<tr><td><a name="64244"><!-- --></a>
<p><code>DirectColorModel</code>

</td><td><a name="65098"><!-- --></a>
<p>Extends: <code>PackedColorModel</code>

<a name="65118"><!-- --></a>
<p>JDK1.1 class. A <code>ColorModel</code> that represents pixel values that have RGB color components embedded directly in the bits of the pixel. This color model is similar to an X11 TrueColor visual. The default RGB <code>ColorModel</code> returned by <code>ColorModel</code><kbd>.</kbd><code>getRGBdefault</code> is a <code>DirectColorModel</code>.

</td></tr>
<tr><td><a name="64260"><!-- --></a>
<p><code>IndexColorModel</code>

</td><td><a name="65100"><!-- --></a>
<p>Extends: <code>ColorModel</code>

<a name="65145"><!-- --></a>
<p>JDK1.1 class. A <code>ColorModel</code> that represents pixel values that are indices into a fixed color map in the sRGB<code> ColorSpace</code>.

</td></tr>
<tr><td><a name="64264"><!-- --></a>
<p><code>PackedColorModel</code>

</td><td><a name="65102"><!-- --></a>
<p>Extends: <code>ColorModel</code>

<a name="65160"><!-- --></a>
<p>An abstract <kbd>ColorModel</kbd> that represents pixel values that have color components embedded directly in the bits of a pixel. <code>DirectColorModel</code> extends <code>PackedColorModel</code> to support pixels that contain RGB color components. 

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>
<br>
<h3>
<a name="68512"><!-- --></a>
<i>5.1.6	</i> Exception Classes
</h3>

<blockquote>
<a name="69810"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="68484"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="68486"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="68488"><!-- --></a>
<p><code>ImagingOpException</code>

</td><td><a name="68490"><!-- --></a>
<p>Extends: <kbd>RuntimeException</kbd>

<a name="68491"><!-- --></a>
<p>Thrown if one of the BufferedImageOp or RasterOp filter methods can&#39;t process the image.

</td></tr>
<tr><td><a name="68493"><!-- --></a>
<p><code>RasterFormatException</code>

</td><td><a name="68495"><!-- --></a>
<p>Extends: <kbd>RuntimeException</kbd>

<a name="68496"><!-- --></a>
<p>Thrown if there is invalid layout information in the Raster.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm.html">PREV</a>
 | <a href="j2d-image.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Nov 02 12:33:41 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm1.html">PREV</a>
 | <a href="j2d-image.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="64209"><i>5.2	</i> Immediate Mode Imaging Concepts
</a></h2>

<blockquote>
<a name="65688"><!-- --></a>
The immediate mode imaging model supports fixed-resolution images stored in memory. The model also supports filtering operations on image data. A number of classes and interfaces are used in this model.<p>
<a name="65861"><!-- --></a>
<p><center><img src="j2d-image.fm.anc6.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="65690"><!-- --></a>
<b>Figure 5-1	</b> <kbd>BufferedImage</kbd> and supporting classes

</p>
</blockquote><blockquote>
<a name="69065"><!-- --></a>
As shown in <a href="j2d-image.fm2.html#65690">Figure&#160;5-1</a>, <kbd>BufferedImage</kbd> provides general image management. A <kbd>BufferedImage</kbd> can be created directly in memory and used to hold and manipulate image data retrieved from a file or URL. A <kbd>BufferedImage</kbd> can be displayed using any <kbd>Graphics2D</kbd> object for a screen device, or rendered to any other destination using appropriate <kbd>Graphics2D</kbd> context. A <kbd>BufferedImage</kbd> object contains two other objects: a <kbd>Raster</kbd> and a <kbd>ColorModel</kbd>. <p>
<a name="65692"><!-- --></a>
The <kbd>Raster</kbd> class provides image data management. It represents the rectangular coordinates of the image, maintains image data in memory, and provides a mechanism for creating multiple subimages from a single image data buffer. It also provides methods for accessing specific pixels within an image. A Raster object contains two other objects, a <kbd>DataBuffer</kbd> and a <kbd>SampleModel</kbd>.   <p>
<a name="65694"><!-- --></a>
The <kbd>DataBuffer</kbd> class holds pixel data in memory. <p>
<a name="65696"><!-- --></a>
The <kbd>SampleModel</kbd> class interprets data in the buffer and provides it as individual pixels or rectangular ranges of pixels. <p>
<a name="65698"><!-- --></a>
The <kbd>ColorModel</kbd> class provides a color interpretation of pixel data provided by the image&#39;s sample model. <p>
<a name="67352"><!-- --></a>
The image package provides additional classes that define filtering operations on <kbd>BufferedImage</kbd> and <kbd>Raster</kbd> objects. Each image processing operation is embodied in a class that implements the <kbd>BufferedImageOp</kbd> interface, the <kbd>RasterOp</kbd> interface, or both interfaces. The operation class defines <kbd>filter</kbd> methods that performs the actual image manipulation. <p>
<a name="67356"><!-- --></a>
<a href="j2d-image.fm2.html#67384">Figure&#160;5-2</a> illustrates the basic model for Java 2D API image processing: <p>
<a name="67382"><!-- --></a>
<p><center><img src="j2d-image.fm.anc.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="67384"><!-- --></a>
<b>Figure 5-2	</b> Image Processing Model

</p>
</blockquote><blockquote>
<a name="67385"><!-- --></a>
The operations supported include:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="67386"><!-- --></a>
Affine transformation
</li>
<li>
<a name="67387"><!-- --></a>
Amplitude scaling
</li>
<li>
<a name="67388"><!-- --></a>
Lookup-table modification
</li>
<li>
<a name="67389"><!-- --></a>
Linear combination of bands
</li>
<li>
<a name="67390"><!-- --></a>
Color conversion
</li>
<li>
<a name="67391"><!-- --></a>
Convolution
</li>
</ul>
</blockquote>
<blockquote>
<a name="67350"><!-- --></a>
Note that if you&#39;re interested just in displaying and manipulating images, you only need to understand the <kbd>BufferedImage</kbd> class and the filtering operation classes. On the other hand, if you&#39;re planning to write filters or otherwise directly access image data, you&#39;ll need to understand the classes associated with <kbd>BufferedImage</kbd>. <p>
</blockquote>
<br>
<h3>
<a name="65725"><!-- --></a>
<i>5.2.1	</i> Terminology
</h3>

<blockquote>
<a name="65727"><!-- --></a>
Here are some terms used throughout the following discussions: <p>
<a name="65758"><!-- --></a>
Data Elements: primitive types used as units of storage of image data. Data elements are individual members of a <kbd>DataBuffer</kbd> array.   The layout of elements in the data buffer is independent of the interpretation of the data as pixels by an image&#39;s <kbd>SampleModel</kbd>.<p>
<a name="65729"><!-- --></a>
Samples: distinct members of the pixels of an image. A <kbd>SampleModel</kbd> provides a mechanism for converting elements in the <kbd>DataBuffer</kbd> to pixels and their samples.   The samples of a pixel may represent primary values in a particular color model. For example, a pixel in an RGB color model consists of three samples: red, green, and blue. <p>
<a name="69136"><!-- --></a>
Components: values of pixels independent of color interpretation. The distinction between component and sample is useful with <kbd>IndexColorModel</kbd>, where pixel components are indexes into the <kbd>LookupTable</kbd>.<p>
<a name="65731"><!-- --></a>
Band: the set of all samples of one type in an image, such as all red samples or all green samples. Pixel data can be stored in a number of ways, the two supported in the Java 2D API being banded and pixel interleaved. Banded storage organizes image data by bands, and a pixel is made up of sample data from the same position in each band. Pixel interleaved storage organizes image data by pixels, with a single array containing all pixels, and bands consisting of the set of samples at the same index position in each pixel.<p>
<a name="65733"><!-- --></a>
Primaries: distinct members of a color value in a specific color model; for example the RGB model forms color values from the primaries red, green, and blue. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm1.html">PREV</a>
 | <a href="j2d-image.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Nov 02 12:33:41 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm2.html">PREV</a>
 | <a href="j2d-image.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="66504"><i>5.3	</i> Using BufferedImages
</a></h2>

<blockquote>
<a name="66506"><!-- --></a>
The <kbd>BufferedImage</kbd> class is the main class supporting the immediate imaging mode. It manages an image in memory, providing ways to store pixel data, interpret pixel data, and to render the pixel data to a <kbd>Graphics</kbd> or <kbd>Graphics2D</kbd> context. <p>
</blockquote>
<br>
<h3>
<a name="66509"><!-- --></a>
<i>5.3.1	</i> Creating a BufferedImage
</h3>

<blockquote>
<a name="67919"><!-- --></a>
To create a <kbd>BufferedImage</kbd>, call the <kbd>Component.createImage</kbd> method; this returns a <kbd>BufferedImage</kbd> whose drawing characteristics match those of the component used to create it&#45;&#45;the created image is opaque, has the foreground and background colors of the <kbd>Component</kbd>, and you can&#39;t adjust the transparency of the image. You could use this technique when you want to do double buffered drawing for animation in a component; the discussion <a href="j2d-image.fm3.html#67210">&#34;Drawing in an Offscreen Buffer&#34; on page&#160;78</a> gives more details. <p>
</blockquote><blockquote><pre>    
public Graphics2D createDemoGraphics2D(Graphics g) {
	Graphics2D g2 = null;
	int width = getSize().width;
	int height = getSize().height;
	
	if (offImg == null || offImg.getWidth() != width ||
					offImg.getHeight() != height) {
		offImg = (BufferedImage) createImage(width, height);
	}         
	
	if (offImg != null) {
		g2 = offImg.createGraphics();
		g2.setBackground(getBackground());
	}
	
	// .. clear canvas ..        
	g2.clearRect(0, 0, width, height);
	
	return g2;   
}</pre></blockquote><blockquote>
<a name="66519"><!-- --></a>
You can also create a blank <kbd>BufferedImage</kbd> in memory using one of several constructor methods provided. <p>
</blockquote>
<br>
<h3>
<a name="66525"><!-- --></a>
<i>5.3.2	</i> Drawing in an Offscreen Buffer
</h3>

<blockquote>
<a name="67511"><!-- --></a>
The <kbd>BufferedImage</kbd> class can be used to prepare graphic elements offscreen then copy them to the screen. This technique is especially useful when a graphic is complex or used repeatedly. For example, if you want to display a complicated shape several times, you could draw it once into an offscreen buffer and then copy it to different locations in the window. By drawing the shape once and copying it, you can display the graphics more quickly. <p>
<a name="67512"><!-- --></a>
The <kbd>java.awt</kbd> package facilitates the use of offscreen buffers by letting you draw to an <kbd>Image</kbd> object the same way that you draw to a window. All of the Java 2D API rendering features can be used when drawing to offscreen images. <p>
<a name="67516"><!-- --></a>
Offscreen buffers are often used for animation. For example, you could use an offscreen buffer to draw an object once and then move it around in a window. Similarly, you could use an offscreen buffer to provide feedback as a user moves a graphic using the mouse. Instead of redrawing the graphic at every mouse location, you could draw the graphic once to an offscreen buffer, and then copy it to the mouse location as the user drags the mouse.<a href="#67519"><sup>1</sup></a><p>
<a name="67523"><!-- --></a>
<p><center><img src="j2d-image.fm.anc7.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="67525"><!-- --></a>
<b>Figure 5-3	</b> Using an Offscreen Buffer

</p>
</blockquote><blockquote>
<a name="67529"><!-- --></a>
<a href="j2d-image.fm3.html#67525">Figure&#160;5-3</a> demonstrates how a program can draw to an offscreen image and then copy that image into a window multiple times. The last time the image is copied, it is transformed. Note that transforming the image instead of redrawing it with the transformation might produce unsatisfactory results.<p>
</blockquote>
<br>
<a name="67530"><!-- --></a>
<h4><i>5.3.2.1	 Creating an Offscreen Buffer
</i></h4>

<blockquote>
<a name="67531"><!-- --></a>
The simplest way to create an image that you can use as an offscreen buffer is to use the <kbd>Component</kbd>.<kbd>createImage</kbd> method.<p>
<a name="67532"><!-- --></a>
By creating an image whose color space, depth, and pixel layout exactly match the window into which you are drawing, the image can be efficiently blitted to a graphics device. This allows <kbd>drawImage</kbd> to do its job quickly.<p>
<a name="67533"><!-- --></a>
You can also construct a<kbd> BufferedImage </kbd>object directly to use as an offscreen buffer. This is useful when you need control over the offscreen image&#39;s type or transparency. <p>
<a name="67534"><!-- --></a>
<kbd>BufferedImage</kbd> supports several predefined image types:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="67535"><!-- --></a>
<kbd>TYPE_3BYTE_BGR</kbd>
</li>
<li>
<a name="67536"><!-- --></a>
<kbd>TYPE_4BYTE_ABGR</kbd>
</li>
<li>
<a name="67537"><!-- --></a>
<kbd>TYPE_4BYTE_ABGR_PRE</kbd>
</li>
<li>
<a name="69224"><!-- --></a>
<kbd>TYPE_BYTE_BINARY</kbd>
</li>
<li>
<a name="69228"><!-- --></a>
<kbd>TYPE_BYTE_GRAY</kbd>
</li>
<li>
<a name="69238"><!-- --></a>
<kbd>TYPE_BYTE_INDEXED</kbd>
</li>
<li>
<a name="67539"><!-- --></a>
<kbd>TYPE_CUSTOM</kbd>
</li>
<li>
<a name="69260"><!-- --></a>
<kbd>TYPE_INT_ARGB_PRE</kbd>
</li>
<li>
<a name="67540"><!-- --></a>
<kbd>TYPE_INT_ARGB</kbd>
</li>
<li>
<a name="69264"><!-- --></a>
<kbd>TYPE_INT_BGR</kbd>
</li>
<li>
<a name="69274"><!-- --></a>
<kbd>TYPE_INT_RGB</kbd>
</li>
<li>
<a name="69284"><!-- --></a>
<kbd>TYPE_USHORT_555_RGB</kbd>
</li>
<li>
<a name="69288"><!-- --></a>
<kbd>TYPE_USHORT_565_RGB</kbd>
</li>
<li>
<a name="69268"><!-- --></a>
<kbd>TYPE_INT_GRAY</kbd>
</li>
</ul>
</blockquote>
<blockquote>
<a name="69324"><!-- --></a>
A <kbd>BufferedImage</kbd> object can contain an alpha channel. In <a href="j2d-image.fm3.html#67525">Figure&#160;5-3</a>, an alpha channel is used to distinguish painted and unpainted areas, allowing an irregular shape to appear over graphics that have already been painted (in this case, a shaded rectangle). In other cases, you might use alpha channel to blend the colors of the new image into those in the existing image. <p>
<a name="69325"><!-- --></a>
Note: unless you need alpha image data for transparency, as with the irregularly shaped images shown in Figure 5-2, you should avoid creating an off-screen buffer with alpha. Using alpha where it&#39;s unnecessary slows rendering performance. <p>
<a name="67543"><!-- --></a>
<kbd>GraphicsConfiguration</kbd> provides convenience methods that automatically create buffered images in a format compatible with your configuration. You can also query the graphics configuration associated with the graphics device on which the window resides to get the information you need to construct a compatible <kbd>BufferedImage</kbd> object. <p>
</blockquote>
<br>
<a name="67210"><!-- --></a>
<h4><i>5.3.2.2	 Drawing in an Offscreen Buffer
</i></h4>

<blockquote>
<a name="66527"><!-- --></a>
To draw in a buffered image, you call its <kbd>BufferedImage.createGraphics</kbd> method, which returns a <kbd>Graphics2D</kbd> object. With this object, you can call all of the <kbd>Graphics2D</kbd> methods to draw graphics primitives, place text, and render other images in the image. This drawing technique supports dithering and other enhancements provided by the 2D imaging package. The following code illustrates the use of offscreen buffering:<p>
</blockquote><blockquote><pre>    
public void update(Graphics g){
	Graphics2D g2 = (Graphics2D)g;
	if(firstTime){
		Dimension dim = getSize();
		int w = dim.width;
		int h = dim.height;
		area = new Rectangle(dim);
		bi = (BufferedImage)createImage(w, h);
		big = bi.createGraphics();
		rect.setLocation(w/2-50, h/2-25);
		big.setStroke(new BasicStroke(8.0f));
		firstTime = false;
	}        
	
	// Clears the rectangle that was previously drawn.
	big.setColor(Color.white);
	big.clearRect(0, 0, area.width, area.height);
	
	// Draws and fills the newly positioned rectangle to the buffer.
	big.setPaint(strokePolka);
	big.draw(rect);
	big.setPaint(fillPolka);
	big.fill(rect);
	
	// Draws the buffered image to the screen.
	g2.drawImage(bi, 0, 0, this);
}
</pre></blockquote>
<br>
<h3>
<a name="67504"><!-- --></a>
<i>5.3.3	</i> Manipulating BufferedImage Data Directly
</h3>

<blockquote>
<a name="67505"><!-- --></a>
In addition to drawing directly in a <kbd>BufferedImage</kbd>, you can directly access and manipulate the image&#39;s pixel data in a couple of ways. These are useful if you&#39;re implementing the <kbd>BufferedImageOp</kbd> filtering interface, as described in <a href="j2d-image.fm8.html#63208">&#34;Image Processing and Enhancement&#34; on page&#160;83</a>. <p>
<a name="66543"><!-- --></a>
You can use the <kbd>BufferedImage</kbd>.<kbd>setRGB</kbd> methods to directly set the value of a pixel or a pixel array to a specific RGB value. Note that no dithering is performed when you modify pixels directly. You can also manipulate pixel data by manipulating a <kbd>WritableRaster</kbd> object associated with a <kbd>BufferedImage</kbd> (see<a href="j2d-image.fm4.html#66674">&#34;Managing and Manipulating Rasters&#34; on page&#160;79</a>). <p>
</blockquote>
<br>
<h3>
<a name="66550"><!-- --></a>
<i>5.3.4	</i> Filtering a BufferedImage
</h3>

<blockquote>
<a name="66611"><!-- --></a>
You can apply a filtering operation to a <kbd>BufferedImage</kbd> using an object that implements <kbd>BufferedImageOp</kbd> interface. Filtering and the classes that provide this filtering interface are discussed in <a href="j2d-image.fm8.html#63208">&#34;Image Processing and Enhancement&#34; on page&#160;83</a>. <p>
</blockquote>
<br>
<h3>
<a name="66557"><!-- --></a>
<i>5.3.5	</i> Rendering a BufferedImage
</h3>

<blockquote>
<a name="66559"><!-- --></a>
To render a buffered image into a specific context, call one of the <kbd>drawImage</kbd> method of the context&#39;s <kbd>Graphics</kbd> object. For example, when rendering within a <kbd>Component</kbd>.<kbd>paint</kbd> method, you call <kbd>drawImage</kbd> on the graphics object passed to the method. <p>
</blockquote><blockquote><pre>    
public void paint(Graphics g) {

	if (getSize().width &lt;= 0 || getSize().height &lt;= 0)
		return;  
	Graphics2D g2 = (Graphics2D) g;
	
	if (offImg != null &amp;&amp; isShowing())  {
		g2.drawImage(offImg, 0, 0, this);
	} 
}

</pre></blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm2.html">PREV</a>
 | <a href="j2d-image.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Nov 02 12:33:41 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm3.html">PREV</a>
 | <a href="j2d-image.fm5.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="66674"><i>5.4	</i> Managing and Manipulating Rasters 
</a></h2>

<blockquote>
<a name="66676"><!-- --></a>
A <kbd>BufferedImage</kbd> object uses a <kbd>Raster</kbd> to manage its rectangular array of pixel data. The <kbd>Raster</kbd> class defines fields for the image&#39;s coordinate system&#45;&#45;width, height, and origin. A <kbd>Raster</kbd> object itself uses two objects to manage the pixel data, a <kbd>DataBuffer</kbd> and a <kbd>SampleModel</kbd>. The <kbd>DataBuffer</kbd> is the object that stores pixel data for the raster (as described on <a href="j2d-image.fm5.html#69487">page&#160;81</a>), and the <kbd>SampleModel</kbd> provides the interpretation of pixel data from the <kbd>DataBuffer</kbd> (as described on <a href="j2d-image.fm6.html#66873">page&#160;81</a>). <p>
</blockquote>
<br>
<h3>
<a name="67258"><!-- --></a>
<i>5.4.1	</i> Creating a Raster
</h3>

<blockquote>
<a name="67259"><!-- --></a>
In most cases, you don&#39;t need to create a <kbd>Raster</kbd> directly, since one is supplied with any <kbd>BufferedImage</kbd> that you create in memory. However, one of the <kbd>BufferedImage</kbd> constructor methods allows you to create a <kbd>Raster</kbd> by passing in a <kbd>WritableRaster</kbd>. <p>
<a name="67264"><!-- --></a>
The <kbd>Raster</kbd> class provides a number of static factory methods for creating <kbd>Rasters</kbd> with the <kbd>DataBuffers</kbd> and <kbd>SampleModels</kbd> you specify. You can use these factories when implementing <kbd>RasterOp</kbd> filtering classes.<p>
</blockquote>
<br>
<h3>
<a name="66680"><!-- --></a>
<i>5.4.2	</i> Parent and Child Rasters
</h3>

<blockquote>
<a name="66682"><!-- --></a>
The <kbd>Raster</kbd> class incorporates the concept of parent and child rasters. This can improve storage efficiency by allowing you to construct any number of buffered images from the same parent. The parent and its children all refer to the same data buffer, and each child has a specific offset and bounds to identify its image location in the buffer. A child identifies its ownership through its <kbd>getParent</kbd> method. <p>
<a name="67257"><!-- --></a>
To create a subraster, you use the <kbd>Raster</kbd>.<kbd>createSubRaster</kbd> method.When you create a subraster, you identify the area of its parent that it covers and its offset from the parent&#39;s origin. <p>
</blockquote>
<br>
<h3>
<a name="66687"><!-- --></a>
<i>5.4.3	</i> Operations on a Raster
</h3>

<blockquote>
<a name="66698"><!-- --></a>
The <kbd>Raster</kbd> class defines a number of ways to access pixels and pixel data. These are useful when you&#39;re implementing the <kbd>RasterOp</kbd> interface, which provides raster-level filtering and manipulation of image data, or when implementing any method that needs to perform low-level pixel manipulation.<p>
<a name="66703"><!-- --></a>
The <kbd>Raster.getPixel</kbd> methods let you get an individual pixel, which is returned as individual samples in an array. The <kbd>Raster</kbd>.<kbd>getDataElements</kbd> methods return a specified run of uninterpreted image data from the <kbd>DataBuffer</kbd>. The <kbd>Raster</kbd>.<kbd>getSample</kbd> method returns samples of an individual pixel. The <kbd>getSamples</kbd> method returns a band for a particular region of an image.<p>
<a name="69483"><!-- --></a>
In addition to these methods, you can also access the data buffer and the sample model through instance variables of the <kbd>Raster</kbd> class. These objects provide additional ways to access and interpret the <kbd>Raster</kbd>&#39;s pixel data. <p>
</blockquote>
<br>
<h3>
<a name="69484"><!-- --></a>
<i>5.4.4	</i> The WritableRaster Subclass
</h3>

<blockquote>
<a name="69485"><!-- --></a>
The <kbd>WritableRaster</kbd> subclass provides methods for setting pixel data and samples. The <kbd>Raster</kbd> associated with a <kbd>BufferedImage</kbd> is actually a <kbd>WritableRaster</kbd>, thus providing full access to manipulate its pixel data.<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm3.html">PREV</a>
 | <a href="j2d-image.fm5.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Nov 02 12:33:41 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm4.html">PREV</a>
 | <a href="j2d-image.fm6.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="69487"><i>5.5	</i> Image Data and DataBuffers
</a></h2>

<blockquote>
<a name="66743"><!-- --></a>
The <kbd>DataBuffer</kbd> belonging to a <kbd>Raster</kbd> represents an array of image data. When you create a <kbd>Raster</kbd> directly or through the <kbd>BufferedImage</kbd> constructors, you specify a width and height in pixels, along with a <kbd>SampleModel</kbd> for the image data. This information is used to create a <kbd>DataBuffer</kbd> of the appropriate data type and size. <p>
<a name="66745"><!-- --></a>
There are three subclasses of <kbd>DataBuffer</kbd>, each representing a different type of data element: <p>
</blockquote>
<blockquote>
<ul><li>
<a name="69504"><!-- --></a>
<kbd>DataBufferByte</kbd> (represents 8-bit values) 
</li>
<li>
<a name="69505"><!-- --></a>
<kbd>DataBufferInt</kbd> (represents 32-bit values) 
</li>
<li>
<a name="69508"><!-- --></a>
<kbd>DataBufferShort</kbd> (represents 16-bit values) 
</li>
<li>
<a name="69512"><!-- --></a>
<kbd>DataBufferUShort</kbd> (represents unsigned short values) 
</li>
</ul>
</blockquote>
<blockquote>
<a name="66749"><!-- --></a>
As defined earlier, elements are the discrete members of the array of the data buffer, and components or samples are the discrete values that together make up a pixel. There can be various mappings between a particular type of element in a <kbd>DataBuffer</kbd> and a particular type of pixel represented by a <kbd>SampleModel</kbd>. It is the responsibility of the various <kbd>SampleModel</kbd> subclasses to implement that mapping and provide a way to get specific pixels from a specific <kbd>DataBuffer</kbd>. <p>
<a name="66755"><!-- --></a>
<kbd>DataBuffer</kbd> constructors provide ways to create buffers of a specific size and a specific number of banks. <p>
<a name="66772"><!-- --></a>
While you can access image data in a <kbd>DataBuffer</kbd> directly, it&#39;s generally easier and more convenient to do so through the methods of the <kbd>Raster</kbd> and <kbd>WritableRaster</kbd> classes. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm4.html">PREV</a>
 | <a href="j2d-image.fm6.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Nov 02 12:33:41 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm5.html">PREV</a>
 | <a href="j2d-image.fm7.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="66873"><i>5.6	</i> Extracting Pixel Data from a SampleModel
</a></h2>

<blockquote>
<a name="66874"><!-- --></a>
The abstract <kbd>SampleModel</kbd> class defines methods for extracting samples of an image without knowing how the underlying data is stored. The class provides fields for tracking the height and width of the image data in the associated <kbd>DataBuffer</kbd>, and for describing the number of bands and the data type of that buffer.   <kbd>SampleModel</kbd> methods provide image data as a collection of pixels, with each pixel consisting of a number of samples or components. <p>
<a name="66875"><!-- --></a>
The <kbd>java.awt.image</kbd> package provides five types of sample models:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="69534"><!-- --></a>
<kbd>ComponentSampleModel</kbd>&#45;&#45;used to extract pixels from images that store sample data in separate data array elements in one bank of a <kbd>DataBuffer</kbd>.
</li>
<li>
<a name="66876"><!-- --></a>
<kbd>BandedSampleModel</kbd>&#45;&#45;used to extract pixels from images that store each sample in a separate data element with bands stored in a sequence of data elements
</li>
<li>
<a name="69565"><!-- --></a>
<kbd>PixelInterleavedSampleModel</kbd>&#45;&#45;used to extract pixels from images that store each sample in a separate data element with pixels stored in a sequence of data elements.
</li>
<li>
<a name="66878"><!-- --></a>
<kbd>MultiPixelPackedSampleModel</kbd>&#45;&#45;used to extract pixels from single banded images that store multiple one-sample pixels in one data element.
</li>
<li>
<a name="66879"><!-- --></a>
<kbd>SinglePixelPackedSampleModel</kbd>&#45;&#45;used to extract samples from images that store sample data for a single pixel in one data array element in the first bank of a <kbd>DataBuffer</kbd>. 
</li>
</ul>
</blockquote>
<blockquote>
<a name="67744"><!-- --></a>
Pixel data presented by the <kbd>SampleModel</kbd> may or may not correlate directly to a color data representation of a particular color model, depending on the data source. For example, in photographic image data, the samples may represent RGB data. In image data from a medical imaging device, samples can represent different types of data such as temperature or bone density. <p>
<a name="66957"><!-- --></a>
There are three categories of methods for accessing image data. The <kbd>getPixel</kbd> methods return a whole pixel as an array, with one entry for each sample. The <kbd>getDataElement</kbd> methods provide access to the raw, uninterpreted data stored in the <kbd>DataBuffer</kbd>. The <kbd>getSample</kbd> methods provide access to pixel components for a specific band. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm5.html">PREV</a>
 | <a href="j2d-image.fm7.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Nov 02 12:33:41 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm6.html">PREV</a>
 | <a href="j2d-image.fm8.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="67775"><i>5.7	</i> ColorModels and Color Data
</a></h2>

<blockquote>
<a name="67781"><!-- --></a>
In addition to the <kbd>Raster</kbd> object for managing image data, the <kbd>BufferedImage</kbd> class includes a <kbd>ColorModel</kbd> for interpreting that data as color pixel values. The abstract <kbd>ColorModel</kbd> class defines methods for turning an image&#39;s pixel data into a color value in its associated <kbd>ColorSpace</kbd>. <p>
<a name="69584"><!-- --></a>
The <kbd>java.awt.image</kbd> package provides four types of color models:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="67777"><!-- --></a>
<kbd>PackedColorModel</kbd>&#45;&#45;An abstract <kbd>ColorModel</kbd> that represents pixel values that have color components embedded directly in the bits of an integer pixel. A <kbd>DirectColorModel</kbd> is a subclass of <kbd>PackedColorModel</kbd>.
</li>
<li>
<a name="63444"><!-- --></a>
<kbd>DirectColorModel</kbd>&#45;&#45;a <kbd>ColorModel</kbd> that represents pixel values that have RGB color components embedded directly in the bits of the pixel itself. <kbd>DirectColorModel</kbd> model is similar to an X11 TrueColor visual.
</li>
<li>
<a name="67801"><!-- --></a>
<kbd>ComponentColorModel</kbd>&#45;&#45;a <kbd>ColorModel</kbd> that can handle an arbitrary <kbd>ColorSpace</kbd> and an array of color components to match the <kbd>ColorSpace</kbd>. 
</li>
<li>
<a name="67802"><!-- --></a>
<kbd>IndexColorModel</kbd>&#45;&#45;a <kbd>ColorModel</kbd> that represents pixel values that are indices into a fixed color map in the sRGB color space.
</li>
</ul>
</blockquote>
<blockquote>
<a name="67788"><!-- --></a>
<kbd>ComponentColorModel</kbd> and <kbd>PackedColorModel</kbd> are new in the JDK 1.2 software release.<p>
<a name="67061"><!-- --></a>
Based on data in the <kbd>DataBuffer</kbd>, the <kbd>SampleModel</kbd> provides the <kbd>ColorModel</kbd> with a pixel, which the <kbd>ColorModel</kbd> then interprets as a color. <p>
</blockquote>
<br>
<h3>
<a name="65329"><!-- --></a>
<i>5.7.1	</i> Lookup Table
</h3>

<blockquote>
<a name="67100"><!-- --></a>
A lookup table contains data for one or more channels or image components; for example, separate arrays for R, G, and B. The <kbd>java.awt.image</kbd> package defines two types of lookup tables that extend the abstract <kbd>LookupTable</kbd> class, one that contains byte data and one that contains short data (<kbd>ByteLookupTable</kbd> and <kbd>ShortLookupData</kbd>).<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm6.html">PREV</a>
 | <a href="j2d-image.fm8.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Nov 02 12:33:41 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm7.html">PREV</a>
 | <a href="j2d-color.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="63208"><i>5.8	</i> Image Processing and Enhancement
</a></h2>

<blockquote>
<a name="61818"><!-- --></a>
The image package provides a pair of interfaces that define operations on <kbd>BufferedImage</kbd> and <kbd>Raster</kbd> objects: <kbd>BufferedImageOp</kbd> and <kbd>RasterOp</kbd>. <p>
<a name="69607"><!-- --></a>
The classes that implement these interfaces include <kbd>AffineTransformOp</kbd>, <kbd>BandCombineOp, ColorConvertOp, ConvolveOp</kbd>, <kbd>LookupOp, RescaleOp</kbd>. These classes can be used to geometrically transform, blur, sharpen, enhance contrast, threshold, and color correct images. <p>
<a name="72067"><!-- --></a>
<a href="j2d-image.fm8.html#72082">Figure&#160;5-4</a> illustrates edge detection and enhancement, an operation that emphasizes sharp changes in intensity within an image. Edge detection is commonly used in medical imaging and mapping applications. Edge detection is used to increase the contrast between adjacent structures in an image, allowing the viewer to discriminate greater detail.<p>
</blockquote><blockquote><pre><p><center><img src="j2d-image.fm.anc1.gif"></center></pre></blockquote>
<blockquote><p>
<a name="72082"><!-- --></a>
<b>Figure 5-4	</b> Edge detection and enhancement

</p>
</blockquote><blockquote>
<a name="72085"><!-- --></a>
The following code illustrates edge detection:<p>
</blockquote><blockquote><pre>
float[] elements = { 0.0f, -1.0f, 0.0f,
		    -1.0f,  4.f, -1.0f,
		     0.0f, -1.0f, 0.0f};
...

BufferedImage bimg = new 
BufferedImage(bw,bh,BufferedImage.TYPE_INT_RGB);
Kernel kernel = new Kernel(3, 3, elements);
ConvolveOp cop = new ConvolveOp(kernel, ConvolveOp.EDGE_NO_OP, null);
cop.filter(bi,bimg);
</pre></blockquote><blockquote>
<a name="71959"><!-- --></a>
<a href="j2d-image.fm8.html#67831">Figure&#160;5-5</a> demonstrates lookup table manipulation. A lookup operation can be used to alter individual components of a pixel.<p><center><img src="j2d-image.fm.anc2.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="67831"><!-- --></a>
<b>Figure 5-5	</b> Lookup-table Manipulation

</p>
</blockquote><blockquote>
<a name="72086"><!-- --></a>
The following code demonstrates Lookup-table manipulation:<p>
</blockquote><blockquote><pre>	
byte reverse[] = new byte[256];
for (int j=0; j&lt;200; j++){
        reverse[j]=(byte)(256-j);}	  
ByteLookupTable blut=new ByteLookupTable(0, reverse);
LookupOp lop = new LookupOp(blut, null);
lop.filter(bi,bimg);
</pre></blockquote><blockquote>
<a name="72032"><!-- --></a>
<a href="j2d-image.fm8.html#72115">Figure&#160;5-6</a> illustrates rescaling. Rescaling can increase or decrease the intensity of all points. Rescaling can be used to increase the dynamic range of an otherwise neutral image, bringing out detail in a region that appears neutral or flat. <p>
<a name="72114"><!-- --></a>
<p><center><img src="j2d-image.fm.ancA6.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="72115"><!-- --></a>
<b>Figure 5-6	</b> Rescaling

</p>
</blockquote><blockquote>
<a name="72128"><!-- --></a>
The following code snippet illustrates rescaling:<p>
</blockquote><blockquote><pre>	
RescaleOp rop = new RescaleOp(1.5f, 1.0f, null);
rop.filter(bi,bimg);</pre></blockquote>
<br>
<h3>
<a name="61900"><!-- --></a>
<i>5.8.1	</i> Using an Image Processing Operation
</h3>

<blockquote>
<a name="72236"><!-- --></a>
Convolution is the process that underlies most spatial filtering algorithms. Convolution is the process of weighting or averaging the value of each pixel in an image with the values of neighboring pixels.This allows each output pixel to be affected by the immediate neighborhood in a way that can be mathematically specified with a kernel. <a href="j2d-image.fm8.html#72247">Figure&#160;5-7</a> illustrates Convolution.<p>
<a name="72256"><!-- --></a>
<p><center><img src="j2d-image.fm.anc8.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="72247"><!-- --></a>
<b>Figure 5-7	</b> Blurring with Convolution

</p>
</blockquote><blockquote>
<a name="72257"><!-- --></a>
The following code fragment illustrates how to use one of the image processing classes, <kbd>ConvolveOp</kbd>. In this example, each pixel in the source image is averaged equally with the eight pixels that surround it.<p>
</blockquote><blockquote><pre>
float weight = 1.0f/9.0f;
float[] elements = new float[9]; // create 2D array

// fill the array with nine equal elements
for (i = 0; i &lt; 9; i++) {
	elements[i] = weight;}
	
// use the array of elements as argument to create a Kernel
private Kernel myKernel = new Kernel(3, 3, elements);
public ConvolveOp simpleBlur = new ConvolveOp(myKernel);

// sourceImage and destImage are instances of BufferedImage
simpleBlur.filter(sourceImage,&#160;destImage) // blur the image</pre></blockquote><blockquote>
<a name="61906"><!-- --></a>
The variable simpleBlur contains a new instance of <kbd>ConvolveOp</kbd> that implements a blur operation on a <kbd>BufferedImage </kbd>or a <kbd>Raster</kbd>. Suppose that sourceImage and destImage are two instances of <kbd>BufferedImage</kbd>. When you call <kbd>filter</kbd>, the core method of the <kbd>ConvolveOp</kbd> class, it sets the value of each pixel in the destination image by averaging the corresponding pixel in the source image with the eight pixels that surround it.<p>
<a name="69780"><!-- --></a>
The convolution kernel in this example could be represented by the following matrix, with elements specified to four significant figures:<p><center><img src="j2d-image.fm.anc3.gif"></center><p>
<a name="72275"><!-- --></a>
When an image is convolved, the value of each pixel in the destination image is calculated by using the kernel as a set of weights to average the pixel&#39;s value with the values of surrounding pixels. This operation is performed on each channel of the image. <p>
<a name="61912"><!-- --></a>
The following formula shows how the weights in the kernel are associated with the pixels in the source image when the convolution is performed. Each value in the kernel is tied to a spatial position in the image. <p><center><img src="j2d-image.fm.anc4.gif"></center><p>
<a name="61916"><!-- --></a>
The value of a destination pixel is the sum of the products of the weights in the kernel multiplied by the value of the corresponding source pixel. For many simple operations, the kernel is a matrix that is square and symmetric, and the sum of its weights adds up to one.<a href="#61919"><sup>1</sup></a><p>
<a name="61920"><!-- --></a>
The convolution kernel in this example is relatively simple. It weights each pixel from the source image equally. By choosing a kernel that weights the source image at a higher or lower level, a program can increase or decrease the intensity of the destination image. The <kbd>Kernel</kbd> object, which is set in the <kbd>ConvolveOp</kbd> constructor, determines the type of filtering that is performed. By setting other values, you can perform other types of convolutions, including blurring (such as Gaussian blur, radial blur, and motion blur), sharpening, and smoothing operations. <a href="j2d-image.fm8.html#72165">Figure&#160;5-8</a> illustrates sharpening using Convolution.<p>
<a name="72156"><!-- --></a>
<p><center><img src="j2d-image.fm.anc9.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="72165"><!-- --></a>
<b>Figure 5-8	</b> Sharpening with Convolution

</p>
</blockquote><blockquote>
<a name="72302"><!-- --></a>
The following code snippet illustrates sharpening with Convolution:<p>
</blockquote><blockquote><pre>
float[] elements = { 0.0f, -1.0f, 0.0f,
		    -1.0f,  5.f, -1.0f,
		     0.0f, -1.0f, 0.0f};
...

Kernel kernel = new Kernel(3,3,elements);
ConvolveOp cop = new ConvolveOp(kernel, ConvolveOp.EDGE_NO_OP, null);	
cop.filter(bi,bimg);</pre></blockquote><blockquote>
<a name="67839"><!-- --></a>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-image.fm7.html">PREV</a>
 | <a href="j2d-color.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Nov 02 12:33:41 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API: 1 - 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-preface.fm.html">PREV</a>
 | <a href="j2d-intro.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 
<a name="60754"><!-- --></a>
<hr size="8" width="35%" align="left" noshade>

<table border=0>
<tr valign=bottom>
<td valign=bottom>
<br>
<U><B><FONT FACE="ARIAL,HELVETICA,TIMES ROMAN">CHAPTER</FONT> 
1 
</B></U>
</td>
</tr>
</table>

<a name="62980"><!-- --> </a>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td align="left">
<h1><FONT SIZE=+4>
Java<sup>TM</sup> 2D API Overview
</font></h1>
</td>
</tr>
</table>
<blockquote>
<a name="62975"><!-- --></a>
The Java<sup>TM</sup> 2D API enhances the graphics, text, and imaging capabilities of the Abstract Windowing Toolkit (AWT), enabling the development of richer user interfaces and new types of Java applications. <p>
<a name="61788"><!-- --></a>
Along with these richer graphics, font, and image APIs, the Java 2D API supports enhanced color definition and composition, hit detection on arbitrary geometric shapes and text, and a uniform rendering model for printers and display devices.<p>
<a name="61790"><!-- --></a>
The Java 2D API also enables the creation of advanced graphics libraries, such as CAD-CAM libraries and graphics or imaging special effects libraries, as well as the creation of image and graphic file read/write filters. <p>
<a name="62464"><!-- --></a>
When used in conjunction with the Java Media Framework and other Java Media APIs, the Java 2D APIs can be used to create and display animations and other multimedia presentations. The Java Animation and Java Media Framework APIs rely on the Java 2D API for rendering support. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-preface.fm.html">PREV</a>
 | <a href="j2d-intro.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Thu Jun 11 14:30:12 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API: 1 - 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm.html">PREV</a>
 | <a href="j2d-intro.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="61793"><i>1.1	</i> Enhanced Graphics, Text, and Imaging
</a></h2>

<blockquote>
<a name="62206"><!-- --></a>
Early versions of the AWT provided a simple rendering package suitable for rendering common HTML pages, but not full-featured enough for complex graphics, text, or imaging. As a simplified rendering package, the early AWT embodied specific cases of more general rendering concepts. The Java 2D API provides a more flexible, full-featured rendering package by expanding the AWT to support more general graphics and rendering operations.<p>
<a name="62878"><!-- --></a>
For example, through the <kbd>Graphics</kbd> class you can draw rectangles, ovals, and polygons. <kbd>Graphics2D</kbd> enhances the concept of geometric rendering by providing a mechanism for rendering virtually any geometric shape. Similarly, with the Java 2D API you can draw styled lines of any width and fill geometric shapes with virtually any texture. <p>
<a name="62964"><!-- --></a>
Geometric shapes are provided through implementations of the <kbd>Shape</kbd> interface, for example <kbd>Rectangle2D</kbd> and <kbd>Ellipse2D</kbd>. Curves and arcs are also specific implementations of <kbd>Shape</kbd>.<p>
<a name="62938"><!-- --></a>
Fill and pen styles are provided through implementations of the <kbd>Paint</kbd> and <kbd>Stroke</kbd> interfaces, for example <kbd>BasicStroke</kbd>, <kbd>GradientPaint</kbd>, <kbd>TexturePaint</kbd>, and <kbd>Color</kbd>. <p>
<a name="62939"><!-- --></a>
<kbd>AffineTransform</kbd> defines linear transformations of 2D coordinates, including scale, translate, rotate, and shear.<p>
<a name="62940"><!-- --></a>
Clip regions are defined by the same implementations of the <kbd>Shape</kbd> interface that are used to define general clipping regions, for example <kbd>Rectangle2D</kbd> and <kbd>GeneralPath</kbd>. <p>
<a name="62960"><!-- --></a>
Color composition is provided by implementations of the <kbd>Composite</kbd> interface, for example <kbd>AlphaComposite</kbd>. <p>
<a name="62961"><!-- --></a>
A <kbd>Font</kbd> is defined by collections of <kbd>Glyphs</kbd>, which are in turn defined by individual <kbd>Shapes</kbd>. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm.html">PREV</a>
 | <a href="j2d-intro.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Thu Jun 11 14:30:12 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API: 1 - 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm1.html">PREV</a>
 | <a href="j2d-intro.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="61830"><i>1.2	</i> Rendering Model
</a></h2>

<blockquote>
<a name="65374"><!-- --></a>
The basic graphics rendering model has not changed with the addition of the Java 2D APIs. To render a graphic, you set up the graphics context and invoke a rendering method on the <kbd>Graphics </kbd>object. <p>
<a name="65379"><!-- --></a>
The Java 2D API class <kbd>Graphics2D</kbd> extends <kbd>Graphics</kbd> to support more graphics attributes and provide new rendering methods. Setting up a <kbd>Graphics2D</kbd> context is described in <a href="j2d-awt.fm.html#70028">&#34;Rendering with Graphics2D&#34; on page&#160;15</a>.<p>
<a name="61854"><!-- --></a>
The Java 2D API automatically compensates for differences in rendering devices and provides a uniform rendering model across different types of devices. At the application level, the rendering process is the same whether the target rendering device is a display or a printer.<p>
</blockquote>
<br>
<h3>
<a name="61857"><!-- --></a>
<i>1.2.1	</i> Coordinate Systems
</h3>

<blockquote>
<a name="61859"><!-- --></a>
The Java 2D API maintains two coordinate systems: <p>
</blockquote>
<blockquote>
<ul><li>
<a name="65480"><!-- --></a>
 <em>User space</em> is a device-independent, logical coordinate system. Applications use this coordinate system exclusively; all geometries passed into Java 2D rendering routines are specified in user space. 
</li>
<li>
<a name="63132"><!-- --></a>
<em>Device spac</em>e is a device-dependent coordinate system that varies according to the target rendering device. 
</li>
</ul>
</blockquote>
<blockquote>
<a name="66049"><!-- --></a>
The Java 2D system automatically performs the necessary conversions between user space and the device space of the target rendering device. Although the coordinate system for a monitor is very different from the coordinate system for a printer, these differences are invisible to applications.<p>
</blockquote>
<br>
<a name="65471"><!-- --></a>
<h4><i>1.2.1.1	 User Space 
</i></h4>

<blockquote>
<a name="63158"><!-- --></a>
As shown in <a href="j2d-intro.fm2.html#61866">Figure&#160;1-1</a>, the user space origin is located in the upper-left corner of the space, with <em>x</em> values increasing to the right and <em>y</em> values increasing downward.<p><center><img src="j2d-intro.fm.anc.gif"></center><p>
</blockquote>
<blockquote><p>
<a name="61866"><!-- --></a>
<b>Figure 1-1	</b> User Space Coordinate System

</p>
</blockquote><blockquote>
<a name="63182"><!-- --></a>
User space represents a uniform abstraction of all possible device coordinate systems. The device space for a particular device might have the same origin and direction as user space, or it might be different. Regardless, user space coordinates are automatically transformed into the appropriate device space when a graphic object is rendered. Often, the underlying platform device drivers are used to perform this conversion. <p>
</blockquote>
<br>
<a name="63193"><!-- --></a>
<h4><i>1.2.1.2	 Device Space
</i></h4>

<blockquote>
<a name="61870"><!-- --></a>
The Java 2D API defines three levels of configuration information that are maintained to support the conversion from user space to device space. This information is encapsulated by three classes:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="61872"><!-- --></a>
<kbd>GraphicsEnviron</kbd>ment
</li>
<li>
<a name="61873"><!-- --></a>
<kbd>GraphicsDevice</kbd>
</li>
<li>
<a name="61874"><!-- --></a>
<kbd>GraphicsConfiguration</kbd>
</li>
</ul>
</blockquote>
<blockquote>
<a name="61876"><!-- --></a>
The <kbd>GraphicsEnvironment</kbd> describes the collection of rendering devices visible to a Java application on a particular platform. Rendering devices include screens, printers, and image buffers. The <kbd>GraphicsEnvironment</kbd> also includes a list of all of the available fonts on the platform. <p>
<a name="63198"><!-- --></a>
A <kbd>GraphicsDevice</kbd> describes an application-visible rendering device, such as a screen or printer. Each possible configuration of the device is represented by a <kbd>GraphicsConfiguration</kbd>. For example, an SVGA display device can operate in several modes: 640x480x16 colors, 640x480x256 colors, and 800x600x256 colors. The SVGA screen is represented by a <kbd>GraphicsDevice </kbd>object and each of the modes is represented by a <kbd>GraphicsConfiguration</kbd> object.<p>
<a name="63248"><!-- --></a>
A <kbd>GraphicsEnvironment</kbd> can contain one or more <kbd>GraphicsDevices</kbd>; in turn, each <kbd>GraphicsDevice</kbd> can have one or more <kbd>GraphicsConfigurations</kbd>.<p>
<a name="63244"><!-- --></a>
Between them, the <kbd>GraphicsEnvironment</kbd>, <kbd>GraphicsDevice</kbd>, and <kbd>GraphicsConfiguration</kbd> represent all of the information necessary for locating a rendering device or font on the Java platform and for converting coordinates from user space to device space. An application can access this information, but does not need to perform any transformations between user space and device space.<p>
</blockquote>
<br>
<h3>
<a name="61888"><!-- --></a>
<i>1.2.2	</i> Transforms
</h3>

<blockquote>
<a name="63314"><!-- --></a>
The Java 2D API has a unified coordinate transformation model. All coordinate transformations, including transformations from user to device space, are represented by <kbd>AffineTransform</kbd> objects. <kbd>AffineTransform</kbd> defines the rules for manipulating coordinates using matrices. <p>
<a name="63322"><!-- --></a>
You can add an <kbd>AffineTransform</kbd> to the graphics context to rotate, scale, translate, or shear a geometric shape, text, or image when it is rendered. The added transform is applied to any graphic object rendered in that context. The transform is performed when user space coordinates are converted to device space coordinates.<p>
</blockquote>
<br>
<h3>
<a name="61894"><!-- --></a>
<i>1.2.3	</i> Fonts
</h3>

<blockquote>
<a name="65521"><!-- --></a>
A string is commonly thought of in terms of the characters that comprise the string. When a string is drawn, its appearance is determined by the font that is selected. However, the shapes that the font uses to display the string don&#39;t always correspond to individual characters. For example, in professional publishing, certain combinations of two or more characters are often replaced by a single shape called a <em>ligature</em>.<p>
<a name="65522"><!-- --></a>
The shapes that a font uses to represent the characters in the string are called <em>glyphs</em>. A font might represent a character such as a lowercase <em>a</em> acute using multiple glyphs, or represent certain character combinations such as the <em>fi</em> in final with a single glyph. In the Java 2D API, a glyph is simply a <kbd>Shape</kbd> that can be manipulated and rendered in the same way as any other <kbd>Shape</kbd>. <p>
<a name="65523"><!-- --></a>
A <em>font</em> can be thought of as a collection of glyphs. A single font might have many versions, such as heavy, medium, oblique, gothic, and regular. These different versions are called <em>faces</em>. All of the faces in a font have a similar typographic design and can be recognized as members of the same <em>family</em>. In other words, a collection of glyphs with a particular style forms a font face, a collection of font faces forms a font family, and a collection of font families forms the set of fonts available within a particular <kbd>GraphicsEnvironment</kbd>. <p>
<a name="61900"><!-- --></a>
In the Java 2D API, fonts are specified by a name that describes a particular font face&#45;&#45;for example, Helvetica Bold. This is different from the JDK 1.1 software, in which fonts are described by logical names that map onto different font faces depending on which font faces are available on a particular platform. For backward compatibility, the Java 2D API supports the specification of fonts by logical name as well as by font face name. <p>
<a name="61904"><!-- --></a>
Using the Java 2D API, you can compose and render strings that contain multiple fonts of different families, faces, sizes, and even languages. The appearance of the text is kept logically separate from the layout of the text. <kbd>Font</kbd> objects are used to describe the appearance, and the layout information is stored in <kbd>TextLayout</kbd> and <kbd>TextAttributeSet</kbd> objects. Keeping the font and layout information separate makes it easier to use the same fonts in different layout configurations.<p>
</blockquote>
<br>
<h3>
<a name="61906"><!-- --></a>
<i>1.2.4	</i> Images
</h3>

<blockquote>
<a name="61908"><!-- --></a>
Images are collections of pixels organized spatially. A <em>pixel</em> defines the appearance of an image at a single display location. A two-dimensional array of pixels is called a <em>raster</em>. <p>
<a name="65775"><!-- --></a>
The pixel&#39;s appearance can be defined directly or as an index into a color table for the image. <p>
<a name="65776"><!-- --></a>
In images that contain many colors (more than 256), the pixels usually directly represent the color, alpha, and other display characteristics for each screen location. Such images tend to be much larger than indexed-color images, but they look more realistic. <p>
<a name="61918"><!-- --></a>
In an indexed-color image, the colors in the image are limited to the colors specified in the color table, often resulting in fewer colors that can be used in the image. However, an index typically requires less storage space than a color value, so images stored as a set of indexed colors are usually smaller. This pixel format is popular for images that contain only 16 or 256 colors.<p>
<a name="61929"><!-- --></a>
Images in the Java 2D API have two primary components: <p>
</blockquote>
<blockquote>
<ul><li>
<a name="63396"><!-- --></a>
The raw image data (the pixels)
</li>
<li>
<a name="65780"><!-- --></a>
The information necessary for interpreting the pixels
</li>
</ul>
</blockquote>
<blockquote>
<a name="65789"><!-- --></a>
The rules for interpreting the pixel are encapsulated by a <kbd>ColorModel</kbd> object&#45;&#45;for example, whether the values should be interpreted as direct or indexed colors. For a pixel to be displayed, it must be paired with a color model. <p>
<a name="65813"><!-- --></a>
A band is one component of the color space for an image. For example, the Red, Green, and Blue components are the bands in an RGB image. A pixel in a direct color model image can be thought of as a collection of band values for a single screen location. <p>
<a name="65816"><!-- --></a>
The <kbd>java.awt.image</kbd> package contains several <kbd>ColorModel</kbd> implementations, including those for packed and component pixel representations. <p>
<a name="65790"><!-- --></a>
A <kbd>ColorSpace</kbd> object encapsulates the rules that govern how a set of numeric measurements corresponds to a particular color. The <kbd>ColorSpace</kbd> implementations in the <kbd>java.awt.color</kbd> represent the most popular color spaces, including RGB and gray scale. Note that a color space is not a collection of colors&#45;&#45;it defines the rules for how to interpret individual color values.<p>
<a name="61933"><!-- --></a>
Separating the color space from the color model provides greater flexibility in how colors are represented and converted from one color representation to another.<p>
</blockquote>
<br>
<h3>
<a name="61939"><!-- --></a>
<i>1.2.5	</i> Fills and Strokes
</h3>

<blockquote>
<a name="65822"><!-- --></a>
With the Java 2D API, you can render <kbd>Shapes</kbd> using different pen styles and fill patterns. Because text is ultimately represented by a set of glyphs, text strings can also be stroked and filled. <p>
<a name="65866"><!-- --></a>
Pen styles are defined by objects that implement the <kbd>Stroke</kbd> interface. Strokes enable you to specify different widths and dashing patterns for lines and curves.<p>
<a name="61943"><!-- --></a>
Fill patterns are defined by objects that implement the <kbd>Paint</kbd> interface. The <kbd>Color</kbd> class, which was available in earlier versions of the AWT, is a simple type of <kbd>Paint</kbd> object used to define solid-color fills. The Java 2D API provides two additional <kbd>Paint</kbd> implementations, <kbd>TexturePaint</kbd> and <kbd>GradientPaint</kbd>. <kbd>TexturePaint</kbd> defines a fill pattern using a simple image fragment that is repeated uniformly. <kbd>GradientPaint</kbd> defines a fill pattern as a gradient between two colors.<p>
<a name="65867"><!-- --></a>
In Java 2D, rendering a shape&#39;s outline and filling the shape with a pattern are two separate operations:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="65874"><!-- --></a>
Using one of the <kbd>draw</kbd> methods renders the shape&#39;s contour or outline using the pen style specified by the <kbd>Stroke</kbd> attribute and the fill pattern specified by the <kbd>Paint</kbd> attribute.
</li>
<li>
<a name="65871"><!-- --></a>
Using the <kbd>fill</kbd> method fills the interior of the shape with the pattern specified by the <kbd>Paint</kbd> attribute.
</li>
</ul>
</blockquote>
<blockquote>
<a name="61947"><!-- --></a>
When a text string is rendered, the current <kbd>Paint</kbd> attribute is applied to the glyphs that form the string. Note, however, that <kbd>drawString</kbd> actually fills the glyphs that are rendered. To stroke the outlines of the glyphs in a text string, you need to get the outlines and render them as shapes using the <kbd>draw</kbd> method.<p>
</blockquote>
<br>
<h3>
<a name="63573"><!-- --></a>
<i>1.2.6	</i> Composites
</h3>

<blockquote>
<a name="61958"><!-- --></a>
When you render an object that overlaps an existing object, you need to determine how to combine the colors of the new object with the colors that already occupy the area where you are going to draw. The Java 2D API encapsulates rules for how to combine colors in a <kbd>Composite</kbd> object. <p>
<a name="63588"><!-- --></a>
Primitive rendering systems provide only basic Boolean operators for combining colors. For example, a Boolean compositing rule might allow the source and destination color values to be ANDed, ORed, or XORed. There are several problems with this approach<p>
</blockquote>
<blockquote>
<ul><li>
<a name="63619"><!-- --></a>
It&#39;s not &#34;human friendly&#34;&#45;&#45;it&#39;s difficult to think in terms of what the resulting color will be if red and blue are ANDed, not added. 
</li>
<li>
<a name="63622"><!-- --></a>
Boolean composition does not support the accurate composition of colors in different color spaces. 
</li>
<li>
<a name="63628"><!-- --></a>
Straight Boolean composition doesn&#39;t take into account the color models of the colors. For example, in an indexed color model, the result of a Boolean operation on two pixel values in an image is the composite of two indices, not two colors.
</li>
</ul>
</blockquote>
<blockquote>
<a name="61960"><!-- --></a>
The Java 2D API avoids these pitfalls by implementing alpha-blending<a href="#66182"><sup>1</sup></a> rules that take color model information into account when compositing colors.   An <kbd>AlphaComposite</kbd> object includes the color model of both the source and destination colors.<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm1.html">PREV</a>
 | <a href="j2d-intro.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Thu Jun 11 14:30:12 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API: 1 - 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm2.html">PREV</a>
 | <a href="j2d-intro.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="61978"><i>1.3	</i> 	Backward Compatibility and Platform Independence
</a></h2>

<blockquote>
<a name="61980"><!-- --></a>
The Java 2D API maintains backward compatibility with JDK 1.1 software.   It is also architected so that applications can maintain platform-independence.<p>
</blockquote>
<br>
<h3>
<a name="63962"><!-- --></a>
<i>1.3.1	</i> Backward Compatibility
</h3>

<blockquote>
<a name="61985"><!-- --></a>
To ensure backward compatibility, the functionality of existing JDK graphics and imaging classes and interfaces was maintained. Existing features were not removed and no package designations were changed for existing classes. The Java 2D API enhances the functionality of the AWT by implementing new methods in existing classes, extending existing classes, and adding new classes and interfaces that don&#39;t affect the legacy APIs.<p>
<a name="61987"><!-- --></a>
For example, much of the Java 2D API functionality is delivered through an expanded graphics context, <kbd>Graphics2D</kbd>. To provide this extended graphics context while maintaining backward compatibility, <kbd>Graphics2D</kbd> extends the <kbd>Graphics</kbd> class from the JDK 1.1 release.<p>
<a name="63834"><!-- --></a>
The usage model of the graphics context remains unchanged. The AWT passes a graphics context to an AWT <kbd>Component</kbd> through the following methods:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="63835"><!-- --></a>
<kbd>paint</kbd>
</li>
<li>
<a name="61997"><!-- --></a>
<kbd>paintAll</kbd>
</li>
<li>
<a name="61998"><!-- --></a>
<kbd>update</kbd>
</li>
<li>
<a name="61999"><!-- --></a>
<kbd>print</kbd>
</li>
<li>
<a name="62839"><!-- --></a>
<kbd>printAll</kbd>
</li>
<li>
<a name="62840"><!-- --></a>
<kbd>getGraphics</kbd>
</li>
</ul>
</blockquote>
<blockquote>
<a name="62841"><!-- --></a>
A JDK 1.1 applet interprets the graphics context that&#39;s passed in as an instance of <kbd>Graphics</kbd>. To gain access to the new features implemented in <kbd>Graphics2D, </kbd>a Java 2D API&#45;compatible applet casts the graphics context to a <kbd>Graphics2D</kbd> object:<p>
</blockquote><blockquote><pre>public void Paint (Graphics g) {	Graphics2D g2 = (Graphics2D) g;	...	...	g2.setTransform (t);}</pre></blockquote><blockquote>
<a name="62013"><!-- --></a>
In some cases, rather than extending a legacy class, the Java 2D API generalizes it. Two techniques were used to generalize legacy classes:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="63864"><!-- --></a>
One or more parent classes were inserted in the hierarchy, and the legacy class was updated to extend the new parent classes. This technique is used to add general implemented methods and instance data to the legacy class. 
</li>
<li>
<a name="63880"><!-- --></a>
One or more interface implementations were added to the legacy class. This technique is used to add general abstract methods to the legacy class. 
</li>
</ul>
</blockquote>
<blockquote>
<a name="63895"><!-- --></a>
For example, the Java 2D API generalizes the AWT <kbd>Rectangle</kbd> class using both of these techniques. The hierarchy for rectangle now looks like:<p>
</blockquote><blockquote><pre>java.lang.object|+-------java.awt.geom.RectangularShape             |             +---------java.awt.geom.Rectangle2D                               |                               +-------java.awt.Rectangle</pre></blockquote><blockquote>
<a name="62856"><!-- --></a>
In the JDK 1.1 software, <kbd>Rectangle</kbd> simply extended <kbd>Object</kbd>. It now extends the new <kbd>Rectangle2D</kbd> class and implements both <kbd>Shape</kbd> and <kbd>Serializable</kbd>. Two parent classes were added to the <kbd>Rectangle </kbd>hierarchy: <kbd>RectangularShape</kbd> and <kbd>Rectangle2D</kbd>. Applets written for JDK 1.1 software are unaware of the new parent classes and interface implementations, but are unaffected because <kbd>Rectangle</kbd> still contains the methods and members that were present in earlier versions.<p>
<a name="62031"><!-- --></a>
The Java 2D API adds several new classes and interfaces that are &#34;orthogonal&#34; to the legacy API. These additions do not extend or generalize existing classes&#45;&#45;they are entirely new and distinct. These new classes and interfaces embody concepts that had no explicit representation in the legacy API. <p>
<a name="63955"><!-- --></a>
For example, the Java 2D API implements several new <kbd>Shape</kbd> classes, including <kbd>Arc2D</kbd>, <kbd>CubicCurve2D</kbd>, and <kbd>QuadCurve2D</kbd>. Although early versions of the AWT could render arcs using the <kbd>drawArc</kbd> and <kbd>fillArc</kbd> methods, there was no general curve abstraction and no discrete classes that embodied arcs. These discrete classes could be added to the Java 2D API without disrupting legacy applets because <kbd>drawArc</kbd> and <kbd>fillArc</kbd> are still supported through the <kbd>Graphics</kbd> class.<p>
</blockquote>
<br>
<h3>
<a name="63963"><!-- --></a>
<i>1.3.2	</i> Platform Independence
</h3>

<blockquote>
<a name="62033"><!-- --></a>
To enable the development of platform-independent applications, the Java 2D API makes no assumptions about the resolution, color space, or color model of the target rendering device. Nor does the Java 2D API assume any particular image file format. <p>
<a name="63973"><!-- --></a>
Truly platform-independent fonts are possible only when the fonts are built-in (provided as part of the JDK software), or when they are mathematically or programmatically generated. The Java 2D API does not currently support built-in or mathematically generated fonts, but it does enable the programmatic definition of entire fonts through their glyph set. Each glyph can in turn be defined by a <kbd>Shape</kbd> that consists of line segments and curves. Many fonts of particular styles and sizes can be derived from a single glyph set. <p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm2.html">PREV</a>
 | <a href="j2d-intro.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Thu Jun 11 14:30:12 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API: 1 - 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm3.html">PREV</a>
 | <a href="j2d-awt.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62037"><i>1.4	</i> The Java 2D API Packages
</a></h2>

<blockquote>
<a name="62039"><!-- --></a>
The Java 2D API classes are organized into the following packages:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="62041"><!-- --></a>
<kbd>java.awt</kbd>
</li>
<li>
<a name="66198"><!-- --></a>
<kbd>java.awt.geom</kbd>
</li>
<li>
<a name="66206"><!-- --></a>
<kbd>java.awt.font</kbd>
</li>
<li>
<a name="66210"><!-- --></a>
<kbd>java.awt.color</kbd>
</li>
<li>
<a name="66194"><!-- --></a>
<kbd>java.awt.image</kbd>
</li>
<li>
<a name="66196"><!-- --></a>
<kbd>java.awt.image.renderable</kbd>
</li>
<li>
<a name="62589"><!-- --></a>
<kbd>java.awt.print</kbd>
</li>
</ul>
</blockquote>
<blockquote>
<a name="66217"><!-- --></a>
Package <kbd>java.awt</kbd> contains those Java 2D API classes and interfaces that are general in nature or that enhance legacy classes. (Obviously, not all of the classes in <kbd>java.awt </kbd>are Java 2D classes.)

<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><td><a name="66220"><!-- --></a>
<p><code>AlphaComposite </code>

</td><td><a name="66222"><!-- --></a>
<p><code>BasicStroke </code>

</td><td><a name="66224"><!-- --></a>
<p><code>Color </code>

</td></tr>
<tr><td><a name="66226"><!-- --></a>
<p><code>Composite</code>

</td><td><a name="66228"><!-- --></a>
<p><code>CompositeContext</code>

</td><td><a name="66230"><!-- --></a>
<p><code>Font</code>

</td></tr>
<tr><td><a name="66232"><!-- --></a>
<p><code>GradientPaint</code>

</td><td><a name="66316"><!-- --></a>
<p><code>Graphics2D</code>

</td><td><a name="66236"><!-- --></a>
<p><code>GraphicsConfiguration</code>

</td></tr>
<tr><td><a name="66317"><!-- --></a>
<p><code>GraphicsDevice</code>

</td><td><a name="66240"><!-- --></a>
<p><code>GraphicsEnvironment</code>

</td><td><a name="66242"><!-- --></a>
<p><code>Paint</code>

</td></tr>
<tr><td><a name="66244"><!-- --></a>
<p><code>PaintContext</code>

</td><td><a name="66246"><!-- --></a>
<p><code>Rectangle</code>

</td><td><a name="66248"><!-- --></a>
<p><code>Shape</code>

</td></tr>
<tr><td><a name="66250"><!-- --></a>
<p><code>Stroke</code>

</td><td><a name="66252"><!-- --></a>
<p><code>TexturePaint</code>

</td><td><a name="66254"><!-- --></a>
<p><code>Transparency</code>

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
<a name="66189"><!-- --></a>
Package<kbd> java.awt.geom</kbd> contains classes and interfaces related to the definition of geometric primitives:

<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><td><a name="66419"><!-- --></a>
<p>AffineTransform

</td><td><a name="66421"><!-- --></a>
<p>Arc2D

</td><td><a name="66423"><!-- --></a>
<p>Arc2D.Double

</td></tr>
<tr><td><a name="66425"><!-- --></a>
<p>Arc2D.Float

</td><td><a name="66427"><!-- --></a>
<p>Area

</td><td><a name="66429"><!-- --></a>
<p>CubicCurve2D

</td></tr>
<tr><td><a name="66431"><!-- --></a>
<p>CubicCurve2D.Double

</td><td><a name="66433"><!-- --></a>
<p>CubicCurve2D.Float

</td><td><a name="66435"><!-- --></a>
<p>Dimension2D

</td></tr>
<tr><td><a name="66437"><!-- --></a>
<p>Ellipse2D

</td><td><a name="66439"><!-- --></a>
<p>Ellipse2D.Double

</td><td><a name="66441"><!-- --></a>
<p>Ellipse2D.Float

</td></tr>
<tr><td><a name="66443"><!-- --></a>
<p>FlatteningPathIterator

</td><td><a name="66445"><!-- --></a>
<p>GeneralPath

</td><td><a name="66447"><!-- --></a>
<p>Line2D

</td></tr>
<tr><td><a name="66545"><!-- --></a>
<p>Line2D.Double

</td><td><a name="66552"><!-- --></a>
<p>Line2D.Float

</td><td><a name="66453"><!-- --></a>
<p>PathIterator

</td></tr>
<tr><td><a name="66455"><!-- --></a>
<p>Point2D

</td><td><a name="66457"><!-- --></a>
<p>Point2D.Double

</td><td><a name="66485"><!-- --></a>
<p>Point2D.Float

</td></tr>
<tr><td><a name="66461"><!-- --></a>
<p>QuadCurve2D

</td><td><a name="66463"><!-- --></a>
<p>QuadCurve2D.Double

</td><td><a name="66503"><!-- --></a>
<p>QuadCurve2D.Float

</td></tr>
<tr><td><a name="66467"><!-- --></a>
<p>Rectangle2D

</td><td><a name="66514"><!-- --></a>
<p>Rectangle2D.Double

</td><td><a name="66520"><!-- --></a>
<p>Rectangle2D.Float

</td></tr>
<tr><td><a name="66473"><!-- --></a>
<p>RectangularShape

</td><td><a name="66475"><!-- --></a>
<p>RoundRectangle2D

</td><td><a name="66576"><!-- --></a>
<p>RoundRectangle2D.Double

</td></tr>
<tr><td><a name="66578"><!-- --></a>
<p>RoundRectangle2D.Float

</td><td><a name="66580"><!-- --></a>
<p>

</td><td><a name="66483"><!-- --></a>
<p>

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
<a name="62052"><!-- --></a>
Many of the geometric primitives have corresponding <kbd>.Float</kbd> and <kbd>.Double</kbd> implementations. This was done to enable both floating single- and double-precision implementations. Double-precision implementations provide greater rendering precision at the expense of performance on some platforms.<p>
<a name="62612"><!-- --></a>
Package <kbd>java.awt.font</kbd> contains classes and interfaces used for text layout and the definition of fonts:

<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><td><a name="66588"><!-- --></a>
<p>FontRenderContext

</td><td><a name="66590"><!-- --></a>
<p>GlyphJustificationInfo

</td><td><a name="66592"><!-- --></a>
<p>GlyphMetrics

</td></tr>
<tr><td><a name="64007"><!-- --></a>
<p>GlyphVector

</td><td><a name="64009"><!-- --></a>
<p>GraphicAttribute

</td><td><a name="64011"><!-- --></a>
<p>ImageGraphicAttribute

</td></tr>
<tr><td><a name="62618"><!-- --></a>
<p>LineBreakMeasurer

</td><td><a name="62620"><!-- --></a>
<p>LineMetrics

</td><td><a name="62622"><!-- --></a>
<p>MultipleMaster

</td></tr>
<tr><td><a name="64021"><!-- --></a>
<p>OpenType

</td><td><a name="64023"><!-- --></a>
<p>ShapeGrapicAttribute

</td><td><a name="64025"><!-- --></a>
<p>TextAttribute

</td></tr>
<tr><td><a name="64034"><!-- --></a>
<p>TextHitInfo

</td><td><a name="64036"><!-- --></a>
<p>TextLayout

</td><td><a name="64038"><!-- --></a>
<p>TransformAttribute

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
<a name="62057"><!-- --></a>
Package<kbd>java.awt.color</kbd> contains classes and interfaces for the definition of color spaces and color profiles:

<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><td><a name="62635"><!-- --></a>
<p>ColorSpace 

</td><td><a name="62637"><!-- --></a>
<p>ICC_ColorSpace 

</td><td><a name="62639"><!-- --></a>
<p>ICC_Profile 

</td></tr>
<tr><td><a name="62641"><!-- --></a>
<p>ICC_ProfileGray 

</td><td><a name="62643"><!-- --></a>
<p>ICC_ProfileRGB

</td><td><a name="62645"><!-- --></a>
<p>

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
<a name="62648"><!-- --></a>
The <kbd>java.awt.image</kbd> and <kbd>java.awt.image.renderable</kbd> packages contain classes and interfaces for the definition and rendering of images:

<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><td><a name="62662"><!-- --></a>
<p><code>AffineTransformOp</code>

</td><td><a name="62664"><!-- --></a>
<p><code>BandCombineOp</code>

</td><td><a name="62666"><!-- --></a>
<p><code>BandedSampleModel</code>

</td></tr>
<tr><td><a name="64138"><!-- --></a>
<p><code>BufferedImage</code>

</td><td><a name="64140"><!-- --></a>
<p><code>BufferedImageFilter</code>

</td><td><a name="64142"><!-- --></a>
<p><code>BufferedImageOp</code>

</td></tr>
<tr><td><a name="62668"><!-- --></a>
<p><code>ByteLookupTable</code>

</td><td><a name="62670"><!-- --></a>
<p><code>ColorConvertOp</code>

</td><td><a name="62672"><!-- --></a>
<p><code>ColorModel</code>

</td></tr>
<tr><td><a name="64086"><!-- --></a>
<p><code>ComponentColorModel</code>

</td><td><a name="64088"><!-- --></a>
<p><code>ComponentSampleModel</code>

</td><td><a name="64090"><!-- --></a>
<p><code>ConvolveOp</code>

</td></tr>
<tr><td colspan=2>
<p><code>ContextualRenderedImageFactory</code>
</td>
<td><a name="65031"><!-- --></a>
<p><code>DataBuffer</code>

</td></tr>
<tr><td><a name="65033"><!-- --></a>
<p><code>DataBufferByte</code>

</td><td><a name="65035"><!-- --></a>
<p><code>DataBufferInt</code>

</td>
<td><a name="62674"><!-- --></a>
<p><code>DataBufferShort</code>

</td></tr>
<tr><td><a name="62676"><!-- --></a>
<p><code>DataBufferUShort</code>

</td><td><a name="62678"><!-- --></a>
<p><code>DirectColorModel</code>

</td>
<td><a name="62680"><!-- --></a>
<p><code>IndexColorModel</code>

</td><tr>
</tr><td><a name="62682"><!-- --></a>
<p><code>Kernel</code>

</td><td><a name="62684"><!-- --></a>
<p><code>LookupOp</code>

</td>
<td><a name="64120"><!-- --></a>
<p><code>LookupTable</code>

</td></tr>
<tr><td>
<p><code>MultiPixelPackedSampleModel</code>
</td>
<td><a name="64122"><!-- --></a>
<p><code>PackedColorModel</code>

</td><td><a name="64124"><!-- --></a>
<p><code>ParameterBlock</code>

</td></tr>
<tr><td>
<p><code>PixelInterleavedSampleModel</code>
</td>
<td><a name="64210"><!-- --></a>
<p><code>Raster</code>

</td><td><a name="64212"><!-- --></a>
<p><code>RasterImageConsumer</code>

</td></tr>
<tr><td><a name="64214"><!-- --></a>
<p><code>RasterOp</code>

</td>
<td><a name="64216"><!-- --></a>
<p><code>RenderableImage</code>

</td><td><a name="64218"><!-- --></a>
<p><code>RenderableImageOp</code>

</td></tr>
<tr><td><a name="64220"><!-- --></a>
<p>RenderableImageProducer<code></code>

</td>
<td><a name="62692"><!-- --></a>
<p><code>RenderContext</code>

</td><td><a name="62694"><!-- --></a>
<p>RenderedImageFactory

</td></tr>
<tr><td><a name="62696"><!-- --></a>
<p><code>RenderedImage</code>

</td>
<td><a name="64998"><!-- --></a>
<p><code>RescaleOp</code>

</td><td><a name="65000"><!-- --></a>
<p><code>SampleModel</code>

</td></tr>
<tr>
<td><a name="65002"><!-- --></a>
<p><code>ShortLookupTable</code>

</td>
<td>
<p><code>SinglePixelPackedSampleModel</code>
</td>
<td><a name="65004"><!-- --></a>
<p><code>TileObserver</code>

</td></tr>
<tr><td><a name="65006"><!-- --></a>
<p><code>WritableRaster</code>

</td><td><a name="65013"><!-- --></a>
<p><code>WritableRenderedImage</code>

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
<a name="62063"><!-- --></a>
Package <kbd>java.awt.image</kbd> was present in earlier versions of the AWT. The Java 2D API enhances the following legacy AWT image classes:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="62064"><!-- --></a>
<kbd>ColorModel</kbd>
</li>
<li>
<a name="62065"><!-- --></a>
<kbd>DirectColorModel</kbd>
</li>
<li>
<a name="62066"><!-- --></a>
<kbd>IndexColorModel</kbd>
</li>
</ul>
</blockquote>
<blockquote>
<a name="62068"><!-- --></a>
These color model classes remain in the <kbd>java.awt.image</kbd> package for backward compatibility. To maintain consistency, the new color model classes are also located in the <kbd>java.awt.image</kbd> package.<p>
<a name="66255"><!-- --></a>
Package java.awt.print contains classes and interfaces that enable printing of all Java 2D&#45;based text, graphics, and images.

<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><td><a name="66278"><!-- --></a>
<p>Book

</td><td><a name="66280"><!-- --></a>
<p>Pageable

</td><td><a name="66282"><!-- --></a>
<p>PageFormat

</td></tr>
<tr><td><a name="66284"><!-- --></a>
<p>Paper

</td><td><a name="66286"><!-- --></a>
<p>Printable

</td><td><a name="66288"><!-- --></a>
<p>PrinterGraphics

</td></tr>
<tr><td><a name="66290"><!-- --></a>
<p>PrinterJob

</td><td><a name="66292"><!-- --></a>
<p>

</td><td><a name="66294"><!-- --></a>
<p>

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
<a name="66274"><!-- --></a>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-intro.fm3.html">PREV</a>
 | <a href="j2d-awt.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Thu Jun 11 14:30:12 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-bookTOC.doc.html">PREV</a>
 | <a href="j2d-intro.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 
<blockquote>
<a name="996874"><!-- --></a>
<p>
This guide describes the features provided by the Java 2D API and illustrates
how you can use the Java 2D API classes to enhance your applications. For additional information about the Java 2D APIs, see:
<p>
<ul>
<li>The Java Tutorial, 2nd Volume. Available online at:
<a href="http://java.sun.com/docs/books/tutorial/2d/index.html">http://java.sun.com/docs/books/tutorial/2d/index.html</a>
<li>The 2D Text Tutorial. Available online from the Java Developer Connection:
<a href="http://developer.java.sun.com/developer/onlineTraining/Graphics/2DText/">http://developer.java.sun.com/developer/onlineTraining/Graphics/2DText/</a>
<li>The Java 2D Sample Programs. Available online at: <a href="http://java.sun.com/products/java-media/2D/samples/index.html">http://java.sun.com/products/java-media/2D/samples/index.html</a>
<li>The Java 2D Demo. Available from the Java 2D website:
<a href="http://java.sun.com/products/java-media/2D/index.html">http://java.sun.com/products/java-media/2D/index.html</a>
</ul>
<p>
This information is organized into seven chapters:<p>
<a name="996875"><!-- --></a>
<blockquote><strong>Overview</strong> &#45;&#45;introduces the packages and key classes in the Java 2D API.</blockquote>

<a name="996877"><!-- --></a>
<blockquote><strong>Rendering with Graphics2D</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt</kbd> package and how to set up the <kbd>Graphics2D</kbd> rendering context. </blockquote>

<a name="996872"><!-- --></a>
<blockquote><strong>Geometries</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.geom</kbd> package and how to define and manipulate 2D shapes and areas. </blockquote>

<a name="996878"><!-- --></a>
<blockquote><strong>Fonts and Text Layout</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.font </kbd>package, how to specify and retrieve font information, and how to display and manipulate international text using the Java 2D text layout APIs directly.</blockquote>

<a name="996945"><!-- --></a>
<blockquote><strong>Imaging</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.image</kbd>, <kbd>java.awt.image.codec</kbd>, and <kbd>java.awt.image.renderable</kbd> packages and how to display and manipulate images and offscreen buffers.</blockquote>

<a name="997091"><!-- --></a>
<blockquote><strong>Color</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.color</kbd> package and color management.</blockquote>

<a name="996946"><!-- --></a>
<blockquote><strong>Printing</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.print</kbd> package and the Java 2D API printing model. </blockquote>

</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-bookTOC.doc.html">PREV</a>
 | <a href="j2d-intro.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:05 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-preface.fm.html">PREV</a>
 | <a href="j2d-intro.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<br>
<h3>
<a name="996747"><!-- --></a>
<i></i> Preface
</h3>

<blockquote>
<a name="996874"><!-- --></a>
<em>This preliminary draft replaces the previously released Java 2D White Paper and Programmer&#39;s Guide. As it is a work in progress, it may contain incomplete or inaccurate information. Where discrepancies exist between this document and the actual Java 2D classes and interfaces, please rely on the information in the .java and HTML reference files. </em><p>
<a name="997037"><!-- --></a>
<em>The code examples in this document have not all been tested. Please refer to the Java 2D demo application and code for validated sample code.</em><p>
<a name="996953"><!-- --></a>
This guide describes the features provided by the Java 2D API and illustrates how you can use the Java 2D API classes to enhance your applications. This information is organized into eight chapters:<p>
<a name="996875"><!-- --></a>
<blockquote><strong>Overview</strong> &#45;&#45;introduces the packages and key classes in the Java 2D API.</blockquote>

<a name="996876"><!-- --></a>
<blockquote><strong>Getting Started with the Java 2D API</strong>&#45;&#45;describes key concepts and illustrates how to perform basic operations with the Java 2D API, such as drawing and transforming 2D shapes, text, and images.</blockquote>

<a name="996877"><!-- --></a>
<blockquote><strong>Graphics2D Context</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt</kbd> package and describes how to set up the Graphics2D context. </blockquote>

<a name="996872"><!-- --></a>
<blockquote><strong>Geometries</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.geom</kbd> package and describes how to define and manipulate 2D shapes and areas. </blockquote>

<a name="996878"><!-- --></a>
<blockquote><strong>Text and Fonts</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.font </kbd>package and describes how to specify and retrieve font information and display and manipulate international text.</blockquote>

<a name="996879"><!-- --></a>
<blockquote><strong>Color</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.color</kbd> package and color management.</blockquote>

<a name="996945"><!-- --></a>
<blockquote><strong>Imaging</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.image</kbd>, <kbd>java.awt.image.codec</kbd>, and <kbd>java.awt.image.renderable</kbd> packages and describes how to display and manipulate images and offscreen buffers.</blockquote>

<a name="996946"><!-- --></a>
<blockquote><strong>Printing</strong>&#45;&#45;describes the Java 2D API classes in the <kbd>java.awt.print</kbd> package and the Java 2D API printing model. </blockquote>

</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-preface.fm.html">PREV</a>
 | <a href="j2d-intro.fm.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Mon Feb 23 13:54:22 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-color.fm2.html">PREV</a>
 | <a href="j2d-print.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 
<a name="418228"><!-- --></a>
<hr size="8" width="35%" align="left" noshade>

<table border=0>
<tr valign=bottom>
<td valign=bottom>
<br>
<U><B><FONT FACE="ARIAL,HELVETICA,TIMES ROMAN">CHAPTER</FONT> 
7 
</B></U>
</td>
</tr>
</table>

<a name="418231"><!-- --> </a>
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td align="left">
<h1><FONT SIZE=+4>
Printing
</font></h1>
</td>
</tr>
</table>
<blockquote>
<a name="417927"><!-- --></a>
The Java Printing API enables applications to:<p>
<blockquote>
<li>
Print all AWT and Java 2D graphics, including composited graphics and images.
</li>
</blockquote>
<blockquote>
<li>
<a name="417929"><!-- --></a>
Control document-composition functions such as soft collating, reverse order printing, and booklet printing.
</li>
<li>
<a name="417930"><!-- --></a>
 Invoke printer-specific functions such as duplex (two-sided) printing and stapling.
</li>
<li>
<a name="417931"><!-- --></a>
Print on all platforms, including Windows and Solaris. This includes printers directly attached to the computer as well as those that the platform software is able to access using network printing protocols.
</li>
</ul>
</blockquote>
<blockquote>
<a name="420589"><!-- --></a>
Not all of these features are supported in the JDK 1.2 Printing API and implementation. The API will be extended to support all of these features in future releases. For example, additional printer controls will be added by augmenting the set of named properties of a print job that the application can control.<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-color.fm2.html">PREV</a>
 | <a href="j2d-print.fm1.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 14:56:01 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm.html">PREV</a>
 | <a href="j2d-print.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="418393"><i>7.1	</i> Interfaces and Classes

<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="418427"><!-- --></a>
<blockquote><hr noshade size="1"><b>Interface</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="418429"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="418415"><!-- --></a>
<p><code>Printable</code>

</td><td><a name="418441"><!-- --></a>
<p>The <code>Printable</code> interface is implemented by each <em>page painter</em>, the application class(es) called by the printing system to render a page. The system calls the page painter&#39;s <code>print</code> method to request that a page be rendered.

</td></tr>
<tr><td><a name="418411"><!-- --></a>
<p><code>Pageable</code>

</td><td><a name="418449"><!-- --></a>
<p>The <code>Pageable</code> interface is implemented by a document that is to be printed by the printing system. Through the <code>Pageable</code> methods, the system can determine the number of pages in the document, the format to use for each page, and the page painter to use to render each page.

</td></tr>
<tr><td><a name="418407"><!-- --></a>
<p><code>PrinterGraphics</code>

</td><td><a name="418457"><!-- --></a>
<p>The <code>Graphics2D</code> objects that a page painter uses to render a page implement the <code>PrinterGraphics</code> interface. This enables an application to get the <code>PrinterJob</code> object that is controlling the printing.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>

</a></h2>

<a name="417944"><!-- --></a>


<br><br>
<Table Border="1" Cellpadding="5">
<caption></caption>

<tr><th><a name="418472"><!-- --></a>
<blockquote><hr noshade size="1"><b>Class</b> 
<hr noshade size="1"></blockquote>
</th><th><a name="418474"><!-- --></a>
<blockquote><hr noshade size="1"><b>Description</b> 
<hr noshade size="1"></blockquote>
</th></tr>
<tr><td><a name="418476"><!-- --></a>
<p><code>Book</code>

</td><td><a name="418478"><!-- --></a>
<p>Implements: <code>Pageable</code>

<a name="418510"><!-- --></a>
<p>Represents a document in which pages can have different page formats and page painters. This class uses the <code>Pageable</code> interface to interact with a <code>PrinterJob</code>.

</td></tr>
<tr><td><a name="418485"><!-- --></a>
<p><code>PageFormat</code>

</td><td><a name="418516"><!-- --></a>
<p>Describes the size and orientation of a page to be printed, as well as the <code>Paper</code> used to print it. For example, <em>portrait</em> and <em>landscape</em> paper orientations are represented by <code>PageFormat</code>.

</td></tr>
<tr><td><a name="418489"><!-- --></a>
<p><code>Paper</code>

</td><td><a name="418524"><!-- --></a>
<p>Describes the physical characteristics of a piece of paper.

</td></tr>
<tr><td><a name="418493"><!-- --></a>
<p><code>PrinterJob</code>

</td><td><a name="418532"><!-- --></a>
<p>The principal class that controls printing. The application calls <code>PrinterJob</code> methods to set up a job, display a print dialog to the user (optional), and to print the pages in the job.

</td></tr>

</Table>
 
<Table>
<tr><td></td>
</tr>
</Table><p>
<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm.html">PREV</a>
 | <a href="j2d-print.fm2.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 14:56:01 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm1.html">PREV</a>
 | <a href="j2d-print.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="417953"><i>7.2	</i> Printing Concepts
</a></h2>

<blockquote>
<a name="420599"><!-- --></a>
The Java Printing API is based on a <em>callback</em> printing model in which the printing system, not the application, controls when pages are printed. The application provides information about the document to be printed and the printing system asks the application to render each page as it needs them. <p>
<a name="420653"><!-- --></a>
The printing system might request that a particular page be rendered more than once or request that pages be rendered out of order. The application must be able to generate the proper page image, no matter which page the printing system requests. In this respect, the printing system is similar to the window toolkit, which can request components to repaint at any time, in any order.<p>
<a name="420654"><!-- --></a>
The callback printing model is more flexible than traditional application-driven printing models and supports printing on a wider range of systems and printers. For example, if a printer stacks output pages in reverse order, the printing system can ask the application to generate pages in reverse order so that the final stack is in proper reading order. <p>
<a name="420602"><!-- --></a>
This model also enables applications to print to a bitmap printer from computers that don&#39;t have enough memory or disk space to buffer a full-page bitmap. In this situation, a page is printed as a series of small bitmaps or <em>bands</em>. For example, if only enough memory to buffer one tenth of a page is available, the page is divided into ten bands. The printing system asks the application to render each page ten times, once to fill each band. The application does not need to be aware of the number or size of the bands; it simply must be able to render each page when requested.<p>
</blockquote>
<br>
<h3>
<a name="420680"><!-- --></a>
<i>7.2.1	</i> Supporting Printing
</h3>

<blockquote>
<a name="420710"><!-- --></a>
An application has to perform two tasks to support printing:<p>
<li>
<a name="420725"><!-- --></a>
Job control&#45;&#45;initiating and managing the print job.
</li>
<li>
<a name="420734"><!-- --></a>
Imaging&#45;&#45;rendering each page when the printing system requests it.
</li>
</blockquote><a name="420756"><!-- --></a>
<b>Job Control</b><br>

<blockquote>
<a name="420777"><!-- --></a>
The user often initiates printing by clicking a button or selecting a menu item in an application. When a print operation is triggered by the user, the application creates a <kbd>PrinterJob</kbd> object and uses it to manage the printing process. <p>
<a name="420807"><!-- --></a>
The application is responsible for setting up the print job, displaying print dialogs to the user, and starting the printing process.<p>
</blockquote><a name="420758"><!-- --></a>
<b>Imaging </b><br>

<blockquote>
<a name="420736"><!-- --></a>
When a document is printed, the application has to render each page when the printing system requests it. To support this mechanism, the application provides a <em>page painter</em> that implements the <kbd>Printable</kbd> interface. When the printing system needs a page rendered, it calls the page painter&#39;s <kbd>print</kbd> method.<p>
<a name="420899"><!-- --></a>
When a page painter&#39;s <kbd>print</kbd> method is called, it is passed a <kbd>Graphics</kbd> context to use to render the page image. It is also passed a <kbd>PageFormat</kbd> object that specifies the geometric layout of the page, and an integer <em>page index</em> that identifies the ordinal position of the page in the print job.<p>
<a name="420607"><!-- --></a>
The printing system supports both <kbd>Graphics</kbd> and <kbd>Graphics2D</kbd> rendering, To print Java 2D <kbd>Shapes</kbd>, <kbd>Text</kbd>, and <kbd>Images</kbd>, you cast the <kbd>Graphics</kbd> object passed into the <kbd>print</kbd> method to a <kbd>Graphics2D</kbd>.<p>
<a name="420859"><!-- --></a>
To print documents in which the pages use different page painters and have different formats, you use a <em>pageable job</em>. To create a pageable job, you can use the <kbd>Book</kbd> class or your own implementation of the <kbd>Pageable</kbd> interface. To implement simple printing operations, you do not need to use a pageable print job; <kbd>Printable</kbd> can be used as long as all of the pages share the same page format and painter.<p>
</blockquote>
<br>
<h3>
<a name="420933"><!-- --></a>
<i>7.2.2	</i> Page Painters
</h3>

<blockquote>
<a name="420934"><!-- --></a>
The principal job of a page painter is to render a page using the graphics context that is provided by the printing system. A page painter implements the <kbd>Printable</kbd>.<kbd>print</kbd> method:<p>
<a name="420935"></a>
<kbd>public int print(Graphics g, PageFormat pf, int pageIndex) </kbd><p><a name="420936"><!-- --></a>
The graphics context passed to the <kbd>print</kbd> method is either an instance of <kbd>Graphics</kbd> or <kbd>Graphics2D</kbd>, depending on the packages loaded in your Java Virtual Machine. To use <kbd>Graphics2D</kbd> features, you can cast the <kbd>Graphics</kbd> object to a <kbd>Graphics2D</kbd>. The <kbd>Graphics</kbd> instance passed to <kbd>print</kbd> also implements the <kbd>PrinterGraphics</kbd> interface.<p>
<a name="420937"><!-- --></a>
The <kbd>PageFormat</kbd> passed to a <kbd>Printable</kbd> describes the geometry of the page being printed. The coordinate system of the graphics context passed to <kbd>print</kbd> is fixed to the page: the origin of the coordinate system is at the upper left corner of the paper, <em>X</em> increases to the right, <em>Y</em> increases downward, and the units are 1/72 inch. If the page is in portrait orientation, the x-axis aligns with the paper&#39;s &#34;width,&#34; while the y-axis aligns with the paper&#39;s &#34;height.&#34; (Normally, but not always, a paper&#39;s height exceeds its width.) If the page is in landscape orientation, the roles are reversed: the x-axis aligns with the paper&#39;s &#34;height&#34; and the y-axis with its &#34;width.&#34; <p>
<a name="420938"><!-- --></a>
Because many printers cannot print on the entire paper surface, the <kbd>PageFormat</kbd> specifies the <em>imageable area</em> of the page: this is the portion of the page in which it&#39;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&#39;t extend into the area where the printer can&#39;t print.<p>
<a name="420939"><!-- --></a>
The graphics context passed to <kbd>print</kbd> has a clip region that describes the portion of the imageable area that should be drawn. It is always safe to draw the entire page into the context; the printing system will handle the necessary clipping. However, to eliminate the overhead of drawing portions of the page that won&#39;t be printed, you can use the clipping region to limit the areas that you render. To get the clipping region from the graphics context, call <kbd>Graphics.getClip</kbd>. You are strongly encouraged to use the clip region to reduce the rendering overhead.<p>
<a name="420940"><!-- --></a>
It is sometimes desirable to launch the entire printing operation &#34;in the background&#34; so that a user can continue to interact with the application while pages are being rendered. To do this, call <kbd>PrinterJob.print</kbd> in a separate thread.<p>
<a name="420941"><!-- --></a>
If possible, you should avoid graphics operations that require knowledge of the previous image contents, such as <kbd>copyArea</kbd>, <kbd>setXOR</kbd>, and compositing. These operations can slow rendering and the results might be inconsistent.<p>
</blockquote>
<br>
<h3>
<a name="417961"><!-- --></a>
<i>7.2.3	</i> Printable Jobs and Pageable Jobs
</h3>

<blockquote>
<a name="417963"><!-- --></a>
A <kbd>Printable</kbd> job provides the simplest way to print. Only one page painter is used; the application provides a single class that implements the <kbd>Printable</kbd> interface. When it&#39;s time to print, the printing system calls the page painter&#39;s <kbd>print</kbd> method to render each page. The pages are requested in order, starting with page index 0. However, the page painter might be asked to render each page several times before it advances to the next page. When the last page has been printed, the page painter&#39;s print method returns NO_SUCH_PAGE. <p>
<a name="419828"><!-- --></a>
In a <kbd>Printable</kbd> job:<p>
<blockquote>
<li>
<a name="418567"><!-- --></a>
All pages use the same page painter and <kbd>PageFormat</kbd>.   If a print dialog is presented, it will not display the number of pages in the document because that information is not available to the printing system.
</li>
<li>
The printing system always asks the page painter to print each page in indexed order, starting with the page at index 0. No pages are skipped. For example, if a user asks to print pages 2 and 3 of a document, the page painter will be called with indices 0, 1, and 2. The printing system might request that a page be rendered multiple times before moving to the next page.
</li>
<li>
<a name="417966"><!-- --></a>
The page painter informs the printing system when the end of the document has been reached.
</li>
<li>
<a name="417967"><!-- --></a>
All page painters are called in the same thread.
</li>
<li>
<a name="417968"><!-- --></a>
Some printing systems might not be able to achieve the ideal output. For example, the stack of pages emerging from the printer might be in the wrong order, or the pages might not be collated if multiple copies are requested.
</li>
</ul>
</blockquote>
<blockquote>
<a name="417969"><!-- --></a>
A <kbd>Pageable</kbd> job is more flexible than a <kbd>Printable</kbd> job. Unlike the pages in a <kbd>Printable</kbd> job, pages in a <kbd>Pageable</kbd> job can differ in layout and implementation. To manage a <kbd>Pageable</kbd> job, you can use the <kbd>Book</kbd> class or implement your own <kbd>Pageable</kbd> class. Through the <kbd>Pageable</kbd>, the printing system can determine the number of pages to print, the page painter to use for each page, and the <kbd>PageFormat</kbd> to use for each page. Applications that need to print documents that have a planned structure and format should use <kbd>Pageable</kbd> jobs. <p>
<a name="419829"><!-- --></a>
In a <kbd>Pageable</kbd> job:<p>
<blockquote>
<li>
<a name="417970"><!-- --></a>
Different pages can use different page painters and <kbd>PageFormats</kbd>. 
</li>
<li>
<a name="417971"><!-- --></a>
The printing system can ask page painters to print pages in an arbitrary order and some pages might be skipped. For example, if a user asks to print pages 2 and 3 of a document, the page painter will be called with indices 1 and 2 and page index 0 will be skipped.
</li>
<li>
<a name="420244"><!-- --></a>
<kbd>Pageable</kbd> jobs do not need to know in advance how many pages are in the document. However, unlike <kbd>Printable</kbd> jobs, they must be able to render pages in any order. There might be gaps in the sequencing and the printing system might request that a page be rendered multiple times before moving to the next page. For example, a request to print pages 2 and 3 of a document might result in a sequence of calls that request pages with indices 2,2,1,1, and 1.
</li>
</ul>
</blockquote>

<br>
<h3>
<a name="420247"><!-- --></a>
<i>7.2.4	</i> Typical Life-Cycle of a PrinterJob
</h3>

<blockquote>
<a name="420223"><!-- --></a>
An application steers the <kbd>PrinterJob</kbd> object through a sequence of steps to complete a printing job. The simplest sequence used by an application is:<p>
<ol>
<li>
Get a new <kbd>PrinterJob</kbd> object by calling <kbd>PrinterJob.getPrinterJob</kbd>.
<li>
Determine what <kbd>PageFormat</kbd> to use for printing. A default <kbd>PageFormat</kbd> can be obtained by calling <kbd>defaultPage</kbd> or you can invoke <kbd>pageDialog</kbd> to present a dialog box that allows the user to specify a format.
<li>
Specify the characteristics of the job to be printed to the <kbd>PrinterJob</kbd>. For a <kbd>Printable</kbd> job, call <kbd>setPrintable</kbd>; for a <kbd>Pageable</kbd> job, call <kbd>setPageable</kbd>. Note that a <kbd>Book</kbd> object is ideal for passing to <kbd>setPageable</kbd>.
<li>
Specify additional print job properties, such as the number of copies to print or the name of the job to print on the banner page.
<li>
Call <kbd>printDialog</kbd> to present a dialog box to the user. This is optional. The contents and appearance of this dialog can vary across different platforms and printers. On most platforms, the user can use this dialog to change the printer selection. If the user cancels the print job, the <kbd>printDialog</kbd> method returns <kbd>FALSE</kbd>.
<li>
Call <kbd>Printerjob.print</kbd> to print the job. This method in turn calls <kbd>print</kbd> on the appropriate page painters.
</ol>
<p>
A job can be interrupted during printing if:<p>
<blockquote>
<li>
<a name="420963"><!-- --></a>
A <kbd>PrinterException</kbd> is thrown&#45;&#45;the exception is caught by the <kbd>print</kbd> method and the job is halted. A page painter throws a <kbd>PrinterException</kbd> if it detects a fatal error. 
</li>
<li>
<a name="417984"><!-- --></a>
 <kbd>PrinterJob.cancel</kbd> is called&#45;&#45;the printing loop is terminated and the job is canceled. The <kbd>cancel</kbd> method can be called from a separate thread that displays a dialog box and allows the user to cancel printing by clicking a button in the box.
</li>
</blockquote>
<a name="417985"><!-- --></a>
Pages generated before a print job is stopped might or might not be printed.<p>
<a name="417986"><!-- --></a>
The print job is usually not finished when the <kbd>print</kbd> method returns. Work is typically still being done by a printer driver, print server, or the printer itself. The state of the <kbd>PrinterJob</kbd> object might not reflect the state of the actual job being printed.<p>
<a name="420329"><!-- --></a>
Because the state of a <kbd>PrinterJob</kbd> changes during its life cycle, it is illegal to invoke certain methods at certain times. For example, calling <kbd>setPageable</kbd> after you&#39;ve called <kbd>print</kbd> makes no sense. When illegal calls are detected, the <kbd>PrinterJob</kbd> throws a <kbd>java.lang.IllegalStateException</kbd>.<p>
</blockquote>
<br>
<h3>
<a name="417988"><!-- --></a>
<i>7.2.5	</i> Dialogs
</h3>

<blockquote>
<a name="417989"><!-- --></a>
The Java Printing API requires that applications invoke user-interface dialogs explicitly. These dialogs might be provided by the platform software (such as Windows) or by a JDK software implementation. For interactive applications, it is customary to use such dialogs. For production printing applications, however, dialogs are not necessary. For example, you wouldn&#39;t want to display a dialog when automatically generating and printing a nightly database report. A print job that requires no user interaction is sometimes called a <em>silent</em> print job.<p>
</blockquote><a name="417990"><!-- --></a>
<b>Page setup dialog</b><br>

<blockquote>
<a name="417991"><!-- --></a>
You can allow the user to alter the page setup information contained in a <kbd>PageFormat</kbd> by displaying a page setup dialog. To display the page setup dialog, you call <kbd>PrinterJob.pageDialog</kbd>. The page setup dialog is initialized using the parameter passed to <kbd>pageDialog</kbd>. If the user clicks the OK button in the dialog, the <kbd>PageFormat</kbd> instance is cloned, altered to reflect the user&#39;s selections, and then returned. If the user cancels the dialog, <kbd>pageDialog</kbd> returns the original unaltered <kbd>PageFormat</kbd>.<p>
</blockquote><a name="417993"><!-- --></a>
<b>Print dialog</b><br>

<blockquote>
<a name="417994"><!-- --></a>
Typically, an application presents a print dialog to the user when a print menu item or button is activated. To display this print dialog, you call the <kbd>PrinterJob&#39;s printDialog</kbd> method. The user&#39;s choices in the dialog are constrained based on the number and format of the pages in the <kbd>Printable</kbd> or <kbd>Pageable</kbd> that have been furnished to the <kbd>PrinterJob</kbd>. If the user clicks OK in the print dialog, <kbd>printDialog</kbd> returns <kbd>TRUE</kbd>. If the user cancels the print dialog, <kbd>FALSE</kbd> is returned and the print job should be considered abandoned.<p>
</blockquote>

<br>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm1.html">PREV</a>
 | <a href="j2d-print.fm3.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 14:56:01 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API 
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm2.html">PREV</a>
 | <a href="j2d-print.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="418013"><i>7.3	</i> Printing with Printables
</a></h2>

<blockquote>
<a name="420973"><!-- --></a>
To provide basic printing support:<p>
<ol>
<li>
Implement the <kbd>Printable</kbd> interface to provide a page painter that can render each page to be printed.
<li>
Create a <kbd>PrinterJob</kbd>.

<li>
Call <kbd>setPrintable</kbd> to tell the <kbd>PrinterJob</kbd> how to print your document.

<li>Call <kbd>print</kbd> on the <kbd>PrinterJob</kbd> object to start the job.
</blockquote>
<a name="418014"><!-- --></a>
In the following example, a <kbd>Printable</kbd> job is used to print five pages, each of which displays a green page number. Job control is managed in the <kbd>main</kbd> method, which obtains and controls the <kbd>PrinterJob</kbd>. Rendering is performed in the page painter&#39;s <kbd>print</kbd> method.<p>

<blockquote><pre>
import java.awt.*; import java.awt.print.*;
public class SimplePrint implements Printable 
{   

  private static Font fnt = new Font("Helvetica",Font.PLAIN,24);


  public static void main(String[] args) 
  {     
    // Get a PrinterJob     
    PrinterJob job = PrinterJob.getPrinterJob();     
    // Specify the Printable is an instance of SimplePrint
    job.setPrintable(new SimplePrint());     
    // Put up the dialog box     
    if (job.printDialog()) 
    { 	
      // Print the job if the user didn't cancel printing 
      try { job.print(); }
      catch (Exception e)
        { /* handle exception */ }
    }     
    System.exit(0);   
  }


  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException 
  {     
    // pageIndex 0 to 4 corresponds to page numbers 1 to 5.
    if (pageIndex &gt;= 5) return Printable.NO_SUCH_PAGE;   
    g.setFont(fnt);     
    g.setColor(Color.green);     
    g.drawString("Page " + (pageIndex+1), 100, 100);     
    return Printable.PAGE_EXISTS;   
  } 
}
</pre></blockquote>
<br>
<h3>
<a name="418019"><!-- --></a>
<i>7.3.1	</i> Using Graphics2D for Rendering 
</h3>

<p>
You can invoke <kbd>Graphics2D</kbd> functions in you page painter&#39;s print method by first casting the <kbd>Graphics</kbd> context to a <kbd>Graphics2D</kbd>.<p>
In the following example, the page numbers are rendered using a red-green gradient. To do this, a <kbd>GradientPaint</kbd> is set in the <kbd>Graphics2D</kbd> context.<p>
<blockquote><pre>
import java.awt.*; import java.awt.print.*;
public class SimplePrint2D implements Printable 
{   
  private static Font fnt = new Font("Helvetica",Font.PLAIN,24);

  private Paint pnt = new GradientPaint(100f, 100f, Color.red, 	                                      136f, 100f, Color.green, true);

  public static void main(String[] args) 
  {     
    // Get a PrinterJob     
    PrinterJob job = PrinterJob.getPrinterJob();     
    // Specify the Printable is an instance of SimplePrint2D
    job.setPrintable(new SimplePrint2D());     
    // Put up the dialog box     
    if (job.printDialog()) 
    { 	
      // Print the job if the user didn't cancel printing 
      try { job.print(); } 	    
      catch (Exception e) { /* handle exception */ }     
    }     
  System.exit(0);   
  }


  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException 
  {     
    // pageIndex 0 to 4 corresponds to page numbers 1 to 5.
    if (pageIndex &gt;= 5) return Printable.NO_SUCH_PAGE;
    Graphics2D g2 = (Graphics2D) g;
    // Use the font defined above
    g2.setFont(fnt);
    // Use the gradient color defined above
    g2.setPaint(pnt);
    g2.drawString("Page " + (pageIndex+1), 100f, 100f);
    return Printable.PAGE_EXISTS;   
  } 
}</pre></blockquote>
<a name="418024"><!-- --></a>
<h3><i>7.3.2	</i> Printing a File</h3><br>

<p>
When a page painter&#39;s print method is invoked several times for the same page, it must generate the same output each time.<p>
There are many ways to ensure that repeated requests to render a page yield the same output. For example, to ensure that the same output is generated each time the printing system requests a particular page of a text file, page painter could either store and reuse file pointers for each page or store the actual page data. <p>
In the following example, a &#34;listing&#34; of a text file is printed. The name of the file is passed as an argument to the <kbd>main</kbd> method. The <kbd>PrintListingPainter</kbd> class stores the file pointer in effect at the beginning of each new page it is asked to render. When the same page is rendered again, the file pointer is reset to the remembered position.<p>
<blockquote><pre>
import java.awt.*; 
import java.awt.print.*; 
import java.io.*;

public class PrintListing 
{   
  public static void main(String[] args) 
  {     
    // Get a PrinterJob
    PrinterJob job = PrinterJob.getPrinterJob();
    // Ask user for page format (e.g., portrait/landscape)
    PageFormat pf = job.pageDialog(job.defaultPage());
    // Specify the Printable is an instance of
    // PrintListingPainter; also provide given PageFormat
    job.setPrintable(new PrintListingPainter(args[0]), pf);
    // Print 1 copy   
    job.setCopies(1);     
    // Put up the dialog box     
    if (job.printDialog()) 
    {
      // Print the job if the user didn't cancel printing
      try { job.print(); }
      catch (Exception e) { /* handle exception */ }     
    }     
    System.exit(0);   
  } 
}

class PrintListingPainter implements Printable 
{
  private RandomAccessFile raf;   
  private String fileName;   
  private Font fnt = new Font("Helvetica", Font.PLAIN, 10);
  private int rememberedPageIndex = -1;   
  private long rememberedFilePointer = -1;   
  private boolean rememberedEOF = false;

  public PrintListingPainter(String file) 
  { 
    fileName = file;     
    try
    { 
      // Open file 	
      raf = new RandomAccessFile(file, "r");     
    } 
    catch (Exception e) { rememberedEOF = true; }   
  }

  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException 
  {
  try 
  { 
    // For catching IOException     
    if (pageIndex != rememberedPageIndex) 
    { 
      // First time we've visited this page
      rememberedPageIndex = pageIndex; 	
      // If encountered EOF on previous page, done 
      if (rememberedEOF) return Printable.NO_SUCH_PAGE;
      // Save current position in input file
      rememberedFilePointer = raf.getFilePointer();
    } 
    else raf.seek(rememberedFilePointer);
    g.setColor(Color.black);     
    g.setFont(fnt); 
	int x = (int) pf.getImageableX() + 10;
	int y = (int) pf.getImageableY() + 12;    
    // Title line     
    g.drawString("File: " + fileName+", page: " + (pageIndex+1), 
                  x, y);
    // Generate as many lines as will fit in imageable area
    y += 36;
    while (y + 12 &lt; pf.getImageableY()+pf.getImageableHeight())
    {
      String line = raf.readLine();
      if (line == null)
      { 
        rememberedEOF = true;
        break; 
		}
        g.drawString(line, x, y); 
        y += 12;     
      }
      return Printable.PAGE_EXISTS;    
    } 
    catch (Exception e) { return Printable.NO_SUCH_PAGE;}
  } 
}</pre></blockquote>

<br>
</blockquote>
<hr>
<!-- Bug in Communicator w/font: NavBar text disappears for Times 14pt pref. -->
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm2.html">PREV</a>
 | <a href="j2d-print.fm4.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 14:56:01 1998 -->
 


</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm3.html">PREV</a>
 | NEXT <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="418034"><i>7.4	</i> Printing with Pageables and Books
</a></h2>

<blockquote>
<a name="418035"><!-- --></a>
<kbd>Pageable</kbd> jobs are suited for applications that build an explicit representation of a document, page by page. The <kbd>Book</kbd> class is a convenient way to use <kbd>Pageables</kbd>, but you can also build your own <kbd>Pageable</kbd> structures if <kbd>Book</kbd> does not suit your needs. This section shows you how to use <kbd>Book</kbd>.<p>
<a name="418036"><!-- --></a>
Although slightly more involved, <kbd>Pageable</kbd> jobs are preferred over <kbd>Printable</kbd> jobs because the printing system has more flexibility. A major advantage of <kbd>Pageables</kbd> is that the number of pages in the document is usually known and can be displayed to the user in the print dialog box. This helps the user to confirm that the job is specified correctly or to select a range of pages for printing.<p>
<a name="418037"><!-- --></a>
A <kbd>Book</kbd> represents a collection of pages. The pages in a book do not have to share the same size, orientation, or page painter. For example, a <kbd>Book</kbd> might contain two letter size pages in portrait orientation and a letter size page in landscape orientation.<p>
<a name="418038"><!-- --></a>
When a <kbd>Book</kbd> is first constructed, it is empty. To add pages to a <kbd>Book</kbd>, you use the <kbd>append</kbd> method. This method takes a <kbd>PageFormat</kbd> object that defines the page&#39;s size, printable area, and orientation and a page painter that implements the <kbd>Printable</kbd> interface.<p>
<a name="418039"><!-- --></a>
Multiple pages in a <kbd>Book</kbd> can share the same page format and painter. The <kbd>append</kbd> method is overloaded to enable you to add a series of pages that have the same attributes by specifying a third parameter, the number of pages.<p>
<a name="420434"><!-- --></a>
If you don&#39;t know the total number of pages in a <kbd>Book</kbd>, you can pass <kbd>UNKNOWN_NUMBER_OF_PAGES</kbd> to the <kbd>append</kbd> method. The printing system will then call your page painters in order of increasing page index until one of them returns <kbd>NO_SUCH_PAGE</kbd>.<p>
<a name="418041"><!-- --></a>
The <kbd>setPage</kbd> method can be used to change a page&#39;s page format or painter. The page to be changed is identified by a page index that indicates the page&#39;s location in the <kbd>Book</kbd>.<p>
<a name="418042"><!-- --></a>
You call <kbd>setPageable</kbd> and pass in the <kbd>Book</kbd> to prepare the print job. The <kbd>setPageable</kbd> and <kbd>setPrintable</kbd> methods are mutually exclusive; that is, you should call one or the other but not both when preparing the <kbd>PrinterJob</kbd>.<p>
</blockquote>
<br>
<h3>
<a name="421072"><!-- --></a>
<i>7.4.1	</i> Using a Pageable Job
</h3>

<blockquote>
<a name="418043"><!-- --></a>
In the following example, a <kbd>Book</kbd> is used to reproduce the first simple printing example. (Because this case is so simple, there is little benefit in using a <kbd>Pageable</kbd> job instead of a <kbd>Printable</kbd> job, but it illustrates the basics of using a <kbd>Book</kbd>.) Note that you still have to implement the <kbd>Printable</kbd> interface and perform page rendering in the page painter&#39;s <kbd>print</kbd> method. <p>
</blockquote><blockquote><pre>
import java.awt.*; 
import java.awt.print.*;

public class SimplePrintBook implements Printable 
{   
  private static Font fnt = new Font("Helvetica",Font.PLAIN,24);
  public static void main(String[] args) 
  {     
    // Get a PrinterJob     
    PrinterJob job = PrinterJob.getPrinterJob();     
    // Set up a book     
    Book bk = new Book();     
    bk.append(new SimplePrintBook(), job.defaultPage(), 5);     
    // Pass the book to the PrinterJob     
    job.setPageable(bk);     
    // Put up the dialog box     
    if (job.printDialog()) 
    {
      // Print the job if the user didn't cancel printing 
      try { job.print(); } 	    
      catch (Exception e) { /* handle exception */ }     
    }     
    System.exit(0);   
  }

  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException 
  {     
    g.setFont(fnt);     
    g.setColor(Color.green);     
    g.drawString("Page " + (pageIndex+1), 100, 100);     
    return Printable.PAGE_EXISTS;   
  }
}</pre></blockquote>
<br>
<h3>
<a name="418048"><!-- --></a>
<i>7.4.2	</i> Using Multiple Page Painters
</h3>

<blockquote>
<a name="421071"><!-- --></a>
In the following example, two different page painters are used: one for a cover page and one for content pages. The cover page is printed in landscape mode and the contents pages are printed in portrait mode.<p>
</blockquote><blockquote><pre>
import java.awt.*; 
import java.awt.print.*;

public class PrintBook 
{
  public static void main(String[] args) 
  {     
    // Get a PrinterJob     
    PrinterJob job = PrinterJob.getPrinterJob();     
    // Create a landscape page format    
    PageFormat pfl = job.defaultPage();  
    pfl.setOrientation(PageFormat.LANDSCAPE);     
    // Set up a book     
    Book bk = new Book();     
    bk.append(new PaintCover(), pfl);     
    bk.append(new PaintContent(), job.defaultPage(), 2);     
    // Pass the book to the PrinterJob     
    job.setPageable(bk);     
    // Put up the dialog box     
    if (job.printDialog()) 
    { 
      // Print the job if the user didn't cancel printing
      try { job.print(); } 
      catch (Exception e) { /* handle exception */ }     
    }     
  System.exit(0);   
  } 
}

class PaintCover implements Printable 
{   
  Font fnt = new Font("Helvetica-Bold", Font.PLAIN, 72);
 
  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException 
  {     
    g.setFont(fnt);     
    g.setColor(Color.black);     
	 int yc = (int) (pf.getImageableY() + 
              pf.getImageableHeight()/2);
    g.drawString("Widgets, Inc.", 72, yc+36);     
    return Printable.PAGE_EXISTS;   
  } 
}
class PaintContent implements Printable 
{   
  public int print(Graphics g, PageFormat pf, int pageIndex)
  throws PrinterException 
  {    
    Graphics2D g2 = (Graphics2D) g;     
    int useRed = 0;     
   int xo = (int) pf.getImageableX();
	int yo = (int) pf.getImageableY(); 
    // Fill page with circles or squares, alternating red &amp; green
	for (int x = 0; x+28 &lt; pf.getImageableWidth(); x += 36)
    for (int y = 0; y+28 &lt; pf.getImageableHeight(); y += 36)
    { 
      if (useRed == 0) g.setColor(Color.red);
      else g.setColor(Color.green);
      useRed = 1 - useRed;
      if (pageIndex % 2 == 0) g.drawRect(xo+x+4, yo+y+4, 28, 28);
      else g.drawOval(xo+x+4, yo+y+4, 28, 28);
    }     
    return   Printable.PAGE_EXISTS;   
  } 
}</pre></blockquote><blockquote>
<a name="418055"><!-- --></a>
<p>
</blockquote>

<br>
<hr>
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm3.html">PREV</a>
 | NEXT <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 14:56:01 1998 -->
 


</body>
</html>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Java 2D API
</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm4.html">PREV</a>
 | <a href="j2d-print.fm6.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right><i>Java 2D API</i></td>
</tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62287"><i>7.5	</i> Displaying a Page Setup Dialog
</a></h2>

<blockquote>
<a name="64305"><!-- --></a>
You can allow the user to select the paper size and orientation by displaying a page setup dialog. To do this, you call <kbd>Toolkit.setupPage</kbd>. <p>
<a name="66268"><!-- --></a>
In the following example:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="66288"><!-- --></a>
<kbd>NumberPainter</kbd> implements the <kbd>Printable</kbd> interface to draw page numbers on each page. 
</li>
<li>
<a name="66289"><!-- --></a>
<kbd>PageFormatPrint</kbd> is identical to <kbd>SimplePrint</kbd>, except that <kbd>setupPage </kbd>is called to display the page setup dialog and set the page format.
</li>
</ul>
</blockquote>
<pre><blockquote>import Java.lang.*;
</blockquote></pre><pre><blockquote>import Java.awt.*;
</blockquote></pre><pre><blockquote>import Java.awt.print.*;
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>public class PageFormatPrint {
</blockquote></pre><pre><blockquote>  public static void main(String[] args) {
</blockquote></pre><pre><blockquote>  Toolkit tk = Toolkit.getDefaultToolkit();
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>  // Create a new book 
</blockquote></pre><pre><blockquote>  Book book = new Book();
</blockquote></pre><pre><blockquote>  // Create a PageFormat and display the Page Setup dialog
</blockquote></pre><pre><blockquote>  PageFormat pageFormat = tk.setupPage(new PageFormat());
</blockquote></pre><pre><blockquote>  // Add two pages to the book that use the same page format and  
</blockquote></pre><pre><blockquote> // painter
</blockquote></pre><pre><blockquote>  book.append(pageFormat, new NumberPainter(), 2);
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>  /* Get a print job from the graphics environment and
</blockquote></pre><pre><blockquote>   * tell it to print our book of three pages.
</blockquote></pre><pre><blockquote>   */
</blockquote></pre><pre><blockquote>  PrintJob job = GraphicsEnvironment.getLocalGraphicsEnvironment().getPrintJob();
</blockquote></pre><pre><blockquote>  if(job.setupJob(book) == true){
</blockquote></pre><pre><blockquote>    job.print(book);
</blockquote></pre><pre><blockquote>    }
</blockquote></pre><pre><blockquote>  System.exit(0);
</blockquote></pre><pre><blockquote>  }
</blockquote></pre><pre><blockquote>
</blockquote></pre><pre><blockquote>}
</blockquote></pre><blockquote>
<a name="62342"><!-- --></a>
<p>
</blockquote>

<br>
<hr>
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm4.html">PREV</a>
 | <a href="j2d-print.fm6.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Tue Feb 24 10:24:35 1998 -->
 


</body>
</html>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html><head><title>Java 2D API
</title></head>
<body bgcolor="#ffffff">
<table width="100%"><tr>
<td><!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm5.html">PREV</a>
 | NEXT <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
 <!-- /font --></td><td align=right><i>Java 2D API</i></td>
 </tr></table>
<br>
 

<p>
<hr size="8" width="35%" align="left" noshade>

<h2><a name="62287"><i>7.6	</i> Displaying a Page Setup Dialog
</a></h2>

<blockquote>
<a name="64305"><!-- --></a>
You can allow the user to select the paper size and orientation by displaying a page setup dialog. To do this, you call <kbd>Toolkit.setupPage</kbd>. <p>
<a name="66268"><!-- --></a>
In the following example:<p>
</blockquote>
<blockquote>
<ul><li>
<a name="66288"><!-- --></a>
<kbd>NumberPainter</kbd> implements the <kbd>Printable</kbd> interface to draw page numbers on each page. 
</li>
<li>
<a name="66289"><!-- --></a>
<kbd>PageFormatPrint</kbd> is identical to <kbd>SimplePrint</kbd>, except that <kbd>setupPage </kbd>is called to display the page setup dialog and set the page format.
</li>
</ul>
</blockquote>
<a name="62291"><!-- --></a>
<pre>import Java.lang.*;
</pre>

<dl><a name="62292"><!-- --></a>
<dd><pre>import Java.awt.*;
</pre>

<a name="62293"><!-- --></a>
<dd><pre>import Java.awt.print.*;
</pre>

<a name="62294"><!-- --></a>
<dd><pre>
</pre>

<a name="62295"><!-- --></a>
<dd><pre>public class PageFormatPrint {
</pre>

<a name="62298"><!-- --></a>
<dd><pre>  public static void main(String[] args) {
</pre>

<a name="62300"><!-- --></a>
<dd><pre>  Toolkit tk = Toolkit.getDefaultToolkit();
</pre>

<a name="66281"><!-- --></a>
<dd><pre>
</pre>

<a name="62302"><!-- --></a>
<dd><pre>  // Create a new book 
</pre>

<a name="62305"><!-- --></a>
<dd><pre>  Book book = new Book();
</pre>

<a name="66282"><!-- --></a>
<dd><pre>  // Create a PageFormat and display the Page Setup dialog
</pre>

<a name="62306"><!-- --></a>
<dd><pre>  PageFormat pageFormat = tk.setupPage(new PageFormat());
</pre>

<a name="66283"><!-- --></a>
<dd><pre>  // Add two pages to the book that use the same page format and  
</pre>

<a name="66284"><!-- --></a>
<dd><pre> // painter
</pre>

<a name="62308"><!-- --></a>
<dd><pre>  book.append(pageFormat, new NumberPainter(), 2);
</pre>

<a name="66285"><!-- --></a>
<dd><pre>
</pre>

<a name="62310"><!-- --></a>
<dd><pre>  /* Get a print job from the graphics environment and
</pre>

<a name="62311"><!-- --></a>
<dd><pre>   * tell it to print our book of three pages.
</pre>

<a name="62312"><!-- --></a>
<dd><pre>   */
</pre>

<a name="62313"><!-- --></a>
<dd><pre>  PrintJob job = GraphicsEnvironment.getLocalGraphicsEnvironment().getPrintJob();
</pre>

<a name="62315"><!-- --></a>
<dd><pre>  if(job.setupJob(book) == true){
</pre>

<a name="62316"><!-- --></a>
<dd><pre>    job.print(book);
</pre>

<a name="62317"><!-- --></a>
<dd><pre>    }
</pre>

<a name="62319"><!-- --></a>
<dd><pre>  System.exit(0);
</pre>

<a name="62320"><!-- --></a>
<dd><pre>  }
</pre>

<a name="62321"><!-- --></a>
<dd><pre>
</pre>

</dl><a name="62322"><!-- --></a>
<pre>}
</pre>

<blockquote>
<a name="62342"><!-- --></a>
<p>
</blockquote>
<br>


<br>
<hr>
<!-- font size="-1" --> <a href="j2d-bookTOC.doc.html">CONTENTS</a> | <a href="j2d-print.fm5.html">PREV</a>
 | NEXT <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
 <!-- /font -->
 
 <hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>

</BODY>
</HTML>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<html>
<head>
<title>Programmer's Guide to the Java 2D API</title>
</head>
<body bgcolor="#ffffff">
 
<table width="100%"><tr>
<td><!-- font size="-1" -->
CONTENTS | PREV | <a href="j2d-bookTOC.doc.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font --></td><td align=right></td>
</tr></table>
<hr>

<TABLE BORDER=0 WIDTH="100%">
<tr>
<td width=40></td>
<td width=40></td>
<td width=40></td>
<td width=40></td>
<td></td>
</tr>
<a name="997233"><!-- --></a>
<center><h1>Programmer's Guide to the Java<sup>TM</sup> 2D API</h1></center>
<hr><p><blockquote>
<a name="997295"><!-- --></a>
<center>
JDK<sup>TM</sup> 1.2 Version<p>
<a name="997302"><!-- --></a>
November 2, 1998<p>
</center>
<a name="997223"><!-- --></a>
<p>
<a name="997224"><!-- --></a>
<p>
<a name="997225"><!-- --></a>
<p>
<a name="997226"><!-- --></a>
<p>
</blockquote><a name="997236"><!-- --></a>
<b></b> &nbsp; 


<a name="997220"><!-- --></a>
<b></b> &nbsp; 


<a name="997221"><!-- --></a>
<b></b> &nbsp; 


<a name="997192"><!-- --></a>
<b></b> &nbsp; <br>
<p><center><img src="j2d-title.fm.anc.gif"></center>



</TABLE>

<!--
<hr>
<h3>Deborah Adair</h3>
-->

<br>
<hr>
<!-- font size="-1" -->
CONTENTS | PREV | <a href="j2d-bookTOC.doc.html">NEXT</a> <!-- | <a href="j2d-print.fm.html">INDEX</a>  -->
<!-- /font -->

<hr>
<font size="-1"><i><A HREF="../../../relnotes/SMICopyright.html">Copyright</a> &#169 1997-1998 Sun Microsystems, Inc. All Rights Reserved.</i></font>


<!-- This HTML file was created with Quadralay WebWorks Publisher 3.5.0 -->
<!-- by Suzette Pelouch -->
<!-- Last updated: Wed Jun 10 13:48:02 1998 -->
 


</body>
</html>
