Deprecate passing floats to RendererAgg.draw_text_image

These were silently truncated to int anyway, so we should make the types
explicit.

Author: QuLogic

doc/api/next_api_changes/deprecations/28967-ES.rst

@@ -0,0 +1,5 @@
+Passing floating-point values to ``RendererAgg.draw_text_image``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Any floating-point values passed to the *x* and *y* parameters were truncated to integers
+silently. This behaviour is now deprecated, and only `int` values should be used.

src/_backend_agg_wrapper.cpp

@@ -58,11 +58,37 @@ PyRendererAgg_draw_path(RendererAgg *self,
 static void
 PyRendererAgg_draw_text_image(RendererAgg *self,
                               py::array_t<agg::int8u, py::array::c_style | py::array::forcecast> image_obj,
-                              double x,
-                              double y,
+                              std::variant<double, int> vx,
+                              std::variant<double, int> vy,
                               double angle,
                               GCAgg &gc)
 {
+    int x, y;
+
+    if (auto value = std::get_if<double>(&vx)) {
+        auto api = py::module_::import("matplotlib._api");
+        auto warn = api.attr("warn_deprecated");
+        warn("since"_a="3.10", "name"_a="x", "obj_type"_a="parameter as float",
+             "alternative"_a="int(x)");
+        x = static_cast<int>(*value);
+    } else if (auto value = std::get_if<int>(&vx)) {
+        x = *value;
+    } else {
+        throw std::runtime_error("Should not happen");
+    }
+
+    if (auto value = std::get_if<double>(&vy)) {
+        auto api = py::module_::import("matplotlib._api");
+        auto warn = api.attr("warn_deprecated");
+        warn("since"_a="3.10", "name"_a="y", "obj_type"_a="parameter as float",
+             "alternative"_a="int(y)");
+        y = static_cast<int>(*value);
+    } else if (auto value = std::get_if<int>(&vy)) {
+        y = *value;
+    } else {
+        throw std::runtime_error("Should not happen");
+    }
+
     // TODO: This really shouldn't be mutable, but Agg's renderer buffers aren't const.
     auto image = image_obj.mutable_unchecked<2>();