Bug 1209812 (part 4) - Add comments to SurfaceFormat. r=jrmuizel,Bas.

gfx/2d/Types.h

@@ -30,14 +30,28 @@ enum class SurfaceType : int8_t {
 };
 
 enum class SurfaceFormat : int8_t {
-  B8G8R8A8,
-  B8G8R8X8,
-  R8G8B8A8,
-  R8G8B8X8,
-  R5G6B5_UINT16,
+  // The following values are named to reflect layout of colors in memory, from
+  // lowest byte to highest byte. The 32-bit value layout depends on machine
+  // endianness.
+  //               in-memory            32-bit LE value   32-bit BE value
+  B8G8R8A8,     // [BB, GG, RR, AA]     0xAARRGGBB        0xBBGGRRAA
+  B8G8R8X8,     // [BB, GG, RR, 00]     0x00RRGGBB        0xBBGGRR00
+  R8G8B8A8,     // [RR, GG, BB, AA]     0xAABBGGRR        0xRRGGBBAA
+  R8G8B8X8,     // [RR, GG, BB, 00]     0x00BBGGRR        0xRRGGBB00
+
+  // The _UINT16 suffix here indicates that the name reflects the layout when
+  // viewed as a uint16_t value. In memory these values are stored using native
+  // endianness.
+  R5G6B5_UINT16,                    // 0bRRRRRGGGGGGBBBBB
+
+  // This one is a single-byte, so endianness isn't an issue.
   A8,
+
+  // These ones are their own special cases.
   YUV,
   NV12,
+
+  // This represents the unknown format.
   UNKNOWN
 };