Merge pull request matplotlib#30591 from timhoffm/safe-blit

FIX: Make widget blitting compatible with swapped canvas

Author: tacaswell

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._original_dpi = getattr(figure, '_original_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*.

lib/matplotlib/widgets.py

@@ -118,6 +118,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)
@@ -146,6 +151,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)
+
 
 def _call_with_reparented_event(func):
     """
@@ -223,7 +248,7 @@ def __init__(self, ax, label, image=None,
                              horizontalalignment='center',
                              transform=ax.transAxes)
 
-        self._useblit = useblit and self.canvas.supports_blit
+        self._useblit = useblit
 
         self._observers = cbook.CallbackRegistry(signals=["clicked"])
 
@@ -260,7 +285,7 @@ def _motion(self, event):
         if not colors.same_color(c, self.ax.get_facecolor()):
             self.ax.set_facecolor(c)
             if self.drawon:
-                if self._useblit:
+                if self._useblit and self.canvas.supports_blit:
                     self.ax.draw_artist(self.ax)
                     self.canvas.blit(self.ax.bbox)
                 else:
@@ -1083,8 +1108,7 @@ def __init__(self, ax, labels, actives=None, *, useblit=True,
         if actives is None:
             actives = [False] * len(labels)
 
-        self._useblit = useblit and self.canvas.supports_blit
-        self._background = None
+        self._useblit = useblit and self.canvas.supports_blit  # TODO: make dynamic
 
         ys = np.linspace(1, 0, len(labels)+2)[1:-1]
 
@@ -1131,7 +1155,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)
 
     @_call_with_reparented_event
@@ -1237,8 +1261,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:
@@ -1676,8 +1701,7 @@ 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
+        self._useblit = useblit and self.canvas.supports_blit  # TODO: make dynamic
 
         label_props = _expand_text_props(label_props)
         self.labels = [
@@ -1719,7 +1743,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)
 
     @_call_with_reparented_event
@@ -1813,8 +1837,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:
@@ -1963,22 +1988,21 @@ def __init__(self, ax, *, horizOn=True, vertOn=True, useblit=False,
         self.visible = True
         self.horizOn = horizOn
         self.vertOn = vertOn
-        self.useblit = useblit and self.canvas.supports_blit
+        self.useblit = useblit and self.canvas.supports_blit  # TODO: make dynamic
 
         if self.useblit:
             lineprops['animated'] = True
         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))
 
     @_call_with_reparented_event
     def onmove(self, event):
@@ -2003,8 +2027,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)
@@ -2093,6 +2118,7 @@ def __init__(self, *args, useblit=True, horizOn=False, vertOn=True,
         self.useblit = (
             useblit
             and all(canvas.supports_blit for canvas in self._canvas_infos))
+            # TODO: make dynamic
 
         if self.useblit:
             lineprops['animated'] = True
@@ -2177,7 +2203,7 @@ def __init__(self, ax, onselect=None, useblit=False, button=None,
             self.onselect = lambda *args: None
         else:
             self.onselect = onselect
-        self.useblit = useblit and self.canvas.supports_blit
+        self._useblit = useblit
         self.connect_default_events()
 
         self._state_modifier_keys = dict(move=' ', clear='escape',
@@ -2186,8 +2212,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:
@@ -2203,6 +2227,11 @@ def __init__(self, ax, onselect=None, useblit=False, button=None,
         self._prev_event = None
         self._state = set()
 
+    @property
+    def useblit(self):
+        """Return whether blitting is used (requested and supported by canvas)."""
+        return self._useblit and self.canvas.supports_blit
+
     def set_active(self, active):
         super().set_active(active)
         if active:
@@ -2243,7 +2272,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)
@@ -2290,8 +2319,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
@@ -2629,7 +2659,14 @@ def __init__(self, ax, onselect, direction, *, minspan=0, useblit=False,
         if props is None:
             props = dict(facecolor='red', alpha=0.5)
 
-        props['animated'] = self.useblit
+        # Note: We set this based on the user setting during ínitialization,
+        #       not on the actual capability of blitting. But the value is
+        #       irrelevant if the backend does not support blitting, so that
+        #       we don't have to dynamically update this on the backend.
+        #       This relies on the current behavior that the request for
+        #       useblit is fixed during initialization and cannot be changed
+        #       afterwards.
+        props['animated'] = self._useblit
 
         self.direction = direction
         self._extents_on_press = None
@@ -2695,7 +2732,7 @@ def _setup_edge_handles(self, props):
         self._edge_handles = ToolLineHandles(self.ax, positions,
                                              direction=self.direction,
                                              line_props=props,
-                                             useblit=self.useblit)
+                                             useblit=self._useblit)
 
     @property
     def _handles_artists(self):
@@ -3269,7 +3306,7 @@ def __init__(self, ax, onselect=None, *, minspanx=0,
         if props is None:
             props = dict(facecolor='red', edgecolor='black',
                          alpha=0.2, fill=True)
-        props = {**props, 'animated': self.useblit}
+        props = {**props, 'animated': self._useblit}
         self._visible = props.pop('visible', self._visible)
         to_draw = self._init_shape(**props)
         self.ax.add_patch(to_draw)
@@ -3294,18 +3331,18 @@ def __init__(self, ax, onselect=None, *, minspanx=0,
             xc, yc = self.corners
             self._corner_handles = ToolHandles(self.ax, xc, yc,
                                                marker_props=self._handle_props,
-                                               useblit=self.useblit)
+                                               useblit=self._useblit)
 
             self._edge_order = ['W', 'S', 'E', 'N']
             xe, ye = self.edge_centers
             self._edge_handles = ToolHandles(self.ax, xe, ye, marker='s',
                                              marker_props=self._handle_props,
-                                             useblit=self.useblit)
+                                             useblit=self._useblit)
 
             xc, yc = self.center
             self._center_handle = ToolHandles(self.ax, [xc], [yc], marker='s',
                                               marker_props=self._handle_props,
-                                              useblit=self.useblit)
+                                              useblit=self._useblit)
 
             self._active_handle = None
 
@@ -3812,7 +3849,7 @@ def __init__(self, ax, onselect=None, *, useblit=True, props=None, button=None):
             **(props if props is not None else {}),
             # Note that self.useblit may be != useblit, if the canvas doesn't
             # support blitting.
-            'animated': self.useblit, 'visible': False,
+            'animated': self._useblit, 'visible': False,
         }
         line = Line2D([], [], **props)
         self.ax.add_line(line)
@@ -3937,7 +3974,7 @@ def __init__(self, ax, onselect=None, *, useblit=False,
 
         if props is None:
             props = dict(color='k', linestyle='-', linewidth=2, alpha=0.5)
-        props = {**props, 'animated': self.useblit}
+        props = {**props, 'animated': self._useblit}
         self._selection_artist = line = Line2D([], [], **props)
         self.ax.add_line(line)
 
@@ -3946,7 +3983,7 @@ def __init__(self, ax, onselect=None, *, useblit=False,
                                 markerfacecolor=props.get('color', 'k'))
         self._handle_props = handle_props
         self._polygon_handles = ToolHandles(self.ax, [], [],
-                                            useblit=self.useblit,
+                                            useblit=self._useblit,
                                             marker_props=self._handle_props)
 
         self._active_handle_idx = -1
@@ -3966,7 +4003,7 @@ def _get_bbox(self):
 
     def _add_box(self):
         self._box = RectangleSelector(self.ax,
-                                      useblit=self.useblit,
+                                      useblit=self._useblit,
                                       grab_range=self.grab_range,
                                       handle_props=self._box_handle_props,
                                       props=self._box_props,
@@ -4248,7 +4285,7 @@ class Lasso(AxesWidget):
     def __init__(self, ax, xy, callback, *, useblit=True, props=None):
         super().__init__(ax)
 
-        self.useblit = useblit and self.canvas.supports_blit
+        self.useblit = useblit and self.canvas.supports_blit  # TODO: Make dynamic
         if self.useblit:
             self.background = self.canvas.copy_from_bbox(self.ax.bbox)