1 /* PathIterator.java -- describes a shape by iterating over its vertices 2 Copyright (C) 2000, 2002, 2003 Free Software Foundation 3 4 This file is part of GNU Classpath. 5 6 GNU Classpath is free software; you can redistribute it and/or modify 7 it under the terms of the GNU General Public License as published by 8 the Free Software Foundation; either version 2, or (at your option) 9 any later version. 10 11 GNU Classpath is distributed in the hope that it will be useful, but 12 WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 You should have received a copy of the GNU General Public License 17 along with GNU Classpath; see the file COPYING. If not, write to the 18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19 02110-1301 USA. 20 21 Linking this library statically or dynamically with other modules is 22 making a combined work based on this library. Thus, the terms and 23 conditions of the GNU General Public License cover the whole 24 combination. 25 26 As a special exception, the copyright holders of this library give you 27 permission to link this library with independent modules to produce an 28 executable, regardless of the license terms of these independent 29 modules, and to copy and distribute the resulting executable under 30 terms of your choice, provided that you also meet, for each linked 31 independent module, the terms and conditions of the license of that 32 module. An independent module is a module which is not derived from 33 or based on this library. If you modify this library, you may extend 34 this exception to your version of the library, but you are not 35 obligated to do so. If you do not wish to do so, delete this 36 exception statement from your version. */ 37 38 package java.awt.geom; 39 40 /** 41 * This interface provides a directed path over the boundary of a shape. The 42 * path can contain 1st through 3rd order Bezier curves (lines, and quadratic 43 * and cubic splines). A shape can have multiple disjoint paths via the 44 * MOVETO directive, and can close a circular path back to the previos 45 * MOVETO via the CLOSE directive. 46 * 47 * @author Tom Tromey (tromey@cygnus.com) 48 * @author Eric Blake (ebb9@email.byu.edu) 49 * @see java.awt.Shape 50 * @see java.awt.Stroke 51 * @see FlatteningPathIterator 52 * @since 1.2 53 * @status updated to 1.4 54 */ 55 public interface PathIterator 56 { 57 /** 58 * The even-odd winding mode: a point is internal to the shape if a ray 59 * from the point to infinity (in any direction) crosses an odd number of 60 * segments. 61 */ 62 int WIND_EVEN_ODD = 0; 63 64 /** 65 * The non-zero winding mode: a point is internal to the shape if a ray 66 * from the point to infinity (in any direction) crosses a different number 67 * of segments headed clockwise than those headed counterclockwise. 68 */ 69 int WIND_NON_ZERO = 1; 70 71 /** 72 * Starts a new subpath. There is no segment from the previous vertex. 73 */ 74 int SEG_MOVETO = 0; 75 76 /** 77 * The current segment is a line. 78 */ 79 int SEG_LINETO = 1; 80 81 /** 82 * The current segment is a quadratic parametric curve. It is interpolated 83 * as t varies from 0 to 1 over the current point (CP), first control point 84 * (P1), and final interpolated control point (P2): 85 * <pre> 86 * P(t) = B(2,0)*CP + B(2,1)*P1 + B(2,2)*P2 87 * 0 <= t <= 1 88 * B(n,m) = mth coefficient of nth degree Bernstein polynomial 89 * = C(n,m) * t^(m) * (1 - t)^(n-m) 90 * C(n,m) = Combinations of n things, taken m at a time 91 * = n! / (m! * (n-m)!) 92 * </pre> 93 */ 94 int SEG_QUADTO = 2; 95 96 /** 97 * The current segment is a cubic parametric curve (more commonly known as 98 * a Bezier curve). It is interpolated as t varies from 0 to 1 over the 99 * current point (CP), first control point (P1), the second control point 100 * (P2), and final interpolated control point (P3): 101 * <pre> 102 * P(t) = B(3,0)*CP + B(3,1)*P1 + B(3,2)*P2 + B(3,3)*P3 103 * 0 <= t <= 1 104 * B(n,m) = mth coefficient of nth degree Bernstein polynomial 105 * = C(n,m) * t^(m) * (1 - t)^(n-m) 106 * C(n,m) = Combinations of n things, taken m at a time 107 * = n! / (m! * (n-m)!) 108 * </pre> 109 */ 110 int SEG_CUBICTO = 3; 111 112 /** 113 * The current segment closes a loop by an implicit line to the previous 114 * SEG_MOVETO coordinate. 115 */ 116 int SEG_CLOSE = 4; 117 118 /** 119 * Returns the winding rule to determine which points are inside this path. 120 * 121 * @return the winding rule 122 * @see #WIND_EVEN_ODD 123 * @see #WIND_NON_ZERO 124 */ getWindingRule()125 int getWindingRule(); 126 127 /** 128 * Tests if the iterator is exhausted. If this returns true, currentSegment 129 * and next may throw a NoSuchElementException (although this is not 130 * required). 131 * 132 * @return true if the iteration is complete 133 */ isDone()134 boolean isDone(); 135 136 /** 137 * Advance to the next segment in the iteration. It is not specified what 138 * this does if called when isDone() returns true. 139 * 140 * @throws java.util.NoSuchElementException optional when isDone() is true 141 */ next()142 void next(); 143 144 /** 145 * Returns the coordinates of the next point(s), as well as the type of 146 * line segment. The input array must be at least a float[6], to accomodate 147 * up to three (x,y) point pairs (although if you know the iterator is 148 * flat, you can probably get by with a float[2]). If the returned type is 149 * SEG_MOVETO or SEG_LINETO, the first point in the array is modified; if 150 * the returned type is SEG_QUADTO, the first two points are modified; if 151 * the returned type is SEG_CUBICTO, all three points are modified; and if 152 * the returned type is SEG_CLOSE, the array is untouched. 153 * 154 * @param coords the array to place the point coordinates in 155 * @return the segment type 156 * @throws NullPointerException if coords is null 157 * @throws ArrayIndexOutOfBoundsException if coords is too small 158 * @throws java.util.NoSuchElementException optional when isDone() is true 159 * @see #SEG_MOVETO 160 * @see #SEG_LINETO 161 * @see #SEG_QUADTO 162 * @see #SEG_CUBICTO 163 * @see #SEG_CLOSE 164 */ currentSegment(float[] coords)165 int currentSegment(float[] coords); 166 167 /** 168 * Returns the coordinates of the next point(s), as well as the type of 169 * line segment. The input array must be at least a double[6], to accomodate 170 * up to three (x,y) point pairs (although if you know the iterator is 171 * flat, you can probably get by with a double[2]). If the returned type is 172 * SEG_MOVETO or SEG_LINETO, the first point in the array is modified; if 173 * the returned type is SEG_QUADTO, the first two points are modified; if 174 * the returned type is SEG_CUBICTO, all three points are modified; and if 175 * the returned type is SEG_CLOSE, the array is untouched. 176 * 177 * @param coords the array to place the point coordinates in 178 * @return the segment type 179 * @throws NullPointerException if coords is null 180 * @throws ArrayIndexOutOfBoundsException if coords is too small 181 * @throws java.util.NoSuchElementException optional when isDone() is true 182 * @see #SEG_MOVETO 183 * @see #SEG_LINETO 184 * @see #SEG_QUADTO 185 * @see #SEG_CUBICTO 186 * @see #SEG_CLOSE 187 */ currentSegment(double[] coords)188 int currentSegment(double[] coords); 189 } // interface PathIterator 190