SDL: surface: Document the in-memory layout of the pixels

From d88bf687a8b2825bfb81fa253e30e2fde60b7bf7 Mon Sep 17 00:00:00 2001
From: Simon McVittie <[EMAIL REDACTED]>
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 <smcv@collabora.com>
---
 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 bdba4d07f3f2..6bf4b1d94c8b 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
 {