Backport PR #24137: Add note about blitting and zorder in animations (#24146)

meeseeksmachine · oscargus · web-flow · commit 3d2bbe3d6774 · 2022-10-12T13:47:38.000-04:00
Co-authored-by: Oscar Gustafsson &lt;oscar.gustafsson@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
