drivers: video: improve video formats documentation

Introduce a new text documentation of the video formats, describing
every bit, gives the position of the most significant bit, outline how
it is cut in bytes, and show the pixel segmentation.

Extra care is taken for the RGB565 which requies paying attention to the
bit endianess as well as the byte endianess.

Signed-off-by: Josuah Demangeon <me@josuah.net>

include/zephyr/drivers/video.h

@@ -818,65 +818,135 @@ void video_closest_frmival(const struct device *dev, enum video_endpoint_id ep,
 
 /**
  * @defgroup video_pixel_formats Video pixel formats
+ * The @c | characters separate the pixels, and spaces separate the bytes.
+ * The uppercase letter represents the most significant bit.
+ * The lowercase letters represent the rest of the bits.
  * @{
  */
 
 /**
- * @name Bayer formats
+ * @name Bayer formats (R, G, B channels).
+ *
+ * The full color information is spread over multiple pixels.
+ *
  * @{
  */
 
-/** BGGR8 pixel format */
-#define VIDEO_PIX_FMT_BGGR8 video_fourcc('B', 'G', 'G', 'R') /*  8  BGBG.. GRGR.. */
-/** GBRG8 pixel format */
-#define VIDEO_PIX_FMT_GBRG8 video_fourcc('G', 'B', 'R', 'G') /*  8  GBGB.. RGRG.. */
-/** GRBG8 pixel format */
-#define VIDEO_PIX_FMT_GRBG8 video_fourcc('G', 'R', 'B', 'G') /*  8  GRGR.. BGBG.. */
-/** RGGB8 pixel format */
-#define VIDEO_PIX_FMT_RGGB8 video_fourcc('R', 'G', 'G', 'B') /*  8  RGRG.. GBGB.. */
+/**
+ * @verbatim
+ * | Bbbbbbbb | Gggggggg | Bbbbbbbb | Gggggggg | Bbbbbbbb | Gggggggg | ...
+ * | Gggggggg | Rrrrrrrr | Gggggggg | Rrrrrrrr | Gggggggg | Rrrrrrrr | ...
+ * @endverbatim
+ */
+#define VIDEO_PIX_FMT_BGGR8 VIDEO_FOURCC('B', 'A', '8', '1')
+
+/**
+ * @verbatim
+ * | Gggggggg | Bbbbbbbb | Gggggggg | Bbbbbbbb | Gggggggg | Bbbbbbbb | ...
+ * | Rrrrrrrr | Gggggggg | Rrrrrrrr | Gggggggg | Rrrrrrrr | Gggggggg | ...
+ * @endverbatim
+ */
+#define VIDEO_PIX_FMT_GBRG8 VIDEO_FOURCC('G', 'B', 'R', 'G')
+
+/**
+ * @verbatim
+ * | Gggggggg | Rrrrrrrr | Gggggggg | Rrrrrrrr | Gggggggg | Rrrrrrrr | ...
+ * | Bbbbbbbb | Gggggggg | Bbbbbbbb | Gggggggg | Bbbbbbbb | Gggggggg | ...
+ * @endverbatim
+ */
+#define VIDEO_PIX_FMT_GRBG8 VIDEO_FOURCC('G', 'R', 'B', 'G')
+
+/**
+ * @verbatim
+ * | Rrrrrrrr | Gggggggg | Rrrrrrrr | Gggggggg | Rrrrrrrr | Gggggggg | ...
+ * | Gggggggg | Bbbbbbbb | Gggggggg | Bbbbbbbb | Gggggggg | Bbbbbbbb | ...
+ * @endverbatim
+ */
+#define VIDEO_PIX_FMT_RGGB8 VIDEO_FOURCC('R', 'G', 'G', 'B')
 
 /**
  * @}
  */
 
 /**
  * @name RGB formats
+ * Per-color (R, G, B) channels.
  * @{
  */
 
-/** RGB565 pixel format */
-#define VIDEO_PIX_FMT_RGB565 video_fourcc('R', 'G', 'B', 'P') /* 16  RGB-5-6-5 */
+/**
+ * 5 red bits [15:11], 6 green bits [10:5], 5 blue bits [4:0].
+ * This 16-bit integer is then packed in big endian format over two bytes:
+ *
+ * @verbatim
+ *   15.....8 7......0
+ * | RrrrrGgg gggBbbbb | ...
+ * @endverbatim
+ */
+#define VIDEO_PIX_FMT_RGB565X VIDEO_FOURCC('R', 'G', 'B', 'R')
+
+/**
+ * 5 red bits [15:11], 6 green bits [10:5], 5 blue bits [4:0].
+ * This 16-bit integer is then packed in little endian format over two bytes:
+ *
+ * @verbatim
+ *   7......0 15.....8
+ * | gggBbbbb RrrrrGgg | ...
+ * @endverbatim
+ */
+#define VIDEO_PIX_FMT_RGB565 VIDEO_FOURCC('R', 'G', 'B', 'P')
 
-/** XRGB32 pixel format */
-#define VIDEO_PIX_FMT_XRGB32 video_fourcc('B', 'X', '2', '4') /* 32  XRGB-8-8-8-8 */
+/**
+ * The first byte is empty (X) for each pixel.
+ *
+ * @verbatim
+ * | Xxxxxxxx Rrrrrrrr Gggggggg Bbbbbbbb | ...
+ * @endverbatim
+ */
+#define VIDEO_PIX_FMT_XRGB32 VIDEO_FOURCC('B', 'X', '2', '4')
 
 /**
  * @}
  */
 
 /**
  * @name YUV formats
+ * Luminance (Y) and chrominance (U, V) channels.
  * @{
  */
 
-/** YUYV pixel format */
-#define VIDEO_PIX_FMT_YUYV video_fourcc('Y', 'U', 'Y', 'V') /* 16  Y0-Cb0 Y1-Cr0 */
-
-/** XYUV32 pixel format */
-#define VIDEO_PIX_FMT_XYUV32 video_fourcc('X', 'Y', 'U', 'V') /* 32  XYUV-8-8-8-8 */
+/**
+ * There is either a missing channel per pixel, U or V.
+ * The value is to be averaged over 2 pixels to get the value of individual pixel.
+ *
+ * @verbatim
+ * | Yyyyyyyy Uuuuuuuu | Yyyyyyyy Vvvvvvvv | ...
+ * @endverbatim
+ */
+#define VIDEO_PIX_FMT_YUYV VIDEO_FOURCC('Y', 'U', 'Y', 'V')
 
 /**
+ * The first byte is empty (X) for each pixel.
  *
+ * @verbatim
+ * | Xxxxxxxx Yyyyyyyy Uuuuuuuu Vvvvvvvv | ...
+ * @endverbatim
+ */
+#define VIDEO_PIX_FMT_XYUV32 VIDEO_FOURCC('X', 'Y', 'U', 'V')
+
+/**
  * @}
  */
 
 /**
- * @name JPEG formats
+ * @name Compressed formats
  * @{
  */
 
-/** JPEG pixel format */
-#define VIDEO_PIX_FMT_JPEG video_fourcc('J', 'P', 'E', 'G') /*  8  JPEG */
+/**
+ * Both JPEG (single frame) and Motion-JPEG (MJPEG, multiple JPEG frames concatenated)
+ */
+#define VIDEO_PIX_FMT_JPEG VIDEO_FOURCC('J', 'P', 'E', 'G')
 
 /**
  * @}