PathIterator


1   /*
2    * @(#)PathIterator.java    1.16 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt.geom;
9   
10  /**
11   * The <code>PathIterator</code> interface provides the mechanism 
12   * for objects that implement the {@link java.awt.Shape Shape}
13   * interface to return the geometry of their boundary by allowing
14   * a caller to retrieve the path of that boundary a segment at a
15   * time.  This interface allows these objects to retrieve the path of
16   * their boundary a segment at a time by using 1st through 3rd order
17   * B&eacute;zier curves, which are lines and quadratic or cubic
18   * B&eacute;zier splines.
19   * <p>
20   * Multiple subpaths can be expressed by using a "MOVETO" segment to
21   * create a discontinuity in the geometry to move from the end of
22   * one subpath to the beginning of the next.
23   * <p>
24   * Each subpath can be closed manually by ending the last segment in
25   * the subpath on the same coordinate as the beginning "MOVETO" segment
26   * for that subpath or by using a "CLOSE" segment to append a line
27   * segment from the last point back to the first.
28   * Be aware that manually closing an outline as opposed to using a
29   * "CLOSE" segment to close the path might result in different line
30   * style decorations being used at the end points of the subpath.
31   * For example, the {@link java.awt.BasicStroke BasicStroke} object 
32   * uses a line "JOIN" decoration to connect the first and last points 
33   * if a "CLOSE" segment is encountered, whereas simply ending the path 
34   * on the same coordinate as the beginning coordinate results in line
35   * "CAP" decorations being used at the ends.
36   *
37   * @see java.awt.Shape
38   * @see java.awt.BasicStroke
39   *
40   * @version 1.16, 12/19/03
41   * @author Jim Graham
42   */
43  public interface PathIterator {
44      /**
45       * The winding rule constant for specifying an even-odd rule
46       * for determining the interior of a path.
47       * The even-odd rule specifies that a point lies inside the
48       * path if a ray drawn in any direction from that point to
49       * infinity is crossed by path segments an odd number of times.
50       */
51      public static final int WIND_EVEN_ODD   = 0;
52  
53      /**
54       * The winding rule constant for specifying a non-zero rule
55       * for determining the interior of a path.
56       * The non-zero rule specifies that a point lies inside the
57       * path if a ray drawn in any direction from that point to
58       * infinity is crossed by path segments a different number
59       * of times in the counter-clockwise direction than the
60       * clockwise direction.
61       */
62      public static final int WIND_NON_ZERO   = 1;
63  
64      /**
65       * The segment type constant for a point that specifies the
66       * starting location for a new subpath.
67       */
68      public static final int SEG_MOVETO      = 0;
69  
70      /**
71       * The segment type constant for a point that specifies the
72       * end point of a line to be drawn from the most recently
73       * specified point.
74       */
75      public static final int SEG_LINETO      = 1;
76  
77      /**
78       * The segment type constant for the pair of points that specify
79       * a quadratic parametric curve to be drawn from the most recently
80       * specified point.
81       * The curve is interpolated by solving the parametric control
82       * equation in the range <code>(t=[0..1])</code> using
83       * the most recently specified (current) point (CP),
84       * the first control point (P1),
85       * and the final interpolated control point (P2).
86       * The parametric control equation for this curve is:
87       * <pre>
88       *          P(t) = B(2,0)*CP + B(2,1)*P1 + B(2,2)*P2
89       *          0 &lt;= t &lt;= 1
90       *
91       *        B(n,m) = mth coefficient of nth degree Bernstein polynomial
92       *               = C(n,m) * t^(m) * (1 - t)^(n-m)
93       *        C(n,m) = Combinations of n things, taken m at a time
94       *               = n! / (m! * (n-m)!)
95       * </pre>
96       */
97      public static final int SEG_QUADTO      = 2;
98  
99      /**
100      * The segment type constant for the set of 3 points that specify
101      * a cubic parametric curve to be drawn from the most recently
102      * specified point.
103      * The curve is interpolated by solving the parametric control
104      * equation in the range <code>(t=[0..1])</code> using
105      * the most recently specified (current) point (CP),
106      * the first control point (P1),
107      * the second control point (P2),
108      * and the final interpolated control point (P3).
109      * The parametric control equation for this curve is:
110      * <pre>
111      *          P(t) = B(3,0)*CP + B(3,1)*P1 + B(3,2)*P2 + B(3,3)*P3
112      *          0 &lt;= t &lt;= 1
113      *
114      *        B(n,m) = mth coefficient of nth degree Bernstein polynomial
115      *               = C(n,m) * t^(m) * (1 - t)^(n-m)
116      *        C(n,m) = Combinations of n things, taken m at a time
117      *               = n! / (m! * (n-m)!)
118      * </pre>
119      * This form of curve is commonly known as a B&eacute;zier curve.
120      */
121     public static final int SEG_CUBICTO     = 3;
122 
123     /**
124      * The segment type constant that specifies that
125      * the preceding subpath should be closed by appending a line segment
126      * back to the point corresponding to the most recent SEG_MOVETO.
127      */
128     public static final int SEG_CLOSE       = 4;
129 
130     /**
131      * Returns the winding rule for determining the interior of the
132      * path.
133      * @return the winding rule.
134      * @see #WIND_EVEN_ODD
135      * @see #WIND_NON_ZERO
136      */
137     public int getWindingRule();
138 
139     /**
140      * Tests if the iteration is complete.
141      * @return <code>true</code> if all the segments have 
142      * been read; <code>false</code> otherwise.
143      */
144     public boolean isDone();
145 
146     /**
147      * Moves the iterator to the next segment of the path forwards
148      * along the primary direction of traversal as long as there are
149      * more points in that direction.
150      */
151     public void next();
152 
153     /**
154      * Returns the coordinates and type of the current path segment in
155      * the iteration.
156      * The return value is the path-segment type:
157      * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
158      * A float array of length 6 must be passed in and can be used to
159      * store the coordinates of the point(s).
160      * Each point is stored as a pair of float x,y coordinates.
161      * SEG_MOVETO and SEG_LINETO types returns one point,
162      * SEG_QUADTO returns two points,
163      * SEG_CUBICTO returns 3 points
164      * and SEG_CLOSE does not return any points.
165      * @param coords an array that holds the data returned from
166      * this method
167      * @return the path-segment type of the current path segment.
168      * @see #SEG_MOVETO
169      * @see #SEG_LINETO
170      * @see #SEG_QUADTO
171      * @see #SEG_CUBICTO
172      * @see #SEG_CLOSE
173      */
174     public int currentSegment(float[] coords);
175 
176     /**
177      * Returns the coordinates and type of the current path segment in
178      * the iteration.
179      * The return value is the path-segment type:
180      * SEG_MOVETO, SEG_LINETO, SEG_QUADTO, SEG_CUBICTO, or SEG_CLOSE.
181      * A double array of length 6 must be passed in and can be used to
182      * store the coordinates of the point(s).
183      * Each point is stored as a pair of double x,y coordinates.
184      * SEG_MOVETO and SEG_LINETO types returns one point,
185      * SEG_QUADTO returns two points,
186      * SEG_CUBICTO returns 3 points
187      * and SEG_CLOSE does not return any points.
188      * @param coords an array that holds the data returned from
189      * this method
190      * @return the path-segment type of the current path segment.
191      * @see #SEG_MOVETO
192      * @see #SEG_LINETO
193      * @see #SEG_QUADTO
194      * @see #SEG_CUBICTO
195      * @see #SEG_CLOSE
196      */
197     public int currentSegment(double[] coords);
198 }
199
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags