From 475d981108a23ca0ef2c1dc8d90a06c5e64bac76 Mon Sep 17 00:00:00 2001
From: MyriadSoft <MyriadSoft@users.noreply.github.com>
Date: Mon, 16 Dec 2024 13:48:04 -0500
Subject: [PATCH] docs: Fix RGB565 format documentation and bit masks
 (flutter/engine#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.
---
 .../shell/platform/embedder/embedder.h        | 46 ++++++++++++-------
 1 file changed, 30 insertions(+), 16 deletions(-)

diff --git a/engine/src/flutter/shell/platform/embedder/embedder.h b/engine/src/flutter/shell/platform/embedder/embedder.h
index 8ca474222d3..4b880a6855d 100644
--- a/engine/src/flutter/shell/platform/embedder/embedder.h
+++ b/engine/src/flutter/shell/platform/embedder/embedder.h
@@ -327,9 +327,10 @@ typedef enum {
 ///     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 @@ typedef enum {
 ///   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;