From 79119754143706b18a01d01dc7d1414d75993900 Mon Sep 17 00:00:00 2001
From: Evan Hemsley <[EMAIL REDACTED]>
Date: Wed, 27 May 2026 16:34:48 -0700
Subject: [PATCH] GPU: Clarify some presentation concerns in docs (#15707)
---
include/SDL3/SDL_gpu.h | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h
index 6cdd8b6a39779..79712e2c004f2 100644
--- a/include/SDL3/SDL_gpu.h
+++ b/include/SDL3/SDL_gpu.h
@@ -4232,10 +4232,12 @@ extern SDL_DECLSPEC SDL_GPUTextureFormat SDLCALL SDL_GetGPUSwapchainTextureForma
* 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
+ * If too many frames are in flight, this function will fill the swapchain texture handle
+ * with NULL and return true. 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.
+ * wait.
+ *
+ * In VSYNC present mode (which is the default) this function may block on vblank.
*
* 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
@@ -4280,7 +4282,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AcquireGPUSwapchainTexture(
Uint32 *swapchain_texture_height);
/**
- * Blocks the thread until a swapchain texture is available to be acquired.
+ * Blocks the thread until all presenting command buffers are finished executing.
*
* \param device a GPU context.
* \param window a window that has been claimed.