pixels: Document the naming convention

Whenever I have to fix something endianness-related, I always get
confused about whether the byte-oriented format that guarantees to put
red in byte 0 is RGBA8888 or RGBA32. (The answer is that it's RGBA32.)

Signed-off-by: Simon McVittie <smcv@collabora.com>

include/SDL3/SDL_pixels.h

@@ -23,6 +23,42 @@
  *  \file SDL_pixels.h
  *
  *  \brief Header for the enumerated pixel format definitions.
+ *
+ *  SDL's pixel formats have the following naming convention:
+ *
+ *      * Names with a list of components and a single bit count, such as
+ *        RGB24 and ABGR32, define a platform-independent encoding into
+ *        bytes in the order specified. For example, in RGB24 data, each
+ *        pixel is encoded in 3 bytes (red, green, blue) in that order,
+ *        and in ABGR32 data, each pixel is encoded in 4 bytes
+ *        (alpha, blue, green, red) in that order. Use these names if the
+ *        property of a format that is important to you is the order of
+ *        the bytes in memory or on disk.
+ *
+ *      * Names with a bit count per component, such as ARGB8888 and
+ *        XRGB1555, are "packed" into an appropriately-sized integer in
+ *        the platform's native endianness. For example, ARGB8888 is
+ *        a sequence of 32-bit integers; in each integer, the most
+ *        significant bits are alpha, and the least significant bits are
+ *        blue. On a little-endian CPU such as x86, the least significant
+ *        bits of each integer are arranged first in memory, but on a
+ *        big-endian CPU such as s390x, the most significant bits are
+ *        arranged first. Use these names if the property of a format that
+ *        is important to you is the meaning of each bit position within a
+ *        native-endianness integer.
+ *
+ *      * In indexed formats such as INDEX4LSB, each pixel is represented
+ *        by encoding an index into the palette into the indicated number
+ *        of bits, with multiple pixels packed into each byte if appropriate.
+ *        In LSB formats, the first (leftmost) pixel is stored in the
+ *        least-significant bits of the byte; in MSB formats, it's stored
+ *        in the most-significant bits. INDEX8 does not need LSB/MSB
+ *        variants, because each pixel exactly fills one byte.
+ *
+ *  The 32-bit byte-array encodings such as RGBA32 are aliases for the
+ *  appropriate 8888 encoding for the current platform. For example,
+ *  RGBA32 is an alias for ABGR8888 on little-endian CPUs like x86,
+ *  or an alias for RGBA8888 on big-endian CPUs.
  */
 
 #ifndef SDL_pixels_h_