[librsvg: 4/6] Docs - Migrating to the geometry APIs

[Marge Bot <marge-bot src gnome org>]

commit 8ae5f9c31c77e8bdd6358fd83a9369b698ac1b86
Author: Federico Mena Quintero <federico gnome org>
Date:   Wed Sep 15 18:50:57 2021 -0500

    Docs - Migrating to the geometry APIs
    
    Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/588>

 doc/migrating.xml | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
---
diff --git a/doc/migrating.xml b/doc/migrating.xml
index 6991181d..dbab592f 100644
--- a/doc/migrating.xml
+++ b/doc/migrating.xml
@@ -182,6 +182,13 @@ gboolean rsvg_handle_render_cairo_sub (RsvgHandle *handle,
       </para>
 
       <programlisting lang="c">
+typedef struct {
+    double x;
+    double y;
+    double width;
+    double height;
+} RsvgRectangle;
+
 gboolean rsvg_handle_render_document (RsvgHandle           *handle,
                                       cairo_t              *cr,
                                       const RsvgRectangle  *viewport,
@@ -374,4 +381,74 @@ void rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle,
       </para>
     </section>
   </section>
+
+  <section id="migrating-to-geometry-apis">
+    <title>Migrating to the geometry APIs</title>
+
+    <para>
+      Until librsvg 2.44, the available APIs to query the geometry of a layer or element were these:
+    </para>
+
+    <programlisting lang="c">
+struct _RsvgPositionData {
+    int x;
+    int y;
+};
+
+gboolean rsvg_handle_get_position_sub (RsvgHandle       *handle,
+                                       RsvgPositionData *position_data,
+                                       const char       *id);
+
+struct _RsvgDimensionData {
+    int width;
+    int height;
+    gdouble em;
+    gdouble ex;
+};
+
+gboolean rsvg_handle_get_dimensions_sub (RsvgHandle        *handle,
+                                         RsvgDimensionData *dimension_data,
+                                         const char        *id);
+    </programlisting>
+
+    <para>
+      These functions are inconvenient — separate calls to get the
+      position and dimensions —, and also inexact, since they only
+      return integer values, while SVG uses floating-point units.
+    </para>
+
+    <para>
+      Since librsvg 2.46, you can use these functions instead:
+    </para>
+
+    <programlisting lang="c">
+typedef struct {
+    double x;
+    double y;
+    double width;
+    double height;
+} RsvgRectangle;
+
+gboolean rsvg_handle_get_geometry_for_layer (RsvgHandle           *handle,
+                                             const char           *id,
+                                             const RsvgRectangle  *viewport,
+                                             RsvgRectangle        *out_ink_rect,
+                                             RsvgRectangle        *out_logical_rect,
+                                             GError              **error);
+
+gboolean rsvg_handle_get_geometry_for_element (RsvgHandle     *handle,
+                                               const char     *id,
+                                               RsvgRectangle  *out_ink_rect,
+                                               RsvgRectangle  *out_logical_rect,
+                                               GError        **error);
+    </programlisting>
+
+    <para>
+      These functions return exact floating-point values.  They also
+      give you the <firstterm>ink rectangle</firstterm>, or area
+      covered by paint, as well as the <firstterm>logical
+      rectangle</firstterm>, which is the extents of unstroked paths
+      (i.e. just the outlines).
+    </para>
+  </section>
 </chapter>