Document performance advantage of cairo_path_extents

The cairo_path_extents function can perform better than either
cairo_stroke_extents or cairo_fill_extents, so provide that
pointer from the documentation of the other two functions.

1 files changed, 12 insertions, 2 deletions

diff --git a/src/cairo.c b/src/cairo.c
index a0fbb4930..8f82cb6a9 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -2299,6 +2299,11 @@ cairo_in_fill (cairo_t *cr, double x, double y)
  * cairo_path_extents() which can be used to compute the non-empty
  * bounds as the line width approaches zero.
  *
+ * Note that cairo_stroke_extents must necessarily do more work to
+ * compute the precise inked areas in light of the stroke parameters,
+ * so cairo_path_extents() may be more desirable for sake of
+ * performance if non-inked path extents are desired.
+ *
  * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
  * cairo_set_line_cap(), cairo_set_dash(), and
  * cairo_stroke_preserve().
@@ -2344,8 +2349,13 @@ cairo_stroke_extents (cairo_t *cr,
  * dimensions and clipping are not taken into account.
  *
  * Contrast with cairo_path_extents(), which is similar, but returns
- * non-zero extents for some paths no inked area, (such as a simple
- * line segment).
+ * non-zero extents for some paths with no inked area, (such as a
+ * simple line segment).
+ *
+ * Note that cairo_fill_extents must necessarily do more work to
+ * compute the precise inked areas in light of the fill rule, so
+ * cairo_path_extents() may be more desirable for sake of performance
+ * if the non-inked path extents are desired.
  *
  * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
  **/