Add screenshot 1342

arcade/__init__.py

@@ -9,6 +9,7 @@
 # Error out if we import Arcade with an incompatible version of Python.
 import sys
 import os
+from datetime import datetime, tzinfo
 from typing import Optional
 
 from pathlib import Path
@@ -34,6 +35,50 @@ def configure_logging(level: Optional[int] = None):
         LOG.addHandler(ch)
 
 
+def get_timestamp(
+        how: str = "%Y_%m_%d_%H%M_%S_%f%Z",
+        when: Optional[types.HasStrftime | datetime] = None,
+        tzinfo: Optional[tzinfo] = None
+) -> str:
+    """Return a timestamp as a formatted string.
+
+    .. tip:: To print text to the console, see :ref:`logging`!
+
+             This function :ref:`helps people who can't <debug-timestamps-who>`
+             use a :ref:`better alternative <debug-better-datetime>`.
+
+    Calling this function without any arguments returns a string
+    with the current system time down to microseconds:
+
+    .. code-block:: python
+
+       # This code assumes the function is called at exactly 3PM
+       # on April 3rd, 2024 in the computer's local time zone.
+       >>> arcade.get_timestamp()
+       `2024_04_03_1500_00_000000'
+
+
+    See the following to learn more:
+
+    * For general information, see :ref:`debug-timestamps`
+    * For custom formatting & times, see :ref:`debug-timestamps-example-when-how`
+    * To use time zones such as UTC, see :ref:`debug-timestamps-example-timezone`
+    * The general :py:mod:`datetime` documentation
+    * Python's guide to
+      :ref:`datetime-like behavior <strftime-strptime-behavior>`
+
+
+    :param how: A :ref:`valid datetime format string <strtime-strptime-behavior>`
+    :param tzinfo: A :py:class:`datetime.tzinfo` instance.
+    :param when: ``None`` or a :ref:`a datetime-like object <strftime-strptime-behavior>`
+    :return: A formatted string for either a passed ``when`` or
+        :py:meth:`datetime.now <datetime.datetime.now>`
+
+    """
+    when = when or datetime.now(tzinfo)
+    return when.strftime(how)
+
+
 # The following is used to load ffmpeg libraries.
 # Currently Arcade is only shipping binaries for Mac OS
 # as ffmpeg is not needed for support on Windows and Linux.
@@ -83,6 +128,7 @@ def configure_logging(level: Optional[int] = None):
 from .window_commands import start_render
 from .window_commands import unschedule
 from .window_commands import schedule_once
+from .window_commands import save_screenshot
 
 from .sections import Section, SectionManager
 
@@ -330,6 +376,7 @@ def configure_logging(level: Optional[int] = None):
     'get_screens',
     'get_sprites_at_exact_point',
     'get_sprites_at_point',
+    'get_timestamp',
     'SpatialHash',
     'get_timings',
     'create_text_sprite',
@@ -353,6 +400,7 @@ def configure_logging(level: Optional[int] = None):
     'read_tmx',
     'load_tilemap',
     'run',
+    'save_screenshot',
     'schedule',
     'set_background_color',
     'set_window',

arcade/application.py

@@ -7,8 +7,8 @@
 import logging
 import os
 import time
-from typing import List, Tuple, Optional
-
+from typing import List, Tuple, Optional, Union
+from pathlib import Path
 import pyglet
 
 import pyglet.gl as gl
@@ -23,6 +23,9 @@
 from arcade.types import Color, RGBOrA255, RGBANormalized
 from arcade import SectionManager
 from arcade.utils import is_raspberry_pi
+from arcade.types import Rect
+from PIL import Image
+
 from arcade.camera import Projector
 from arcade.camera.default import DefaultProjector
 
@@ -915,6 +918,58 @@ def on_mouse_leave(self, x: int, y: int):
         """
         pass
 
+    def save_screenshot(
+            self,
+            path: Union[Path, str],
+            format: Optional[str] = None,
+            **kwargs
+    ) -> None:
+        """Save a screenshot to a specified file name.
+
+        .. warning:: This may overwrite existing files!
+
+        .. code-block:: python
+
+           # By default, the image format is detected from the
+           # file extension on the path you pass.
+           window_instance.save_screenshot("screenshot.png")
+
+        You can also use the same arguments as :py:meth:`PIL.Image.save`:
+
+        * You can pass a ``format`` to stop Pillow from guessing the
+          format from the file name
+        * The pillow documentation provides a list of supported
+          :external+PIL:ref:`image-file-formats`
+
+        :param path: The full path and the png image filename to save.
+        :param format: A :py:mod:`PIL` format name.
+        :param kwargs: Varies with :external+PIL:ref:`selected format <image-file-formats>`
+        """
+        img = self.ctx.get_framebuffer_image(self.ctx.screen)
+        img.save(path, format=format, **kwargs)
+
+    def get_image(
+            self,
+            viewport: Rect | None
+        ) -> Image.Image:
+        """Get an image from the window.
+
+        .. code-block:: python
+
+           # Get an image from a portion of the window by specfying the viewport.
+           viewport = Rect(10, 16, 20, 20)
+           image = window_instance.get_image(viewport)
+
+           # Get an image of the whole Window
+           image = window_instance.get_image()
+
+        :param viewport: The area of the screen to get defined by the x, y, width, height values
+        """
+        return self.ctx.get_framebuffer_image(self.ctx.screen, viewport=viewport)
+
+    def get_pixel(self):
+        pass
+
 
 def open_window(
     width: int,

arcade/context.py

@@ -22,6 +22,8 @@
 from arcade.gl.framebuffer import Framebuffer
 from pyglet.math import Mat4
 from arcade.texture_atlas import TextureAtlas
+from arcade.types import Rect
+
 
 __all__ = ["ArcadeContext"]
 
@@ -497,19 +499,28 @@ def get_framebuffer_image(
         fbo: Framebuffer,
         components: int = 4,
         flip: bool = True,
+        viewport: Optional[Rect] = None
     ) -> Image.Image:
         """
         Shortcut method for reading data from a framebuffer and converting it to a PIL image.
 
         :param fbo: Framebuffer to get image from
         :param components: Number of components to read
         :param flip: Flip the image upside down
+        :param viewport: x, y, width, height to read
         """
         mode = "RGBA"[:components]
+        if viewport:
+            width = viewport[2] - viewport[0]
+            height = viewport[3] - viewport[1]
+        else:
+            width = fbo.width
+            height = fbo.height
+
         image = Image.frombuffer(
             mode,
-            (fbo.width, fbo.height),
-            fbo.read(components=components),
+            (width, height),
+            fbo.read(viewport=viewport, components=components),
         )
         if flip:
             image = image.transpose(Image.Transpose.FLIP_TOP_BOTTOM)

arcade/examples/debug_screenshot.py

@@ -0,0 +1,65 @@
+"""Take screenshots for debugging.
+
+This example shows you how to take debug screenshots by:
+
+1. Setting the window's background to a non-transparent color
+2. Randomly arranging sprites to display a pattern over it
+3. Using arcade.save_screenshot
+
+After installing arcade version 3.0.0 or higher, this example can be run
+from the command line with:
+python -m arcade.examples.debug_screenshot
+"""
+import random
+import arcade
+from arcade.types import Color
+
+
+SCREENSHOT_FILE_NAME = "debug_screenshot_image.png"
+
+# How many sprites to draw and how big they'll be
+NUM_SPRITES = 100
+MIN_RADIUS_PX = 5
+MAX_RADIUS_PX = 50
+
+# Window size
+WIDTH_PX = 800
+HEIGHT_PX = 600
+
+
+class ScreenshotWindow(arcade.Window):
+
+    def __init__(self):
+        super().__init__(WIDTH_PX, HEIGHT_PX, "Press space to save a screenshot")
+
+        # Important: we have to set a non-transparent background color,
+        # or else the screenshot will have a transparent background.
+        self.background_color = arcade.color.AMAZON
+
+        # Randomize circle sprite positions, sizes, and colors
+        self.sprites = arcade.SpriteList()
+        for i in range(NUM_SPRITES):
+            sprite = arcade.SpriteCircle(
+                random.randint(MIN_RADIUS_PX, MAX_RADIUS_PX),
+                Color.random(a=255)
+            )
+            sprite.position = (
+                random.uniform(0, self.width),
+                random.uniform(0, self.height)
+            )
+            self.sprites.append(sprite)
+
+    def on_draw(self):
+        self.clear()
+        self.sprites.draw()
+
+    def on_key_press(self, key, modifiers):
+        if key == arcade.key.SPACE:
+            arcade.save_screenshot(SCREENSHOT_FILE_NAME)
+            # You can also use the format below instead.
+            # self.save_screenshot(SCREENSHOT_FILE_NAME)
+
+
+if __name__ == "__main__":
+    window = ScreenshotWindow()
+    arcade.run()

arcade/types.py

@@ -19,7 +19,8 @@
     Tuple,
     Union,
     TYPE_CHECKING,
-    TypeVar
+    TypeVar,
+    Protocol
 )
 from typing_extensions import Self
 
@@ -496,6 +497,27 @@ class TiledObject(NamedTuple):
     type: Optional[str] = None
 
 
+class HasStrftime(Protocol):
+    """Marks :ref:`datetime-like <strftime-strptime-behavior>` behavior.
+
+    Ideally, this will be one of the
+    :ref:`improved replacements <debug-better-datettime>` for :py:mod:`datetime`.
+    """
+
+    def strftime(self, format: str) -> str:
+        """Uses a C89 format string to format datetime-like data.
+
+        To learn more, see:
+
+        * :ref:`debug-better-datetime`
+        * The Python documentation's guide to :external:ref:`strftime-strptime-behavior`
+
+        :param format: A valid format string.
+        :return: The object's data as a formatter string.
+        """
+        ...
+
+
 if sys.version_info >= (3, 12):
     from collections.abc import Buffer as BufferProtocol
 else:

arcade/window_commands.py

@@ -9,12 +9,13 @@
 import os
 
 import pyglet
-
+from pathlib import Path
 from typing import (
     Callable,
     Optional,
     Tuple,
-    TYPE_CHECKING
+    TYPE_CHECKING,
+    Union
 )
 from arcade.types import RGBA255, Color
 
@@ -36,7 +37,8 @@
     "set_background_color",
     "schedule",
     "unschedule",
-    "schedule_once"
+    "schedule_once",
+    "save_screenshot"
 ]
 
 
@@ -302,3 +304,29 @@ def some_action(delta_time):
     :param delay: Delay in seconds
     """
     pyglet.clock.schedule_once(function_pointer, delay)
+
+
+def save_screenshot(
+    path: Union[ Path, str],
+    format: Optional[str] = None,
+    **kwargs
+) -> None:
+    """Save a screenshot to a specified file name.
+
+    .. warning:: This may overwrite existing files!
+
+    .. code-block:: python
+
+       # By default, the image format is detected from the
+       # file extension on the path you pass.
+       window_instance.save_screenshot("screenshot.png")
+
+    This works identically to
+    :py:meth:`Window.save_screenshot <arcade.Window.save_screenshot>`
+
+    :param path: The full path and the png image filename to save.
+    :param format: A :py:mod:`PIL` format name.
+     :param kwargs: Varies with :external+PIL:ref:`selected format <image-file-formats>`
+    """
+    window = get_window()
+    window.save_screenshot(path, format=format, **kwargs)

doc/index.rst

@@ -112,6 +112,7 @@ The Python Arcade Library
        programming_guide/texture_atlas
        programming_guide/edge_artifacts/index
        programming_guide/logging
+       programming_guide/screenshots_timestamps
        programming_guide/opengl_notes
        programming_guide/performance_tips
        programming_guide/headless

doc/programming_guide/logging.rst

@@ -7,6 +7,9 @@ Arcade has a few options to log additional information around timings and how
 things are working internally. The two major ways to do this by turning on
 logging, and by querying the OpenGL context.
 
+To export data as part of debugging rather than logging, you may want to see
+the :ref:`debug-helpers`.
+
 Turn on logging
 ---------------