Start end render (#2204)

* rect_draw: allow specifying atlas

* Revamp start/finish_render

* Fix examples still using start_render

* Unit test + fix old tests

Author: einarf

arcade/application.py

@@ -8,7 +8,7 @@
 import logging
 import os
 import time
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
 
 import pyglet
 import pyglet.gl as gl
@@ -17,12 +17,17 @@
 from pyglet.window import MouseCursor
 
 import arcade
-from arcade import SectionManager, get_display_size, set_window
 from arcade.clock import Clock, FixedClock
 from arcade.color import TRANSPARENT_BLACK
 from arcade.context import ArcadeContext
+from arcade.sections import SectionManager
 from arcade.types import LBWH, Color, Rect, RGBANormalized, RGBOrA255
 from arcade.utils import is_raspberry_pi
+from arcade.window_commands import get_display_size, set_window
+
+if TYPE_CHECKING:
+    from arcade.start_finish_data import StartFinishRenderData
+
 
 LOG = logging.getLogger(__name__)
 
@@ -235,8 +240,6 @@ def __init__(
         self._current_view: Optional[View] = None
         self.textbox_time = 0.0
         self.key: Optional[int] = None
-        self.flip_count: int = 0
-        self.static_display: bool = False
 
         # See if we should center the window
         if center_window:
@@ -255,6 +258,12 @@ def __init__(
             self.keyboard = None
             self.mouse = None
 
+        # Framebuffer for drawing content into when start_render is called.
+        # These are typically functions just at module level wrapped in
+        # start_render and finish_render calls. The framebuffer is repeatedly
+        # rendered to the window when the event loop starts.
+        self._start_finish_render_data: Optional[StartFinishRenderData] = None
+
     @property
     def current_view(self) -> Optional["View"]:
         """
@@ -629,6 +638,11 @@ def on_draw(self) -> Optional[bool]:
         """
         Override this function to add your custom drawing code.
         """
+        if self._start_finish_render_data:
+            self.clear()
+            self._start_finish_render_data.draw()
+            return True
+
         return False
 
     def on_resize(self, width: int, height: int) -> Optional[bool]:
@@ -890,13 +904,6 @@ def flip(self) -> None:
         num_collected = self.ctx.gc()
         LOG.debug("Garbage collected %s OpenGL resource(s)", num_collected)
 
-        # Attempt to handle static draw setups
-        if self.static_display:
-            if self.flip_count > 0:
-                return
-            else:
-                self.flip_count += 1
-
         super().flip()
 
     def switch_to(self) -> None:

arcade/draw/rect.py

@@ -1,10 +1,12 @@
 import array
+from typing import Optional
 
 from arcade import gl
 from arcade.color import WHITE
 from arcade.math import rotate_point
 from arcade.sprite import BasicSprite
 from arcade.texture import Texture
+from arcade.texture_atlas.base import TextureAtlasBase
 from arcade.types import LBWH, LRBT, RGBA255, XYWH, Color, PointList, Rect
 from arcade.window_commands import get_window
 
@@ -20,6 +22,7 @@ def draw_texture_rect(
     blend=True,
     alpha=1.0,
     pixelated=False,
+    atlas: Optional[TextureAtlasBase] = None,
 ) -> None:
     """
     Draw a texture on a rectangle.
@@ -30,6 +33,7 @@ def draw_texture_rect(
     :param angle: Rotation of the texture in degrees. Defaults to zero.
     :param blend: If True, enable alpha blending. Defaults to True.
     :param alpha: Transparency of image. 0.0 is fully transparent, 1.0 (default) is visible.
+    :param atlas: The texture atlas the texture resides in. if not supplied the default texture atlas is used
     """
     ctx = get_window().ctx
 
@@ -38,9 +42,9 @@ def draw_texture_rect(
     else:
         ctx.disable(ctx.BLEND)
 
-    atlas = ctx.default_atlas
+    atlas = atlas or ctx.default_atlas
 
-    texture_id, _ = ctx.default_atlas.add(texture)
+    texture_id, _ = atlas.add(texture)
     if pixelated:
         atlas.texture.filter = gl.NEAREST, gl.NEAREST
     else:
@@ -64,11 +68,22 @@ def draw_texture_rect(
         ctx.disable(ctx.BLEND)
 
 
-def draw_sprite(sprite: BasicSprite, *, blend: bool = True, alpha=1.0, pixelated=False) -> None:
+def draw_sprite(
+    sprite: BasicSprite,
+    *,
+    blend: bool = True,
+    alpha=1.0,
+    pixelated=False,
+    atlas: Optional[TextureAtlasBase] = None,
+) -> None:
     """
     Draw a sprite.
 
     :param sprite: The sprite to draw.
+    :param blend: Draw the sprite with or without alpha blending
+    :param alpha: Fade the sprite from completely transparent to opaque (range: 0.0 to 1.0)
+    :param pixelated: If true the sprite will be render in pixelated style. Otherwise smooth/linear
+    :param atlas: The texture atlas the texture resides in. if not supplied the default texture atlas is used
     """
     draw_texture_rect(
         sprite.texture,
@@ -78,16 +93,28 @@ def draw_sprite(sprite: BasicSprite, *, blend: bool = True, alpha=1.0, pixelated
         blend=blend,
         alpha=alpha,
         pixelated=pixelated,
+        atlas=atlas,
     )
 
 
 def draw_sprite_rect(
-    sprite: BasicSprite, rect: Rect, *, blend: bool = True, alpha=1.0, pixelated=False
+    sprite: BasicSprite,
+    rect: Rect,
+    *,
+    blend: bool = True,
+    alpha=1.0,
+    pixelated=False,
+    atlas: Optional[TextureAtlasBase] = None,
 ) -> None:
     """
     Draw a sprite.
 
     :param sprite: The sprite to draw.
+    :param rect: The location and size of the sprite
+    :param blend: Draw the sprite with or without alpha blending
+    :param alpha: Fade the sprite from completely transparent to opaque (range: 0.0 to 1.0)
+    :param pixelated: If true the sprite will be render in pixelated style. Otherwise smooth/linear
+    :param atlas: The texture atlas the texture resides in. if not supplied the default texture atlas is used
     """
     draw_texture_rect(
         sprite.texture,
@@ -97,6 +124,7 @@ def draw_sprite_rect(
         blend=blend,
         alpha=alpha,
         pixelated=pixelated,
+        atlas=atlas,
     )
 
 

arcade/examples/drawing_primitives.py

@@ -21,7 +21,7 @@
 import arcade
 
 # Open the window. Set the window title and dimensions (width and height)
-arcade.open_window(600, 600, "Drawing Primitives Example")
+arcade.open_window(600, 600, "Drawing Primitives Example", resizable=True)
 
 # Set the background color to white
 # For a list of named colors see

arcade/examples/happy_face.py

@@ -13,7 +13,7 @@
 SCREEN_TITLE = "Happy Face Example"
 
 # Open the window. Set the window title and dimensions
-arcade.open_window(SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_TITLE)
+arcade.open_window(SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_TITLE, resizable=True)
 
 # Set the background color
 arcade.set_background_color(arcade.color.WHITE)

arcade/examples/sections_demo_3.py

@@ -283,7 +283,7 @@ def __init__(self):
         self.section_manager.add_section(self.map)
 
     def on_draw(self):
-        arcade.start_render()
+        self.clear()
 
 
 def main():

arcade/gui/examples/exp_scroll_area.py

@@ -41,7 +41,7 @@ def __init__(self):
         anchor.add(UIInputText().with_border())
 
     def on_draw(self):
-        arcade.start_render()
+        self.clear()
         self.ui.draw()
 
 

arcade/gui/examples/side_bars_with_box_layout.py

@@ -55,7 +55,7 @@ def on_key_press(self, symbol: int, modifiers: int):
         pass
 
     def on_draw(self):
-        arcade.start_render()
+        self.clear()
         self.ui.draw()
 
 

arcade/start_finish_data.py

@@ -0,0 +1,57 @@
+from arcade.draw.rect import draw_texture_rect
+from arcade.texture.texture import Texture
+from arcade.types import LBWH, AnchorPoint
+from arcade.window_commands import get_window
+
+
+class StartFinishRenderData:
+    """
+    State data for offscreen rendering with :py:meth:`arcade.start_render` and
+    :py:meth:`arcade.finish_render`. This is only meant for simply module level
+    drawing like creating a static image we display on the screen.
+
+    :param pixelated: Should the image be pixelated or smooth when scaled?
+    :param blend: Should we draw with alpha blending enabled?
+    """
+
+    def __init__(self, pixelated: bool = False, blend: bool = True):
+        from arcade.texture_atlas.atlas_default import DefaultTextureAtlas
+
+        self.window = get_window()
+        self.pixelated = pixelated
+        self.blend = blend
+        self.atlas = DefaultTextureAtlas(self.window.get_framebuffer_size(), border=0)
+        self.texture = Texture.create_empty(
+            "start_finish_render_texture", size=self.window.get_framebuffer_size()
+        )
+        self.atlas.add(self.texture)
+        self._generator_func = None
+        self.completed = False
+
+    def begin(self):
+        """Enable rendering into the buffer"""
+        self.generator_func = self.atlas.render_into(self.texture)
+        fbo = self.generator_func.__enter__()
+        fbo.clear(color=self.window.background_color)
+
+        if self.blend:
+            self.window.ctx.enable(self.window.ctx.BLEND)
+
+    def end(self):
+        """Switch back to rendering into the window"""
+        self.generator_func.__exit__(None, None, None)
+        self.completed = True
+
+    def draw(self):
+        """Draw the buffer to the screen"""
+        # Stretch the texture to the window size with black bars if needed
+        w, h = self.window.get_size()
+        min_factor = min(w / self.texture.width, h / self.texture.height)
+        region = LBWH(0, 0, self.texture.width, self.texture.height).scale(
+            min_factor, anchor=AnchorPoint.BOTTOM_LEFT
+        )
+        region = region.move(dx=(w - region.width) / 2, dy=(h - region.height) / 2)
+
+        draw_texture_rect(
+            self.texture, region, pixelated=self.pixelated, blend=False, atlas=self.atlas
+        )

arcade/window_commands.py

@@ -179,31 +179,51 @@ def exit() -> None:
     pyglet.app.exit()
 
 
-def start_render() -> None:
+def start_render(pixelated=False, blend=True) -> None:
     """
-    Clears the window.
+    Start recording drawing functions into an offscreen buffer.
+    Call :py:func:`arcade.finish_render` to stop recording. The
+    start_render/finish_render calls can only be called once.
 
-    More practical alternatives to this function is
-    :py:meth:`arcade.Window.clear`
-    or :py:meth:`arcade.View.clear`.
-    """
-    get_window().clear()
+    When running arcade this buffer will be presented to the screen.
 
+    A few configuration options are available in this function.
 
-def finish_render():
+    :param pixelated: If True, the buffer will be be pixelated when resized. Otherwise, it will be smooth.
+    :param blend: If alpha blending
     """
-    Swap buffers and displays what has been drawn.
+    from arcade.start_finish_data import StartFinishRenderData
+
+    window = get_window()
+    if window._start_finish_render_data is not None:
+        raise RuntimeError(
+            (
+                "start_render() can only be called once during the application's lifetime "
+                "and should only be used when calling draw functions at module level in "
+                "a simple script to produce a static image. If you are seeing this error "
+                "you likely intended to call clear() instead."
+            )
+        )
 
-    .. Warning::
+    window._start_finish_render_data = StartFinishRenderData(pixelated=pixelated, blend=blend)
+    window._start_finish_render_data.begin()
 
-        If you are extending the :py:class:`~arcade.Window` class, this function
-        should not be called. The event loop will automatically swap the window
-        framebuffer for you after ``on_draw``.
 
+def finish_render() -> None:
     """
-    get_window().static_display = True
-    get_window().flip_count = 0
-    get_window().flip()
+    Stop recording drawing functions into an offscreen buffer.
+    :py:func:`arcade.start_render` should be called before this function.
+
+    :py:func:`arcade.run` can be called after this function to present the buffer.
+    """
+    window = get_window()
+    if window._start_finish_render_data is None:
+        raise RuntimeError("finish_render() was called without a matching start_render() call.")
+
+    if window._start_finish_render_data.completed:
+        raise RuntimeError("finish_render() was called more than once.")
+
+    window._start_finish_render_data.end()
 
 
 def set_background_color(color: RGBA255) -> None:

tests/conftest.py

@@ -48,6 +48,7 @@ def prepare_window(window: arcade.Window):
     # ctx._atlas = None  # Clear the global atlas
     # default_texture_cache.flush()  # Clear the global/default texture cache
     arcade.SpriteList.DEFAULT_TEXTURE_FILTER = gl.LINEAR, gl.LINEAR
+    window._start_finish_render_data = None
     window.hide_view()  # Disable views if any is active
     window.dispatch_pending_events()
     try:
@@ -170,6 +171,14 @@ def background_color(self, color):
     def current_camera(self):
         return self.window.current_camera
 
+    @property
+    def _start_finish_render_data(self):
+        return self.window._start_finish_render_data
+    
+    @_start_finish_render_data.setter
+    def _start_finish_render_data(self, data):
+        self.window._start_finish_render_data = data
+
     @current_camera.setter
     def current_camera(self, new_camera):
         self.window.current_camera = new_camera
@@ -200,6 +209,9 @@ def get_size(self):
     def set_size(self, width, height):
         self.window.set_size(width, height)
 
+    def get_framebuffer_size(self):
+        return self.window.get_framebuffer_size()
+
     def get_pixel_ratio(self):
         return self.window.get_pixel_ratio()
 
@@ -283,7 +295,9 @@ def window_proxy():
 
     _open_window = arcade.open_window
     def open_window(*args, **kwargs):
-        return create_window(*args, **kwargs)
+        window = create_window(*args, **kwargs)
+        prepare_window(window)
+        return window
     arcade.open_window = open_window
 
     yield None