render_frame()

Helper function to render a single frame using the passed draw function argument.

Examples

1
2
3
4
5
6
7
8
def draw_message(s: py5.Sketch):
    s.background(255)
    s.fill(255, 0, 0)
    s.text_size(20)
    s.text_align(s.CENTER, s.CENTER)
    s.text('hello world', s.width/2, s.height/2)

frame = py5.render_frame(draw_message, 400, 200)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
def draw_message(s: py5.Sketch, message='hello world', color=(255, 0, 0)):
    s.background(255)
    s.fill(*color)
    s.text_size(20)
    s.text_align(s.CENTER, s.CENTER)
    s.text(message, s.width/2, s.height/2)

frame = py5.render_frame(draw_message, 400, 200, py5.P2D,
                         draw_args=('I LIKE ORANGE THINGS',),
                         draw_kwargs=dict(color=(255, 128, 0)))
1
2
3
4
5
def random_squares(g: py5.Py5Graphics):
    for _ in range(10):
        g.rect(np.random.randint(g.width), np.random.randint(g.height), 10, 10)

frame = py5.render_frame(random_squares, 100, 100, use_py5graphics=True)

Description

Helper function to render a single frame using the passed draw function argument. The output is returned as a PIL.Image object.

The passed function’s first parameter must be either a py5.Sketch object or a py5.Py5Graphics object, depending on the parameter use_py5graphics. That object must be used for all of the function’s py5 commands. The function can have additional positional and keyword arguments. To use them, pass the desired values as render_frame’s draw_args and draw_kwargs arguments.

On OSX, only the default renderer is currently supported. Other platforms support the default renderer and the OpenGL renderers (P2D and P3D).

The rendered frame can have transparent pixels if and only if the use_py5graphics parameter is True because only a py5.Py5Graphics object can create an image with transparency. There is no need to call Py5Graphics.begin_draw() or Py5Graphics.end_draw() in the passed function as render_frame() does that for you.

This function facilitates the creation and execution of a py5 Sketch, and as a result makes it easy to run a Sketch inside of another Sketch. This is discouraged, and may fail catastrophically.

This function is available in decorator form as @render().

Syntax

render_frame(draw: Callable, width: int, height: int, renderer: str = Sketch.HIDDEN, *, draw_args: Tuple = None, draw_kwargs: Dict = None, use_py5graphics: bool = False) -> Image

Parameters

  • draw: Callable - function that executes py5 draw commands

  • draw_args: Tuple = None - additional positional arguments to pass to draw function

  • draw_kwargs: Dict = None - additional keyword arguments to pass to draw function

  • height: int - height of the display window in units of pixels

  • renderer: str = Sketch.HIDDEN - rendering engine to use

  • use_py5graphics: bool = False - pass a py5graphics object instead of a sketch object

  • width: int - width of the display window in units of pixels

Updated on September 11, 2021 16:51:34pm UTC