From 9cb87375f7d0892c1c1584c010c24236f8a6aac9 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Feb 2024 22:16:08 -0500 Subject: [PATCH 1/8] Refresh top-level docstring for drawing text objects with pyglet example --- arcade/examples/drawing_text_objects_batch.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/arcade/examples/drawing_text_objects_batch.py b/arcade/examples/drawing_text_objects_batch.py index 5bfce1cc3..7aac71e67 100644 --- a/arcade/examples/drawing_text_objects_batch.py +++ b/arcade/examples/drawing_text_objects_batch.py @@ -1,11 +1,13 @@ """ -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 From a84c1a727962ab2d731f493479a05fe6d1c48563 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Feb 2024 22:19:14 -0500 Subject: [PATCH 2/8] Simplify imports by only importing pyglet.graphics.Batch --- arcade/examples/drawing_text_objects_batch.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/arcade/examples/drawing_text_objects_batch.py b/arcade/examples/drawing_text_objects_batch.py index 7aac71e67..02c22fe2c 100644 --- a/arcade/examples/drawing_text_objects_batch.py +++ b/arcade/examples/drawing_text_objects_batch.py @@ -13,7 +13,7 @@ python -m arcade.examples.drawing_text_objects_batch """ import arcade -import pyglet.graphics +from pyglet.graphics import Batch SCREEN_WIDTH = 1200 SCREEN_HEIGHT = 800 @@ -34,7 +34,7 @@ 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 From 5f32b64f45d7b37080cf37d16e69e16b7a6f5f61 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Feb 2024 22:21:26 -0500 Subject: [PATCH 3/8] Rename window constants for accuracy --- arcade/examples/drawing_text_objects_batch.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/arcade/examples/drawing_text_objects_batch.py b/arcade/examples/drawing_text_objects_batch.py index 02c22fe2c..5b52345a8 100644 --- a/arcade/examples/drawing_text_objects_batch.py +++ b/arcade/examples/drawing_text_objects_batch.py @@ -15,9 +15,9 @@ import arcade from pyglet.graphics import Batch -SCREEN_WIDTH = 1200 -SCREEN_HEIGHT = 800 -SCREEN_TITLE = "Drawing Text Example" +WINDOW_WIDTH = 1200 +WINDOW_HEIGHT = 800 +WINDOW_TITLE = "Drawing Text Example" DEFAULT_LINE_HEIGHT = 45 DEFAULT_FONT_SIZE = 20 @@ -38,14 +38,14 @@ def __init__(self, width, height, title): # 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, ) @@ -53,7 +53,7 @@ def __init__(self, width, height, title): # 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, @@ -221,7 +221,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, @@ -386,7 +386,7 @@ def on_draw(self): def main(): - MyGame(SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_TITLE) + MyGame(WINDOW_WIDTH, WINDOW_HEIGHT, WINDOW_TITLE) arcade.run() From ce1e4e5ba7b488975e7fcf7efba51d3c520057f8 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Feb 2024 22:26:17 -0500 Subject: [PATCH 4/8] Explain the text drawing example's constants using comments --- arcade/examples/drawing_text_objects_batch.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/arcade/examples/drawing_text_objects_batch.py b/arcade/examples/drawing_text_objects_batch.py index 5b52345a8..0701f9331 100644 --- a/arcade/examples/drawing_text_objects_batch.py +++ b/arcade/examples/drawing_text_objects_batch.py @@ -15,11 +15,11 @@ import arcade from pyglet.graphics import Batch -WINDOW_WIDTH = 1200 -WINDOW_HEIGHT = 800 -WINDOW_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): From bc4eb77fce2bc59073e855aa43e69833e7c4227c Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Feb 2024 22:26:35 -0500 Subject: [PATCH 5/8] Add missing newline --- arcade/examples/drawing_text_objects_batch.py | 1 + 1 file changed, 1 insertion(+) diff --git a/arcade/examples/drawing_text_objects_batch.py b/arcade/examples/drawing_text_objects_batch.py index 0701f9331..011d6bd5b 100644 --- a/arcade/examples/drawing_text_objects_batch.py +++ b/arcade/examples/drawing_text_objects_batch.py @@ -15,6 +15,7 @@ import arcade from pyglet.graphics import Batch + WINDOW_WIDTH = 1200 # Window width in pixels WINDOW_HEIGHT = 800 # Window height in pixels WINDOW_TITLE = "Drawing Text Example" # Window title From 2cabe48cdb491deb8bb94834707b45dff2c697d5 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Feb 2024 22:37:09 -0500 Subject: [PATCH 6/8] Expose the batch drawing example in the doc --- .../drawing_text_objects_batch.rst | 22 +++++++++++++++++++ doc/example_code/how_to_examples/index.rst | 6 +++++ 2 files changed, 28 insertions(+) create mode 100644 doc/example_code/how_to_examples/drawing_text_objects_batch.rst diff --git a/doc/example_code/how_to_examples/drawing_text_objects_batch.rst b/doc/example_code/how_to_examples/drawing_text_objects_batch.rst new file mode 100644 index 000000000..287c0e0d1 --- /dev/null +++ b/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: diff --git a/doc/example_code/how_to_examples/index.rst b/doc/example_code/how_to_examples/index.rst index c19b2e279..61f1d6288 100644 --- a/doc/example_code/how_to_examples/index.rst +++ b/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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 13cb0b81defcead0e5c540bdfb95eae83da88d86 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Feb 2024 22:49:46 -0500 Subject: [PATCH 7/8] Rename and update the text object eexample page --- .../how_to_examples/drawing_text_objects.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/example_code/how_to_examples/drawing_text_objects.rst b/doc/example_code/how_to_examples/drawing_text_objects.rst index 64a0f033d..25ed6b7ae 100644 --- a/doc/example_code/how_to_examples/drawing_text_objects.rst +++ b/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 From 4d43b986b64aede78445387836418cf882a1d5e5 Mon Sep 17 00:00:00 2001 From: pushfoo <36696816+pushfoo@users.noreply.github.com> Date: Fri, 23 Feb 2024 22:55:00 -0500 Subject: [PATCH 8/8] Update the draw_text example page --- doc/example_code/how_to_examples/drawing_text.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/doc/example_code/how_to_examples/drawing_text.rst b/doc/example_code/how_to_examples/drawing_text.rst index d4019752d..54673966a 100644 --- a/doc/example_code/how_to_examples/drawing_text.rst +++ b/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