001 /*
002 * Copyright 1997-2000 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.geom;
027
028 /**
029 * The <code>PathIterator</code> interface provides the mechanism
030 * for objects that implement the {@link java.awt.Shape Shape}
031 * interface to return the geometry of their boundary by allowing
032 * a caller to retrieve the path of that boundary a segment at a
033 * time. This interface allows these objects to retrieve the path of
034 * their boundary a segment at a time by using 1st through 3rd order
035 * Bézier curves, which are lines and quadratic or cubic
036 * Bézier splines.
037 * <p>
038 * Multiple subpaths can be expressed by using a "MOVETO" segment to
039 * create a discontinuity in the geometry to move from the end of
040 * one subpath to the beginning of the next.
041 * <p>
042 * Each subpath can be closed manually by ending the last segment in
043 * the subpath on the same coordinate as the beginning "MOVETO" segment
044 * for that subpath or by using a "CLOSE" segment to append a line
045 * segment from the last point back to the first.
046 * Be aware that manually closing an outline as opposed to using a
047 * "CLOSE" segment to close the path might result in different line
048 * style decorations being used at the end points of the subpath.
049 * For example, the {@link java.awt.BasicStroke BasicStroke} object
050 * uses a line "JOIN" decoration to connect the first and last points
051 * if a "CLOSE" segment is encountered, whereas simply ending the path
052 * on the same coordinate as the beginning coordinate results in line
053 * "CAP" decorations being used at the ends.
054 *
055 * @see java.awt.Shape
056 * @see java.awt.BasicStroke
057 *
058 * @version 1.23, 05/05/07
059 * @author Jim Graham
060 */
061 public interface PathIterator {
062 /**
063 * The winding rule constant for specifying an even-odd rule
064 * for determining the interior of a path.
065 * The even-odd rule specifies that a point lies inside the
066 * path if a ray drawn in any direction from that point to
067 * infinity is crossed by path segments an odd number of times.
068 */
069 public static final int WIND_EVEN_ODD = 0;
070
071 /**
072 * The winding rule constant for specifying a non-zero rule
073 * for determining the interior of a path.
074 * The non-zero rule specifies that a point lies inside the
075 * path if a ray drawn in any direction from that point to
076 * infinity is crossed by path segments a different number
077 * of times in the counter-clockwise direction than the
078 * clockwise direction.
079 */
080 public static final int WIND_NON_ZERO = 1;
081
082 /**
083 * The segment type constant for a point that specifies the
084 * starting location for a new subpath.
085 */
086 public static final int SEG_MOVETO = 0;
087
088 /**
089 * The segment type constant for a point that specifies the
090 * end point of a line to be drawn from the most recently
091 * specified point.
092 */
093 public static final int SEG_LINETO = 1;
094
095 /**
096 * The segment type constant for the pair of points that specify
097 * a quadratic parametric curve to be drawn from the most recently
098 * specified point.
099 * The curve is interpolated by solving the parametric control
100 * equation in the range <code>(t=[0..1])</code> using
101 * the most recently specified (current) point (CP),
102 * the first control point (P1),
103 * and the final interpolated control point (P2).
104 * The parametric control equation for this curve is:
105 * <pre>
106 * P(t) = B(2,0)*CP + B(2,1)*P1 + B(2,2)*P2
107 * 0 <= t <= 1
108 *
109 * B(n,m) = mth coefficient of nth degree Bernstein polynomial
110 * = C(n,m) * t^(m) * (1 - t)^(n-m)
111 * C(n,m) = Combinations of n things, taken m at a time
112 * = n! / (m! * (n-m)!)
113 * </pre>
114 */
115 public static final int SEG_QUADTO = 2;
116
117 /**
118 * The segment type constant for the set of 3 points that specify
119 * a cubic parametric curve to be drawn from the most recently
120 * specified point.
121 * The curve is interpolated by solving the parametric control
122 * equation in the range <code>(t=[0..1])</code> using
123 * the most recently specified (current) point (CP),
124 * the first control point (P1),
125 * the second control point (P2),
126 * and the final interpolated control point (P3).
127 * The parametric control equation for this curve is:
128 * <pre>
129 * P(t) = B(3,0)*CP + B(3,1)*P1 + B(3,2)*P2 + B(3,3)*P3
130 * 0 <= t <= 1
131 *
132 * B(n,m) = mth coefficient of nth degree Bernstein polynomial
133 * = C(n,m) * t^(m) * (1 - t)^(n-m)
134 * C(n,m) = Combinations of n things, taken m at a time
135 * = n! / (m! * (n-m)!)
136 * </pre>
137 * This form of curve is commonly known as a Bézier curve.
138 */
139 public static final int SEG_CUBICTO = 3;
140
141 /**
142 * The segment type constant that specifies that
143 * the preceding subpath should be closed by appending a line segment
144 * back to the point corresponding to the most recent SEG_MOVETO.
145 */
146 public static final int SEG_CLOSE = 4;
147
148 /**
149 * Returns the winding rule for determining the interior of the
150 * path.
151 * @return the winding rule.
152 * @see #WIND_EVEN_ODD
153 * @see #WIND_NON_ZERO
154 */
155 public int getWindingRule();
156
157 /**
158 * Tests if the iteration is complete.
159 * @return <code>true</code> if all the segments have
160 * been read; <code>false</code> otherwise.
161 */
162 public boolean isDone();
163
164 /**
165 * Moves the iterator to the next segment of the path forwards
166 * along the primary direction of traversal as long as there are
167 * more points in that direction.
168 */
169 public void next();
170
171 /**
172 * Returns the coordinates and type of the current path segment in
173 * the iteration.
174 * The return value is the path-segment type:
175 * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
176 * A float array of length 6 must be passed in and can be used to
177 * store the coordinates of the point(s).
178 * Each point is stored as a pair of float x,y coordinates.
179 * SEG_MOVETO and SEG_LINETO types returns one point,
180 * SEG_QUADTO returns two points,
181 * SEG_CUBICTO returns 3 points
182 * and SEG_CLOSE does not return any points.
183 * @param coords an array that holds the data returned from
184 * this method
185 * @return the path-segment type of the current path segment.
186 * @see #SEG_MOVETO
187 * @see #SEG_LINETO
188 * @see #SEG_QUADTO
189 * @see #SEG_CUBICTO
190 * @see #SEG_CLOSE
191 */
192 public int currentSegment(float[] coords);
193
194 /**
195 * Returns the coordinates and type of the current path segment in
196 * the iteration.
197 * The return value is the path-segment type:
198 * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
199 * A double array of length 6 must be passed in and can be used to
200 * store the coordinates of the point(s).
201 * Each point is stored as a pair of double x,y coordinates.
202 * SEG_MOVETO and SEG_LINETO types returns one point,
203 * SEG_QUADTO returns two points,
204 * SEG_CUBICTO returns 3 points
205 * and SEG_CLOSE does not return any points.
206 * @param coords an array that holds the data returned from
207 * this method
208 * @return the path-segment type of the current path segment.
209 * @see #SEG_MOVETO
210 * @see #SEG_LINETO
211 * @see #SEG_QUADTO
212 * @see #SEG_CUBICTO
213 * @see #SEG_CLOSE
214 */
215 public int currentSegment(double[] coords);
216 }
|