CubicCurve2D.java (contains): Docfix for URL of embedded drawing.

2003-10-29  Sascha Brawer  <brawer@dandelis.ch>

        * java/awt/geom/CubicCurve2D.java (contains): Docfix for URL of embedded drawing.
        * java/awt/geom/QuadCurve2D.java: Likewise.

2003-10-29  Sascha Brawer  <brawer@dandelis.ch>

	* java/awt/geom/CubicCurve2D.java: Added documentation.
	* java/awt/geom/QuadCurve2D.java: Likewise.

	* java/awt/geom/doc-files/QuadCurve2D-4.png,
	java/awt/geom/doc-files/QuadCurve2D-5.png,
	java/awt/geom/doc-files/CubicCurve2D-4.png,
	java/awt/geom/doc-files/Cubicurve2D-5.png: New illustrations.

2003-10-29  Sascha Brawer  <brawer@dandelis.ch>

	* java/awt/geom/CubicCurve2D.java (getFlatnessSq): Implement.
	(subdivide(CubicCurve2D, CubicCurve2D)): Avoid useless object allocation.
	(subdivide(double[],int,double[],int,double[],int)): Implement.

2003-10-29  Sascha Brawer  <brawer@dandelis.ch>

	* java/awt/geom/doc-files/CubicCurve2D-1.png,
	java/awt/geom/doc-files/CubicCurve2D-2.png,
	java/awt/geom/doc-files/CubicCurve2D-3.png: New illustrations.

From-SVN: r73048

1 files changed, 196 insertions, 6 deletions

diff --git a/libjava/java/awt/geom/QuadCurve2D.java b/libjava/java/awt/geom/QuadCurve2D.java
index e737ec1..5bc63e6 100644
--- a/libjava/java/awt/geom/QuadCurve2D.java
+++ b/libjava/java/awt/geom/QuadCurve2D.java
@@ -51,6 +51,7 @@ import java.util.NoSuchElementException;
  * alt="A drawing of a QuadCurve2D" />
  *
  * @author Eric Blake (ebb9@email.byu.edu)
+ * @author Graydon Hoare (graydon@redhat.com)
  * @author Sascha Brawer (brawer@dandelis.ch)
  *
  * @since 1.2
@@ -129,7 +130,8 @@ public abstract class QuadCurve2D
 
 
   /**
-   * Changes the geometry of the curve.
+   * Changes the curve geometry, separately specifying each coordinate
+   * value.
    *
    * @param x1 the <i>x</i> coordinate of the curve&#x2019;s new start
    * point.
@@ -153,6 +155,23 @@ public abstract class QuadCurve2D
                                 double x2, double y2);
 
 
+  /**
+   * Changes the curve geometry, passing coordinate values in an
+   * array.
+   *
+   * @param coords an array containing the new coordinate values.  The
+   * <i>x</i> coordinate of the new start point is located at
+   * <code>coords[offset]</code>, its <i>y</i> coordinate at
+   * <code>coords[offset + 1]</code>.  The <i>x</i> coordinate of the
+   * new control point is located at <code>coords[offset + 2]</code>,
+   * its <i>y</i> coordinate at <code>coords[offset + 3]</code>. The
+   * <i>x</i> coordinate of the new end point is located at
+   * <code>coords[offset + 4]</code>, its <i>y</i> coordinate at
+   * <code>coords[offset + 5]</code>.
+   *
+   * @param offset the offset of the first coordinate value in
+   * <code>coords</code>.
+   */
   public void setCurve(double[] coords, int offset)
   {
     setCurve(coords[offset++], coords[offset++],
@@ -161,6 +180,22 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Changes the curve geometry, specifying coordinate values in
+   * separate Point objects.
+   *
+   * <p><img src="doc-files/QuadCurve2D-1.png" width="350" height="180"
+   * alt="A drawing of a QuadCurve2D" />
+   *
+   * <p>The curve does not keep any reference to the passed point
+   * objects. Therefore, a later change to <code>p1</code>,
+   * <code>c</code> <code>p2</code> will not affect the curve
+   * geometry.
+   *
+   * @param p1 the new start point.
+   * @param c the new control point.
+   * @param p2 the new end point.
+   */
   public void setCurve(Point2D p1, Point2D c, Point2D p2)
   {
     setCurve(p1.getX(), p1.getY(), c.getX(), c.getY(),
@@ -168,11 +203,29 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Changes the curve geometry, specifying coordinate values in an
+   * array of Point objects.
+   *
+   * <p><img src="doc-files/QuadCurve2D-1.png" width="350" height="180"
+   * alt="A drawing of a QuadCurve2D" />
+   *
+   * <p>The curve does not keep references to the passed point
+   * objects. Therefore, a later change to the <code>pts</code> array
+   * or any of its elements will not affect the curve geometry.
+   *
+   * @param pts an array containing the points. The new start point
+   * is located at <code>pts[offset]</code>, the new control
+   * point at <code>pts[offset + 1]</code>, and the new end point
+   * at <code>pts[offset + 2]</code>.
+   *
+   * @param offset the offset of the start point in <code>pts</code>.
+   */
   public void setCurve(Point2D[] pts, int offset)
   {
-    setCurve(pts[offset].getX(), pts[offset++].getY(),
-             pts[offset].getX(), pts[offset++].getY(),
-             pts[offset].getX(), pts[offset++].getY());
+    setCurve(pts[offset].getX(), pts[offset].getY(),
+             pts[offset + 1].getX(), pts[offset + 1].getY(),
+             pts[offset + 2].getX(), pts[offset + 2].getY());
   }
 
 
@@ -188,6 +241,26 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Calculates the squared flatness of a quadratic curve, directly
+   * specifying each coordinate value. The flatness is the distance of
+   * the control point to the line between start and end point.
+   *
+   * <p><img src="doc-files/QuadCurve2D-4.png" width="350" height="180"
+   * alt="A drawing that illustrates the flatness" />
+   *
+   * <p>In the above drawing, the straight line connecting start point
+   * P1 and end point P2 is depicted in gray.  The result will be the
+   * the square of the distance between C and the gray line, i.e.
+   * the squared length of the red line.
+   *
+   * @param x1 the <i>x</i> coordinate of the start point P1.
+   * @param y1 the <i>y</i> coordinate of the start point P1.
+   * @param cx the <i>x</i> coordinate of the control point C.
+   * @param cy the <i>y</i> coordinate of the control point C.
+   * @param x2 the <i>x</i> coordinate of the end point P2.
+   * @param y2 the <i>y</i> coordinate of the end point P2.
+   */
   public static double getFlatnessSq(double x1, double y1, double cx,
                                      double cy, double x2, double y2)
   {
@@ -195,6 +268,26 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Calculates the flatness of a quadratic curve, directly specifying
+   * each coordinate value. The flatness is the distance of the
+   * control point to the line between start and end point.
+   *
+   * <p><img src="doc-files/QuadCurve2D-4.png" width="350" height="180"
+   * alt="A drawing that illustrates the flatness" />
+   *
+   * <p>In the above drawing, the straight line connecting start point
+   * P1 and end point P2 is depicted in gray.  The result will be the
+   * the distance between C and the gray line, i.e. the length of
+   * the red line.
+   *
+   * @param x1 the <i>x</i> coordinate of the start point P1.
+   * @param y1 the <i>y</i> coordinate of the start point P1.
+   * @param cx the <i>x</i> coordinate of the control point C.
+   * @param cy the <i>y</i> coordinate of the control point C.
+   * @param x2 the <i>x</i> coordinate of the end point P2.
+   * @param y2 the <i>y</i> coordinate of the end point P2.
+   */
   public static double getFlatness(double x1, double y1, double cx, double cy,
                                    double x2, double y2)
   {
@@ -202,6 +295,32 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Calculates the squared flatness of a quadratic curve, specifying
+   * the coordinate values in an array. The flatness is the distance
+   * of the control point to the line between start and end point.
+   *
+   * <p><img src="doc-files/QuadCurve2D-4.png" width="350" height="180"
+   * alt="A drawing that illustrates the flatness" />
+   *
+   * <p>In the above drawing, the straight line connecting start point
+   * P1 and end point P2 is depicted in gray.  The result will be the
+   * the square of the distance between C and the gray line, i.e.
+   * the squared length of the red line.
+   *
+   * @param coords an array containing the coordinate values.  The
+   * <i>x</i> coordinate of the start point P1 is located at
+   * <code>coords[offset]</code>, its <i>y</i> coordinate at
+   * <code>coords[offset + 1]</code>.  The <i>x</i> coordinate of the
+   * control point C is located at <code>coords[offset + 2]</code>,
+   * its <i>y</i> coordinate at <code>coords[offset + 3]</code>. The
+   * <i>x</i> coordinate of the end point P2 is located at
+   * <code>coords[offset + 4]</code>, its <i>y</i> coordinate at
+   * <code>coords[offset + 5]</code>.
+   *
+   * @param offset the offset of the first coordinate value in
+   * <code>coords</code>.
+   */
   public static double getFlatnessSq(double[] coords, int offset)
   {
     return Line2D.ptSegDistSq(coords[offset], coords[offset + 1],
@@ -210,6 +329,32 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Calculates the flatness of a quadratic curve, specifying the
+   * coordinate values in an array. The flatness is the distance of
+   * the control point to the line between start and end point.
+   *
+   * <p><img src="doc-files/QuadCurve2D-4.png" width="350" height="180"
+   * alt="A drawing that illustrates the flatness" />
+   *
+   * <p>In the above drawing, the straight line connecting start point
+   * P1 and end point P2 is depicted in gray.  The result will be the
+   * the the distance between C and the gray line, i.e.  the length of
+   * the red line.
+   *
+   * @param coords an array containing the coordinate values.  The
+   * <i>x</i> coordinate of the start point P1 is located at
+   * <code>coords[offset]</code>, its <i>y</i> coordinate at
+   * <code>coords[offset + 1]</code>.  The <i>x</i> coordinate of the
+   * control point C is located at <code>coords[offset + 2]</code>,
+   * its <i>y</i> coordinate at <code>coords[offset + 3]</code>. The
+   * <i>x</i> coordinate of the end point P2 is located at
+   * <code>coords[offset + 4]</code>, its <i>y</i> coordinate at
+   * <code>coords[offset + 5]</code>.
+   *
+   * @param offset the offset of the first coordinate value in
+   * <code>coords</code>.
+   */
   public static double getFlatness(double[] coords, int offset)
   {
     return Line2D.ptSegDist(coords[offset], coords[offset + 1],
@@ -218,6 +363,19 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Calculates the squared flatness of this curve. The flatness is
+   * the distance of the control point to the line between start and
+   * end point.
+   *
+   * <p><img src="doc-files/QuadCurve2D-4.png" width="350" height="180"
+   * alt="A drawing that illustrates the flatness" />
+   *
+   * <p>In the above drawing, the straight line connecting start point
+   * P1 and end point P2 is depicted in gray.  The result will be the
+   * the square of the distance between C and the gray line, i.e. the
+   * squared length of the red line.
+   */
   public double getFlatnessSq()
   {
     return Line2D.ptSegDistSq(getX1(), getY1(),
@@ -226,6 +384,19 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Calculates the flatness of this curve. The flatness is the
+   * distance of the control point to the line between start and end
+   * point.
+   *
+   * <p><img src="doc-files/QuadCurve2D-4.png" width="350" height="180"
+   * alt="A drawing that illustrates the flatness" />
+   *
+   * <p>In the above drawing, the straight line connecting start point
+   * P1 and end point P2 is depicted in gray.  The result will be the
+   * the distance between C and the gray line, i.e.  the length of the
+   * red line.
+   */
   public double getFlatness()
   {
     return Line2D.ptSegDist(getX1(), getY1(),
@@ -417,6 +588,16 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Determines whether a point lies inside the area that is bounded
+   * by the curve and the straight line connecting its end points.
+   *
+   * <p><img src="doc-files/QuadCurve2D-5.png" width="350" height="180"
+   * alt="A drawing of the area spanned by the curve" />
+   *
+   * <p>The above drawing illustrates in which area points are
+   * considered &#x201c;contained&#x201d; in a QuadCurve2D.
+   */
   public boolean contains(double x, double y)
   {
     // XXX Implement.
@@ -424,6 +605,16 @@ public abstract class QuadCurve2D
   }
 
 
+  /**
+   * Determines whether a point lies inside the area that is bounded
+   * by the curve and the straight line connecting its end points.
+   *
+   * <p><img src="doc-files/QuadCurve2D-5.png" width="350" height="180"
+   * alt="A drawing of the area spanned by the curve" />
+   *
+   * <p>The above drawing illustrates in which area points are
+   * considered &#x201c;contained&#x201d; in a QuadCurve2D.
+   */
   public boolean contains(Point2D p)
   {
     return contains(p.getX(), p.getY());
@@ -563,8 +754,7 @@ public abstract class QuadCurve2D
 
 
   /**
-   * Creates a new curve with the same contents as
-   * this one.
+   * Creates a new curve with the same contents as this one.
    *
    * @return the clone.
    */