Quick answer: Pygame display.toggle_fullscreen() losing surface state, dimming, or breaking the GL context? Behavior is SDL-version-dependent; prefer set_mode with FULLSCREEN flag for reliability.

A game offers a fullscreen toggle in settings. On Linux, toggling produces a black screen until alt-tab; on Windows, surfaces stop accepting blits.

Recreate via set_mode

flags = pygame.FULLSCREEN if wants_full else 0
screen = pygame.display.set_mode(size, flags)

Tears down and recreates the display. All blits / draws continue from the new surface. Slower than toggle but consistent across platforms.

Reload Sprite Surfaces

Some Pygame versions invalidate converted surfaces on display recreation. Reload key textures (or convert again) after the swap.

Borderless Fullscreen

Alternative: SCALED | FULLSCREEN for borderless. Less disruptive than exclusive fullscreen, alt-tab friendly.

OpenGL Context

If using PyOpenGL, set_mode with OPENGL flag tears down and recreates the GL context. Re-upload textures, recompile shaders.

Verifying

Toggling fullscreen and back works reliably. Surfaces continue to render; alt-tab returns the game cleanly.

“set_mode is reliable; toggle_fullscreen is SDL-version-dependent.”

Borderless fullscreen is the “just works” choice for modern games — exclusive fullscreen has alt-tab issues across desktops.