SDL_ACQUIREGPUSWAPCHAINTEXTURE(3)

💖 SDL_AcquireGPUSwapchainTexture(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where we're gonna talk about getting yourself a swapchain texture so your lil' rendering vibes can actually show up on screen. no cap, this one's a banger. 🎀

---

✨ NAME ✨

SDL_AcquireGPUSwapchainTexture — grab a texture to use for presentation. that's it, that's the whole job. 💅

---

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_gpu.h>

bool SDL_AcquireGPUSwapchainTexture(
    SDL_GPUCommandBuffer *command_buffer,
    SDL_Window *window,
    SDL_GPUTexture **swapchain_texture,
    Uint32 *swapchain_texture_width,
    Uint32 *swapchain_texture_height);

---

🌸 DESCRIPTION 🌸

so here's the tea. when you acquire a swapchain texture on a command buffer, it gets automatically submitted for presentation the moment that command buffer is submitted. no extra steps, it just happens. and the swapchain texture should only be referenced by the command buffer you used to acquire it — like, that's its one friend group, don't be messy about it.

now the important part, and ngl this trips people up: this function will fill the swapchain texture handle with NULL if too many frames are in flight. that is not an error, bestie, breathe. but you must NOT pass that NULL pointer back into SDL. instead, treat it as the universe telling you to chill and wait until the swapchain is available. 🧘

if you use this function, you can lowkey create a situation where tons of command buffers get allocated while the rendering context is just sitting there waiting for the GPU to catch up — and that makes memory usage grow. like, it grows-grows. so unless you genuinely know what you're doing with timing, you should use SDL_WaitAndAcquireGPUSwapchainTexture() instead. fr fr.

also: the swapchain texture is managed by the implementation and must not be freed by the user. not your texture, not your problem. and you MUST NOT call this function from any thread other than the one that created the window. periodt. 👑

---

🎀 FUNCTION PARAMETERS 🎀

• command_buffer — a command buffer. iconic, we love her.
• window — a window that has been claimed. claimed, babes. don't show up with an unclaimed window.
• swapchain_texture — a pointer that gets filled in with a swapchain texture handle.
• swapchain_texture_width — a pointer that gets filled in with the swapchain texture width. may be NULL.
• swapchain_texture_height — a pointer that gets filled in with the swapchain texture height. may be NULL.

---

⭐ RETURN VALUE ⭐

returns true on success, false on error. if it's a false, go call SDL_GetError() for the deets. she'll tell you what went wrong. 🫶

---

💜 THREAD SAFETY 💜

this function should only be called from the thread that created the window. same thread, bestie. don't be out here threading wild. 🚫🧵

---

🌈 AVAILABILITY 🌈

this function has been available since SDL 3.2.0. she's been around. she's established. 👑

---

🔥 SEE ALSO 🔥

• SDL_ClaimWindowForGPUDevice(3)
• SDL_SubmitGPUCommandBuffer(3)
• SDL_SubmitGPUCommandBufferAndAcquireFence(3)
• SDL_CancelGPUCommandBuffer(3)
• SDL_GetWindowSizeInPixels(3)
• SDL_WaitForGPUSwapchain(3)
• SDL_WaitAndAcquireGPUSwapchainTexture(3)
• SDL_SetGPUAllowedFramesInFlight(3)

---

and that's the whole page, bestie!! brought to you by Simple Directmedia Layer, SDL 3.4.18, and the one and only SDL_AcquireGP...pchainTexture(3). go forth and acquire those swapchains responsibly. mwah. 💖✨🎀🦋🌸💅