001 /* PathIterator.java -- describes a shape by iterating over its vertices 002 Copyright (C) 2000, 2002, 2003 Free Software Foundation 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 package java.awt.geom; 039 040 /** 041 * This interface provides a directed path over the boundary of a shape. The 042 * path can contain 1st through 3rd order Bezier curves (lines, and quadratic 043 * and cubic splines). A shape can have multiple disjoint paths via the 044 * MOVETO directive, and can close a circular path back to the previos 045 * MOVETO via the CLOSE directive. 046 * 047 * @author Tom Tromey (tromey@cygnus.com) 048 * @author Eric Blake (ebb9@email.byu.edu) 049 * @see java.awt.Shape 050 * @see java.awt.Stroke 051 * @see FlatteningPathIterator 052 * @since 1.2 053 * @status updated to 1.4 054 */ 055 public interface PathIterator 056 { 057 /** 058 * The even-odd winding mode: a point is internal to the shape if a ray 059 * from the point to infinity (in any direction) crosses an odd number of 060 * segments. 061 */ 062 int WIND_EVEN_ODD = 0; 063 064 /** 065 * The non-zero winding mode: a point is internal to the shape if a ray 066 * from the point to infinity (in any direction) crosses a different number 067 * of segments headed clockwise than those headed counterclockwise. 068 */ 069 int WIND_NON_ZERO = 1; 070 071 /** 072 * Starts a new subpath. There is no segment from the previous vertex. 073 */ 074 int SEG_MOVETO = 0; 075 076 /** 077 * The current segment is a line. 078 */ 079 int SEG_LINETO = 1; 080 081 /** 082 * The current segment is a quadratic parametric curve. It is interpolated 083 * as t varies from 0 to 1 over the current point (CP), first control point 084 * (P1), and final interpolated control point (P2): 085 * <pre> 086 * P(t) = B(2,0)*CP + B(2,1)*P1 + B(2,2)*P2 087 * 0 <= t <= 1 088 * B(n,m) = mth coefficient of nth degree Bernstein polynomial 089 * = C(n,m) * t^(m) * (1 - t)^(n-m) 090 * C(n,m) = Combinations of n things, taken m at a time 091 * = n! / (m! * (n-m)!) 092 * </pre> 093 */ 094 int SEG_QUADTO = 2; 095 096 /** 097 * The current segment is a cubic parametric curve (more commonly known as 098 * a Bezier curve). It is interpolated as t varies from 0 to 1 over the 099 * 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 */ 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 */ 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 */ 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 */ 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 */ 188 int currentSegment(double[] coords); 189 } // interface PathIterator