From cdd784277d1ebca5b69fd4533e8834f38e1256e8 Mon Sep 17 00:00:00 2001 From: Bruce Mitchener Date: Sat, 3 Aug 2024 07:34:45 +0700 Subject: [PATCH] Deprecate `BezPath::flatten`, prefer `flatten`. The free-standing function is more useful as it works on a wider range of types. The `BezPath` method has the documentation though and is just a wrapper around the free-standing function. Most people will want to use the free-standing function, so we can encourage that and make that the place where the docs live. --- CHANGELOG.md | 1 + src/bezpath.rs | 136 ++++++++++++++++++++++++------------------------- 2 files changed, 67 insertions(+), 70 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b344df0a..fb0066be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ This release has an [MSRV][] of 1.65. ### Changed - Move `Self: Sized` bound from `Shape` to methods. ([#340] by [@waywardmonkeys]) +- Deprecate `BezPath::flatten`, prefer `flatten`. ([#xxx] by [@waywardmonkeys]) ### Fixed diff --git a/src/bezpath.rs b/src/bezpath.rs index baa943d8..c5139bf9 100644 --- a/src/bezpath.rs +++ b/src/bezpath.rs @@ -95,7 +95,7 @@ use crate::common::FloatFuncs; /// [A Primer on Bézier Curves]: https://pomax.github.io/bezierinfo/ /// [`iter`]: BezPath::iter /// [`segments`]: BezPath::segments -/// [`flatten`]: BezPath::flatten +/// [`flatten`]: flatten /// [`intersect_line`]: PathSeg::intersect_line /// [`segments` free function]: segments /// [`FromIterator`]: std::iter::FromIterator @@ -290,72 +290,8 @@ impl BezPath { /// Flatten the path, invoking the callback repeatedly. /// - /// Flattening is the action of approximating a curve with a succession of line segments. - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// → - /// - /// - /// - /// The tolerance value controls the maximum distance between the curved input - /// segments and their polyline approximations. (In technical terms, this is the - /// Hausdorff distance). The algorithm attempts to bound this distance between - /// by `tolerance` but this is not absolutely guaranteed. The appropriate value - /// depends on the use, but for antialiased rendering, a value of 0.25 has been - /// determined to give good results. The number of segments tends to scale as the - /// inverse square root of tolerance. - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// - /// The callback will be called in order with each element of the generated - /// path. Because the result is made of polylines, these will be straight-line - /// path elements only, no curves. - /// - /// This algorithm is based on the blog post [Flattening quadratic Béziers] - /// but with some refinements. For one, there is a more careful approximation - /// at cusps. For two, the algorithm is extended to work with cubic Béziers - /// as well, by first subdividing into quadratics and then computing the - /// subdivision of each quadratic. However, as a clever trick, these quadratics - /// are subdivided fractionally, and their endpoints are not included. - /// - /// TODO: write a paper explaining this in more detail. - /// - /// Note: the [`flatten`] function provides the same - /// functionality but works with slices and other [`PathEl`] iterators. - /// - /// [Flattening quadratic Béziers]: https://raphlinus.github.io/graphics/curves/2019/12/23/flatten-quadbez.html + /// See [`flatten`] for more discussion. + #[deprecated(since = "0.11.1", note = "use the free function flatten instead")] pub fn flatten(&self, tolerance: f64, callback: impl FnMut(PathEl)) { flatten(self, tolerance, callback); } @@ -551,9 +487,69 @@ const TO_QUAD_TOL: f64 = 0.1; /// Flatten the path, invoking the callback repeatedly. /// -/// See [`BezPath::flatten`] for more discussion. -/// This signature is a bit more general, allowing flattening of `&[PathEl]` slices -/// and other iterators yielding `PathEl`. +/// Flattening is the action of approximating a curve with a succession of line segments. +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// → +/// +/// +/// +/// The tolerance value controls the maximum distance between the curved input +/// segments and their polyline approximations. (In technical terms, this is the +/// Hausdorff distance). The algorithm attempts to bound this distance between +/// by `tolerance` but this is not absolutely guaranteed. The appropriate value +/// depends on the use, but for antialiased rendering, a value of 0.25 has been +/// determined to give good results. The number of segments tends to scale as the +/// inverse square root of tolerance. +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// +/// The callback will be called in order with each element of the generated +/// path. Because the result is made of polylines, these will be straight-line +/// path elements only, no curves. +/// +/// This algorithm is based on the blog post [Flattening quadratic Béziers] +/// but with some refinements. For one, there is a more careful approximation +/// at cusps. For two, the algorithm is extended to work with cubic Béziers +/// as well, by first subdividing into quadratics and then computing the +/// subdivision of each quadratic. However, as a clever trick, these quadratics +/// are subdivided fractionally, and their endpoints are not included. +/// +/// TODO: write a paper explaining this in more detail. +/// +/// [Flattening quadratic Béziers]: https://raphlinus.github.io/graphics/curves/2019/12/23/flatten-quadbez.html pub fn flatten( path: impl IntoIterator, tolerance: f64,