KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > geom > PathIterator


1 /*
2  * @(#)PathIterator.java 1.16 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.awt.geom;
9
10 /**
11  * The <code>PathIterator</code> interface provides the mechanism
12  * for objects that implement the {@link java.awt.Shape Shape}
13  * interface to return the geometry of their boundary by allowing
14  * a caller to retrieve the path of that boundary a segment at a
15  * time. This interface allows these objects to retrieve the path of
16  * their boundary a segment at a time by using 1st through 3rd order
17  * B&eacute;zier curves, which are lines and quadratic or cubic
18  * B&eacute;zier splines.
19  * <p>
20  * Multiple subpaths can be expressed by using a "MOVETO" segment to
21  * create a discontinuity in the geometry to move from the end of
22  * one subpath to the beginning of the next.
23  * <p>
24  * Each subpath can be closed manually by ending the last segment in
25  * the subpath on the same coordinate as the beginning "MOVETO" segment
26  * for that subpath or by using a "CLOSE" segment to append a line
27  * segment from the last point back to the first.
28  * Be aware that manually closing an outline as opposed to using a
29  * "CLOSE" segment to close the path might result in different line
30  * style decorations being used at the end points of the subpath.
31  * For example, the {@link java.awt.BasicStroke BasicStroke} object
32  * uses a line "JOIN" decoration to connect the first and last points
33  * if a "CLOSE" segment is encountered, whereas simply ending the path
34  * on the same coordinate as the beginning coordinate results in line
35  * "CAP" decorations being used at the ends.
36  *
37  * @see java.awt.Shape
38  * @see java.awt.BasicStroke
39  *
40  * @version 1.16, 12/19/03
41  * @author Jim Graham
42  */

43 public interface PathIterator {
44     /**
45      * The winding rule constant for specifying an even-odd rule
46      * for determining the interior of a path.
47      * The even-odd rule specifies that a point lies inside the
48      * path if a ray drawn in any direction from that point to
49      * infinity is crossed by path segments an odd number of times.
50      */

51     public static final int WIND_EVEN_ODD = 0;
52
53     /**
54      * The winding rule constant for specifying a non-zero rule
55      * for determining the interior of a path.
56      * The non-zero rule specifies that a point lies inside the
57      * path if a ray drawn in any direction from that point to
58      * infinity is crossed by path segments a different number
59      * of times in the counter-clockwise direction than the
60      * clockwise direction.
61      */

62     public static final int WIND_NON_ZERO = 1;
63
64     /**
65      * The segment type constant for a point that specifies the
66      * starting location for a new subpath.
67      */

68     public static final int SEG_MOVETO = 0;
69
70     /**
71      * The segment type constant for a point that specifies the
72      * end point of a line to be drawn from the most recently
73      * specified point.
74      */

75     public static final int SEG_LINETO = 1;
76
77     /**
78      * The segment type constant for the pair of points that specify
79      * a quadratic parametric curve to be drawn from the most recently
80      * specified point.
81      * The curve is interpolated by solving the parametric control
82      * equation in the range <code>(t=[0..1])</code> using
83      * the most recently specified (current) point (CP),
84      * the first control point (P1),
85      * and the final interpolated control point (P2).
86      * The parametric control equation for this curve is:
87      * <pre>
88      * P(t) = B(2,0)*CP + B(2,1)*P1 + B(2,2)*P2
89      * 0 &lt;= t &lt;= 1
90      *
91      * B(n,m) = mth coefficient of nth degree Bernstein polynomial
92      * = C(n,m) * t^(m) * (1 - t)^(n-m)
93      * C(n,m) = Combinations of n things, taken m at a time
94      * = n! / (m! * (n-m)!)
95      * </pre>
96      */

97     public static final int SEG_QUADTO = 2;
98
99     /**
100      * The segment type constant for the set of 3 points that specify
101      * a cubic parametric curve to be drawn from the most recently
102      * specified point.
103      * The curve is interpolated by solving the parametric control
104      * equation in the range <code>(t=[0..1])</code> using
105      * the most recently specified (current) point (CP),
106      * the first control point (P1),
107      * the second control point (P2),
108      * and the final interpolated control point (P3).
109      * The parametric control equation for this curve is:
110      * <pre>
111      * P(t) = B(3,0)*CP + B(3,1)*P1 + B(3,2)*P2 + B(3,3)*P3
112      * 0 &lt;= t &lt;= 1
113      *
114      * B(n,m) = mth coefficient of nth degree Bernstein polynomial
115      * = C(n,m) * t^(m) * (1 - t)^(n-m)
116      * C(n,m) = Combinations of n things, taken m at a time
117      * = n! / (m! * (n-m)!)
118      * </pre>
119      * This form of curve is commonly known as a B&eacute;zier curve.
120      */

121     public static final int SEG_CUBICTO = 3;
122
123     /**
124      * The segment type constant that specifies that
125      * the preceding subpath should be closed by appending a line segment
126      * back to the point corresponding to the most recent SEG_MOVETO.
127      */

128     public static final int SEG_CLOSE = 4;
129
130     /**
131      * Returns the winding rule for determining the interior of the
132      * path.
133      * @return the winding rule.
134      * @see #WIND_EVEN_ODD
135      * @see #WIND_NON_ZERO
136      */

137     public int getWindingRule();
138
139     /**
140      * Tests if the iteration is complete.
141      * @return <code>true</code> if all the segments have
142      * been read; <code>false</code> otherwise.
143      */

144     public boolean isDone();
145
146     /**
147      * Moves the iterator to the next segment of the path forwards
148      * along the primary direction of traversal as long as there are
149      * more points in that direction.
150      */

151     public void next();
152
153     /**
154      * Returns the coordinates and type of the current path segment in
155      * the iteration.
156      * The return value is the path-segment type:
157      * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
158      * A float array of length 6 must be passed in and can be used to
159      * store the coordinates of the point(s).
160      * Each point is stored as a pair of float x,y coordinates.
161      * SEG_MOVETO and SEG_LINETO types returns one point,
162      * SEG_QUADTO returns two points,
163      * SEG_CUBICTO returns 3 points
164      * and SEG_CLOSE does not return any points.
165      * @param coords an array that holds the data returned from
166      * this method
167      * @return the path-segment type of the current path segment.
168      * @see #SEG_MOVETO
169      * @see #SEG_LINETO
170      * @see #SEG_QUADTO
171      * @see #SEG_CUBICTO
172      * @see #SEG_CLOSE
173      */

174     public int currentSegment(float[] coords);
175
176     /**
177      * Returns the coordinates and type of the current path segment in
178      * the iteration.
179      * The return value is the path-segment type:
180      * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
181      * A double array of length 6 must be passed in and can be used to
182      * store the coordinates of the point(s).
183      * Each point is stored as a pair of double x,y coordinates.
184      * SEG_MOVETO and SEG_LINETO types returns one point,
185      * SEG_QUADTO returns two points,
186      * SEG_CUBICTO returns 3 points
187      * and SEG_CLOSE does not return any points.
188      * @param coords an array that holds the data returned from
189      * this method
190      * @return the path-segment type of the current path segment.
191      * @see #SEG_MOVETO
192      * @see #SEG_LINETO
193      * @see #SEG_QUADTO
194      * @see #SEG_CUBICTO
195      * @see #SEG_CLOSE
196      */

197     public int currentSegment(double[] coords);
198 }
199
Popular Tags