Why SDL_UpdateWindowSurface() Instead of SDL_SwapBuffers()?

While the effect of SDL_UpdateWindowSurface() in a typical double-buffered scenario is to make the newly drawn frame visible, its name reflects what it fundamentally does from the perspective of the SDL surface API.

When you work with SDL_Surface obtained via SDL_GetWindowSurface(), you're manipulating a block of pixel data in CPU memory. This surface represents the content you want the window to display.

The function SDL_UpdateWindowSurface() takes this CPU-side pixel data and copies it to the actual window managed by the operating system and graphics drivers. This "update" operation makes the content visible.

Why Not SDL_SwapBuffers()?

The term "Swap Buffers" usually implies a very specific mechanism often used in hardware-accelerated graphics (like OpenGL or DirectX, which SDL's Renderer API wraps). In those contexts, "swapping" often means telling the graphics card to simply change which memory buffer is being scanned out to the monitor - a potentially very fast operation, like changing a pointer.

SDL_UpdateWindowSurface(), however, guarantees a copy of the pixel data from your SDL_Surface to the window's display area. The underlying system might use double buffering internally to make this smooth, but the SDL API call itself is primarily concerned with getting your surface data onto the screen.

Consider these points:

• Abstraction: SDL aims to provide a consistent API across different platforms (Windows, macOS, Linux). The underlying mechanism for updating the window might differ significantly between them. SDL_UpdateWindowSurface() provides a platform-agnostic way to say "make this surface visible in the window".
• CPU Focus: The SDL_Surface API is primarily CPU-based. The function emphasizes updating the window with the surface data you've prepared on the CPU.
• Contrast with Renderer: SDL's SDL_Renderer API, which uses hardware acceleration, has a function called SDL_RenderPresent(). This name is closer to the concept of presenting a completed (back) buffer, which often does involve a true buffer swap on the GPU.

So, SDL_UpdateWindowSurface() is named for its core action within the surface API: updating the visible window content from a specific SDL_Surface in CPU memory. While it facilitates the effect of double buffering, it doesn't necessarily perform a low-level "buffer swap" in the hardware sense.