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 | 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</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 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])</code> 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 <= t <= 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])</code> 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 <= t <= 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é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 */ 156 public int getWindingRule(); 157 158 /** 159 * Tests if the iteration is complete. 160 * @return <code>true</code> if all the segments have 161 * been read; <code>false</code> otherwise. 162 */ 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 |