Doc: Explain how Qt computes arcs and ellipses

The angle arguments of QPainterPath::arcTo(), QPainterPath::arcMoveTo()
and the QPainter arc functions are eccentric angles: they parameterize
the ellipse fitted into the bounding rectangle rather than measuring a
direction from its center. In general the two coincide only for a square
bounding rectangle. On a 400 by 100 rectangle, an angle of 45 degrees
yields a point roughly 14 degrees above the horizontal as seen from the
center.

Separately, arcs and ellipses are approximated with cubic Bezier curves
scaled by QT_PATH_KAPPA rather than evaluated trigonometrically, so the
resulting points sit slightly off where qSin() and qCos() would place
them. For a circle the offset stays below 0.1% of the radius.

Neither property was documented, which repeatedly surprises users who
build paths from trigonometry and then compare the result against Qt's.
Document both in a new "Arcs and Ellipses" section of the QPainterPath
overview, reference it from the affected functions, and note the
approximation next to the existing stroker limitation in the QPainter
overview.

The eccentric angle behavior was judged intentional in QTBUG-2644 in
2009, where adding a doc hint was agreed on but never done.

Fixes: QTBUG-149880
Pick-to: 6.12 6.11 6.8
Change-Id: Ib1dcb6c6fe27533ef582acc38b15195a87f71269
Reviewed-by: Eirik Aavitsland <eirik.aavitsland@qt.io>

Author: kkoehne

src/gui/painting/qpainter.cpp

@@ -1307,6 +1307,14 @@ void QPainterPrivate::updateState(QPainterState *newState)
     Another workaround is to convert the paths to polygons first and then draw the
     polygons instead.
 
+    Qt likewise approximates arcs and ellipses with cubic Bezier curves instead
+    of evaluating them trigonometrically, so points on an arc are slightly off
+    their true positions. Related to this, the angles that \l{drawArc()},
+    \l{drawPie()}, and \l{drawChord()} take are eccentric angles: they measure
+    the direction from the center of the bounding rectangle only when that
+    rectangle is square. See \l{QPainterPath#Arcs and Ellipses}{Arcs and
+    Ellipses} for details on both.
+
     \section1 Performance
 
     QPainter is a rich framework that allows developers to do a great
@@ -4170,7 +4178,10 @@ void QPainter::drawEllipse(const QRect &r)
     a degree, i.e. a full circle equals 5760 (16 * 360). Positive
     values for the angles mean counter-clockwise while negative values
     mean the clockwise direction. Zero degrees is at the 3 o'clock
-    position.
+    position. If \a rectangle is not square, the angles are eccentric
+    angles and do not measure the direction from the center of the
+    rectangle, as described in \l{QPainterPath#Arcs and Ellipses}{Arcs
+    and Ellipses}.
 
     \table 100%
     \row
@@ -4235,7 +4246,10 @@ void QPainter::drawArc(const QRectF &r, int a, int alen)
     degree, i.e. a full circle equals 5760 (16 * 360). Positive values
     for the angles mean counter-clockwise while negative values mean
     the clockwise direction. Zero degrees is at the 3 o'clock
-    position.
+    position. If \a rectangle is not square, the angles are eccentric
+    angles and do not measure the direction from the center of the
+    rectangle, as described in \l{QPainterPath#Arcs and Ellipses}{Arcs
+    and Ellipses}.
 
     \table 100%
     \row
@@ -4306,7 +4320,10 @@ void QPainter::drawPie(const QRectF &r, int a, int alen)
     degree, i.e. a full circle equals 5760 (16 * 360). Positive values
     for the angles mean counter-clockwise while negative values mean
     the clockwise direction. Zero degrees is at the 3 o'clock
-    position.
+    position. If \a rectangle is not square, the angles are eccentric
+    angles and do not measure the direction from the center of the
+    rectangle, as described in \l{QPainterPath#Arcs and Ellipses}{Arcs
+    and Ellipses}.
 
     \table 100%
     \row

src/gui/painting/qpainterpath.cpp

@@ -225,6 +225,35 @@ static void qt_debug_path(const QPainterPath &path)
     using the fillRule() function, and altered using the setFillRule()
     function.
 
+    \section1 Arcs and Ellipses
+
+    The angle arguments of \l{arcTo()}, \l{arcMoveTo()},
+    \l{QPainter::drawArc()}, \l{QPainter::drawPie()}, and
+    \l{QPainter::drawChord()} are \e{eccentric} angles. An eccentric
+    angle parameterizes the ellipse that fits into the bounding
+    rectangle; it does not measure the direction from the center of that
+    rectangle to the resulting point. In general the two coincide only
+    when the bounding rectangle is square. On a 400 by 100 rectangle, for
+    example, an angle of 45 degrees yields a point that lies roughly 14
+    degrees above the horizontal as seen from the center.
+
+    To place a point at a given direction from the center instead,
+    compute that point yourself and pass it to \l{moveTo()} or
+    \l{lineTo()}. Alternatively, keep using these functions and convert
+    the direction: on a bounding rectangle of the given \c width and
+    \c height, the direction \c theta, in radians, corresponds to the
+    eccentric angle
+    \c{qRadiansToDegrees(qAtan2(width * qSin(theta), height * qCos(theta)))}.
+
+    Because a painter path stores only lines and Bezier segments, Qt
+    approximates arcs and ellipses with cubic Bezier curves instead of
+    evaluating them trigonometrically. For a circle, the approximation
+    places points less than 0.1% of the radius away from their true
+    positions. Code that compares a point from \l{arcMoveTo()} against
+    one computed with \l{<QtMath>::}{qSin()} and \l{<QtMath>::}{qCos()}
+    must therefore allow for a tolerance instead of testing for
+    equality.
+
     \section1 QPainterPath Information
 
     The QPainterPath class provides a collection of functions that
@@ -895,7 +924,10 @@ void QPainterPath::quadTo(const QPointF &c, const QPointF &e)
     counter-clockwise.
 
     Angles are specified in degrees. Clockwise arcs can be specified
-    using negative angles.
+    using negative angles. If \a rectangle is not square, the angles are
+    eccentric angles and do not measure the direction from the center of
+    the rectangle, as described in \l{QPainterPath#Arcs and
+    Ellipses}{Arcs and Ellipses}.
 
     Note that this function connects the starting point of the arc to
     the current position if they are not already connected. After the
@@ -967,9 +999,13 @@ void QPainterPath::arcTo(const QRectF &rect, qreal startAngle, qreal sweepLength
     rectangle at \a angle.
 
     Angles are specified in degrees. Clockwise arcs can be specified
-    using negative angles.
+    using negative angles. If \a rectangle is not square, \a angle is an
+    eccentric angle and does not measure the direction from the center of
+    the rectangle, as described in \l{QPainterPath#Arcs and
+    Ellipses}{Arcs and Ellipses}.
 
-    \sa moveTo(), arcTo()
+    \sa moveTo(), arcTo(), {QPainterPath#Arcs and Ellipses}{Arcs and
+    Ellipses}
 */
 
 void QPainterPath::arcMoveTo(const QRectF &rect, qreal angle)
@@ -1102,7 +1138,10 @@ void QPainterPath::addPolygon(const QPolygonF &polygon)
     and adds it to the painter path as a closed subpath.
 
     The ellipse is composed of a clockwise curve, starting and
-    finishing at zero degrees (the 3 o'clock position).
+    finishing at zero degrees (the 3 o'clock position). The curve is a
+    cubic Bezier approximation of the ellipse, not an exact
+    representation of it, as described in \l{QPainterPath#Arcs and
+    Ellipses}{Arcs and Ellipses}.
 
     \table 100%
     \row