Add note about blitting and zorder in animations (#24137)

oscargus · timhoffm · QuLogic · web-flow · commit 94b993a62463 · 2022-10-12T12:33:20.000-04:00
* Add note about blitting and zorder in animations

Co-authored-by: Tim Hoffmann &lt;2836374+timhoffm@users.noreply.github.com&gt;
Co-authored-by: Elliott Sales de Andrade &lt;quantum.analyst@gmail.com&gt;
Co-authored-by: hannah &lt;story645@gmail.com&gt;
diff --git a/doc/api/animation_api.rst b/doc/api/animation_api.rst
@@ -97,6 +97,11 @@ this hopefully minimalist example gives a sense of how ``init_func``
 and ``func`` are used inside of `FuncAnimation` and the theory of how
 'blitting' works.
 
+.. note::
+
+    The zorder of artists is not taken into account when 'blitting'
+    because the 'blitted' artists are always drawn on top.
+
 The expected signature on ``func`` and ``init_func`` is very simple to
 keep `FuncAnimation` out of your book keeping and plotting logic, but
 this means that the callable objects you pass in must know what
