New user predraw_update() function

[hx2A]

This discussion thread is to introduce a new py5 feature: a user update() function that is called before every call to draw(). I'll explain how it works and why it is useful. I'd like to hear others' thoughts on this feature and how to best explain it and introduce it to others.

Bottom line, this new feature can make small (5-10%) performance improvements in many cases. It is not a game changer, but it is a simple way to make a small improvement and will benefit someone who is attempting to performance tune a Sketch.

To begin, consider the following py5 sketch. This example draws to an oversized Py5Graphics object and then draws the Py5Graphics object to the screen. This example a bit contrived to exagerate an performance issue but for now it is useful to clearly demonstrate the performance benefit of the new update() function.

import time
import numpy as np
import py5


G_SCALE = 10
PAUSE = 0.15


def slow_function():
    # simulate a slow, complex calculation
    time.sleep(PAUSE)
    return py5.random_int(0, 255)


def setup():
    global g
    py5.size(800, 800, py5.P2D)
    py5.stroke_weight(5)
    py5.stroke(0)
    g = py5.create_graphics(G_SCALE * 750, G_SCALE * 750, py5.JAVA2D)


def draw():
    val = slow_function()

    with g.begin_draw():
        g.clear()
        g.fill(val)
        points = G_SCALE * 750 * np.random.rand(10, 2)
        with g.begin_closed_shape():
            g.vertices(points)

    py5.image(g, 25, 25, 750, 750)


py5.run_sketch()

On my old MacOS laptop, this Sketch gets about 2.5 frames per second. The giant Py5Graphics object hurts performance. Also, the 150 ms pause in slow_function() doesn't help.

Now, let's think about the draw() function. Conceptually, we think about draw() being called repeatedly, which no gap between the end of one call and the beginning of the next. However, this isn't the truth. There is a small time gap between the end of one call to draw() and the beginning of the next.

We can measure this gap with some extra code to grab some timestamps:

G_SCALE = 10
PAUSE = 0.15

idle_times = []
draw_times = []

last_time = None


def slow_function():
    # simulate a slow, complex calculation
    time.sleep(PAUSE)
    return py5.random_int(0, 255)


def setup():
    global g
    py5.size(800, 800, py5.P2D)
    py5.stroke_weight(5)
    py5.stroke(0)
    g = py5.create_graphics(G_SCALE * 750, G_SCALE * 750, py5.JAVA2D)


def draw():
    global last_time

    if last_time is None:
        last_time = time.time()
    else:
        idle_times.append((t := time.time()) - last_time)
        last_time = t

    val = slow_function()

    with g.begin_draw():
        g.clear()
        g.fill(val)
        points = G_SCALE * 750 * np.random.rand(10, 2)
        with g.begin_closed_shape():
            g.vertices(points)

    py5.image(g, 25, 25, 750, 750)

    draw_times.append((t := time.time()) - last_time)
    last_time = t


py5.run_sketch()

If I run that code for a while, I can then analyze the results:

# ignore the first few measurements
idle_times = idle_times[5:]
draw_times = draw_times[5:]

total_idle_time = sum(idle_times)
total_draw_time = sum(draw_times)
total_time = total_idle_time + total_draw_time

print(f"total time: {total_time} seconds")
print(f"frame rate: {py5.frame_count / total_time:.2f} fps")
print(f"idle time: {100 * total_idle_time / total_time:.2f}%")
print(f"draw time: {100 * total_draw_time / total_time:.2f}%")

]
Here are the results:

total time: 99.57868385314941 seconds
frame rate: 2.54 fps
idle time: 39.49%
draw time: 60.51%

These numbers are telling us that when this Sketch is running, 60% of the time is spent in the draw() function, and 40% of the time is spent in the time gap between the end of one call to draw() and the beginning of the next.

I do want to make it clear that these numbers are not typical. For a more typical Sketch, 85-90% of the time is spent in draw() and 10-15% of the time is spent in the time gap between the end of one call to draw() and the beginning of the next call to draw(). This example is contrived to exagerate the time gap. I happen to know that Processing does a lot of work on our behalf to prepare the large Py5Graphics object to be used as a texture, and that work has a cost. This work is done after the draw() function completes. Processing always does some work for us after the draw() function completes, but in this case the work is more expensive than usual.

Now here's the key point: because of the Python + Java design of py5, during that gap, the Python interpreter is idle. The purpose of the new update() function is to give the user an opportunity run code during the time between calls to draw() that the Python interpreter would otherwise be idle.

Let's ignore the contrived nature of this Sketch and think about how we can use the new update() function to improve performance. The update() function is guaranteed to complete before each call to draw(). You can't draw anything to the screen in this update() function, similar to the limitations of the mouse and key event functions such as mouse_pressed() and key_pressed(). However, you can do other things, such as prepare data for the next call to draw(). For our example, let's move slow_function() to the update() function.

G_SCALE = 10
PAUSE = 0.15

idle_times = []
draw_times = []

last_time = None


def slow_function():
    # simulate a slow, complex calculation
    time.sleep(PAUSE)
    return py5.random_int(0, 255)


def setup():
    global g
    py5.size(800, 800, py5.P2D)
    py5.stroke_weight(5)
    py5.stroke(0)
    g = py5.create_graphics(G_SCALE * 750, G_SCALE * 750, py5.JAVA2D)


def update():
    global val
    val = slow_function()


def draw():
    global last_time

    if last_time is None:
        last_time = time.time()
    else:
        idle_times.append((t := time.time()) - last_time)
        last_time = t

    with g.begin_draw():
        g.clear()
        g.fill(val)
        points = G_SCALE * 750 * np.random.rand(10, 2)
        with g.begin_closed_shape():
            g.vertices(points)

    py5.image(g, 25, 25, 750, 750)

    draw_times.append((t := time.time()) - last_time)
    last_time = t


py5.run_sketch()

How did the measurements change?

total time: 73.46133828163147 seconds
frame rate: 3.57 fps
idle time: 56.77%
draw time: 43.23%

Now the Sketch has a frame rate of 3.57 fps, which is a ~41% improvement over the version without update().

This 41% performance improvement is not typical. The reason why it helped so much is because for this Sketch the idle time between calls to draw() was so large. That excessive idle time left a lot of room for improvement. Normally the idle time would be much smaller, perhaps around 10-15%. For those Sketches, the frame rate could improve by maybe 5-10%.

Is this new feature something to get excited about? No. It isn't going to magically turn a slow Sketch into a fast Sketch. And for many use cases, a 5-10% improvement isn't worth the bother. However, someone who is performance tuning a Sketch will typically make a lot of small improvements that add up to a big improvement. This new update() function is a quick way to provide one of those small improvements.

Is this a feature you'd want to teach to beginner coders? No. I recall @villares has talked about the "cognitive load" of beginners and adding a new function to the mix only complicates things for learners. I agree with that. Not everyone cares about a 5-10% performance improvement, and that's fine.

Note the update() function could be added to Processing or perhaps even p5. I did notice there is a request for new feature proposals for p5 2.0. I don't think this would add as much value to p5 or Processing because neither has the dual-language design of py5. In py5, Python interpreter just doesn't compete with the Java Virtual Machine for execution resources. This contrasts with a p5 Sketch, where the user code and the p5 library run along side each other in the browser. However, I could be wrong, and it could help. It would be interesting to measure the idle time in a p5 Sketch and see if there is a similar opportunity for improvement. If someone would like to work with me on that, let me know.

[villares]

Looks very interesting!
I wonder if can apply this to some slow flocking & particle simulations I have been playing with.

Another thing, unrelated to this feature I guess, but simulation performance related, is that I'm unsure I'm making good use of the Py5Shape object .set_strokes() & .set_fills methods. I should open a discussion about it with my code when I get the chance...

[hx2A]

I wonder if can apply this to some slow flocking & particle simulations I have been playing with.

Yes, it would be a good fit for something like that if you can easily separate it from the drawing stuff. It will be a small improvement but it is an easy change to make.

I'm unsure I'm making good use of the Py5Shape object .set_strokes() & .set_fills methods.

Sure, start a thread about this! Those two methods were created mainly because the trimesh integration code needed them to exist for that code to be efficient. I haven't used them anywhere else.

[villares]

Something to think about... isn't update() maybe a common name for user functions, wouldn't it trip people adding it without being aware of the feature? Could we find perhaps something less likely to to be used accidentally? How about predraw_update() ? Another thing would be a warning if you call yourself the feature-function.

[hx2A]

Something to think about... isn't update() maybe a common name for user functions, wouldn't it trip people adding it without being aware of the feature? Could we find perhaps something less likely to to be used accidentally? How about predraw_update() ? Another thing would be a warning if you call yourself the feature-function.

Hmmm, good point. I can't think of a reasonable way to issue such a warning, and since update() is a common name for user functions, I don't want to create a conflict with this like what we previously had with g as the graphics object and not the commonly used variable for green values. I like your name predraw_update(), especially because what it is and how it works is built into the name. I'll use that name instead of update().

[hx2A]

Just renamed it. Thanks, @villares , for the thoughtful feedback!

[JulienBacquart]

Something to think about... isn't update() maybe a common name for user functions, wouldn't it trip people adding it without being aware of the feature? Could we find perhaps something less likely to to be used accidentally? How about predraw_update() ? Another thing would be a warning if you call yourself the feature-function.

I personally like the idea of the "update" name, it seems to be a pretty common pattern that when you write a small simulation, for example several bouncing balls, to end up with something like:

def draw():
    for ball in list_ball:
        ball.update()
        ball.draw()

So it would seem pretty natural to me to do something like that:

def update():
    for ball in list_ball:
        ball.update()

def draw():
    for ball in list_ball:
        ball.draw()

But I don't know if the performance boost from using the update function would make up for the performance hit of iterating two time on the list.

I'm more wondering about the case where the simulation is time dependent and you use a deltatime in your update, would it lead to weird cases ?
For example, let's say you have a simulation that is trivial and run at unlimited fps, but is limited to 60 FPS by py5.
If I understand right, right now the execution would look something like:

call to draw() where you update your simulation with deltatime = 0ms
wait 16ms ...
call to draw() where you update your simulation with deltatime = 16ms
wait 16ms ...
call to draw() where you update your simulation with deltatime = 16ms
...

But then you decide to implement your simulation with the new update function, would you end up with something like this ?

call to update() where you update your simulation with deltatime = 0ms
call to draw()
call to update() where you update your simulation with deltatime = 1ms
wait 15ms ...
call to draw()
call to update() where you update your simulation with deltatime = 16ms
wait 15ms ...
call to draw()
call to update() where you update your simulation with deltatime = 16ms
...

That would probably not be noticeable, but might be weird to understand what is happening. I am missing something ?

[villares]

The problem would be that a beginner would create an update() function, and, unaware of this advanced feature, would call update() themselves and it would be executed more than once without them understanding what was going on... that's why I like the proposal of a more unusual name.

[hx2A]

Hi @JulienBacquart ! Thank you for your thoughts.

I personally like the idea of the "update" name, it seems to be a pretty common pattern that when you write a small simulation,

Right, it is pretty common and it was my first thought for what to name this, but I agree with @villares 's thought that it might be too common and collide with functions meant for other purposes.

For example, there are cases where it could lead to some confusion by users who didn't know about the feature. For example, let's say you wrote a function to update something in your sketch and it had this signature:

def update(foo, bar):
    # do something
    ...

py5 would know to ignore this function because it would see the two parameters. Then let's say you modified your code to remove the two parameters because you decide foo and bar are no longer necessary. After you do that, py5 would start calling your update() function, thinking that you want that to run before draw(). This would be a confusing and hard to debug problem, particularly for someone new at coding. To avoid giving someone this headache, we can name it something else.

Perhaps you could make the same argument about setup() and draw(), but everyone knows about these already so it seems unlikely that anybody would make a similar mistake with them. Since this is a new feature, it is best to avoid tripping anyone up over it.

Also, this problem could also emerge if someone already had an update() function in their Sketch and then installs the new version of py5 that supports this feature. Then the Sketch would start behaving differently and it would be confusing as to why. This scenario is probably more likely than when I describe above.

Another benefit of the predraw_update() name is that what the function is and when it is called is built into the name.

But I don't know if the performance boost from using the update function would make up for the performance hit of iterating two time on the list.

Yes, two iterations through a list might have a negative performance impact if the list was large and the update code was very fast. This might be the case for a particle simulation, for example. For other use cases, when the list is smaller and the update code is slow, this feature would add value. When I document this I'll make sure to mention that this feature most helpful when the update code is slow relative to the time for iterating through objects, etc.

I'm more wondering about the case where the simulation is time dependent and you use a deltatime in your update, would it lead to weird cases ?

Interesting, I had not thought of this. I can see how this would be the case for someone working with live audio, for example.

I would need to double-check if what I am about to say is exactly true, but from what I recall about calls to draw(), the time it is called is at specific intervals for the OpenGL renderers P2D and P3D because it is driven by the animation thread. For the default renderer, the exact time the draw() function is called is less structured because of how that renderer manages the frame rate. For the default renderer, the time of the calls to draw() are not at reliable intervals but will average out to whatever it needs to be for the desired frame rate.

If the user is using the default renderer they wouldn't be really losing any simulation accuracy because the exact time the draw() function was getting called wasn't that precise to begin with. For the OpenGL renderers it would be off by a few milliseconds, and if that difference matters to someone, they could add an offset to adjust, or maybe this feature isn't right for what they are trying to do.

In any case, the time issue you brought up should be included in the documentation of predraw_update() so folks can evaluate it as they decide if using this extra function would work for them.

@JulienBacquart , thanks for your thoughts and bringing up issues that should be included in the documentation so people can make best use of this for their coding projects!