Expose batch drawing text example in the web doc (#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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^