diff --git a/include/SDL_video.h b/include/SDL_video.h
index fa47d30991..b0d7598985 100644
--- a/include/SDL_video.h
+++ b/include/SDL_video.h
@@ -1297,6 +1297,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasWindowSurface(SDL_Window *window);
  * This surface will be invalidated if the window is resized. After resizing a
  * window this function must be called again to return a valid surface.
  *
+ * Note that on some platforms the pixels pointer of the surface may be
+ * modified after each call to SDL_UpdateWindowSurface(), so that the platform
+ * code can implement efficient double or triple buffering.
+ *
  * You may not combine this with 3D or the rendering API on this window.
  *
  * This function is affected by `SDL_HINT_FRAMEBUFFER_ACCELERATION`.