SDL_WaitAndA...pchainTexture(3)

💖 SDL_WaitAndAcquireGPUSwapchainTexture — bestie edition 💖

okay so real talk, we're in the SDL3 FUNCTIONS manual, page SDL_WaitAndA...pchainTexture(3) (yes the title got truncated, the terminal did that, not me 😭), and today's main character is a function that literally just waits for you. patiently. like a good friend holding your iced coffee. 🫶

---

✨ NAME ✨

SDL_WaitAndAcquireGPUSwapchainTexture — blocks the thread until a swapchain texture is available to be acquired, and then acquires it. no cap, that's the whole vibe.

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_gpu.h>

bool SDL_WaitAndAcquireGPUSwapchainTexture(
    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 a swapchain texture gets acquired on a command buffer, it will automatically be submitted for presentation when that command buffer is submitted. like, it just happens, you don't have to do anything extra, slay.

but 💅 the swapchain texture should only be referenced by the command buffer that was used to acquire it. don't be messy about it.

🚨 it is an error to call SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired. that's not a "oops teehee" situation, that's an actual error. periodt.

this function can fill the swapchain texture handle with NULL in certain cases — for example, if the window is minimized. and bestie, listen: this is not an error. it's just a thing that happens. you should always make sure to check whether the pointer is NULL before you actually use it, because dereferencing a NULL pointer is giving 💀 energy.

the swapchain texture is managed by the implementation and must not be freed by the user. hands off, it's not yours, it's the implementation's.

and now the big one:

👑 You MUST NOT call this function from any thread other than the one that created the window. i'm so serious. this is a capital-M MUST NOT.

also the swapchain texture is write-only and cannot be used as a sampler or for another reading operation. it writes, it doesn't read. it's not a book club, it's a broadcast. 📢

---

✨ FUNCTION PARAMETERS ✨

• command_buffer — a command buffer. that's it, that's the description, she's brief and she's valid. ✨
• window — a window that has been claimed. (claim your window before you come for this function, iykyk)
• swapchain_texture — a pointer filled in with a swapchain texture handle. this is where the good stuff lands 🎀
• swapchain_texture_width — a pointer filled in with the swapchain texture width, and it may be NULL. optional queen 🌸
• swapchain_texture_height — a pointer filled in with the swapchain texture height, and it may be NULL. also optional, also valid 💜

---

✨ RETURN VALUE ✨

returns true on success, false on error. and if it's false, go call SDL_GetError() for more information — she will tell you what went wrong, she's very forthcoming like that. 🔍

---

✨ THREAD SAFETY ✨

this function should only be called from the thread that created the window. same thread, same window, no crossover episodes. 🙅‍♀️

---

✨ AVAILABILITY ✨

this function is available since SDL 3.2.0 ⭐

---

✨ SEE ALSO ✨

go read these next, they're all besties with this function:

• SDL_SubmitGPUCommandBuffer(3)
• SDL_SubmitGPUCommandBufferAndAcquireFence(3)
• SDL_AcquireGPUSwapchainTexture(3)

---

okay that's the whole page, you ate it, i'm so proud of you 🥹💖 this has been Simple Directmedia Layer, version SDL 3.4.18, page SDL_WaitAndA...pchainTexture(3) — and yes the title is still truncated, we're all just living with it. bye bestie, go check your pointers for NULL 🦋✨