diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py index ced1e002d385..b6f13f898f50 100644 --- a/lib/matplotlib/artist.py +++ b/lib/matplotlib/artist.py @@ -1004,7 +1004,15 @@ def set_visible(self, b): def set_animated(self, b): """ - Set the artist's animation state. + Set whether the artist is intended to be used in an animation. + + If True, the artist is excluded from regular drawing of the figure. + You have to call `.Figure.draw_artist` / `.Axes.draw_artist` + explicitly on the artist. This appoach is used to speed up animations + using blitting. + + See also `matplotlib.animation` and + :doc:`/tutorials/advanced/blitting`. Parameters ---------- diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index b85275bce970..84647e459896 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -2930,8 +2930,8 @@ def draw_artist(self, a): """ Efficiently redraw a single artist. - This method can only be used after an initial draw which caches the - renderer. + This method can only be used after an initial draw of the figure, + because that creates and caches the renderer needed here. """ if self.figure._cachedRenderer is None: raise AttributeError("draw_artist can only be used after an " diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index f4e5183e3838..eb4e67e7fc33 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2673,9 +2673,10 @@ def draw(self, renderer): def draw_artist(self, a): """ - Draw `.Artist` instance *a* only. + Draw `.Artist` *a* only. - This can only be called after the figure has been drawn. + This method can only be used after an initial draw of the figure, + because that creates and caches the renderer needed here. """ if self._cachedRenderer is None: raise AttributeError("draw_artist can only be used after an " diff --git a/tutorials/advanced/blitting.py b/tutorials/advanced/blitting.py index 32486b236732..868b48a497bd 100644 --- a/tutorials/advanced/blitting.py +++ b/tutorials/advanced/blitting.py @@ -1,9 +1,9 @@ """ -================= -Blitting tutorial -================= +================================== +Faster rendering by using blitting +================================== -'Blitting' is a `standard technique +*Blitting* is a `standard technique `__ in raster graphics that, in the context of Matplotlib, can be used to (drastically) improve performance of interactive figures. For example, the @@ -11,25 +11,29 @@ internally. Here, we demonstrate how to implement your own blitting, outside of these classes. -The source of the performance gains is simply not re-doing work we do -not have to. If the limits of an Axes have not changed, then there is -no need to re-draw all of the ticks and tick-labels (particularly -because text is one of the more expensive things to render). +Blitting speeds up repetitive drawing by rendering all non-changing +graphic elements into a background image once. Then, for every draw, only the +changing elements need to be drawn onto this background. For example, +if the limits of an Axes have not changed, we can render the empty Axes +including all ticks and labels once, and only draw the changing data later. -The procedure to save our work is roughly: +The strategy is -- draw the figure, but exclude any artists marked as 'animated' -- save a copy of the RBGA buffer +- Prepare the constant background: -In the future, to update the 'animated' artists we + - Draw the figure, but exclude all artists that you want to animate by + marking them as *animated* (see `.Artist.set_animated`). + - Save a copy of the RBGA buffer. -- restore our copy of the RGBA buffer -- redraw only the animated artists -- show the resulting image on the screen +- Render the individual images: -thus saving us from having to re-draw everything which is _not_ -animated. One consequence of this procedure is that your animated -artists are always drawn at a higher z-order than the static artists. + - Restore the copy of the RGBA buffer. + - Redraw the animated artists using `.Axes.draw_artist` / + `.Figure.draw_artist`. + - Show the resulting image on the screen. + +One consequence of this procedure is that your animated artists are always +drawn on top of the static artists. Not all backends support blitting. You can check if a given canvas does via the `.FigureCanvasBase.supports_blit` property.