GPU: device & frameSDL 3.2

SDL_WaitAndAcquireGPUSwapchainTexture

Gets this frame's window image to draw into, waiting if all of them are still busy.

Signature

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

How it works

The texture you get is the window's next image. Use it as a render pass color target; when the command buffer is submitted, SDL presents it.

Two different outcomes need two checks. false is a real error. true with a NULL texture is NOT an error: it happens when the window is minimized, and simply means "nothing to draw this frame". Submit the command buffer anyway and skip the drawing.

Parameters

command_bufferSDL_GPUCommandBuffer *

This frame's command buffer.

windowSDL_Window *

A window claimed with SDL_ClaimWindowForGPUDevice.

swapchain_textureSDL_GPUTexture **

Receives the texture, or NULL when there is nothing to draw to.

swapchain_texture_widthUint32 *

Receives its width in pixels, or NULL.

swapchain_texture_heightUint32 *

Receives its height in pixels, or NULL.

Return value

true on success (the texture may still be NULL), false on error.

Tips & pitfalls

Do not release the swapchain texture: it belongs to the window.

Example

example.cpp

1SDL_GPUTexture* swapchain = nullptr;
2Uint32 w = 0, h = 0;
3if (!SDL_WaitAndAcquireGPUSwapchainTexture(cmd, window, &swapchain, &w, &h)) {
4    SDL_Log("acquire: %s", SDL_GetError());       // real error
5    SDL_CancelGPUCommandBuffer(cmd);
6    return;
7}
8if (!swapchain) {                                  // minimized: not an error
9    SDL_SubmitGPUCommandBuffer(cmd);
10    return;
11}

Official SDL wiki