From d88bf687a8b2825bfb81fa253e30e2fde60b7bf7 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 29 Sep 2023 15:54:32 +0100 Subject: [PATCH] surface: Document the in-memory layout of the pixels I don't think we ever explicitly said this. Signed-off-by: Simon McVittie --- include/SDL3/SDL_surface.h | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h index bdba4d07f..6bf4b1d94 100644 --- a/include/SDL3/SDL_surface.h +++ b/include/SDL3/SDL_surface.h @@ -66,8 +66,22 @@ typedef struct SDL_BlitMap SDL_BlitMap; /* this is an opaque type. */ /** * \brief A collection of pixels used in software blitting. * + * Pixels are arranged in memory in rows, with the top row first. + * Each row occupies an amount of memory given by the pitch (sometimes + * known as the row stride in non-SDL APIs). + * + * Within each row, pixels are arranged from left to right until the + * width is reached. + * Each pixel occupies a number of bits appropriate for its format, with + * most formats representing each pixel as one or more whole bytes + * (in some indexed formats, instead multiple pixels are packed into + * each byte), and a byte order given by the format. + * After encoding all pixels, any remaining bytes to reach the pitch are + * used as padding to reach a desired alignment, and have undefined contents. + * * \note This structure should be treated as read-only, except for \c pixels, * which, if not NULL, contains the raw pixel data for the surface. + * \sa SDL_CreateSurfaceFrom */ typedef struct SDL_Surface {