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