[librsvg: 16/29] Deprecate rsvg_set_default_dpi() and rsvg_set_default_dpi_x_y().

[Federico Mena Quintero <federico src gnome org>]

commit 33ef0e0123a51e66da29017cc51e715b9ab5f779
Author: Federico Mena Quintero <federico gnome org>
Date:   Tue Feb 6 11:13:51 2018 -0600

    Deprecate rsvg_set_default_dpi() and rsvg_set_default_dpi_x_y().
    
    These functions are unsound.  They would only work if called before
    the registration of RsvgHandleClass (e.g. before the first
    instantiation of an RsvgHandle), as the global value they set is what
    is used for g_object_class_install_property(..., "dpi-x") and "dpi-y".
    
    We maintain their behavior, but instead recommend that callers use
    rsvg_handle_set_dpi() or rsvg_handle_set_dpi_x_y().

 rsvg-base.c   | 20 ++++++++++++++------
 rsvg-handle.c | 16 +++++-----------
 rsvg.h        |  3 +++
 3 files changed, 22 insertions(+), 17 deletions(-)
---
diff --git a/rsvg-base.c b/rsvg-base.c
index 2dd383e..0953528 100644
--- a/rsvg-base.c
+++ b/rsvg-base.c
@@ -1279,11 +1279,15 @@ rsvg_drawing_ctx_free (RsvgDrawingCtx * handle)
  * rsvg_set_default_dpi:
  * @dpi: Dots Per Inch (aka Pixels Per Inch)
  *
- * Sets the DPI for the all future outgoing pixbufs. Common values are
- * 75, 90, and 300 DPI. Passing a number <= 0 to @dpi will
- * reset the DPI to whatever the default value happens to be.
+ * Do not use this function.  Create an #RsvgHandle and call
+ * rsvg_handle_set_dpi() on it instead.
  *
  * Since: 2.8
+ *
+ * Deprecated: 2.42.3: This function used to set a global default DPI.  However,
+ * it only worked if it was called before any #RsvgHandle objects had been
+ * created; it would not work after that.  To avoid global mutable state, please
+ * use rsvg_handle_set_dpi() instead.
  */
 void
 rsvg_set_default_dpi (double dpi)
@@ -1296,11 +1300,15 @@ rsvg_set_default_dpi (double dpi)
  * @dpi_x: Dots Per Inch (aka Pixels Per Inch)
  * @dpi_y: Dots Per Inch (aka Pixels Per Inch)
  *
- * Sets the DPI for the all future outgoing pixbufs. Common values are
- * 75, 90, and 300 DPI. Passing a number <= 0 to @dpi will
- * reset the DPI to whatever the default value happens to be.
+ * Do not use this function.  Create an #RsvgHandle and call
+ * rsvg_handle_set_dpi_x_y() on it instead.
  *
  * Since: 2.8
+ *
+ * Deprecated: 2.42.3: This function used to set a global default DPI.  However,
+ * it only worked if it was called before any #RsvgHandle objects had been
+ * created; it would not work after that.  To avoid global mutable state, please
+ * use rsvg_handle_set_dpi() instead.
  */
 void
 rsvg_set_default_dpi_x_y (double dpi_x, double dpi_y)
diff --git a/rsvg-handle.c b/rsvg-handle.c
index a728311..b407250 100644
--- a/rsvg-handle.c
+++ b/rsvg-handle.c
@@ -87,17 +87,11 @@
  * # Resolution of the rendered image (dots per inch, or DPI)
  *
  * SVG images can contain dimensions like "<literal>5 cm</literal>" or
- * "<literal>2 pt</literal>" that must be converted from physical units
- * into device units.  To do this, librsvg needs to know the actual dots per
- * inch (DPI) of your target device.
- *
- * The recommended way to set the DPI is to use rsvg_handle_set_dpi() or
- * rsvg_handle_set_dpi_x_y() on an RsvgHandle before rendering it.
- *
- * Alternatively, you can use rsvg_set_default_dpi() or
- * rsvg_set_default_dpi_x_y() <emphasis>before</emphasis> creating any
- * RsvgHandle objects.  These functions will make RsvgHandle objects created
- * afterwards to have the default DPI value you specified.
+ * "<literal>2 pt</literal>" that must be converted from physical units into
+ * device units.  To do this, librsvg needs to know the actual dots per inch
+ * (DPI) of your target device.  You can call rsvg_handle_set_dpi() or
+ * rsvg_handle_set_dpi_x_y() on an RsvgHandle to set the DPI before rendering
+ * it.
  *
  * # Rendering
  *
diff --git a/rsvg.h b/rsvg.h
index 9461085..2e73dbf 100644
--- a/rsvg.h
+++ b/rsvg.h
@@ -128,7 +128,10 @@ struct _RsvgPositionData {
 
 void rsvg_cleanup (void);
 
+RSVG_DEPRECATED
 void rsvg_set_default_dpi      (double dpi);
+
+RSVG_DEPRECATED
 void rsvg_set_default_dpi_x_y  (double dpi_x, double dpi_y);
 
 void rsvg_handle_set_dpi       (RsvgHandle * handle, double dpi);