1 /*
2 * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.awt.geom;
27
28 /**
29 * The <code>PathIterator</code> interface provides the mechanism
30 * for objects that implement the {@link java.awt.Shape Shape}
31 * interface to return the geometry of their boundary by allowing
32 * a caller to retrieve the path of that boundary a segment at a
33 * time. This interface allows these objects to retrieve the path of
34 * their boundary a segment at a time by using 1st through 3rd order
35 * Bézier curves, which are lines and quadratic or cubic
36 * Bézier splines.
37 * <p>
38 * Multiple subpaths can be expressed by using a "MOVETO" segment to
39 * create a discontinuity in the geometry to move from the end of
40 * one subpath to the beginning of the next.
41 * <p>
42 * Each subpath can be closed manually by ending the last segment in
43 * the subpath on the same coordinate as the beginning "MOVETO" segment
44 * for that subpath or by using a "CLOSE" segment to append a line
45 * segment from the last point back to the first.
46 * Be aware that manually closing an outline as opposed to using a
47 * "CLOSE" segment to close the path might result in different line
48 * style decorations being used at the end points of the subpath.
49 * For example, the {@link java.awt.BasicStroke BasicStroke} object
50 * uses a line "JOIN" decoration to connect the first and last points
51 * if a "CLOSE" segment is encountered, whereas simply ending the path
52 * on the same coordinate as the beginning coordinate results in line
53 * "CAP" decorations being used at the ends.
54 *
55 * @see java.awt.Shape
56 * @see java.awt.BasicStroke
57 *
58 * @author Jim Graham
59 */
60 public interface PathIterator {
61 /**
62 * The winding rule constant for specifying an even-odd rule
63 * for determining the interior of a path.
64 * The even-odd rule specifies that a point lies inside the
65 * path if a ray drawn in any direction from that point to
66 * infinity is crossed by path segments an odd number of times.
67 */
68 public static final int WIND_EVEN_ODD = 0;
69
70 /**
71 * The winding rule constant for specifying a non-zero rule
72 * for determining the interior of a path.
73 * The non-zero rule specifies that a point lies inside the
74 * path if a ray drawn in any direction from that point to
75 * infinity is crossed by path segments a different number
76 * of times in the counter-clockwise direction than the
77 * clockwise direction.
78 */
79 public static final int WIND_NON_ZERO = 1;
80
81 /**
82 * The segment type constant for a point that specifies the
83 * starting location for a new subpath.
84 */
85 public static final int SEG_MOVETO = 0;
86
87 /**
88 * The segment type constant for a point that specifies the
89 * end point of a line to be drawn from the most recently
90 * specified point.
91 */
92 public static final int SEG_LINETO = 1;
93
94 /**
95 * The segment type constant for the pair of points that specify
96 * a quadratic parametric curve to be drawn from the most recently
97 * specified point.
98 * The curve is interpolated by solving the parametric control
99 * equation in the range <code>(t=[0..1])</code> using
100 * the most recently specified (current) point (CP),
101 * the first control point (P1),
102 * and the final interpolated control point (P2).
103 * The parametric control equation for this curve is:
104 * <pre>
105 * P(t) = B(2,0)*CP + B(2,1)*P1 + B(2,2)*P2
106 * 0 <= t <= 1
107 *
108 * B(n,m) = mth coefficient of nth degree Bernstein polynomial
109 * = C(n,m) * t^(m) * (1 - t)^(n-m)
110 * C(n,m) = Combinations of n things, taken m at a time
111 * = n! / (m! * (n-m)!)
112 * </pre>
113 */
114 public static final int SEG_QUADTO = 2;
115
116 /**
117 * The segment type constant for the set of 3 points that specify
118 * a cubic parametric curve to be drawn from the most recently
119 * specified point.
120 * The curve is interpolated by solving the parametric control
121 * equation in the range <code>(t=[0..1])</code> using
122 * the most recently specified (current) point (CP),
123 * the first control point (P1),
124 * the second control point (P2),
125 * and the final interpolated control point (P3).
126 * The parametric control equation for this curve is:
127 * <pre>
128 * P(t) = B(3,0)*CP + B(3,1)*P1 + B(3,2)*P2 + B(3,3)*P3
129 * 0 <= t <= 1
130 *
131 * B(n,m) = mth coefficient of nth degree Bernstein polynomial
132 * = C(n,m) * t^(m) * (1 - t)^(n-m)
133 * C(n,m) = Combinations of n things, taken m at a time
134 * = n! / (m! * (n-m)!)
135 * </pre>
136 * This form of curve is commonly known as a Bézier curve.
137 */
138 public static final int SEG_CUBICTO = 3;
139
140 /**
141 * The segment type constant that specifies that
142 * the preceding subpath should be closed by appending a line segment
143 * back to the point corresponding to the most recent SEG_MOVETO.
144 */
145 public static final int SEG_CLOSE = 4;
146
147 /**
148 * Returns the winding rule for determining the interior of the
149 * path.
150 * @return the winding rule.
151 * @see #WIND_EVEN_ODD
152 * @see #WIND_NON_ZERO
153 */
154 public int getWindingRule();
155
156 /**
157 * Tests if the iteration is complete.
158 * @return <code>true</code> if all the segments have
159 * been read; <code>false</code> otherwise.
160 */
161 public boolean isDone();
162
163 /**
164 * Moves the iterator to the next segment of the path forwards
165 * along the primary direction of traversal as long as there are
166 * more points in that direction.
167 */
168 public void next();
169
170 /**
171 * Returns the coordinates and type of the current path segment in
172 * the iteration.
173 * The return value is the path-segment type:
174 * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
175 * A float array of length 6 must be passed in and can be used to
176 * store the coordinates of the point(s).
177 * Each point is stored as a pair of float x,y coordinates.
178 * SEG_MOVETO and SEG_LINETO types returns one point,
179 * SEG_QUADTO returns two points,
180 * SEG_CUBICTO returns 3 points
181 * and SEG_CLOSE does not return any points.
182 * @param coords an array that holds the data returned from
183 * this method
184 * @return the path-segment type of the current path segment.
185 * @see #SEG_MOVETO
186 * @see #SEG_LINETO
187 * @see #SEG_QUADTO
188 * @see #SEG_CUBICTO
189 * @see #SEG_CLOSE
190 */
191 public int currentSegment(float[] coords);
192
193 /**
194 * Returns the coordinates and type of the current path segment in
195 * the iteration.
196 * The return value is the path-segment type:
197 * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
198 * A double array of length 6 must be passed in and can be used to
199 * store the coordinates of the point(s).
200 * Each point is stored as a pair of double x,y coordinates.
201 * SEG_MOVETO and SEG_LINETO types returns one point,
202 * SEG_QUADTO returns two points,
203 * SEG_CUBICTO returns 3 points
204 * and SEG_CLOSE does not return any points.
205 * @param coords an array that holds the data returned from
206 * this method
207 * @return the path-segment type of the current path segment.
208 * @see #SEG_MOVETO
209 * @see #SEG_LINETO
210 * @see #SEG_QUADTO
211 * @see #SEG_CUBICTO
212 * @see #SEG_CLOSE
213 */
214 public int currentSegment(double[] coords);
215 }
Save This Page