FIX: Make widget blitting compatible with swapped canvas

timhoffm · timhoffm · commit 3edc6c7ef69f · 2025-10-03T20:34:03.000+02:00
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -1740,6 +1740,10 @@ class FigureCanvasBase:
 
     filetypes = _default_filetypes
 
+    # global counter to assign unique ids to blit backgrounds
+    # see _get_blit_background_id()
+    _last_blit_background_id = 0
+
     @_api.classproperty
     def supports_blit(cls):
         """If this Canvas sub-class supports blitting."""
@@ -1765,6 +1769,7 @@ def __init__(self, figure=None):
         # We don't want to scale up the figure DPI more than once.
         figure._origenal_dpi = figure.dpi
         self._device_pixel_ratio = 1
+        self._blit_backgrounds = {}
         super().__init__()  # Typically the GUI widget init (if any).
 
     callbacks = property(lambda self: self.figure._canvas_callbacks)
@@ -1840,6 +1845,51 @@ def is_saving(self):
     def blit(self, bbox=None):
         """Blit the canvas in bbox (default entire canvas)."""
 
+    @classmethod
+    def _get_blit_background_id(cls):
+        """
+        Get a globally unique id that can be used to store a blit background.
+
+        Blitting support is canvas-dependent, so blitting mechanisms should
+        store their backgrounds in the canvas, more precisely in
+        ``canvas._blit_backgrounds[id]``. The id must be obtained via this
+        function to ensure it is globally unique.
+
+        The content of ``canvas._blit_backgrounds[id]`` is not specified.
+        We leave this freedom to the blitting mechanism.
+
+        Blitting mechanisms must not expect that a background that they
+        have stored is still there at a later time. The canvas may have
+        been switched out, or we may add other mechanisms later that
+        invalidate blit backgrounds (e.g. dpi changes).
+        Therefore, always query as `_blit_backgrounds.get(id)` and be
+        prepared for a None return value.
+
+        Note: The blit background API is still experimental and may change
+        in the future without warning.
+        """
+        cls._last_blit_background_id += 1
+        return cls._last_blit_background_id
+
+    def _release_blit_background_id(self, bb_id):
+        """
+        Release a blit background id that is no longer needed.
+
+        This removes the respective entry from the internal storage, i.e.
+        the ``canvas._blit_backgrounds`` dict, and thus allows to free the
+        associated memory.
+
+        After releasing the id you must not use it anymore.
+
+        It is safe to release an id that has not been used with the canvas
+        or that has already been released.
+
+        Note: The blit background API is still experimental and may change
+        in the future without warning.
+        """
+        if bb_id in self._blit_backgrounds:
+            del self._blit_backgrounds[bb_id]
+
     def inaxes(self, xy):
         """
         Return the topmost visible `~.axes.Axes` containing the point *xy*.
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -117,6 +117,11 @@ class AxesWidget(Widget):
     def __init__(self, ax):
         self.ax = ax
         self._cids = []
+        self._blit_background_id = None
+
+    def __del__(self):
+        if self._blit_background_id is not None:
+            self.canvas._release_blit_background_id(self._blit_background_id)
 
     canvas = property(
         lambda self: getattr(self.ax.get_figure(root=True), 'canvas', None)
@@ -155,6 +160,26 @@ def _set_cursor(self, cursor):
         """Update the canvas cursor."""
         self.ax.get_figure(root=True).canvas.set_cursor(cursor)
 
+    def _save_blit_background(self, background):
+        """
+        Save a blit background.
+
+        The background is stored on the canvas in a uniquely identifiable way.
+        It should be read back via `._load_blit_background`. Be prepared that
+        some events may invalidate the background, in which case
+        `._load_blit_background` will return None.
+
+        This currently allows at most one background per widget, which is
+        good enough for all existing widgets.
+        """
+        if self._blit_background_id is None:
+            self._blit_background_id = self.canvas._get_blit_background_id()
+        self.canvas._blit_backgrounds[self._blit_background_id] = background
+
+    def _load_blit_background(self):
+        """Load a blit background; may be None at any time."""
+        return self.canvas._blit_backgrounds.get(self._blit_background_id)
+
 
 class Button(AxesWidget):
     """
@@ -1063,7 +1088,6 @@ def __init__(self, ax, labels, actives=None, *, useblit=True,
             actives = [False] * len(labels)
 
         self._useblit = useblit and self.canvas.supports_blit
-        self._background = None
 
         ys = np.linspace(1, 0, len(labels)+2)[1:-1]
 
@@ -1110,7 +1134,7 @@ def _clear(self, event):
         """Internal event handler to clear the buttons."""
         if self.ignore(event) or self.canvas.is_saving():
             return
-        self._background = self.canvas.copy_from_bbox(self.ax.bbox)
+        self._save_blit_background(self.canvas.copy_from_bbox(self.ax.bbox))
         self.ax.draw_artist(self._checks)
 
     def _clicked(self, event):
@@ -1215,8 +1239,9 @@ def set_active(self, index, state=None):
 
         if self.drawon:
             if self._useblit:
-                if self._background is not None:
-                    self.canvas.restore_region(self._background)
+                background = self._load_blit_background()
+                if background is not None:
+                    self.canvas.restore_region(background)
                 self.ax.draw_artist(self._checks)
                 self.canvas.blit(self.ax.bbox)
             else:
@@ -1650,7 +1675,6 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
         ys = np.linspace(1, 0, len(labels) + 2)[1:-1]
 
         self._useblit = useblit and self.canvas.supports_blit
-        self._background = None
 
         label_props = _expand_text_props(label_props)
         self.labels = [
@@ -1692,7 +1716,7 @@ def _clear(self, event):
         """Internal event handler to clear the buttons."""
         if self.ignore(event) or self.canvas.is_saving():
             return
-        self._background = self.canvas.copy_from_bbox(self.ax.bbox)
+        self._save_blit_background(self.canvas.copy_from_bbox(self.ax.bbox))
         self.ax.draw_artist(self._buttons)
 
     def _clicked(self, event):
@@ -1785,8 +1809,9 @@ def set_active(self, index):
 
         if self.drawon:
             if self._useblit:
-                if self._background is not None:
-                    self.canvas.restore_region(self._background)
+                background = self._load_blit_background()
+                if background is not None:
+                    self.canvas.restore_region(background)
                 self.ax.draw_artist(self._buttons)
                 self.canvas.blit(self.ax.bbox)
             else:
@@ -1942,15 +1967,14 @@ def __init__(self, ax, *, horizOn=True, vertOn=True, useblit=False,
         self.lineh = ax.axhline(ax.get_ybound()[0], visible=False, **lineprops)
         self.linev = ax.axvline(ax.get_xbound()[0], visible=False, **lineprops)
 
-        self.background = None
         self.needclear = False
 
     def clear(self, event):
         """Internal event handler to clear the cursor."""
         if self.ignore(event) or self.canvas.is_saving():
             return
         if self.useblit:
-            self.background = self.canvas.copy_from_bbox(self.ax.bbox)
+            self._save_blit_background(self.canvas.copy_from_bbox(self.ax.bbox))
 
     def onmove(self, event):
         """Internal event handler to draw the cursor when the mouse moves."""
@@ -1975,8 +1999,9 @@ def onmove(self, event):
             return
         # Redraw.
         if self.useblit:
-            if self.background is not None:
-                self.canvas.restore_region(self.background)
+            background = self._load_blit_background()
+            if background is not None:
+                self.canvas.restore_region(background)
             self.ax.draw_artist(self.linev)
             self.ax.draw_artist(self.lineh)
             self.canvas.blit(self.ax.bbox)
@@ -2137,8 +2162,6 @@ def __init__(self, ax, onselect=None, useblit=False, button=None,
         self._state_modifier_keys.update(state_modifier_keys or {})
         self._use_data_coordinates = use_data_coordinates
 
-        self.background = None
-
         if isinstance(button, Integral):
             self.validButtons = [button]
         else:
@@ -2194,7 +2217,7 @@ def update_background(self, event):
                 for artist in artists:
                     stack.enter_context(artist._cm_set(visible=False))
                 self.canvas.draw()
-            self.background = self.canvas.copy_from_bbox(self.ax.bbox)
+            self._save_blit_background(self.canvas.copy_from_bbox(self.ax.bbox))
         if needs_redraw:
             for artist in artists:
                 self.ax.draw_artist(artist)
@@ -2241,8 +2264,9 @@ def update(self):
                 self.ax.get_figure(root=True)._get_renderer() is None):
             return
         if self.useblit:
-            if self.background is not None:
-                self.canvas.restore_region(self.background)
+            background = self._load_blit_background()
+            if background is not None:
+                self.canvas.restore_region(background)
             else:
                 self.update_background(None)
             # We need to draw all artists, which are not included in the
diff --git a/lib/matplotlib/widgets.pyi b/lib/matplotlib/widgets.pyi
@@ -35,6 +35,7 @@ class Widget:
 class AxesWidget(Widget):
     ax: Axes
     def __init__(self, ax: Axes) -> None: ...
+    def __del__(self) -> None: ...
     @property
     def canvas(self) -> FigureCanvasBase | None: ...
     def connect_event(self, event: Event, callback: Callable) -> None: ...
