docs: Fix RGB565 format documentation and bit masks (#57210)
The RGB565 format documentation in embedder.h incorrectly stated that the red component uses the least significant bits. Unit tests in embedder/testdefs/embedder_unittests.cc demonstrate this is incorrect, showing:
- Red test (0xF800): Uses bits [15:11]
- Green test (0x07E0): Uses bits [10:5]
- Blue test (0x001F): Uses bits [4:0]
This commit fixes the documentation to correctly reflect the actual bit layout:
- Red uses 5 MSBs [15:11]
- Green uses 6 middle bits [10:5]
- Blue uses 5 LSBs [4:0]
Also fixes the example bit extraction code to use correct masks, matching the test expectations.
Impact: This change helps prevent potential developer confusion about RGB565 bit ordering and ensures the documentation matches the actual implementation as verified by the test suite.
diff --git a/shell/platform/embedder/embedder.h b/shell/platform/embedder/embedder.h
index 8ca4742..4b880a6 100644
--- a/shell/platform/embedder/embedder.h
+++ b/shell/platform/embedder/embedder.h
@@ -327,9 +327,10 @@
/// occupying the lowest memory address.
///
/// - all other formats are called packed formats, and the component order
-/// as specified in the format name refers to the order in the native type.
-/// for example, for kFlutterSoftwarePixelFormatRGB565, the R component
-/// uses the 5 least significant bits of the uint16_t pixel value.
+/// as specified in the format name refers to the order from most
+/// significant to least significant bits in the native type. for example,
+/// for kFlutterSoftwarePixelFormatRGB565, R occupies the 5 most significant
+/// bits, G the middle 6 bits, and B the 5 least significant bits.
///
/// Each pixel format in this list is documented with an example on how to get
/// the color components from the pixel.
@@ -342,33 +343,46 @@
/// can get the p for a RGBA8888 formatted buffer like this:
/// const uint8_t *p = ((const uint8_t*) allocation) + row_bytes*y + x*4;
typedef enum {
- /// pixel with 8 bit grayscale value.
+ /// Pixel with 8 bit grayscale value.
/// The grayscale value is the luma value calculated from r, g, b
/// according to BT.709. (gray = r*0.2126 + g*0.7152 + b*0.0722)
kFlutterSoftwarePixelFormatGray8,
- /// pixel with 5 bits red, 6 bits green, 5 bits blue, in 16-bit word.
- /// r = p & 0x3F; g = (p>>5) & 0x3F; b = p>>11;
+ /// Pixel with 5 bits red, 6 bits green, 5 bits blue, in 16-bit word.
+ /// r = (p >> 11) & 0x1F;
+ /// g = (p >> 5) & 0x3F;
+ /// b = p & 0x1F;
kFlutterSoftwarePixelFormatRGB565,
- /// pixel with 4 bits for alpha, red, green, blue; in 16-bit word.
- /// r = p & 0xF; g = (p>>4) & 0xF; b = (p>>8) & 0xF; a = p>>12;
+ /// Pixel with 4 bits each for alpha, red, green, blue; in 16-bit word.
+ /// r = (p >> 8) & 0xF;
+ /// g = (p >> 4) & 0xF;
+ /// b = p & 0xF;
+ /// a = (p >> 12) & 0xF;
kFlutterSoftwarePixelFormatRGBA4444,
- /// pixel with 8 bits for red, green, blue, alpha.
- /// r = p[0]; g = p[1]; b = p[2]; a = p[3];
+ /// Pixel with 8 bits each for red, green, blue, alpha.
+ /// r = p[0];
+ /// g = p[1];
+ /// b = p[2];
+ /// a = p[3];
kFlutterSoftwarePixelFormatRGBA8888,
- /// pixel with 8 bits for red, green and blue and 8 unused bits.
- /// r = p[0]; g = p[1]; b = p[2];
+ /// Pixel with 8 bits each for red, green and blue and 8 unused bits.
+ /// r = p[0];
+ /// g = p[1];
+ /// b = p[2];
kFlutterSoftwarePixelFormatRGBX8888,
- /// pixel with 8 bits for blue, green, red and alpha.
- /// r = p[2]; g = p[1]; b = p[0]; a = p[3];
+ /// Pixel with 8 bits each for blue, green, red and alpha.
+ /// r = p[2];
+ /// g = p[1];
+ /// b = p[0];
+ /// a = p[3];
kFlutterSoftwarePixelFormatBGRA8888,
- /// either kFlutterSoftwarePixelFormatBGRA8888 or
- /// kFlutterSoftwarePixelFormatRGBA8888 depending on CPU endianess and OS
+ /// Either kFlutterSoftwarePixelFormatBGRA8888 or
+ /// kFlutterSoftwarePixelFormatRGBA8888 depending on CPU endianess and OS.
kFlutterSoftwarePixelFormatNative32,
} FlutterSoftwarePixelFormat;
