Add Sprite & SpriteList programming guide pages (#1691)

* Add new Programming Guide index page to fix toctree issues

* Add intro text to Programming Guide index page

* Add Sprite & SpriteList programming guide page

* Rename ref target for sprite examples

* Link SpriteLists doc from Programming Guide index

* Fix ommitted link in sprites index page

* Remove extra newline after section heading

* Remove exclamation point in subsection heading per review

* Move minimal Sprite example into a separate file

* Remove redundant wording about time to read a page

* Fix formatting on sprite_minimal example

* Phrasing & line length improvements in advanced SpriteList page

* Reverse table entry ordering for better section flow

* Use non-directory-style ref target for camera examples

---------

Co-authored-by: Paul V Craven <paul@cravenfamily.com>

Author: pushfoo

arcade/examples/sprite_minimal.py

@@ -0,0 +1,35 @@
+"""
+Minimal Sprite Example
+
+Draws a single sprite in the middle screen.
+
+If Python and Arcade are installed, this example can be run from the command line with:
+python -m arcade.examples.sprite_minimal
+"""
+import arcade
+
+
+class WhiteSpriteCircleExample(arcade.Window):
+
+    def __init__(self):
+        super().__init__(800, 600, "White SpriteCircle Example")
+        self.sprites = None
+        self.setup()
+
+    def setup(self):
+        # 1. Create the SpriteList
+        self.sprites = arcade.SpriteList()
+
+        # 2. Create & append your Sprite instance to the SpriteList
+        self.circle = arcade.SpriteCircle(30, arcade.color.WHITE)  # 30 pixel radius circle
+        self.circle.position = self.width // 2, self.height // 2  # Put it in the middle
+        self.sprites.append(self.circle)  # Append the instance to the SpriteList
+
+    def on_draw(self):
+        # 3. Call draw() on the SpriteList inside an on_draw() method
+        self.sprites.draw()
+
+
+if __name__ == "__main__":
+    game = WhiteSpriteCircleExample()
+    game.run()

doc/example_code/how_to_examples/index.rst

@@ -105,7 +105,8 @@ Faster Drawing with ShapeElementLists
 
    :ref:`gradients`
 
-.. _sprites:
+
+.. _sprite_examples:
 
 Sprites
 -------
@@ -403,7 +404,7 @@ Backgrounds
 
    :ref:`background_parallax`
 
-.. _examples_cameras:
+.. _camera_examples:
 
 Cameras
 ^^^^^^^

doc/index.rst

@@ -75,6 +75,7 @@ The Python Arcade Library
 
    programming_guide/install/index
    programming_guide/get_started
+   programming_guide/sprites/index
    programming_guide/how_to_get_help
    programming_guide/directory_structure
    programming_guide/edge_artifacts/index

doc/programming_guide/index.rst

@@ -21,6 +21,7 @@ external documentation where applicable.
 
    install/index
    get_started
+   sprites/index
    how_to_get_help
    directory_structure
    edge_artifacts/index

doc/programming_guide/sprites/advanced.rst

@@ -0,0 +1,204 @@
+.. _pg_spritelists_advanced:
+
+Advanced SpriteList Techniques
+------------------------------
+
+This page provides overviews of advanced techniques. Runnable examples are
+not guaranteed, as the reader is expected to be able to put the work into
+implementing them.
+
+Beginners should be careful of the following sections. Some of these techniques
+can slow down or crash your game if misused.
+
+
+.. _pg_spritelists_advanced_draw_order_and_sorting:
+
+Draw Order & Sorting
+^^^^^^^^^^^^^^^^^^^^
+
+In some cases, you can combine two features of SpriteList:
+
+* By default, SpriteLists draw starting from their lowest index.
+* :py:class:`~arcade.SpriteList` has a :py:meth:`~arcade.SpriteList.sort`
+  method nearly identical to :py:meth:`list.sort`.
+
+
+First, Consider Alternatives
+""""""""""""""""""""""""""""
+
+Sorting in Python is a slow, CPU-bound function. Consider the following
+techniques to eliminate or minimize this cost:
+
+* Use multiple sprite lists or :py:class:`arcade.Scene` to
+  achieve layering
+* Chunk your game world into smaller regions with sprite lists
+  for each, and only sort when something inside moves or changes
+* Use the :py:attr:`Sprite.depth <arcade.BasicSprite.depth>` attribute
+  with :ref:`shaders <tutorials_shaders>` to sort on the GPU
+
+For a conceptual overview of chunks as used in a commercial 2D game, please
+see the following:
+
+* `Chunks in Factorio <https://wiki.factorio.com/Map_structure#Chunk>`_
+
+
+Sorting SpriteLists
+"""""""""""""""""""
+
+Although the alternative listed above are often better, sorting sprite lists to
+control draw order can still be useful.
+
+Like Python's built-in :py:meth:`list.sort`, you can pass a
+`callable object <https://docs.python.org/3/library/functions.html#callable>`_
+via the key argument to specify how to sort, along with an optional ``reverse``
+keyword to reverse the direction of sorting.
+
+Here's an example of how you could use sorting to quickly create an
+inefficient prototype:
+
+.. code:: python
+
+
+    import random
+    import arcade
+
+
+    # Warning: the bottom property is extra slow compared to other attributes!
+    def bottom_edge_as_sort_key(sprite):
+        return sprite.bottom
+
+
+    class InefficientTopDownGame(arcade.Window):
+        """
+        Uses sorting to allow the player to move in front of & behind shrubs
+
+        For non-prototyping purposes, other approaches will be better.
+        """
+
+        def __init__(self, num_shrubs=50):
+            super().__init__(800, 600, "Inefficient Top-Down Game")
+
+            self.background_color = arcade.color.SAND
+            self.shrubs = arcade.SpriteList()
+            self.drawable = arcade.SpriteList()
+
+            # Randomly place pale green shrubs around the screen
+            for i in range(num_shrubs):
+                shrub = arcade.SpriteSolidColor(20, 40, color=arcade.color.BUD_GREEN)
+                shrub.position = random.randrange(self.width), random.randrange(self.height)
+                self.shrubs.append(shrub)
+                self.drawable.append(shrub)
+
+            self.player = arcade.SpriteSolidColor(16, 30, color=arcade.color.RED)
+            self.drawable.append(self.player)
+
+        def on_mouse_motion(self, x, y, dx, dy):
+            # Update the player position
+            self.player.position = x, y
+            # Sort the sprites so the highest on the screen draw first
+            self.drawable.sort(key=bottom_edge_as_sort_key, reverse=True)
+
+        def on_draw(self):
+            self.clear()
+            self.drawable.draw()
+
+
+    game = InefficientTopDownGame()
+    game.run()
+
+
+.. _pg_spritelist_advanced_texture_atlases:
+
+Custom Texture Atlases
+^^^^^^^^^^^^^^^^^^^^^^
+
+A :py:class:`~arcade.TextureAtlas` represents :py:class:`~arcade.Texture`
+data packed side-by-side in video memory. As textures are added, the atlas
+grows to fit them all into the same portion of your GPU's memory.
+
+By default, each :py:class:`~arcade.SpriteList` uses the same default
+atlas. Use the ``atlas`` keyword argument to specify a custom atlas
+for an instance.
+
+This is especially useful to prevent problems when using large or oddly
+shaped textures.
+
+Please see the following for more information:
+
+* :ref:`pg_textureatlas_custom_atlas`
+* The :py:class:`~arcade.TextureAtlas` API documentation
+
+
+.. _pg_spritelist_advanced_lazy_spritelists:
+
+Lazy SpriteLists
+^^^^^^^^^^^^^^^^
+
+You can delay creating the OpenGL resources for a
+:py:class:`~arcade.SpriteList` by passing ``lazy=True`` on creation:
+
+.. code:: python
+
+    sprite_list = SpriteList(lazy=True)
+
+The SpriteList won't create the OpenGL resources until forced to
+by one of the following:
+
+1. The first :py:meth:`SpriteList.draw() <arcade.SpriteList.draw>` call on it
+2. :py:meth:`SpriteList.initialize() <arcade.SpriteList.initialize>`
+3. GPU-backed collisions, if enabled
+
+This behavior is most useful in the following cases:
+
+.. list-table::
+    :header-rows: 1
+
+    * - Case
+      - Primary Purpose
+
+    * - Creating SpriteLists before a Window
+      - CPU-only `unit tests <https://docs.python.org/3/library/unittest.html>`_ which
+        never draw
+
+    * - Parallelized SpriteList creation
+      - Faster loading & world generation via :py:mod:`threading`
+        or :py:mod:`subprocess` & :py:mod:`pickle`
+
+
+.. _pg_spritelist_advanced_parallel_loading:
+
+Parallelized Loading
+""""""""""""""""""""
+
+To increase loading speed & reduce stutters during gameplay, you can
+run pre-gameplay tasks in parallel, such as pre-generating maps
+or pre-loading assets from disk into RAM.
+
+
+.. warning:: Only the main thread is allowed to access OpenGL!
+
+             Attempting to access OpenGL from non-main threads will
+             raise an OpenGL Error!
+
+To safely implement parallel loading, you will want to use the following
+general approach before allowing gameplay to begin:
+
+1. Pass ``lazy=True`` when creating :py:class:`~arcade.SpriteList` instances
+   in your loading code as described above
+2. Sync the SpriteList data back to the main thread or process once loading
+   is finished
+3. Inside the main thread, call
+   :py:meth:`Spritelist.initialize() <arcade.SpriteList.initialize>` on each
+   sprite list once it's ready to allocate GPU resources
+
+
+Very advanced users can use :py:mod:`subprocess` to create SpriteLists
+inside another process and the :py:mod:`pickle` module to help pass data
+back to the main process.
+
+Please see the following for additional information:
+
+* :ref:`Arcade's OpenGL notes <open_gl_notes>` for arcade-specific
+  threading considerations
+* Python's :py:mod:`threading` documentation
+* Python's :py:mod:`subprocess` and :py:mod:`pickle` documentation

doc/programming_guide/sprites/index.rst

@@ -0,0 +1,37 @@
+.. _sprites:
+
+Drawing & Using Sprites
+=======================
+
+Most games built with Arcade will use sprites and sprite lists to draw image
+data. This section of the programming guide will help you achieve that by
+covering:
+
+* What sprites & sprite lists are
+* The essentials of how to use them
+* How to get started with images
+* Non-drawing features such as collisions
+* Overviews of various advanced techniques
+
+Beginners should start by reading & following :ref:`pg_spritelists` page
+(~10 minute read). If you get stuck, see :ref:`how-to-get-help`.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   spritelists
+   advanced
+
+
+I'm Impatient!
+--------------
+
+Beginners should at least skim :ref:`pg_spritelists` (~10 minute read),
+but you can skip to the tutorials and full example code if you'd like:
+
+* :ref:`pg_spritelists_minimal_sprite_drawing`
+* :ref:`Arcade's Sprite Examples <sprites>`
+* :ref:`Arcade's Simple Platformer Tutorial <platformer_tutorial>`