I've read a little about surface locking and unlocking in pygame in Beginning Game Development with Python and Pygame. However, I still don't understand it.

I've read that it can improve the game performance, so I'm wondering about its other advantages.

So overall, what are the main uses of surface locking and unlocking ?

How does it improve performance ?

Is it necessary to lock and unlock the screen everytime I blit an image into it ?


Here is a part of the passage that I read in that book :

Whenever Pygame draws onto a surface, it first has to be locked. When a surface is locked, Pygame has full control over the surface and no other process on the computer can use it until it is unlocked. Locking and unlocking happens automatically whenever you draw onto a surface, but it can become inefficient if Pygame has too many locks and unlocks.


I'm mostly wondering about manual locks and unlocks and not just about automatic ones and btw to lock and unlock a surface manually, all is needed is :

# applying some changes to that surface

1 Answer 1


Surface locking allows you to directly access the pixel data of accelerated surfaces. It's not so much about improving performance. Rather, an accelerated surface already has performance improvements, but it comes with a trade off of requiring locking & unlocking if you're going to directly change its data.

All of the built in Pygame functions will automatically lock and unlock the Surface data as needed. So for basic blitting, you don't need to worry about it.

When might you need it? Let's say you had some code that required multiple get_at() &/or set_at() calls. Each such call requires locking & unlocking the surface & according to the docs:

Getting and setting pixels one at a time is generally too slow to be used in a game or realtime situation.

In that situation, it would likely be more performant to lock the surface once, perform any required reads & writes to the pixel data and then unlock it.

Here's what the the docs say about locking:

On accelerated Surfaces, the pixel data may be stored in volatile video memory or nonlinear compressed forms. When a Surface is locked the pixel memory becomes available to access by regular software. Code that reads or writes pixel values will need the Surface to be locked.

Surfaces should not remain locked for more than necessary. A locked Surface can often not be displayed or managed by pygame.

Not all Surfaces require locking. The mustlock() method can determine if it is actually required. There is no performance penalty for locking and unlocking a Surface that does not need it.

All pygame functions will automatically lock and unlock the Surface data as needed. If a section of code is going to make calls that will repeatedly lock and unlock the Surface many times, it can be helpful to wrap the block inside a lock and unlock pair.

It is safe to nest locking and unlocking calls. The surface will only be unlocked after the final lock is released.

  • \$\begingroup\$ thanks a lot , I finally understood locking and unlocking ! \$\endgroup\$
    – Salem
    Jul 18, 2021 at 17:33

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .