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