From 79119754143706b18a01d01dc7d1414d75993900 Mon Sep 17 00:00:00 2001
From: Evan Hemsley <2342303+thatcosmonaut@users.noreply.github.com>
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 6cdd8b6a39..79712e2c00 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.