surface: Document the in-memory layout of the pixels

I don't think we ever explicitly said this.

Signed-off-by: Simon McVittie <[email protected]>

Author: smcv

Diff for: 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
 {