1 /*
2  * Copyright (c) 1997, 2013, 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 java.lang.annotation.Native;
29 
30 /**
31  * The {@code PathIterator} 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 public interface PathIterator {
63     /**
64      * The winding rule constant for specifying an even-odd rule
65      * for determining the interior of a path.
66      * The even-odd rule specifies that a point lies inside the
67      * path if a ray drawn in any direction from that point to
68      * infinity is crossed by path segments an odd number of times.
69      */
70     @Native public static final int WIND_EVEN_ODD       = 0;
71 
72     /**
73      * The winding rule constant for specifying a non-zero rule
74      * for determining the interior of a path.
75      * The non-zero rule specifies that a point lies inside the
76      * path if a ray drawn in any direction from that point to
77      * infinity is crossed by path segments a different number
78      * of times in the counter-clockwise direction than the
79      * clockwise direction.
80      */
81     @Native public static final int WIND_NON_ZERO       = 1;
82 
83     /**
84      * The segment type constant for a point that specifies the
85      * starting location for a new subpath.
86      */
87     @Native public static final int SEG_MOVETO          = 0;
88 
89     /**
90      * The segment type constant for a point that specifies the
91      * end point of a line to be drawn from the most recently
92      * specified point.
93      */
94     @Native public static final int SEG_LINETO          = 1;
95 
96     /**
97      * The segment type constant for the pair of points that specify
98      * a quadratic parametric curve to be drawn from the most recently
99      * specified point.
100      * The curve is interpolated by solving the parametric control
101      * equation in the range {@code (t=[0..1])} using
102      * the most recently specified (current) point (CP),
103      * the first control point (P1),
104      * and the final interpolated control point (P2).
105      * The parametric control equation for this curve is:
106      * <pre>
107      *          P(t) = B(2,0)*CP + B(2,1)*P1 + B(2,2)*P2
108      *          0 &lt;= t &lt;= 1
109      *
110      *        B(n,m) = mth coefficient of nth degree Bernstein polynomial
111      *               = C(n,m) * t^(m) * (1 - t)^(n-m)
112      *        C(n,m) = Combinations of n things, taken m at a time
113      *               = n! / (m! * (n-m)!)
114      * </pre>
115      */
116     @Native public static final int SEG_QUADTO          = 2;
117 
118     /**
119      * The segment type constant for the set of 3 points that specify
120      * a cubic parametric curve to be drawn from the most recently
121      * specified point.
122      * The curve is interpolated by solving the parametric control
123      * equation in the range {@code (t=[0..1])} using
124      * the most recently specified (current) point (CP),
125      * the first control point (P1),
126      * the second control point (P2),
127      * and the final interpolated control point (P3).
128      * The parametric control equation for this curve is:
129      * <pre>
130      *          P(t) = B(3,0)*CP + B(3,1)*P1 + B(3,2)*P2 + B(3,3)*P3
131      *          0 &lt;= t &lt;= 1
132      *
133      *        B(n,m) = mth coefficient of nth degree Bernstein polynomial
134      *               = C(n,m) * t^(m) * (1 - t)^(n-m)
135      *        C(n,m) = Combinations of n things, taken m at a time
136      *               = n! / (m! * (n-m)!)
137      * </pre>
138      * This form of curve is commonly known as a B&eacute;zier curve.
139      */
140     @Native public static final int SEG_CUBICTO         = 3;
141 
142     /**
143      * The segment type constant that specifies that
144      * the preceding subpath should be closed by appending a line segment
145      * back to the point corresponding to the most recent SEG_MOVETO.
146      */
147     @Native public static final int SEG_CLOSE           = 4;
148 
149     /**
150      * Returns the winding rule for determining the interior of the
151      * path.
152      * @return the winding rule.
153      * @see #WIND_EVEN_ODD
154      * @see #WIND_NON_ZERO
155      */
getWindingRule()156     public int getWindingRule();
157 
158     /**
159      * Tests if the iteration is complete.
160      * @return {@code true} if all the segments have
161      * been read; {@code false} otherwise.
162      */
isDone()163     public boolean isDone();
164 
165     /**
166      * Moves the iterator to the next segment of the path forwards
167      * along the primary direction of traversal as long as there are
168      * more points in that direction.
169      */
next()170     public void next();
171 
172     /**
173      * Returns the coordinates and type of the current path segment in
174      * the iteration.
175      * The return value is the path-segment type:
176      * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
177      * A float array of length 6 must be passed in and can be used to
178      * store the coordinates of the point(s).
179      * Each point is stored as a pair of float x,y coordinates.
180      * SEG_MOVETO and SEG_LINETO types returns one point,
181      * SEG_QUADTO returns two points,
182      * SEG_CUBICTO returns 3 points
183      * and SEG_CLOSE does not return any points.
184      * @param coords an array that holds the data returned from
185      * this method
186      * @return the path-segment type of the current path segment.
187      * @see #SEG_MOVETO
188      * @see #SEG_LINETO
189      * @see #SEG_QUADTO
190      * @see #SEG_CUBICTO
191      * @see #SEG_CLOSE
192      */
currentSegment(float[] coords)193     public int currentSegment(float[] coords);
194 
195     /**
196      * Returns the coordinates and type of the current path segment in
197      * the iteration.
198      * The return value is the path-segment type:
199      * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
200      * A double array of length 6 must be passed in and can be used to
201      * store the coordinates of the point(s).
202      * Each point is stored as a pair of double x,y coordinates.
203      * SEG_MOVETO and SEG_LINETO types returns one point,
204      * SEG_QUADTO returns two points,
205      * SEG_CUBICTO returns 3 points
206      * and SEG_CLOSE does not return any points.
207      * @param coords an array that holds the data returned from
208      * this method
209      * @return the path-segment type of the current path segment.
210      * @see #SEG_MOVETO
211      * @see #SEG_LINETO
212      * @see #SEG_QUADTO
213      * @see #SEG_CUBICTO
214      * @see #SEG_CLOSE
215      */
currentSegment(double[] coords)216     public int currentSegment(double[] coords);
217 }
218