Expose batch drawing text example in the web doc (pythonarcade#1987)

* Refresh top-level docstring for drawing text objects with pyglet example

* Simplify imports by only importing pyglet.graphics.Batch

* Rename window constants for accuracy

* Explain the text drawing example's constants using comments

* Add missing newline

* Expose the batch drawing example in the doc

* Rename and update the text object eexample page

* Update the draw_text example page

Author: pushfoo

arcade/examples/drawing_text_objects_batch.py

@@ -1,23 +1,26 @@
 """
-This is the same as the examples for drawing text using the one-off draw_text function
-as well as the Text objects example. This takes it one step further though. Here we are
-creating Text objects, and then adding them to a Pyglet Batch object, and drawing them
-all with one draw command.
+The current fastest way to draw text with arcade.
 
-Using this method, we can draw thousands and thousands of text objects with nearly the
-same cost as drawing just one Text object directly.
+This example improves on the other two text-drawing examples
+by using pyglet's batch functionality.
+
+Although pyglet's batches do not support non-drawing features like
+arcade's SpriteList, they offer similar benefits for drawing. Adding
+arcade.Text objects to a batch allows drawing thousands of them with
+almost the same cost as drawing a single one directly.
 
 If Python and Arcade are installed, this example can be run from the command line with:
 python -m arcade.examples.drawing_text_objects_batch
 """
 import arcade
-import pyglet.graphics
+from pyglet.graphics import Batch
+
 
-SCREEN_WIDTH = 1200
-SCREEN_HEIGHT = 800
-SCREEN_TITLE = "Drawing Text Example"
-DEFAULT_LINE_HEIGHT = 45
-DEFAULT_FONT_SIZE = 20
+WINDOW_WIDTH = 1200  # Window width in pixels
+WINDOW_HEIGHT = 800  # Window height in pixels
+WINDOW_TITLE = "Drawing Text Example"  # Window title
+DEFAULT_LINE_HEIGHT = 45  # Line height to use in pixels
+DEFAULT_FONT_SIZE = 20  # Default font size in points
 
 
 class MyGame(arcade.Window):
@@ -32,26 +35,26 @@ def __init__(self, width, height, title):
         self.text_angle = 0
         self.time_elapsed = 0.0
 
-        self.batch = pyglet.graphics.Batch()
+        self.batch = Batch()
 
         # Add the screen title
         start_x = 0
-        start_y = SCREEN_HEIGHT - DEFAULT_LINE_HEIGHT * 1.5
+        start_y = WINDOW_HEIGHT - DEFAULT_LINE_HEIGHT * 1.5
         self.title = arcade.Text(
             "Text Drawing Examples",
             start_x,
             start_y,
             arcade.color.BLACK,
             DEFAULT_FONT_SIZE * 2,
-            width=SCREEN_WIDTH,
+            width=WINDOW_WIDTH,
             align="center",
             batch=self.batch,
         )
 
         # start_x and start_y make the start point for the text. We draw a dot to make it
         # easy too see the text in relation to its start x and y.
         start_x = 10
-        start_y = SCREEN_HEIGHT - DEFAULT_LINE_HEIGHT * 3
+        start_y = WINDOW_HEIGHT - DEFAULT_LINE_HEIGHT * 3
         self.fonts = arcade.Text(
             "Fonts:",
             start_x,
@@ -219,7 +222,7 @@ def __init__(self, width, height, title):
 
         # --- Column 2 ---
         start_x = 750
-        start_y = SCREEN_HEIGHT - DEFAULT_LINE_HEIGHT * 3
+        start_y = WINDOW_HEIGHT - DEFAULT_LINE_HEIGHT * 3
         self.text_positioning = arcade.Text(
             "Text Positioning:",
             start_x,
@@ -384,7 +387,7 @@ def on_draw(self):
 
 
 def main():
-    MyGame(SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_TITLE)
+    MyGame(WINDOW_WIDTH, WINDOW_HEIGHT, WINDOW_TITLE)
     arcade.run()
 
 

doc/example_code/how_to_examples/drawing_text.rst

@@ -10,10 +10,15 @@ Slow but Easy Text Drawing
     :align: center
     :alt: Screenshot of drawing text
 
-This example shows how to draw text. While it is simple to draw using the
-techniques shown here, it is also slow. Using "text objects" can result in
-significant performance improvements. See :ref:`drawing_text_objects`.
+This example shows an easy but very slow way to draw text.
 
+Its main benefit is ease of use. More complicated approaches
+with :py:class:`arcade.Text` objects can run thousands of times
+faster.
+
+* See :ref:`drawing_text_objects` for a medium-performance approach
+* See :ref:`drawing_text_objects_batch` if you want the best performance
+  possible
 
 .. literalinclude:: ../../../arcade/examples/drawing_text.py
     :caption: drawing_text.py

doc/example_code/how_to_examples/drawing_text_objects.rst

@@ -2,16 +2,19 @@
 
 .. _drawing_text_objects:
 
-Fast Text Drawing
-=================
+Better Text Drawing with Text Objects
+=====================================
 
 .. image:: drawing_text_objects.png
     :width: 500px
     :align: center
     :alt: Screenshot of drawing with text objects
 
-This example shows how to draw text using "text objects." It is the fastest
-way to draw text. If you are looking for something simpler, see :ref:`drawing_text`.
+This example shows how to draw text using "text objects." It can be many
+times faster than using :py:func:`arcade.draw_text`.
+
+* If you want to be as efficient as possible, see :ref:`drawing_text_objects_batch`.
+* If you are looking for something simpler, see :ref:`drawing_text`.
 
 .. literalinclude:: ../../../arcade/examples/drawing_text_objects.py
     :caption: drawing_text_objects.py

doc/example_code/how_to_examples/drawing_text_objects_batch.rst

@@ -0,0 +1,22 @@
+:orphan:
+
+.. _drawing_text_objects_batch:
+
+The Fastest Text Drawing: pyglet Batches
+========================================
+
+.. image:: drawing_text_objects.png
+    :width: 500px
+    :align: center
+    :alt: Screenshot of drawing with text objects
+
+This example demonstrates the most efficient way to render
+:py:class:`arcade.Text` objects: adding them to pyglet's
+:py:class:`~pyglet.graphics.Batch`. Otherwise, it is the
+same as the :ref:`drawing_text_objects` example.
+
+For a much simpler and slower approach,  see :ref:`drawing_text`.
+
+.. literalinclude:: ../../../arcade/examples/drawing_text_objects.py
+    :caption: drawing_text_objects.py
+    :linenos:

doc/example_code/how_to_examples/index.rst

@@ -49,6 +49,12 @@ Drawing Primitives
 
    :ref:`drawing_text_objects`
 
+.. figure:: thumbs/drawing_text_objects.png
+   :figwidth: 170px
+   :target: drawing_text_objects_batch.html
+
+   :ref:`drawing_text_objects_batch`
+
 Animating Drawing Primitives
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^