SDL_AcquireGPUSwapchainTexture(3)

NAME
SDL_AcquireGPUSwapchainTexture - Acquire a texture to use in presentation.

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
When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it.

This function will fill the swapchain texture handle with NULL if too many frames are in flight. This is not an error. This NULL pointer should not be passed back into SDL. Instead, it should be considered as an indication to wait until the swapchain is available.

If you use this function, it is possible to create a situation where many command buffers are allocated while the rendering context waits for the GPU to catch up, which will cause memory usage to grow. You should use SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing with timing.

The swapchain texture is managed by the implementation and must not be freed by the user. You MUST NOT call this function from any thread other than the one that created the window.

FUNCTION PARAMETERS

command_buffer
    a command buffer.

window
    a window that has been claimed.

swapchain_texture
    a pointer filled in with a swapchain texture handle.

swapchain_texture_width
    a pointer filled in with the swapchain texture width, may be NULL.

swapchain_texture_height
    a pointer filled in with the swapchain texture height, may be NULL.

RETURN VALUE
Returns true on success, false on error; call SDL_GetError() for more information.

THREAD SAFETY
This function should only be called from the thread that created the window.

AVAILABILITY
This function is available since SDL 3.2.0.

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)