From 3698630bbc8e2ac501127c9c522cc0463a6c1565 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 29 Sep 2023 15:49:24 +0100 Subject: [PATCH] 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 --- include/SDL3/SDL_pixels.h | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h index 6da0b93a8b..82d4feb338 100644 --- a/include/SDL3/SDL_pixels.h +++ b/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_