Clarify sweep gradient angle rotation and unit (#130)

See linebender/vello#1205 and [#vello > Sweep
Gradient Convention @
💬](https://xi.zulipchat.com/#narrow/channel/197075-vello/topic/Sweep.20Gradient.20Convention/near/538611201).

This lifts some wording from
[`kurbo::Affine::rotate`](https://docs.rs/kurbo/0.12.0/kurbo/struct.Affine.html#method.rotate).

Author: tomcur

CHANGELOG.md

@@ -26,6 +26,10 @@ This release has an [MSRV] of 1.82.
 
 - Breaking change: `Image` has been renamed to `ImageBrush`, which now consists of an `ImageData` and an `ImageSampler`. ([#117][], [#123][] by [@nicoburns][], [@DJMcNab][])
 - Breaking change: `Font` has been renamed to `FontData` to match `ImageData`. ([#126][] by [@nicoburns][])
+- Breaking change: the angle directions of `SweepGradientPosition` are now described to be clockwise in a Y-down coordinate system, as is common in computer graphics.
+  This is reversed from the most likely reading of the previous wording.
+  More generally, the angle directions are now described numerically to be unambiguous across coordinate systems.
+  The angle unit is now specified to be in radians. ([#130][] by [@tomcur][])
 - Update to `color` 0.3.2. ([#115][] by [@sagudev][])
 
 ### Raw Resource Changes
@@ -154,13 +158,16 @@ This release has an [MSRV] of 1.70.
 [#120]: https://github.com/linebender/peniko/pull/120
 [#121]: https://github.com/linebender/peniko/pull/121
 [#123]: https://github.com/linebender/peniko/pull/123
+[#126]: https://github.com/linebender/peniko/pull/126
+[#130]: https://github.com/linebender/peniko/pull/130
 
 [@dfrg]: https://github.com/dfrg
 [@DJMcNab]: https://github.com/DJMcNab
 [@liferooter]: https://github.com/liferooter
 [@nicoburns]: https://github.com/nicoburns
 [@ratmice]: https://github.com/ratmice
 [@sagudev]: https://github.com/sagudev
+[@tomcur]: https://github.com/tomcur
 [@waywardmonkeys]: https://github.com/waywardmonkeys
 
 [Unreleased]: https://github.com/linebender/peniko/compare/v0.4.0...HEAD

src/gradient.rs

@@ -198,14 +198,22 @@ impl RadialGradientPosition {
 }
 
 /// Parameters that define the position of a sweep gradient.
+///
+/// Conventionally, a positive increase in one of the sweep angles is a clockwise rotation in a
+/// Y-down, X-right coordinate system (as is common for graphics). More generally, the convention
+/// for rotations is that a positive angle rotates a positive X direction into positive Y.
 #[derive(Copy, Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct SweepGradientPosition {
     /// Center point.
     center: Point,
-    /// Start angle of the sweep, counter-clockwise of the x-axis.
+    /// Start angle of the sweep in radians, measuring from the positive X-axis.
+    ///
+    /// Clockwise in a Y-down coordinate system.
     start_angle: f32,
-    /// End angle of the sweep, counter-clockwise of the x-axis.
+    /// End angle of the sweep in radians, measuring from the positive X-axis.
+    ///
+    /// Clockwise in a Y-down coordinate system.
     end_angle: f32,
 }
 impl SweepGradientPosition {