From 29df99ee388b427c6e747a817facbac5922bc57a Mon Sep 17 00:00:00 2001 From: Sam Lantinga Date: Tue, 25 Feb 2025 10:25:17 -0800 Subject: [PATCH] Clarified SDL_RenderReadPixels() documentation Clarified that the rect to be read is clipped against the current viewport, not actually relative to it. Also added a note for people using SDL_SetRenderLogicalPresentation() so they know they have to map between logical space and render space if they want to read back. --- include/SDL3/SDL_render.h | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h index 891e994524..2998ddbb94 100644 --- a/include/SDL3/SDL_render.h +++ b/include/SDL3/SDL_render.h @@ -2247,15 +2247,17 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, /** * Read pixels from the current rendering target. * - * The returned surface should be freed with SDL_DestroySurface() + * The returned surface contains pixels inside the desired area clipped to the current viewport, and should be freed with SDL_DestroySurface(). + * + * Note that this returns the actual pixels on the screen, so if you are using logical presentation you should use SDL_GetRenderLogicalPresentationRect() to get the area containing your content. * * **WARNING**: This is a very slow operation, and should not be used * frequently. If you're using this on the main rendering target, it should be * called after rendering and before SDL_RenderPresent(). * * \param renderer the rendering context. - * \param rect an SDL_Rect structure representing the area in pixels relative - * to the to current viewport, or NULL for the entire viewport. + * \param rect an SDL_Rect structure representing the area to read, which will be clipped to the current viewport, + * or NULL for the entire viewport. * \returns a new SDL_Surface on success or NULL on failure; call * SDL_GetError() for more information. *