* [PATCH/RFC 01/16] media: videodev2.h: Remove unneeded comment about 4CC value
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 02/16] media: videodev2.h: Move HI240 format to vendor-specific section Laurent Pinchart
` (14 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
The V4L2_PIX_FMT_BGRA444 format has a comment that explains why its 4CC
value is GA12. This explains the development history and isn't of much
interest to readers, it should have been part of a commit message
instead. Drop the comment, anyone interested in history can turn to git.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
include/uapi/linux/videodev2.h | 6 ------
1 file changed, 6 deletions(-)
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index c7b70ff53bc1..e89b6c5ca799 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -529,12 +529,6 @@ struct v4l2_pix_format {
#define V4L2_PIX_FMT_RGBX444 v4l2_fourcc('R', 'X', '1', '2') /* 16 rrrrgggg bbbbxxxx */
#define V4L2_PIX_FMT_ABGR444 v4l2_fourcc('A', 'B', '1', '2') /* 16 aaaabbbb ggggrrrr */
#define V4L2_PIX_FMT_XBGR444 v4l2_fourcc('X', 'B', '1', '2') /* 16 xxxxbbbb ggggrrrr */
-
-/*
- * Originally this had 'BA12' as fourcc, but this clashed with the older
- * V4L2_PIX_FMT_SGRBG12 which inexplicably used that same fourcc.
- * So use 'GA12' instead for V4L2_PIX_FMT_BGRA444.
- */
#define V4L2_PIX_FMT_BGRA444 v4l2_fourcc('G', 'A', '1', '2') /* 16 bbbbgggg rrrraaaa */
#define V4L2_PIX_FMT_BGRX444 v4l2_fourcc('B', 'X', '1', '2') /* 16 bbbbgggg rrrrxxxx */
#define V4L2_PIX_FMT_RGB555 v4l2_fourcc('R', 'G', 'B', 'O') /* 16 RGB-5-5-5 */
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 02/16] media: videodev2.h: Move HI240 format to vendor-specific section
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 01/16] media: videodev2.h: Remove unneeded comment about 4CC value Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 03/16] media: videodev2.h: Move HM12 format to YUV semi-planar section Laurent Pinchart
` (13 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
V4L2_PIX_FMT_HI240 is a 8-bit dithered RGB format specific to BTTV. Move
it from the packed YUV formats section where it was misplaced to the
vendor-specific formats section.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
include/uapi/linux/videodev2.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index e89b6c5ca799..63bf69d326df 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -594,7 +594,6 @@ struct v4l2_pix_format {
#define V4L2_PIX_FMT_XYUV32 v4l2_fourcc('X', 'Y', 'U', 'V') /* 32 XYUV-8-8-8-8 */
#define V4L2_PIX_FMT_VUYA32 v4l2_fourcc('V', 'U', 'Y', 'A') /* 32 VUYA-8-8-8-8 */
#define V4L2_PIX_FMT_VUYX32 v4l2_fourcc('V', 'U', 'Y', 'X') /* 32 VUYX-8-8-8-8 */
-#define V4L2_PIX_FMT_HI240 v4l2_fourcc('H', 'I', '2', '4') /* 8 8-bit color */
#define V4L2_PIX_FMT_HM12 v4l2_fourcc('H', 'M', '1', '2') /* 8 YUV 4:2:0 16x16 macroblocks */
#define V4L2_PIX_FMT_M420 v4l2_fourcc('M', '4', '2', '0') /* 12 YUV 4:2:0 2 lines y, 1 line uv interleaved */
@@ -737,6 +736,7 @@ struct v4l2_pix_format {
#define V4L2_PIX_FMT_INZI v4l2_fourcc('I', 'N', 'Z', 'I') /* Intel Planar Greyscale 10-bit and Depth 16-bit */
#define V4L2_PIX_FMT_SUNXI_TILED_NV12 v4l2_fourcc('S', 'T', '1', '2') /* Sunxi Tiled NV12 Format */
#define V4L2_PIX_FMT_CNF4 v4l2_fourcc('C', 'N', 'F', '4') /* Intel 4-bit packed depth confidence information */
+#define V4L2_PIX_FMT_HI240 v4l2_fourcc('H', 'I', '2', '4') /* BTTV 8-bit dithered RGB */
/* 10bit raw bayer packed, 32 bytes for every 25 pixels, last LSB 6 bits unused */
#define V4L2_PIX_FMT_IPU3_SBGGR10 v4l2_fourcc('i', 'p', '3', 'b') /* IPU3 packed 10-bit BGGR bayer */
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 03/16] media: videodev2.h: Move HM12 format to YUV semi-planar section
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 01/16] media: videodev2.h: Remove unneeded comment about 4CC value Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 02/16] media: videodev2.h: Move HI240 format to vendor-specific section Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 04/16] media: doc: pixfmt-rgb: Remove layout table for packed RGB formats Laurent Pinchart
` (12 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
V4L2_PIX_FMT_HM12 is a YUV semi-planar macro-block format. Move it from
the packed YUV formats section where it was misplaced to the YUV
semi-planar formats section.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
include/uapi/linux/videodev2.h | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 63bf69d326df..f4b66bfb859f 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -594,7 +594,6 @@ struct v4l2_pix_format {
#define V4L2_PIX_FMT_XYUV32 v4l2_fourcc('X', 'Y', 'U', 'V') /* 32 XYUV-8-8-8-8 */
#define V4L2_PIX_FMT_VUYA32 v4l2_fourcc('V', 'U', 'Y', 'A') /* 32 VUYA-8-8-8-8 */
#define V4L2_PIX_FMT_VUYX32 v4l2_fourcc('V', 'U', 'Y', 'X') /* 32 VUYX-8-8-8-8 */
-#define V4L2_PIX_FMT_HM12 v4l2_fourcc('H', 'M', '1', '2') /* 8 YUV 4:2:0 16x16 macroblocks */
#define V4L2_PIX_FMT_M420 v4l2_fourcc('M', '4', '2', '0') /* 12 YUV 4:2:0 2 lines y, 1 line uv interleaved */
/* two planes -- one Y, one Cr + Cb interleaved */
@@ -604,6 +603,7 @@ struct v4l2_pix_format {
#define V4L2_PIX_FMT_NV61 v4l2_fourcc('N', 'V', '6', '1') /* 16 Y/CrCb 4:2:2 */
#define V4L2_PIX_FMT_NV24 v4l2_fourcc('N', 'V', '2', '4') /* 24 Y/CbCr 4:4:4 */
#define V4L2_PIX_FMT_NV42 v4l2_fourcc('N', 'V', '4', '2') /* 24 Y/CrCb 4:4:4 */
+#define V4L2_PIX_FMT_HM12 v4l2_fourcc('H', 'M', '1', '2') /* 8 YUV 4:2:0 16x16 macroblocks */
/* two non contiguous planes - one Y, one Cr + Cb interleaved */
#define V4L2_PIX_FMT_NV12M v4l2_fourcc('N', 'M', '1', '2') /* 12 Y/CbCr 4:2:0 */
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 04/16] media: doc: pixfmt-rgb: Remove layout table for packed RGB formats
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (2 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 03/16] media: videodev2.h: Move HM12 format to YUV semi-planar section Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 05/16] media: doc: pixfmt-rgb: Add title for deprecated formats Laurent Pinchart
` (11 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
The packed RGB formats documentation includes a layout table without any
context. This doesn't bring much useful information, and is confusing at
best. Remove it.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../userspace-api/media/v4l/pixfmt-rgb.rst | 71 -------------------
1 file changed, 71 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
index 89cc2a37b285..231383c49e15 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
@@ -1006,77 +1006,6 @@ The XRGB and XBGR formats contain undefined bits (-). Applications,
devices and drivers must ignore those bits, for both
:ref:`capture` and :ref:`output` devices.
-**Byte Order.**
-Each cell is one byte.
-
-
-.. raw:: latex
-
- \small
-
-.. tabularcolumns:: |p{3.1cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|p{0.8cm}|
-
-.. flat-table:: RGB byte order
- :header-rows: 0
- :stub-columns: 0
- :widths: 11 3 3 3 3 3 3 3 3 3 3 3 3
-
- * - start + 0:
- - B\ :sub:`00`
- - G\ :sub:`00`
- - R\ :sub:`00`
- - B\ :sub:`01`
- - G\ :sub:`01`
- - R\ :sub:`01`
- - B\ :sub:`02`
- - G\ :sub:`02`
- - R\ :sub:`02`
- - B\ :sub:`03`
- - G\ :sub:`03`
- - R\ :sub:`03`
- * - start + 12:
- - B\ :sub:`10`
- - G\ :sub:`10`
- - R\ :sub:`10`
- - B\ :sub:`11`
- - G\ :sub:`11`
- - R\ :sub:`11`
- - B\ :sub:`12`
- - G\ :sub:`12`
- - R\ :sub:`12`
- - B\ :sub:`13`
- - G\ :sub:`13`
- - R\ :sub:`13`
- * - start + 24:
- - B\ :sub:`20`
- - G\ :sub:`20`
- - R\ :sub:`20`
- - B\ :sub:`21`
- - G\ :sub:`21`
- - R\ :sub:`21`
- - B\ :sub:`22`
- - G\ :sub:`22`
- - R\ :sub:`22`
- - B\ :sub:`23`
- - G\ :sub:`23`
- - R\ :sub:`23`
- * - start + 36:
- - B\ :sub:`30`
- - G\ :sub:`30`
- - R\ :sub:`30`
- - B\ :sub:`31`
- - G\ :sub:`31`
- - R\ :sub:`31`
- - B\ :sub:`32`
- - G\ :sub:`32`
- - R\ :sub:`32`
- - B\ :sub:`33`
- - G\ :sub:`33`
- - R\ :sub:`33`
-
-.. raw:: latex
-
- \normalsize
Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and
must not be used by new drivers. They are documented here for reference.
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 05/16] media: doc: pixfmt-rgb: Add title for deprecated formats
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (3 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 04/16] media: doc: pixfmt-rgb: Remove layout table for packed RGB formats Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 06/16] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats Laurent Pinchart
` (10 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Improve readability of the documentation by adding a section title for
the deprecated formats.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
Documentation/userspace-api/media/v4l/pixfmt-rgb.rst | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
index 231383c49e15..3208ec94db4c 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
@@ -1007,12 +1007,14 @@ devices and drivers must ignore those bits, for both
:ref:`capture` and :ref:`output` devices.
+Deprecated RGB Formats
+======================
+
Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and
must not be used by new drivers. They are documented here for reference.
The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in
either the corresponding ARGB or XRGB format, depending on the driver.
-
.. raw:: latex
\begingroup
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 06/16] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (4 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 05/16] media: doc: pixfmt-rgb: Add title for deprecated formats Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-24 18:05 ` Nicolas Dufresne
2020-10-01 13:33 ` Hans Verkuil
2020-09-23 2:43 ` [PATCH/RFC 07/16] media: doc: pixfmt-yuv: Document subsampling in more details Laurent Pinchart
` (9 subsequent siblings)
15 siblings, 2 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
The naming scheme for the RGB pixel formats has been developed
organically, and isn't consistent between formats stored in 1 or 2
bytes, and formats stored in 3 or 4 bytes. For the latter category, the
names use a components order convention that is the opposite of the
first category, and the opposite of DRM pixel formats. This has lead to
lots of confusion in the past, and would really benefit from being
explained more precisely. Do so, which also prepares for the addition of
additional RGB pixels formats.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../userspace-api/media/v4l/pixfmt-rgb.rst | 196 ++++++++++++------
include/uapi/linux/videodev2.h | 4 +-
2 files changed, 141 insertions(+), 59 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
index 3208ec94db4c..32bfd68af425 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
@@ -13,13 +13,63 @@
RGB Formats
***********
-Description
-===========
+These formats encode each pixel as a triplet of RGB values. They are packed
+formats, meaning that the RGB values for one pixel are stored consecutively in
+memory. Multiple pixels are however not packed in the same byte, each pixel
+consumes an integer number of bytes. When the number of bits required to store
+a pixel is not aligned to a byte boundary, the data is padded with additional
+bits to fill the remaining byte.
-These formats are designed to match the pixel formats of typical PC
-graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
-These are all packed-pixel formats, meaning all the data for a pixel lie
-next to each other in memory.
+The formats differ by the number of bits per RGB component (typically but not
+always the same for all components), the order of components in memory, and the
+presence of an alpha component or an additional padding byte.
+
+The usage and value of the alpha bits in formats that support them (named ARGB
+or a permutation thereof, collectively referred to as alpha formats) depend on
+the device type and hardware operation. :ref:`Capture <capture>` devices
+(including capture queues of mem-to-mem devices) fill the alpha component in
+memory. When the device captures an alpha channel the alpha component will have
+a meaningful value. Otherwise, when the device doesn't capture an alpha channel
+but can set the alpha bit to a user-configurable value, the
+:ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control is used to
+specify that alpha value, and the alpha component of all pixels will be set to
+the value specified by that control. Otherwise a corresponding format without
+an alpha component (XRGB or XBGR) must be used instead of an alpha format.
+
+:ref:`Output <output>` devices (including output queues of mem-to-mem devices
+and :ref:`video output overlay <osd>` devices) read the alpha component from
+memory. When the device processes the alpha channel the alpha component must be
+filled with meaningful values by applications. Otherwise a corresponding format
+without an alpha component (XRGB or XBGR) must be used instead of an alpha
+format.
+
+Formats that contain padding bits are named XRGB (or a permutation thereof).
+The padding bits contain undefined values and must be ignored by applications,
+devices and drivers, for both :ref:`capture` and :ref:`output` devices.
+
+.. note::
+
+ - In all the tables that follow, bit 7 is the most significant bit in a byte.
+ - 'r', 'g' and 'b' denote bits of the red, green and blue components
+ respectively. 'a' denotes bits of the the alpha component (if supported by
+ the format), and '-' denotes padding bits.
+
+
+8 or 16 Bits Per Pixel
+======================
+
+These formats store an RGB triplet in one or two bytes. They are named based on
+the order of the RGB components as seen in a 8- or 16-bit word, which is then
+stored in memory in little endian byte order (unless otherwise noted by the
+presence of bit 31 in the 4CC value), and on the number of bits for each
+component. For instance, the RGB565 format stores a pixel in a 16-bit word
+[15:0] laid out at as [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
+R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2` G\ :sub:`1`
+G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`], and
+stored in memory in two bytes, [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
+R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3`] followed by [G\ :sub:`2`
+G\ :sub:`1` G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1`
+B\ :sub:`0`].
.. raw:: latex
@@ -27,10 +77,10 @@ next to each other in memory.
\tiny
\setlength{\tabcolsep}{2pt}
-.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
+.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
-.. flat-table:: RGB Image Formats
+.. flat-table:: RGB Formats With 8 or 16 Bits Per Pixel
:header-rows: 2
:stub-columns: 0
@@ -38,8 +88,6 @@ next to each other in memory.
- Code
- :cspan:`7` Byte 0 in memory
- :cspan:`7` Byte 1
- - :cspan:`7` Byte 2
- - :cspan:`7` Byte 3
* -
-
- 7
@@ -59,24 +107,6 @@ next to each other in memory.
- 2
- 1
- 0
-
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
-
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
* .. _V4L2-PIX-FMT-RGB332:
- ``V4L2_PIX_FMT_RGB332``
@@ -551,6 +581,82 @@ next to each other in memory.
- b\ :sub:`1`
- b\ :sub:`0`
-
+
+.. raw:: latex
+
+ \endgroup
+
+
+24 or 32 Bits Per Pixel
+=======================
+
+These formats store an RGB triplet in three or four bytes. They are named based
+on the order of the RGB components as stored in memory, and on the total number
+of bits per pixel (with an exception for the BGR666 format). For instance,
+RGB24 format stores a pixel with [R\ :sub:`7` R\ :sub:`6` R\ :sub:`5`
+R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` R\ :sub:`0`] in the first byte,
+[G\ :sub:`7` G\ :sub:`6` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2`
+G\ :sub:`1` G\ :sub:`0`] in the second byte and [B\ :sub:`7` B\ :sub:`6`
+B\ :sub:`5` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`] in the
+third byte. This differs from the DRM format nomenclature that instead use the
+order of components as seen in a 24- or 32-bit little endian word.
+
+.. raw:: latex
+
+ \begingroup
+ \tiny
+ \setlength{\tabcolsep}{2pt}
+
+.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
+
+
+.. flat-table:: RGB Formats With 24 or 32 Bits Per Pixel
+ :header-rows: 2
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - :cspan:`7` Byte 0 in memory
+ - :cspan:`7` Byte 1
+ - :cspan:`7` Byte 2
+ - :cspan:`7` Byte 3
+ * -
+ -
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
+
+ - 7
+ - 6
+ - 5
+ - 4
+ - 3
+ - 2
+ - 1
+ - 0
* .. _V4L2-PIX-FMT-BGR24:
- ``V4L2_PIX_FMT_BGR24``
@@ -980,40 +1086,14 @@ next to each other in memory.
\endgroup
-.. note:: Bit 7 is the most significant bit.
-
-The usage and value of the alpha bits (a) in the ARGB and ABGR formats
-(collectively referred to as alpha formats) depend on the device type
-and hardware operation. :ref:`Capture <capture>` devices (including
-capture queues of mem-to-mem devices) fill the alpha component in
-memory. When the device outputs an alpha channel the alpha component
-will have a meaningful value. Otherwise, when the device doesn't output
-an alpha channel but can set the alpha bit to a user-configurable value,
-the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
-is used to specify that alpha value, and the alpha component of all
-pixels will be set to the value specified by that control. Otherwise a
-corresponding format without an alpha component (XRGB or XBGR) must be
-used instead of an alpha format.
-
-:ref:`Output <output>` devices (including output queues of mem-to-mem
-devices and :ref:`video output overlay <osd>` devices) read the alpha
-component from memory. When the device processes the alpha channel the
-alpha component must be filled with meaningful values by applications.
-Otherwise a corresponding format without an alpha component (XRGB or
-XBGR) must be used instead of an alpha format.
-
-The XRGB and XBGR formats contain undefined bits (-). Applications,
-devices and drivers must ignore those bits, for both
-:ref:`capture` and :ref:`output` devices.
-
Deprecated RGB Formats
======================
-Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and
-must not be used by new drivers. They are documented here for reference.
-The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in
-either the corresponding ARGB or XRGB format, depending on the driver.
+Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and must not be
+used by new drivers. They are documented here for reference. The meaning of
+their alpha bits ``(a)`` is ill-defined and they are interpreted as in either
+the corresponding ARGB or XRGB format, depending on the driver.
.. raw:: latex
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index f4b66bfb859f..3f5f1cf8d1c0 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -520,7 +520,7 @@ struct v4l2_pix_format {
/* Pixel format FOURCC depth Description */
-/* RGB formats */
+/* RGB formats (1 or 2 bytes per pixel) */
#define V4L2_PIX_FMT_RGB332 v4l2_fourcc('R', 'G', 'B', '1') /* 8 RGB-3-3-2 */
#define V4L2_PIX_FMT_RGB444 v4l2_fourcc('R', '4', '4', '4') /* 16 xxxxrrrr ggggbbbb */
#define V4L2_PIX_FMT_ARGB444 v4l2_fourcc('A', 'R', '1', '2') /* 16 aaaarrrr ggggbbbb */
@@ -545,6 +545,8 @@ struct v4l2_pix_format {
#define V4L2_PIX_FMT_ARGB555X v4l2_fourcc_be('A', 'R', '1', '5') /* 16 ARGB-5-5-5 BE */
#define V4L2_PIX_FMT_XRGB555X v4l2_fourcc_be('X', 'R', '1', '5') /* 16 XRGB-5-5-5 BE */
#define V4L2_PIX_FMT_RGB565X v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */
+
+/* RGB formats (3 or 4 bytes per pixel) */
#define V4L2_PIX_FMT_BGR666 v4l2_fourcc('B', 'G', 'R', 'H') /* 18 BGR-6-6-6 */
#define V4L2_PIX_FMT_BGR24 v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */
#define V4L2_PIX_FMT_RGB24 v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 06/16] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-09-23 2:43 ` [PATCH/RFC 06/16] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats Laurent Pinchart
@ 2020-09-24 18:05 ` Nicolas Dufresne
2020-10-31 23:26 ` Laurent Pinchart
2020-10-01 13:33 ` Hans Verkuil
1 sibling, 1 reply; 31+ messages in thread
From: Nicolas Dufresne @ 2020-09-24 18:05 UTC (permalink / raw)
To: Laurent Pinchart, linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> The naming scheme for the RGB pixel formats has been developed
> organically, and isn't consistent between formats stored in 1 or 2
> bytes, and formats stored in 3 or 4 bytes. For the latter category, the
> names use a components order convention that is the opposite of the
> first category, and the opposite of DRM pixel formats. This has lead to
> lots of confusion in the past, and would really benefit from being
> explained more precisely. Do so, which also prepares for the addition of
> additional RGB pixels formats.
This makes it looks like if V4L2 byte order naming is special, while in
fact only a subset of DRM format uses the opposite order and outside of
the Linux kernel, DRM is the special case. I agree there is this RGB565
name that is indeed opposite outside Linux too.
I would rephrase this, otherwise the following changes looks good to
me.
>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> .../userspace-api/media/v4l/pixfmt-rgb.rst | 196 ++++++++++++------
> include/uapi/linux/videodev2.h | 4 +-
> 2 files changed, 141 insertions(+), 59 deletions(-)
>
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> index 3208ec94db4c..32bfd68af425 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> @@ -13,13 +13,63 @@
> RGB Formats
> ***********
>
> -Description
> -===========
> +These formats encode each pixel as a triplet of RGB values. They are packed
> +formats, meaning that the RGB values for one pixel are stored consecutively in
> +memory. Multiple pixels are however not packed in the same byte, each pixel
> +consumes an integer number of bytes. When the number of bits required to store
> +a pixel is not aligned to a byte boundary, the data is padded with additional
> +bits to fill the remaining byte.
>
> -These formats are designed to match the pixel formats of typical PC
> -graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
> -These are all packed-pixel formats, meaning all the data for a pixel lie
> -next to each other in memory.
> +The formats differ by the number of bits per RGB component (typically but not
> +always the same for all components), the order of components in memory, and the
> +presence of an alpha component or an additional padding byte.
> +
> +The usage and value of the alpha bits in formats that support them (named ARGB
> +or a permutation thereof, collectively referred to as alpha formats) depend on
> +the device type and hardware operation. :ref:`Capture <capture>` devices
> +(including capture queues of mem-to-mem devices) fill the alpha component in
> +memory. When the device captures an alpha channel the alpha component will have
> +a meaningful value. Otherwise, when the device doesn't capture an alpha channel
> +but can set the alpha bit to a user-configurable value, the
> +:ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control is used to
> +specify that alpha value, and the alpha component of all pixels will be set to
> +the value specified by that control. Otherwise a corresponding format without
> +an alpha component (XRGB or XBGR) must be used instead of an alpha format.
> +
> +:ref:`Output <output>` devices (including output queues of mem-to-mem devices
> +and :ref:`video output overlay <osd>` devices) read the alpha component from
> +memory. When the device processes the alpha channel the alpha component must be
> +filled with meaningful values by applications. Otherwise a corresponding format
> +without an alpha component (XRGB or XBGR) must be used instead of an alpha
> +format.
> +
> +Formats that contain padding bits are named XRGB (or a permutation thereof).
> +The padding bits contain undefined values and must be ignored by applications,
> +devices and drivers, for both :ref:`capture` and :ref:`output` devices.
> +
> +.. note::
> +
> + - In all the tables that follow, bit 7 is the most significant bit in a byte.
> + - 'r', 'g' and 'b' denote bits of the red, green and blue components
> + respectively. 'a' denotes bits of the the alpha component (if supported by
> + the format), and '-' denotes padding bits.
> +
> +
> +8 or 16 Bits Per Pixel
> +======================
> +
> +These formats store an RGB triplet in one or two bytes. They are named based on
> +the order of the RGB components as seen in a 8- or 16-bit word, which is then
> +stored in memory in little endian byte order (unless otherwise noted by the
> +presence of bit 31 in the 4CC value), and on the number of bits for each
> +component. For instance, the RGB565 format stores a pixel in a 16-bit word
> +[15:0] laid out at as [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
> +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2` G\ :sub:`1`
> +G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`], and
> +stored in memory in two bytes, [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
> +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3`] followed by [G\ :sub:`2`
> +G\ :sub:`1` G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1`
> +B\ :sub:`0`].
>
> .. raw:: latex
>
> @@ -27,10 +77,10 @@ next to each other in memory.
> \tiny
> \setlength{\tabcolsep}{2pt}
>
> -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
>
>
> -.. flat-table:: RGB Image Formats
> +.. flat-table:: RGB Formats With 8 or 16 Bits Per Pixel
> :header-rows: 2
> :stub-columns: 0
>
> @@ -38,8 +88,6 @@ next to each other in memory.
> - Code
> - :cspan:`7` Byte 0 in memory
> - :cspan:`7` Byte 1
> - - :cspan:`7` Byte 2
> - - :cspan:`7` Byte 3
> * -
> -
> - 7
> @@ -59,24 +107,6 @@ next to each other in memory.
> - 2
> - 1
> - 0
> -
> - - 7
> - - 6
> - - 5
> - - 4
> - - 3
> - - 2
> - - 1
> - - 0
> -
> - - 7
> - - 6
> - - 5
> - - 4
> - - 3
> - - 2
> - - 1
> - - 0
> * .. _V4L2-PIX-FMT-RGB332:
>
> - ``V4L2_PIX_FMT_RGB332``
> @@ -551,6 +581,82 @@ next to each other in memory.
> - b\ :sub:`1`
> - b\ :sub:`0`
> -
> +
> +.. raw:: latex
> +
> + \endgroup
> +
> +
> +24 or 32 Bits Per Pixel
> +=======================
> +
> +These formats store an RGB triplet in three or four bytes. They are named based
> +on the order of the RGB components as stored in memory, and on the total number
> +of bits per pixel (with an exception for the BGR666 format). For instance,
> +RGB24 format stores a pixel with [R\ :sub:`7` R\ :sub:`6` R\ :sub:`5`
> +R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` R\ :sub:`0`] in the first byte,
> +[G\ :sub:`7` G\ :sub:`6` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2`
> +G\ :sub:`1` G\ :sub:`0`] in the second byte and [B\ :sub:`7` B\ :sub:`6`
> +B\ :sub:`5` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`] in the
> +third byte. This differs from the DRM format nomenclature that instead use the
> +order of components as seen in a 24- or 32-bit little endian word.
> +
> +.. raw:: latex
> +
> + \begingroup
> + \tiny
> + \setlength{\tabcolsep}{2pt}
> +
> +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> +
> +
> +.. flat-table:: RGB Formats With 24 or 32 Bits Per Pixel
> + :header-rows: 2
> + :stub-columns: 0
> +
> + * - Identifier
> + - Code
> + - :cspan:`7` Byte 0 in memory
> + - :cspan:`7` Byte 1
> + - :cspan:`7` Byte 2
> + - :cspan:`7` Byte 3
> + * -
> + -
> + - 7
> + - 6
> + - 5
> + - 4
> + - 3
> + - 2
> + - 1
> + - 0
> +
> + - 7
> + - 6
> + - 5
> + - 4
> + - 3
> + - 2
> + - 1
> + - 0
> +
> + - 7
> + - 6
> + - 5
> + - 4
> + - 3
> + - 2
> + - 1
> + - 0
> +
> + - 7
> + - 6
> + - 5
> + - 4
> + - 3
> + - 2
> + - 1
> + - 0
> * .. _V4L2-PIX-FMT-BGR24:
>
> - ``V4L2_PIX_FMT_BGR24``
> @@ -980,40 +1086,14 @@ next to each other in memory.
>
> \endgroup
>
> -.. note:: Bit 7 is the most significant bit.
> -
> -The usage and value of the alpha bits (a) in the ARGB and ABGR formats
> -(collectively referred to as alpha formats) depend on the device type
> -and hardware operation. :ref:`Capture <capture>` devices (including
> -capture queues of mem-to-mem devices) fill the alpha component in
> -memory. When the device outputs an alpha channel the alpha component
> -will have a meaningful value. Otherwise, when the device doesn't output
> -an alpha channel but can set the alpha bit to a user-configurable value,
> -the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
> -is used to specify that alpha value, and the alpha component of all
> -pixels will be set to the value specified by that control. Otherwise a
> -corresponding format without an alpha component (XRGB or XBGR) must be
> -used instead of an alpha format.
> -
> -:ref:`Output <output>` devices (including output queues of mem-to-mem
> -devices and :ref:`video output overlay <osd>` devices) read the alpha
> -component from memory. When the device processes the alpha channel the
> -alpha component must be filled with meaningful values by applications.
> -Otherwise a corresponding format without an alpha component (XRGB or
> -XBGR) must be used instead of an alpha format.
> -
> -The XRGB and XBGR formats contain undefined bits (-). Applications,
> -devices and drivers must ignore those bits, for both
> -:ref:`capture` and :ref:`output` devices.
> -
>
> Deprecated RGB Formats
> ======================
>
> -Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and
> -must not be used by new drivers. They are documented here for reference.
> -The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in
> -either the corresponding ARGB or XRGB format, depending on the driver.
> +Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and must not be
> +used by new drivers. They are documented here for reference. The meaning of
> +their alpha bits ``(a)`` is ill-defined and they are interpreted as in either
> +the corresponding ARGB or XRGB format, depending on the driver.
>
> .. raw:: latex
>
> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> index f4b66bfb859f..3f5f1cf8d1c0 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -520,7 +520,7 @@ struct v4l2_pix_format {
>
> /* Pixel format FOURCC depth Description */
>
> -/* RGB formats */
> +/* RGB formats (1 or 2 bytes per pixel) */
> #define V4L2_PIX_FMT_RGB332 v4l2_fourcc('R', 'G', 'B', '1') /* 8 RGB-3-3-2 */
> #define V4L2_PIX_FMT_RGB444 v4l2_fourcc('R', '4', '4', '4') /* 16 xxxxrrrr ggggbbbb */
> #define V4L2_PIX_FMT_ARGB444 v4l2_fourcc('A', 'R', '1', '2') /* 16 aaaarrrr ggggbbbb */
> @@ -545,6 +545,8 @@ struct v4l2_pix_format {
> #define V4L2_PIX_FMT_ARGB555X v4l2_fourcc_be('A', 'R', '1', '5') /* 16 ARGB-5-5-5 BE */
> #define V4L2_PIX_FMT_XRGB555X v4l2_fourcc_be('X', 'R', '1', '5') /* 16 XRGB-5-5-5 BE */
> #define V4L2_PIX_FMT_RGB565X v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */
> +
> +/* RGB formats (3 or 4 bytes per pixel) */
> #define V4L2_PIX_FMT_BGR666 v4l2_fourcc('B', 'G', 'R', 'H') /* 18 BGR-6-6-6 */
> #define V4L2_PIX_FMT_BGR24 v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */
> #define V4L2_PIX_FMT_RGB24 v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 06/16] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-09-24 18:05 ` Nicolas Dufresne
@ 2020-10-31 23:26 ` Laurent Pinchart
0 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-10-31 23:26 UTC (permalink / raw)
To: Nicolas Dufresne
Cc: linux-media, Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Hi Nicolas,
On Thu, Sep 24, 2020 at 02:05:57PM -0400, Nicolas Dufresne wrote:
> Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> > The naming scheme for the RGB pixel formats has been developed
> > organically, and isn't consistent between formats stored in 1 or 2
> > bytes, and formats stored in 3 or 4 bytes. For the latter category, the
> > names use a components order convention that is the opposite of the
> > first category, and the opposite of DRM pixel formats. This has lead to
> > lots of confusion in the past, and would really benefit from being
> > explained more precisely. Do so, which also prepares for the addition of
> > additional RGB pixels formats.
>
> This makes it looks like if V4L2 byte order naming is special, while in
> fact only a subset of DRM format uses the opposite order and outside of
> the Linux kernel, DRM is the special case. I agree there is this RGB565
> name that is indeed opposite outside Linux too.
>
> I would rephrase this, otherwise the following changes looks good to
> me.
I'm not opposed to rephrasing the commit message, but I'm not sure why
you interpret it as making V4L2 appear special. How do you think it
could be better phrased ?
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> > .../userspace-api/media/v4l/pixfmt-rgb.rst | 196 ++++++++++++------
> > include/uapi/linux/videodev2.h | 4 +-
> > 2 files changed, 141 insertions(+), 59 deletions(-)
> >
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > index 3208ec94db4c..32bfd68af425 100644
> > --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > @@ -13,13 +13,63 @@
> > RGB Formats
> > ***********
> >
> > -Description
> > -===========
> > +These formats encode each pixel as a triplet of RGB values. They are packed
> > +formats, meaning that the RGB values for one pixel are stored consecutively in
> > +memory. Multiple pixels are however not packed in the same byte, each pixel
> > +consumes an integer number of bytes. When the number of bits required to store
> > +a pixel is not aligned to a byte boundary, the data is padded with additional
> > +bits to fill the remaining byte.
> >
> > -These formats are designed to match the pixel formats of typical PC
> > -graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
> > -These are all packed-pixel formats, meaning all the data for a pixel lie
> > -next to each other in memory.
> > +The formats differ by the number of bits per RGB component (typically but not
> > +always the same for all components), the order of components in memory, and the
> > +presence of an alpha component or an additional padding byte.
> > +
> > +The usage and value of the alpha bits in formats that support them (named ARGB
> > +or a permutation thereof, collectively referred to as alpha formats) depend on
> > +the device type and hardware operation. :ref:`Capture <capture>` devices
> > +(including capture queues of mem-to-mem devices) fill the alpha component in
> > +memory. When the device captures an alpha channel the alpha component will have
> > +a meaningful value. Otherwise, when the device doesn't capture an alpha channel
> > +but can set the alpha bit to a user-configurable value, the
> > +:ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control is used to
> > +specify that alpha value, and the alpha component of all pixels will be set to
> > +the value specified by that control. Otherwise a corresponding format without
> > +an alpha component (XRGB or XBGR) must be used instead of an alpha format.
> > +
> > +:ref:`Output <output>` devices (including output queues of mem-to-mem devices
> > +and :ref:`video output overlay <osd>` devices) read the alpha component from
> > +memory. When the device processes the alpha channel the alpha component must be
> > +filled with meaningful values by applications. Otherwise a corresponding format
> > +without an alpha component (XRGB or XBGR) must be used instead of an alpha
> > +format.
> > +
> > +Formats that contain padding bits are named XRGB (or a permutation thereof).
> > +The padding bits contain undefined values and must be ignored by applications,
> > +devices and drivers, for both :ref:`capture` and :ref:`output` devices.
> > +
> > +.. note::
> > +
> > + - In all the tables that follow, bit 7 is the most significant bit in a byte.
> > + - 'r', 'g' and 'b' denote bits of the red, green and blue components
> > + respectively. 'a' denotes bits of the the alpha component (if supported by
> > + the format), and '-' denotes padding bits.
> > +
> > +
> > +8 or 16 Bits Per Pixel
> > +======================
> > +
> > +These formats store an RGB triplet in one or two bytes. They are named based on
> > +the order of the RGB components as seen in a 8- or 16-bit word, which is then
> > +stored in memory in little endian byte order (unless otherwise noted by the
> > +presence of bit 31 in the 4CC value), and on the number of bits for each
> > +component. For instance, the RGB565 format stores a pixel in a 16-bit word
> > +[15:0] laid out at as [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
> > +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2` G\ :sub:`1`
> > +G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`], and
> > +stored in memory in two bytes, [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
> > +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3`] followed by [G\ :sub:`2`
> > +G\ :sub:`1` G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1`
> > +B\ :sub:`0`].
> >
> > .. raw:: latex
> >
> > @@ -27,10 +77,10 @@ next to each other in memory.
> > \tiny
> > \setlength{\tabcolsep}{2pt}
> >
> > -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> > +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> >
> >
> > -.. flat-table:: RGB Image Formats
> > +.. flat-table:: RGB Formats With 8 or 16 Bits Per Pixel
> > :header-rows: 2
> > :stub-columns: 0
> >
> > @@ -38,8 +88,6 @@ next to each other in memory.
> > - Code
> > - :cspan:`7` Byte 0 in memory
> > - :cspan:`7` Byte 1
> > - - :cspan:`7` Byte 2
> > - - :cspan:`7` Byte 3
> > * -
> > -
> > - 7
> > @@ -59,24 +107,6 @@ next to each other in memory.
> > - 2
> > - 1
> > - 0
> > -
> > - - 7
> > - - 6
> > - - 5
> > - - 4
> > - - 3
> > - - 2
> > - - 1
> > - - 0
> > -
> > - - 7
> > - - 6
> > - - 5
> > - - 4
> > - - 3
> > - - 2
> > - - 1
> > - - 0
> > * .. _V4L2-PIX-FMT-RGB332:
> >
> > - ``V4L2_PIX_FMT_RGB332``
> > @@ -551,6 +581,82 @@ next to each other in memory.
> > - b\ :sub:`1`
> > - b\ :sub:`0`
> > -
> > +
> > +.. raw:: latex
> > +
> > + \endgroup
> > +
> > +
> > +24 or 32 Bits Per Pixel
> > +=======================
> > +
> > +These formats store an RGB triplet in three or four bytes. They are named based
> > +on the order of the RGB components as stored in memory, and on the total number
> > +of bits per pixel (with an exception for the BGR666 format). For instance,
> > +RGB24 format stores a pixel with [R\ :sub:`7` R\ :sub:`6` R\ :sub:`5`
> > +R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` R\ :sub:`0`] in the first byte,
> > +[G\ :sub:`7` G\ :sub:`6` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2`
> > +G\ :sub:`1` G\ :sub:`0`] in the second byte and [B\ :sub:`7` B\ :sub:`6`
> > +B\ :sub:`5` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`] in the
> > +third byte. This differs from the DRM format nomenclature that instead use the
> > +order of components as seen in a 24- or 32-bit little endian word.
> > +
> > +.. raw:: latex
> > +
> > + \begingroup
> > + \tiny
> > + \setlength{\tabcolsep}{2pt}
> > +
> > +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> > +
> > +
> > +.. flat-table:: RGB Formats With 24 or 32 Bits Per Pixel
> > + :header-rows: 2
> > + :stub-columns: 0
> > +
> > + * - Identifier
> > + - Code
> > + - :cspan:`7` Byte 0 in memory
> > + - :cspan:`7` Byte 1
> > + - :cspan:`7` Byte 2
> > + - :cspan:`7` Byte 3
> > + * -
> > + -
> > + - 7
> > + - 6
> > + - 5
> > + - 4
> > + - 3
> > + - 2
> > + - 1
> > + - 0
> > +
> > + - 7
> > + - 6
> > + - 5
> > + - 4
> > + - 3
> > + - 2
> > + - 1
> > + - 0
> > +
> > + - 7
> > + - 6
> > + - 5
> > + - 4
> > + - 3
> > + - 2
> > + - 1
> > + - 0
> > +
> > + - 7
> > + - 6
> > + - 5
> > + - 4
> > + - 3
> > + - 2
> > + - 1
> > + - 0
> > * .. _V4L2-PIX-FMT-BGR24:
> >
> > - ``V4L2_PIX_FMT_BGR24``
> > @@ -980,40 +1086,14 @@ next to each other in memory.
> >
> > \endgroup
> >
> > -.. note:: Bit 7 is the most significant bit.
> > -
> > -The usage and value of the alpha bits (a) in the ARGB and ABGR formats
> > -(collectively referred to as alpha formats) depend on the device type
> > -and hardware operation. :ref:`Capture <capture>` devices (including
> > -capture queues of mem-to-mem devices) fill the alpha component in
> > -memory. When the device outputs an alpha channel the alpha component
> > -will have a meaningful value. Otherwise, when the device doesn't output
> > -an alpha channel but can set the alpha bit to a user-configurable value,
> > -the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
> > -is used to specify that alpha value, and the alpha component of all
> > -pixels will be set to the value specified by that control. Otherwise a
> > -corresponding format without an alpha component (XRGB or XBGR) must be
> > -used instead of an alpha format.
> > -
> > -:ref:`Output <output>` devices (including output queues of mem-to-mem
> > -devices and :ref:`video output overlay <osd>` devices) read the alpha
> > -component from memory. When the device processes the alpha channel the
> > -alpha component must be filled with meaningful values by applications.
> > -Otherwise a corresponding format without an alpha component (XRGB or
> > -XBGR) must be used instead of an alpha format.
> > -
> > -The XRGB and XBGR formats contain undefined bits (-). Applications,
> > -devices and drivers must ignore those bits, for both
> > -:ref:`capture` and :ref:`output` devices.
> > -
> >
> > Deprecated RGB Formats
> > ======================
> >
> > -Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and
> > -must not be used by new drivers. They are documented here for reference.
> > -The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in
> > -either the corresponding ARGB or XRGB format, depending on the driver.
> > +Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and must not be
> > +used by new drivers. They are documented here for reference. The meaning of
> > +their alpha bits ``(a)`` is ill-defined and they are interpreted as in either
> > +the corresponding ARGB or XRGB format, depending on the driver.
> >
> > .. raw:: latex
> >
> > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > index f4b66bfb859f..3f5f1cf8d1c0 100644
> > --- a/include/uapi/linux/videodev2.h
> > +++ b/include/uapi/linux/videodev2.h
> > @@ -520,7 +520,7 @@ struct v4l2_pix_format {
> >
> > /* Pixel format FOURCC depth Description */
> >
> > -/* RGB formats */
> > +/* RGB formats (1 or 2 bytes per pixel) */
> > #define V4L2_PIX_FMT_RGB332 v4l2_fourcc('R', 'G', 'B', '1') /* 8 RGB-3-3-2 */
> > #define V4L2_PIX_FMT_RGB444 v4l2_fourcc('R', '4', '4', '4') /* 16 xxxxrrrr ggggbbbb */
> > #define V4L2_PIX_FMT_ARGB444 v4l2_fourcc('A', 'R', '1', '2') /* 16 aaaarrrr ggggbbbb */
> > @@ -545,6 +545,8 @@ struct v4l2_pix_format {
> > #define V4L2_PIX_FMT_ARGB555X v4l2_fourcc_be('A', 'R', '1', '5') /* 16 ARGB-5-5-5 BE */
> > #define V4L2_PIX_FMT_XRGB555X v4l2_fourcc_be('X', 'R', '1', '5') /* 16 XRGB-5-5-5 BE */
> > #define V4L2_PIX_FMT_RGB565X v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */
> > +
> > +/* RGB formats (3 or 4 bytes per pixel) */
> > #define V4L2_PIX_FMT_BGR666 v4l2_fourcc('B', 'G', 'R', 'H') /* 18 BGR-6-6-6 */
> > #define V4L2_PIX_FMT_BGR24 v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */
> > #define V4L2_PIX_FMT_RGB24 v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */
>
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH/RFC 06/16] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-09-23 2:43 ` [PATCH/RFC 06/16] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats Laurent Pinchart
2020-09-24 18:05 ` Nicolas Dufresne
@ 2020-10-01 13:33 ` Hans Verkuil
2020-11-01 0:11 ` Laurent Pinchart
1 sibling, 1 reply; 31+ messages in thread
From: Hans Verkuil @ 2020-10-01 13:33 UTC (permalink / raw)
To: Laurent Pinchart, linux-media; +Cc: Sakari Ailus, Dylan Yip, Vishal Sagar
On 23/09/2020 04:43, Laurent Pinchart wrote:
> The naming scheme for the RGB pixel formats has been developed
> organically, and isn't consistent between formats stored in 1 or 2
> bytes, and formats stored in 3 or 4 bytes. For the latter category, the
> names use a components order convention that is the opposite of the
> first category, and the opposite of DRM pixel formats. This has lead to
lead -> led
> lots of confusion in the past, and would really benefit from being
> explained more precisely. Do so, which also prepares for the addition of
> additional RGB pixels formats.
>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> .../userspace-api/media/v4l/pixfmt-rgb.rst | 196 ++++++++++++------
> include/uapi/linux/videodev2.h | 4 +-
> 2 files changed, 141 insertions(+), 59 deletions(-)
>
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> index 3208ec94db4c..32bfd68af425 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> @@ -13,13 +13,63 @@
> RGB Formats
> ***********
>
> -Description
> -===========
> +These formats encode each pixel as a triplet of RGB values. They are packed
> +formats, meaning that the RGB values for one pixel are stored consecutively in
> +memory. Multiple pixels are however not packed in the same byte, each pixel
"Multiple pixels are however not packed in the same byte": that's confusing.
I think it can be dropped and instead just say:
"meaning that the RGB values for one pixel are stored consecutively in memory
and each pixel consumes an integer number of bytes."
> +consumes an integer number of bytes. When the number of bits required to store
> +a pixel is not aligned to a byte boundary, the data is padded with additional
> +bits to fill the remaining byte.
>
> -These formats are designed to match the pixel formats of typical PC
> -graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
> -These are all packed-pixel formats, meaning all the data for a pixel lie
> -next to each other in memory.
> +The formats differ by the number of bits per RGB component (typically but not
> +always the same for all components), the order of components in memory, and the
> +presence of an alpha component or an additional padding byte.
I think you should say: "or additional padding bits". That is consistent with the
previous paragraph.
> +
> +The usage and value of the alpha bits in formats that support them (named ARGB
> +or a permutation thereof, collectively referred to as alpha formats) depend on
> +the device type and hardware operation. :ref:`Capture <capture>` devices
> +(including capture queues of mem-to-mem devices) fill the alpha component in
> +memory. When the device captures an alpha channel the alpha component will have
> +a meaningful value. Otherwise, when the device doesn't capture an alpha channel
> +but can set the alpha bit to a user-configurable value, the
> +:ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control is used to
> +specify that alpha value, and the alpha component of all pixels will be set to
> +the value specified by that control. Otherwise a corresponding format without
> +an alpha component (XRGB or XBGR) must be used instead of an alpha format.
> +
> +:ref:`Output <output>` devices (including output queues of mem-to-mem devices
> +and :ref:`video output overlay <osd>` devices) read the alpha component from
> +memory. When the device processes the alpha channel the alpha component must be
> +filled with meaningful values by applications. Otherwise a corresponding format
> +without an alpha component (XRGB or XBGR) must be used instead of an alpha
> +format.
> +
> +Formats that contain padding bits are named XRGB (or a permutation thereof).
> +The padding bits contain undefined values and must be ignored by applications,
> +devices and drivers, for both :ref:`capture` and :ref:`output` devices.
Should we mention here that it is highly desirable that padding bits are set to 0?
> +
> +.. note::
> +
> + - In all the tables that follow, bit 7 is the most significant bit in a byte.
> + - 'r', 'g' and 'b' denote bits of the red, green and blue components
> + respectively. 'a' denotes bits of the the alpha component (if supported by
> + the format), and '-' denotes padding bits.
> +
> +
> +8 or 16 Bits Per Pixel
> +======================
> +
> +These formats store an RGB triplet in one or two bytes. They are named based on
> +the order of the RGB components as seen in a 8- or 16-bit word, which is then
> +stored in memory in little endian byte order (unless otherwise noted by the
> +presence of bit 31 in the 4CC value), and on the number of bits for each
> +component. For instance, the RGB565 format stores a pixel in a 16-bit word
> +[15:0] laid out at as [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
> +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2` G\ :sub:`1`
> +G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`], and
> +stored in memory in two bytes, [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
> +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3`] followed by [G\ :sub:`2`
> +G\ :sub:`1` G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1`
> +B\ :sub:`0`].
>
> .. raw:: latex
>
> @@ -27,10 +77,10 @@ next to each other in memory.
> \tiny
> \setlength{\tabcolsep}{2pt}
>
> -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
>
>
> -.. flat-table:: RGB Image Formats
> +.. flat-table:: RGB Formats With 8 or 16 Bits Per Pixel
> :header-rows: 2
> :stub-columns: 0
>
> @@ -38,8 +88,6 @@ next to each other in memory.
> - Code
> - :cspan:`7` Byte 0 in memory
> - :cspan:`7` Byte 1
> - - :cspan:`7` Byte 2
> - - :cspan:`7` Byte 3
> * -
> -
> - 7
> @@ -59,24 +107,6 @@ next to each other in memory.
> - 2
> - 1
> - 0
> -
> - - 7
> - - 6
> - - 5
> - - 4
> - - 3
> - - 2
> - - 1
> - - 0
> -
> - - 7
> - - 6
> - - 5
> - - 4
> - - 3
> - - 2
> - - 1
> - - 0
> * .. _V4L2-PIX-FMT-RGB332:
>
> - ``V4L2_PIX_FMT_RGB332``
> @@ -551,6 +581,82 @@ next to each other in memory.
> - b\ :sub:`1`
> - b\ :sub:`0`
> -
> +
> +.. raw:: latex
> +
> + \endgroup
> +
> +
> +24 or 32 Bits Per Pixel
> +=======================
> +
> +These formats store an RGB triplet in three or four bytes. They are named based
> +on the order of the RGB components as stored in memory, and on the total number
> +of bits per pixel (with an exception for the BGR666 format). For instance,
> +RGB24 format stores a pixel with [R\ :sub:`7` R\ :sub:`6` R\ :sub:`5`
> +R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` R\ :sub:`0`] in the first byte,
> +[G\ :sub:`7` G\ :sub:`6` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2`
> +G\ :sub:`1` G\ :sub:`0`] in the second byte and [B\ :sub:`7` B\ :sub:`6`
> +B\ :sub:`5` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`] in the
> +third byte. This differs from the DRM format nomenclature that instead use the
> +order of components as seen in a 24- or 32-bit little endian word.
> +
> +.. raw:: latex
> +
> + \begingroup
> + \tiny
> + \setlength{\tabcolsep}{2pt}
> +
> +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> +
> +
> +.. flat-table:: RGB Formats With 24 or 32 Bits Per Pixel
> + :header-rows: 2
> + :stub-columns: 0
> +
> + * - Identifier
> + - Code
> + - :cspan:`7` Byte 0 in memory
> + - :cspan:`7` Byte 1
> + - :cspan:`7` Byte 2
> + - :cspan:`7` Byte 3
> + * -
> + -
> + - 7
> + - 6
> + - 5
> + - 4
> + - 3
> + - 2
> + - 1
> + - 0
> +
> + - 7
> + - 6
> + - 5
> + - 4
> + - 3
> + - 2
> + - 1
> + - 0
> +
> + - 7
> + - 6
> + - 5
> + - 4
> + - 3
> + - 2
> + - 1
> + - 0
> +
> + - 7
> + - 6
> + - 5
> + - 4
> + - 3
> + - 2
> + - 1
> + - 0
> * .. _V4L2-PIX-FMT-BGR24:
>
> - ``V4L2_PIX_FMT_BGR24``
> @@ -980,40 +1086,14 @@ next to each other in memory.
>
> \endgroup
>
> -.. note:: Bit 7 is the most significant bit.
> -
> -The usage and value of the alpha bits (a) in the ARGB and ABGR formats
> -(collectively referred to as alpha formats) depend on the device type
> -and hardware operation. :ref:`Capture <capture>` devices (including
> -capture queues of mem-to-mem devices) fill the alpha component in
> -memory. When the device outputs an alpha channel the alpha component
> -will have a meaningful value. Otherwise, when the device doesn't output
> -an alpha channel but can set the alpha bit to a user-configurable value,
> -the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
> -is used to specify that alpha value, and the alpha component of all
> -pixels will be set to the value specified by that control. Otherwise a
> -corresponding format without an alpha component (XRGB or XBGR) must be
> -used instead of an alpha format.
> -
> -:ref:`Output <output>` devices (including output queues of mem-to-mem
> -devices and :ref:`video output overlay <osd>` devices) read the alpha
> -component from memory. When the device processes the alpha channel the
> -alpha component must be filled with meaningful values by applications.
> -Otherwise a corresponding format without an alpha component (XRGB or
> -XBGR) must be used instead of an alpha format.
> -
> -The XRGB and XBGR formats contain undefined bits (-). Applications,
> -devices and drivers must ignore those bits, for both
> -:ref:`capture` and :ref:`output` devices.
> -
>
> Deprecated RGB Formats
> ======================
>
> -Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and
> -must not be used by new drivers. They are documented here for reference.
> -The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in
> -either the corresponding ARGB or XRGB format, depending on the driver.
> +Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and must not be
> +used by new drivers. They are documented here for reference. The meaning of
> +their alpha bits ``(a)`` is ill-defined and they are interpreted as in either
> +the corresponding ARGB or XRGB format, depending on the driver.
>
> .. raw:: latex
>
> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> index f4b66bfb859f..3f5f1cf8d1c0 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -520,7 +520,7 @@ struct v4l2_pix_format {
>
> /* Pixel format FOURCC depth Description */
>
> -/* RGB formats */
> +/* RGB formats (1 or 2 bytes per pixel) */
> #define V4L2_PIX_FMT_RGB332 v4l2_fourcc('R', 'G', 'B', '1') /* 8 RGB-3-3-2 */
> #define V4L2_PIX_FMT_RGB444 v4l2_fourcc('R', '4', '4', '4') /* 16 xxxxrrrr ggggbbbb */
> #define V4L2_PIX_FMT_ARGB444 v4l2_fourcc('A', 'R', '1', '2') /* 16 aaaarrrr ggggbbbb */
> @@ -545,6 +545,8 @@ struct v4l2_pix_format {
> #define V4L2_PIX_FMT_ARGB555X v4l2_fourcc_be('A', 'R', '1', '5') /* 16 ARGB-5-5-5 BE */
> #define V4L2_PIX_FMT_XRGB555X v4l2_fourcc_be('X', 'R', '1', '5') /* 16 XRGB-5-5-5 BE */
> #define V4L2_PIX_FMT_RGB565X v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */
> +
> +/* RGB formats (3 or 4 bytes per pixel) */
> #define V4L2_PIX_FMT_BGR666 v4l2_fourcc('B', 'G', 'R', 'H') /* 18 BGR-6-6-6 */
> #define V4L2_PIX_FMT_BGR24 v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */
> #define V4L2_PIX_FMT_RGB24 v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */
>
Regards,
Hans
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 06/16] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-10-01 13:33 ` Hans Verkuil
@ 2020-11-01 0:11 ` Laurent Pinchart
0 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-11-01 0:11 UTC (permalink / raw)
To: Hans Verkuil; +Cc: linux-media, Sakari Ailus, Dylan Yip, Vishal Sagar
Hi Hans,
On Thu, Oct 01, 2020 at 03:33:51PM +0200, Hans Verkuil wrote:
> On 23/09/2020 04:43, Laurent Pinchart wrote:
> > The naming scheme for the RGB pixel formats has been developed
> > organically, and isn't consistent between formats stored in 1 or 2
> > bytes, and formats stored in 3 or 4 bytes. For the latter category, the
> > names use a components order convention that is the opposite of the
> > first category, and the opposite of DRM pixel formats. This has lead to
>
> lead -> led
>
> > lots of confusion in the past, and would really benefit from being
> > explained more precisely. Do so, which also prepares for the addition of
> > additional RGB pixels formats.
> >
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> > .../userspace-api/media/v4l/pixfmt-rgb.rst | 196 ++++++++++++------
> > include/uapi/linux/videodev2.h | 4 +-
> > 2 files changed, 141 insertions(+), 59 deletions(-)
> >
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > index 3208ec94db4c..32bfd68af425 100644
> > --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > @@ -13,13 +13,63 @@
> > RGB Formats
> > ***********
> >
> > -Description
> > -===========
> > +These formats encode each pixel as a triplet of RGB values. They are packed
> > +formats, meaning that the RGB values for one pixel are stored consecutively in
> > +memory. Multiple pixels are however not packed in the same byte, each pixel
>
> "Multiple pixels are however not packed in the same byte": that's confusing.
> I think it can be dropped and instead just say:
>
> "meaning that the RGB values for one pixel are stored consecutively in memory
> and each pixel consumes an integer number of bytes."
>
> > +consumes an integer number of bytes. When the number of bits required to store
> > +a pixel is not aligned to a byte boundary, the data is padded with additional
> > +bits to fill the remaining byte.
> >
> > -These formats are designed to match the pixel formats of typical PC
> > -graphics frame buffers. They occupy 8, 16, 24 or 32 bits per pixel.
> > -These are all packed-pixel formats, meaning all the data for a pixel lie
> > -next to each other in memory.
> > +The formats differ by the number of bits per RGB component (typically but not
> > +always the same for all components), the order of components in memory, and the
> > +presence of an alpha component or an additional padding byte.
>
> I think you should say: "or additional padding bits". That is consistent with the
> previous paragraph.
>
> > +
> > +The usage and value of the alpha bits in formats that support them (named ARGB
> > +or a permutation thereof, collectively referred to as alpha formats) depend on
> > +the device type and hardware operation. :ref:`Capture <capture>` devices
> > +(including capture queues of mem-to-mem devices) fill the alpha component in
> > +memory. When the device captures an alpha channel the alpha component will have
> > +a meaningful value. Otherwise, when the device doesn't capture an alpha channel
> > +but can set the alpha bit to a user-configurable value, the
> > +:ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control is used to
> > +specify that alpha value, and the alpha component of all pixels will be set to
> > +the value specified by that control. Otherwise a corresponding format without
> > +an alpha component (XRGB or XBGR) must be used instead of an alpha format.
> > +
> > +:ref:`Output <output>` devices (including output queues of mem-to-mem devices
> > +and :ref:`video output overlay <osd>` devices) read the alpha component from
> > +memory. When the device processes the alpha channel the alpha component must be
> > +filled with meaningful values by applications. Otherwise a corresponding format
> > +without an alpha component (XRGB or XBGR) must be used instead of an alpha
> > +format.
> > +
> > +Formats that contain padding bits are named XRGB (or a permutation thereof).
> > +The padding bits contain undefined values and must be ignored by applications,
> > +devices and drivers, for both :ref:`capture` and :ref:`output` devices.
>
> Should we mention here that it is highly desirable that padding bits are set to 0?
I'll adjust the text according to all the previous comments. Here,
however, I'm not sure what purpose this would serve. We can't mandate
that devices write those bits to 0, as not all of them can do so. As a
consequence, to keep applications generic, they can't rely on the bits
being 0, so what difference would it make ? There are 3 categories of
devices I believe:
- Devices that don't write the padding bits or that write them to random
values. This is quite uncommon I believe. Not writing padding bits
would only work when there's a full padding byte, and it would make
DMA pretty inefficient. Writing random values also doesn't make that
much sense. Still, this could be possible, and there's not much we
could do about it.
- Devices that write a hardcoded value. We can't do much in that case,
the value is what it is, drivers can't influence it.
- Devices that write a configurable value. Here the specification
advising drivers to set padding bits to 0 could make a difference.
I think the third category should expose an ARGB format with the alpha
control instead of XRGB, to give flexibility to applications. This
leaves only the first two categories for XRGB formats, and there drivers
don't have any choice. I'd even think that devices that write a
hardcoded value should also expose ARGB formats, with a read-only alpha
control.
We could recommend usage of ARGB over XRGB for the last two categories,
but I think that should go in a separate patch.
> > +
> > +.. note::
> > +
> > + - In all the tables that follow, bit 7 is the most significant bit in a byte.
> > + - 'r', 'g' and 'b' denote bits of the red, green and blue components
> > + respectively. 'a' denotes bits of the the alpha component (if supported by
> > + the format), and '-' denotes padding bits.
> > +
> > +
> > +8 or 16 Bits Per Pixel
> > +======================
> > +
> > +These formats store an RGB triplet in one or two bytes. They are named based on
> > +the order of the RGB components as seen in a 8- or 16-bit word, which is then
> > +stored in memory in little endian byte order (unless otherwise noted by the
> > +presence of bit 31 in the 4CC value), and on the number of bits for each
> > +component. For instance, the RGB565 format stores a pixel in a 16-bit word
> > +[15:0] laid out at as [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
> > +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2` G\ :sub:`1`
> > +G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`], and
> > +stored in memory in two bytes, [R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1`
> > +R\ :sub:`0` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3`] followed by [G\ :sub:`2`
> > +G\ :sub:`1` G\ :sub:`0` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1`
> > +B\ :sub:`0`].
> >
> > .. raw:: latex
> >
> > @@ -27,10 +77,10 @@ next to each other in memory.
> > \tiny
> > \setlength{\tabcolsep}{2pt}
> >
> > -.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> > +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> >
> >
> > -.. flat-table:: RGB Image Formats
> > +.. flat-table:: RGB Formats With 8 or 16 Bits Per Pixel
> > :header-rows: 2
> > :stub-columns: 0
> >
> > @@ -38,8 +88,6 @@ next to each other in memory.
> > - Code
> > - :cspan:`7` Byte 0 in memory
> > - :cspan:`7` Byte 1
> > - - :cspan:`7` Byte 2
> > - - :cspan:`7` Byte 3
> > * -
> > -
> > - 7
> > @@ -59,24 +107,6 @@ next to each other in memory.
> > - 2
> > - 1
> > - 0
> > -
> > - - 7
> > - - 6
> > - - 5
> > - - 4
> > - - 3
> > - - 2
> > - - 1
> > - - 0
> > -
> > - - 7
> > - - 6
> > - - 5
> > - - 4
> > - - 3
> > - - 2
> > - - 1
> > - - 0
> > * .. _V4L2-PIX-FMT-RGB332:
> >
> > - ``V4L2_PIX_FMT_RGB332``
> > @@ -551,6 +581,82 @@ next to each other in memory.
> > - b\ :sub:`1`
> > - b\ :sub:`0`
> > -
> > +
> > +.. raw:: latex
> > +
> > + \endgroup
> > +
> > +
> > +24 or 32 Bits Per Pixel
> > +=======================
> > +
> > +These formats store an RGB triplet in three or four bytes. They are named based
> > +on the order of the RGB components as stored in memory, and on the total number
> > +of bits per pixel (with an exception for the BGR666 format). For instance,
> > +RGB24 format stores a pixel with [R\ :sub:`7` R\ :sub:`6` R\ :sub:`5`
> > +R\ :sub:`4` R\ :sub:`3` R\ :sub:`2` R\ :sub:`1` R\ :sub:`0`] in the first byte,
> > +[G\ :sub:`7` G\ :sub:`6` G\ :sub:`5` G\ :sub:`4` G\ :sub:`3` G\ :sub:`2`
> > +G\ :sub:`1` G\ :sub:`0`] in the second byte and [B\ :sub:`7` B\ :sub:`6`
> > +B\ :sub:`5` B\ :sub:`4` B\ :sub:`3` B\ :sub:`2` B\ :sub:`1` B\ :sub:`0`] in the
> > +third byte. This differs from the DRM format nomenclature that instead use the
> > +order of components as seen in a 24- or 32-bit little endian word.
> > +
> > +.. raw:: latex
> > +
> > + \begingroup
> > + \tiny
> > + \setlength{\tabcolsep}{2pt}
> > +
> > +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
> > +
> > +
> > +.. flat-table:: RGB Formats With 24 or 32 Bits Per Pixel
> > + :header-rows: 2
> > + :stub-columns: 0
> > +
> > + * - Identifier
> > + - Code
> > + - :cspan:`7` Byte 0 in memory
> > + - :cspan:`7` Byte 1
> > + - :cspan:`7` Byte 2
> > + - :cspan:`7` Byte 3
> > + * -
> > + -
> > + - 7
> > + - 6
> > + - 5
> > + - 4
> > + - 3
> > + - 2
> > + - 1
> > + - 0
> > +
> > + - 7
> > + - 6
> > + - 5
> > + - 4
> > + - 3
> > + - 2
> > + - 1
> > + - 0
> > +
> > + - 7
> > + - 6
> > + - 5
> > + - 4
> > + - 3
> > + - 2
> > + - 1
> > + - 0
> > +
> > + - 7
> > + - 6
> > + - 5
> > + - 4
> > + - 3
> > + - 2
> > + - 1
> > + - 0
> > * .. _V4L2-PIX-FMT-BGR24:
> >
> > - ``V4L2_PIX_FMT_BGR24``
> > @@ -980,40 +1086,14 @@ next to each other in memory.
> >
> > \endgroup
> >
> > -.. note:: Bit 7 is the most significant bit.
> > -
> > -The usage and value of the alpha bits (a) in the ARGB and ABGR formats
> > -(collectively referred to as alpha formats) depend on the device type
> > -and hardware operation. :ref:`Capture <capture>` devices (including
> > -capture queues of mem-to-mem devices) fill the alpha component in
> > -memory. When the device outputs an alpha channel the alpha component
> > -will have a meaningful value. Otherwise, when the device doesn't output
> > -an alpha channel but can set the alpha bit to a user-configurable value,
> > -the :ref:`V4L2_CID_ALPHA_COMPONENT <v4l2-alpha-component>` control
> > -is used to specify that alpha value, and the alpha component of all
> > -pixels will be set to the value specified by that control. Otherwise a
> > -corresponding format without an alpha component (XRGB or XBGR) must be
> > -used instead of an alpha format.
> > -
> > -:ref:`Output <output>` devices (including output queues of mem-to-mem
> > -devices and :ref:`video output overlay <osd>` devices) read the alpha
> > -component from memory. When the device processes the alpha channel the
> > -alpha component must be filled with meaningful values by applications.
> > -Otherwise a corresponding format without an alpha component (XRGB or
> > -XBGR) must be used instead of an alpha format.
> > -
> > -The XRGB and XBGR formats contain undefined bits (-). Applications,
> > -devices and drivers must ignore those bits, for both
> > -:ref:`capture` and :ref:`output` devices.
> > -
> >
> > Deprecated RGB Formats
> > ======================
> >
> > -Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and
> > -must not be used by new drivers. They are documented here for reference.
> > -The meaning of their alpha bits ``(a)`` are ill-defined and interpreted as in
> > -either the corresponding ARGB or XRGB format, depending on the driver.
> > +Formats defined in :ref:`pixfmt-rgb-deprecated` are deprecated and must not be
> > +used by new drivers. They are documented here for reference. The meaning of
> > +their alpha bits ``(a)`` is ill-defined and they are interpreted as in either
> > +the corresponding ARGB or XRGB format, depending on the driver.
> >
> > .. raw:: latex
> >
> > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > index f4b66bfb859f..3f5f1cf8d1c0 100644
> > --- a/include/uapi/linux/videodev2.h
> > +++ b/include/uapi/linux/videodev2.h
> > @@ -520,7 +520,7 @@ struct v4l2_pix_format {
> >
> > /* Pixel format FOURCC depth Description */
> >
> > -/* RGB formats */
> > +/* RGB formats (1 or 2 bytes per pixel) */
> > #define V4L2_PIX_FMT_RGB332 v4l2_fourcc('R', 'G', 'B', '1') /* 8 RGB-3-3-2 */
> > #define V4L2_PIX_FMT_RGB444 v4l2_fourcc('R', '4', '4', '4') /* 16 xxxxrrrr ggggbbbb */
> > #define V4L2_PIX_FMT_ARGB444 v4l2_fourcc('A', 'R', '1', '2') /* 16 aaaarrrr ggggbbbb */
> > @@ -545,6 +545,8 @@ struct v4l2_pix_format {
> > #define V4L2_PIX_FMT_ARGB555X v4l2_fourcc_be('A', 'R', '1', '5') /* 16 ARGB-5-5-5 BE */
> > #define V4L2_PIX_FMT_XRGB555X v4l2_fourcc_be('X', 'R', '1', '5') /* 16 XRGB-5-5-5 BE */
> > #define V4L2_PIX_FMT_RGB565X v4l2_fourcc('R', 'G', 'B', 'R') /* 16 RGB-5-6-5 BE */
> > +
> > +/* RGB formats (3 or 4 bytes per pixel) */
> > #define V4L2_PIX_FMT_BGR666 v4l2_fourcc('B', 'G', 'R', 'H') /* 18 BGR-6-6-6 */
> > #define V4L2_PIX_FMT_BGR24 v4l2_fourcc('B', 'G', 'R', '3') /* 24 BGR-8-8-8 */
> > #define V4L2_PIX_FMT_RGB24 v4l2_fourcc('R', 'G', 'B', '3') /* 24 RGB-8-8-8 */
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH/RFC 07/16] media: doc: pixfmt-yuv: Document subsampling in more details
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (5 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 06/16] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 08/16] media: doc: pixfmt-yuv: Move all packed YUV formats to common file Laurent Pinchart
` (8 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Document YUV subsampling, including chroma spatial siting, and replace
the siting examples in individual formats by references to the common
documentation.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../userspace-api/media/v4l/pixfmt-m420.rst | 59 +----
.../userspace-api/media/v4l/pixfmt-nv12.rst | 57 +---
.../userspace-api/media/v4l/pixfmt-nv12m.rst | 60 +----
.../userspace-api/media/v4l/pixfmt-nv16.rst | 73 +----
.../userspace-api/media/v4l/pixfmt-nv16m.rst | 73 +----
.../userspace-api/media/v4l/pixfmt-uyvy.rst | 44 +--
.../userspace-api/media/v4l/pixfmt-vyuy.rst | 42 +--
.../userspace-api/media/v4l/pixfmt-y41p.rst | 62 +----
.../userspace-api/media/v4l/pixfmt-yuv410.rst | 59 +----
.../media/v4l/pixfmt-yuv411p.rst | 39 +--
.../userspace-api/media/v4l/pixfmt-yuv420.rst | 66 +----
.../media/v4l/pixfmt-yuv420m.rst | 66 +----
.../media/v4l/pixfmt-yuv422m.rst | 44 +--
.../media/v4l/pixfmt-yuv422p.rst | 44 +--
.../media/v4l/pixfmt-yuv444m.rst | 33 +--
.../userspace-api/media/v4l/pixfmt-yuyv.rst | 49 +---
.../userspace-api/media/v4l/pixfmt-yvyu.rst | 42 +--
.../userspace-api/media/v4l/yuv-formats.rst | 250 +++++++++++++++++-
18 files changed, 278 insertions(+), 884 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst
index 5180bbe16c6e..38c2bde6a87d 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst
@@ -74,60 +74,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- - 2
- -
- - 3
- * - 0
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * - 1
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- * - 2
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * - 3
- - Y
- -
- - Y
- - Y
- -
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally and vertically.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst
index 19d47b38e02a..26d7df9e1298 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst
@@ -79,58 +79,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- - 2
- -
- - 3
- * - 0
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * - 1
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- * - 2
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * - 3
- - Y
- -
- - Y
- - Y
- -
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally and vertically.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst
index 115ea603c13f..752c42a0f52c 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst
@@ -91,61 +91,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- - 2
- -
- - 3
- * - 0
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * - 1
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- * - 2
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- -
- - C
- -
- * - 3
- - Y
- -
- - Y
- - Y
- -
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally and vertically.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst
index 977636fc98d6..82659557daae 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst
@@ -87,74 +87,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- - 2
- -
- - 3
- * - 0
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * - 1
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * -
- * - 2
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * - 3
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst
index cf33942d942d..3e8ae54c846e 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst
@@ -91,74 +91,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- - 2
- -
- - 3
- * - 0
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * - 1
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * -
- * - 2
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
- * - 3
- - Y
- -
- - Y
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- - C
- -
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst b/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst
index 776cb37f76f1..5571d771af89 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst
@@ -73,45 +73,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- - 2
- -
- - 3
- * - 0
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 1
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 2
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 3
- - Y
- - C
- - Y
- - Y
- - C
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst b/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst
index 6cd574e78e4c..3d0dce59c591 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst
@@ -73,43 +73,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- -
- - 2
- - 3
- * - 0
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 1
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 2
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 3
- - Y
- - C
- - Y
- - Y
- - C
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst
index 211afd7593cc..880e87490b25 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst
@@ -96,63 +96,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- - 1
- -
- - 2
- - 3
- - 4
- - 5
- -
- - 6
- - 7
- * - 0
- - Y
- - Y
- - C
- - Y
- - Y
- - Y
- - Y
- - C
- - Y
- - Y
- * - 1
- - Y
- - Y
- - C
- - Y
- - Y
- - Y
- - Y
- - C
- - Y
- - Y
- * - 2
- - Y
- - Y
- - C
- - Y
- - Y
- - Y
- - Y
- - C
- - Y
- - Y
- * - 3
- - Y
- - Y
- - C
- - Y
- - Y
- - Y
- - Y
- - C
- - Y
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst
index 1d20115f2b1d..b4b0bcd96f6e 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst
@@ -75,60 +75,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- -
- - 2
- -
- - 3
- * - 0
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
- * -
- * - 1
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
- * -
- -
- -
- -
- - C
- -
- -
- -
- * - 2
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
- * -
- * - 3
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally and vertically.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst
index 967ba7ce41a2..65d5a9b54500 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst
@@ -83,40 +83,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- - 1
- -
- - 2
- - 3
- * - 0
- - Y
- - Y
- - C
- - Y
- - Y
- * - 1
- - Y
- - Y
- - C
- - Y
- - Y
- * - 2
- - Y
- - Y
- - C
- - Y
- - Y
- * - 3
- - Y
- - Y
- - C
- - Y
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst
index 7cb685cc8289..cc1a5df03248 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst
@@ -84,67 +84,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- -
- - 2
- -
- - 3
- * - 0
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- -
- - C
- -
- * - 1
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
- * -
- * - 2
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- -
- - C
- -
- * - 3
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally and vertically.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst
index 80c14d4f5acb..d189903d8ff3 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst
@@ -93,67 +93,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- -
- - 2
- -
- - 3
- * - 0
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- -
- - C
- -
- * - 1
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
- * -
- * - 2
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
- * -
- -
- - C
- -
- -
- -
- - C
- -
- * - 3
- - Y
- -
- - Y
- -
- - Y
- -
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally and vertically.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst
index 29b78480ccad..5ffea984a160 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst
@@ -104,45 +104,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- - 2
- -
- - 3
- * - 0
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 1
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 2
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 3
- - Y
- - C
- - Y
- - Y
- - C
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst
index 73fde222d820..ee4e7badbf4c 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst
@@ -92,45 +92,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- - 2
- -
- - 3
- * - 0
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 1
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 2
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 3
- - Y
- - C
- - Y
- - Y
- - C
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst
index 7073ac7f842d..52ebc67d7ebe 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst
@@ -114,35 +114,4 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- - 1
- - 2
- - 3
- * - 0
- - YC
- - YC
- - YC
- - YC
- * - 1
- - YC
- - YC
- - YC
- - YC
- * - 2
- - YC
- - YC
- - YC
- - YC
- * - 3
- - YC
- - YC
- - YC
- - YC
+Chroma samples are :ref:`co-sited<yuv-chroma-cosited>`.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst
index fe70e007787d..0ad1169b221f 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst
@@ -76,50 +76,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- -
- - 2
- -
- - 3
- * - 0
- - Y
- - C
- - Y
- -
- - Y
- - C
- - Y
- * - 1
- - Y
- - C
- - Y
- -
- - Y
- - C
- - Y
- * - 2
- - Y
- - C
- - Y
- -
- - Y
- - C
- - Y
- * - 3
- - Y
- - C
- - Y
- -
- - Y
- - C
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst b/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst
index 96c1b537d5a0..c9f35d7183c5 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst
@@ -73,43 +73,5 @@ Each cell is one byte.
**Color Sample Location:**
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * -
- - 0
- -
- - 1
- - 2
- -
- - 3
- * - 0
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 1
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 2
- - Y
- - C
- - Y
- - Y
- - C
- - Y
- * - 3
- - Y
- - C
- - Y
- - Y
- - C
- - Y
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst
index 8ee92d0cd769..77ab71c7d0f5 100644
--- a/Documentation/userspace-api/media/v4l/yuv-formats.rst
+++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst
@@ -21,11 +21,251 @@ reconstructed by subtracting from the brightness component. See
:ref:`colorspaces` for conversion examples. YUV was chosen because
early television would only transmit brightness information. To add
color in a way compatible with existing receivers a new signal carrier
-was added to transmit the color difference signals. Secondary in the YUV
-format the U and V components usually have lower resolution than the Y
-component. This is an analog video compression technique taking
-advantage of a property of the human visual system, being more sensitive
-to brightness information.
+was added to transmit the color difference signals.
+
+
+Subsampling
+===========
+
+YUV formats commonly encode images with a lower resolution for the chroma
+components than for the luma component. This compression technique, taking
+advantage of the human eye being more sensitive to luminance than color
+differences, is called chroma subsampling.
+
+While many combinations of subsampling factors in the horizontal and vertical
+direction are possible, common factors are 1 (no subsampling), 2 and 4, with
+horizontal subsampling always larger than or equal to vertical subsampling.
+Common combinations are named as follows.
+
+- `4:4:4`: No subsampling
+- `4:2:2`: Horizontal subsampling by 2, no vertical subsampling
+- `4:2:0`: Horizontal subsampling by 2, vertical subsampling by 2
+- `4:1:1`: Horizontal subsampling by 4, no vertical subsampling
+- `4:1:0`: Horizontal subsampling by 4, vertical subsampling by 4
+
+Subsampling the chroma component effectively creates chroma values that can be
+located in different spatial locations:
+
+- .. _yuv-chroma-centered:
+
+ The subsampled chroma value may be calculated by simply averaging the chroma
+ value of two consecutive pixels. It effectively models the chroma of a pixel
+ sited between the two original pixels. This is referred to as centered or
+ interstitially sited chroma.
+
+- .. _yuv-chroma-cosited:
+
+ The other option is to subsample chroma values in a way that place them in
+ the same spatial sites as the pixels. This may be performed by skipping every
+ other chroma sample (creating aliasing artifacts), or with filters using an
+ odd number of taps. This is referred to as co-sited chroma.
+
+The following examples show different combination of chroma siting in a 4x4
+image.
+
+.. flat-table:: 4:2:2 subsampling, interstitially sited
+ :header-rows: 1
+ :stub-columns: 1
+
+ * -
+ - 0
+ -
+ - 1
+ -
+ - 2
+ -
+ - 3
+ * - 0
+ - Y
+ - C
+ - Y
+ -
+ - Y
+ - C
+ - Y
+ * - 1
+ - Y
+ - C
+ - Y
+ -
+ - Y
+ - C
+ - Y
+ * - 2
+ - Y
+ - C
+ - Y
+ -
+ - Y
+ - C
+ - Y
+ * - 3
+ - Y
+ - C
+ - Y
+ -
+ - Y
+ - C
+ - Y
+
+.. flat-table:: 4:2:2 subsampling, co-sited
+ :header-rows: 1
+ :stub-columns: 1
+
+ * -
+ - 0
+ -
+ - 1
+ -
+ - 2
+ -
+ - 3
+ * - 0
+ - Y/C
+ -
+ - Y
+ -
+ - Y/C
+ -
+ - Y
+ * - 1
+ - Y/C
+ -
+ - Y
+ -
+ - Y/C
+ -
+ - Y
+ * - 2
+ - Y/C
+ -
+ - Y
+ -
+ - Y/C
+ -
+ - Y
+ * - 3
+ - Y/C
+ -
+ - Y
+ -
+ - Y/C
+ -
+ - Y
+
+.. flat-table:: 4:2:0 subsampling, horizontally interstitially sited, vertically co-sited
+ :header-rows: 1
+ :stub-columns: 1
+
+ * -
+ - 0
+ -
+ - 1
+ -
+ - 2
+ -
+ - 3
+ * - 0
+ - Y
+ - C
+ - Y
+ -
+ - Y
+ - C
+ - Y
+ * - 1
+ - Y
+ -
+ - Y
+ -
+ - Y
+ -
+ - Y
+ * - 2
+ - Y
+ - C
+ - Y
+ -
+ - Y
+ - C
+ - Y
+ * - 3
+ - Y
+ -
+ - Y
+ -
+ - Y
+ -
+ - Y
+
+.. flat-table:: 4:1:0 subsampling, horizontally and vertically interstitially sited
+ :header-rows: 1
+ :stub-columns: 1
+
+ * -
+ - 0
+ -
+ - 1
+ -
+ - 2
+ -
+ - 3
+ * - 0
+ - Y
+ -
+ - Y
+ -
+ - Y
+ -
+ - Y
+ * -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ * - 1
+ - Y
+ -
+ - Y
+ -
+ - Y
+ -
+ - Y
+ * -
+ -
+ -
+ -
+ - C
+ -
+ -
+ -
+ * - 2
+ - Y
+ -
+ - Y
+ -
+ - Y
+ -
+ - Y
+ * -
+ -
+ -
+ -
+ -
+ -
+ -
+ -
+ * - 3
+ - Y
+ -
+ - Y
+ -
+ - Y
+ -
+ - Y
.. toctree::
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 08/16] media: doc: pixfmt-yuv: Move all packed YUV formats to common file
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (6 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 07/16] media: doc: pixfmt-yuv: Document subsampling in more details Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 09/16] media: doc: pixfmt-packed-yuv: Fill padding bits with '-' Laurent Pinchart
` (7 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
The pixfmt-packed-yuv.rst file documents packed YUV 4:4:4 formats, but
is titled generically as "Packed YUV formats". 4:2:2 and 4:1:1 packed
YUV formats are documented in separate files, which can be confusing.
Group all packed YUV formats in pixfmt-packed-yuv.rst, which allows
documenting the 4:2:2 formats in a more concise way.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../media/v4l/pixfmt-packed-yuv.rst | 147 +++++++++++++++++-
.../userspace-api/media/v4l/pixfmt-uyvy.rst | 77 ---------
.../userspace-api/media/v4l/pixfmt-vyuy.rst | 77 ---------
.../userspace-api/media/v4l/pixfmt-y41p.rst | 100 ------------
.../userspace-api/media/v4l/pixfmt-yuyv.rst | 80 ----------
.../userspace-api/media/v4l/pixfmt-yvyu.rst | 77 ---------
.../userspace-api/media/v4l/yuv-formats.rst | 5 -
7 files changed, 140 insertions(+), 423 deletions(-)
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y41p.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
index bbd4bd094deb..08b4361ba879 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -13,12 +13,16 @@
Packed YUV formats
******************
-Description
-===========
+Similarly to the packed RGB formats, the packed YUV formats store the Y, Cb and
+Cr components consecutively in memory. They may apply subsampling to the chroma
+components and thus differ in how they interlave the three components.
-Similar to the packed RGB formats these formats store the Y, Cb and Cr
-component of each pixel in one 16 or 32 bit word.
+4:4:4 Subsampling
+=================
+
+These formats do not subsample the chroma components and store each pixels as a
+full triplet of Y, Cb and Cr values.
.. raw:: latex
@@ -26,11 +30,9 @@ component of each pixel in one 16 or 32 bit word.
\tiny
\setlength{\tabcolsep}{2pt}
-.. _packed-yuv-formats:
-
.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|
-.. flat-table:: Packed YUV Image Formats
+.. flat-table:: Packed YUV 4:4:4 Image Formats
:header-rows: 2
:stub-columns: 0
@@ -378,3 +380,134 @@ component of each pixel in one 16 or 32 bit word.
expected to contain a meaningful value that can be used by drivers
and applications. And, the formats XYUV32 and VUYX32 contain undefined
alpha values that must be ignored by all applications and drivers.
+
+
+4:2:2 Subsampling
+=================
+
+These formats, commonly referred to as YUYV or YUY2, subsample the chroma
+components horizontally by 2, storing 2 pixels in 4 bytes.
+
+.. flat-table:: Packed YUV 4:2:2 Formats
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - Byte 0
+ - Byte 1
+ - Byte 2
+ - Byte 3
+ - Byte 4
+ - Byte 5
+ - Byte 6
+ - Byte 7
+ * .. _V4L2-PIX-FMT-UYVY:
+
+ - ``V4L2_PIX_FMT_UYVY``
+ - 'UYVY'
+
+ - Cb\ :sub:`0`
+ - Y'\ :sub:`0`
+ - Cr\ :sub:`0`
+ - Y'\ :sub:`1`
+ - Cb\ :sub:`2`
+ - Y'\ :sub:`2`
+ - Cr\ :sub:`2`
+ - Y'\ :sub:`3`
+ * .. _V4L2-PIX-FMT-VYUY:
+
+ - ``V4L2_PIX_FMT_VYUY``
+ - 'VYUY'
+
+ - Cr\ :sub:`0`
+ - Y'\ :sub:`0`
+ - Cb\ :sub:`0`
+ - Y'\ :sub:`1`
+ - Cr\ :sub:`2`
+ - Y'\ :sub:`2`
+ - Cb\ :sub:`2`
+ - Y'\ :sub:`3`
+ * .. _V4L2-PIX-FMT-YUYV:
+
+ - ``V4L2_PIX_FMT_YUYV``
+ - 'YUYV'
+
+ - Y'\ :sub:`0`
+ - Cb\ :sub:`0`
+ - Y'\ :sub:`1`
+ - Cr\ :sub:`0`
+ - Y'\ :sub:`2`
+ - Cb\ :sub:`2`
+ - Y'\ :sub:`3`
+ - Cr\ :sub:`2`
+ * .. _V4L2-PIX-FMT-YVYU:
+
+ - ``V4L2_PIX_FMT_YVYU``
+ - 'YVYU'
+
+ - Y'\ :sub:`0`
+ - Cr\ :sub:`0`
+ - Y'\ :sub:`1`
+ - Cb\ :sub:`0`
+ - Y'\ :sub:`2`
+ - Cr\ :sub:`2`
+ - Y'\ :sub:`3`
+ - Cb\ :sub:`2`
+
+**Color Sample Location:**
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
+
+
+4:1:1 Subsampling
+=================
+
+This format subsamples the chroma components horizontally by 4, storing 8
+pixels in 12 bytes.
+
+.. flat-table:: Packed YUV 4:1:1 Formats
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - Byte 0
+ - Byte 1
+ - Byte 2
+ - Byte 3
+ - Byte 4
+ - Byte 5
+ - Byte 6
+ - Byte 7
+ - Byte 8
+ - Byte 9
+ - Byte 10
+ - Byte 11
+ * .. _V4L2-PIX-FMT-Y41P:
+
+ - ``V4L2_PIX_FMT_Y41P``
+ - 'Y41P'
+
+ - Cb\ :sub:`0`
+ - Y'\ :sub:`0`
+ - Cr\ :sub:`0`
+ - Y'\ :sub:`1`
+ - Cb\ :sub:`4`
+ - Y'\ :sub:`2`
+ - Cr\ :sub:`4`
+ - Y'\ :sub:`3`
+ - Y'\ :sub:`4`
+ - Y'\ :sub:`5`
+ - Y'\ :sub:`6`
+ - Y'\ :sub:`7`
+
+.. note::
+
+ Do not confuse ``V4L2_PIX_FMT_Y41P`` with
+ :ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived from
+ "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1 *planar*".
+
+**Color Sample Location:**
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst b/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst
deleted file mode 100644
index 5571d771af89..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-UYVY:
-
-**************************
-V4L2_PIX_FMT_UYVY ('UYVY')
-**************************
-
-
-Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
-memory
-
-
-Description
-===========
-
-In this format each four bytes is two pixels. Each four bytes is two
-Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
-belong to both pixels. As you can see, the Cr and Cb components have
-half the horizontal resolution of the Y component.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Cb\ :sub:`00`
- - Y'\ :sub:`00`
- - Cr\ :sub:`00`
- - Y'\ :sub:`01`
- - Cb\ :sub:`01`
- - Y'\ :sub:`02`
- - Cr\ :sub:`01`
- - Y'\ :sub:`03`
- * - start + 8:
- - Cb\ :sub:`10`
- - Y'\ :sub:`10`
- - Cr\ :sub:`10`
- - Y'\ :sub:`11`
- - Cb\ :sub:`11`
- - Y'\ :sub:`12`
- - Cr\ :sub:`11`
- - Y'\ :sub:`13`
- * - start + 16:
- - Cb\ :sub:`20`
- - Y'\ :sub:`20`
- - Cr\ :sub:`20`
- - Y'\ :sub:`21`
- - Cb\ :sub:`21`
- - Y'\ :sub:`22`
- - Cr\ :sub:`21`
- - Y'\ :sub:`23`
- * - start + 24:
- - Cb\ :sub:`30`
- - Y'\ :sub:`30`
- - Cr\ :sub:`30`
- - Y'\ :sub:`31`
- - Cb\ :sub:`31`
- - Y'\ :sub:`32`
- - Cr\ :sub:`31`
- - Y'\ :sub:`33`
-
-
-**Color Sample Location:**
-Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
-horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst b/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst
deleted file mode 100644
index 3d0dce59c591..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-VYUY:
-
-**************************
-V4L2_PIX_FMT_VYUY ('VYUY')
-**************************
-
-
-Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
-memory
-
-
-Description
-===========
-
-In this format each four bytes is two pixels. Each four bytes is two
-Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
-belong to both pixels. As you can see, the Cr and Cb components have
-half the horizontal resolution of the Y component.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Cr\ :sub:`00`
- - Y'\ :sub:`00`
- - Cb\ :sub:`00`
- - Y'\ :sub:`01`
- - Cr\ :sub:`01`
- - Y'\ :sub:`02`
- - Cb\ :sub:`01`
- - Y'\ :sub:`03`
- * - start + 8:
- - Cr\ :sub:`10`
- - Y'\ :sub:`10`
- - Cb\ :sub:`10`
- - Y'\ :sub:`11`
- - Cr\ :sub:`11`
- - Y'\ :sub:`12`
- - Cb\ :sub:`11`
- - Y'\ :sub:`13`
- * - start + 16:
- - Cr\ :sub:`20`
- - Y'\ :sub:`20`
- - Cb\ :sub:`20`
- - Y'\ :sub:`21`
- - Cr\ :sub:`21`
- - Y'\ :sub:`22`
- - Cb\ :sub:`21`
- - Y'\ :sub:`23`
- * - start + 24:
- - Cr\ :sub:`30`
- - Y'\ :sub:`30`
- - Cb\ :sub:`30`
- - Y'\ :sub:`31`
- - Cr\ :sub:`31`
- - Y'\ :sub:`32`
- - Cb\ :sub:`31`
- - Y'\ :sub:`33`
-
-
-**Color Sample Location:**
-Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
-horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst
deleted file mode 100644
index 880e87490b25..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst
+++ /dev/null
@@ -1,100 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-Y41P:
-
-**************************
-V4L2_PIX_FMT_Y41P ('Y41P')
-**************************
-
-
-Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1
-
-
-Description
-===========
-
-In this format each 12 bytes is eight pixels. In the twelve bytes are
-two CbCr pairs and eight Y's. The first CbCr pair goes with the first
-four Y's, and the second CbCr pair goes with the other four Y's. The Cb
-and Cr components have one fourth the horizontal resolution of the Y
-component.
-
-Do not confuse this format with
-:ref:`V4L2_PIX_FMT_YUV411P <V4L2-PIX-FMT-YUV411P>`. Y41P is derived
-from "YUV 4:1:1 *packed*", while YUV411P stands for "YUV 4:1:1
-*planar*".
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Cb\ :sub:`00`
- - Y'\ :sub:`00`
- - Cr\ :sub:`00`
- - Y'\ :sub:`01`
- - Cb\ :sub:`01`
- - Y'\ :sub:`02`
- - Cr\ :sub:`01`
- - Y'\ :sub:`03`
- - Y'\ :sub:`04`
- - Y'\ :sub:`05`
- - Y'\ :sub:`06`
- - Y'\ :sub:`07`
- * - start + 12:
- - Cb\ :sub:`10`
- - Y'\ :sub:`10`
- - Cr\ :sub:`10`
- - Y'\ :sub:`11`
- - Cb\ :sub:`11`
- - Y'\ :sub:`12`
- - Cr\ :sub:`11`
- - Y'\ :sub:`13`
- - Y'\ :sub:`14`
- - Y'\ :sub:`15`
- - Y'\ :sub:`16`
- - Y'\ :sub:`17`
- * - start + 24:
- - Cb\ :sub:`20`
- - Y'\ :sub:`20`
- - Cr\ :sub:`20`
- - Y'\ :sub:`21`
- - Cb\ :sub:`21`
- - Y'\ :sub:`22`
- - Cr\ :sub:`21`
- - Y'\ :sub:`23`
- - Y'\ :sub:`24`
- - Y'\ :sub:`25`
- - Y'\ :sub:`26`
- - Y'\ :sub:`27`
- * - start + 36:
- - Cb\ :sub:`30`
- - Y'\ :sub:`30`
- - Cr\ :sub:`30`
- - Y'\ :sub:`31`
- - Cb\ :sub:`31`
- - Y'\ :sub:`32`
- - Cr\ :sub:`31`
- - Y'\ :sub:`33`
- - Y'\ :sub:`34`
- - Y'\ :sub:`35`
- - Y'\ :sub:`36`
- - Y'\ :sub:`37`
-
-
-**Color Sample Location:**
-Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
-horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst
deleted file mode 100644
index 0ad1169b221f..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-YUYV:
-
-**************************
-V4L2_PIX_FMT_YUYV ('YUYV')
-**************************
-
-
-Packed format with ½ horizontal chroma resolution, also known as YUV
-4:2:2
-
-
-Description
-===========
-
-In this format each four bytes is two pixels. Each four bytes is two
-Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
-belong to both pixels. As you can see, the Cr and Cb components have
-half the horizontal resolution of the Y component. ``V4L2_PIX_FMT_YUYV``
-is known in the Windows environment as YUY2.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Y'\ :sub:`00`
- - Cb\ :sub:`00`
- - Y'\ :sub:`01`
- - Cr\ :sub:`00`
- - Y'\ :sub:`02`
- - Cb\ :sub:`01`
- - Y'\ :sub:`03`
- - Cr\ :sub:`01`
- * - start + 8:
- - Y'\ :sub:`10`
- - Cb\ :sub:`10`
- - Y'\ :sub:`11`
- - Cr\ :sub:`10`
- - Y'\ :sub:`12`
- - Cb\ :sub:`11`
- - Y'\ :sub:`13`
- - Cr\ :sub:`11`
- * - start + 16:
- - Y'\ :sub:`20`
- - Cb\ :sub:`20`
- - Y'\ :sub:`21`
- - Cr\ :sub:`20`
- - Y'\ :sub:`22`
- - Cb\ :sub:`21`
- - Y'\ :sub:`23`
- - Cr\ :sub:`21`
- * - start + 24:
- - Y'\ :sub:`30`
- - Cb\ :sub:`30`
- - Y'\ :sub:`31`
- - Cr\ :sub:`30`
- - Y'\ :sub:`32`
- - Cb\ :sub:`31`
- - Y'\ :sub:`33`
- - Cr\ :sub:`31`
-
-
-**Color Sample Location:**
-Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
-horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst b/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst
deleted file mode 100644
index c9f35d7183c5..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-YVYU:
-
-**************************
-V4L2_PIX_FMT_YVYU ('YVYU')
-**************************
-
-
-Variation of ``V4L2_PIX_FMT_YUYV`` with different order of samples in
-memory
-
-
-Description
-===========
-
-In this format each four bytes is two pixels. Each four bytes is two
-Y's, a Cb and a Cr. Each Y goes to one of the pixels, and the Cb and Cr
-belong to both pixels. As you can see, the Cr and Cb components have
-half the horizontal resolution of the Y component.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Y'\ :sub:`00`
- - Cr\ :sub:`00`
- - Y'\ :sub:`01`
- - Cb\ :sub:`00`
- - Y'\ :sub:`02`
- - Cr\ :sub:`01`
- - Y'\ :sub:`03`
- - Cb\ :sub:`01`
- * - start + 8:
- - Y'\ :sub:`10`
- - Cr\ :sub:`10`
- - Y'\ :sub:`11`
- - Cb\ :sub:`10`
- - Y'\ :sub:`12`
- - Cr\ :sub:`11`
- - Y'\ :sub:`13`
- - Cb\ :sub:`11`
- * - start + 16:
- - Y'\ :sub:`20`
- - Cr\ :sub:`20`
- - Y'\ :sub:`21`
- - Cb\ :sub:`20`
- - Y'\ :sub:`22`
- - Cr\ :sub:`21`
- - Y'\ :sub:`23`
- - Cb\ :sub:`21`
- * - start + 24:
- - Y'\ :sub:`30`
- - Cr\ :sub:`30`
- - Y'\ :sub:`31`
- - Cb\ :sub:`30`
- - Y'\ :sub:`32`
- - Cr\ :sub:`31`
- - Y'\ :sub:`33`
- - Cb\ :sub:`31`
-
-
-**Color Sample Location:**
-Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
-horizontally.
diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst
index 77ab71c7d0f5..afe4f7956e7f 100644
--- a/Documentation/userspace-api/media/v4l/yuv-formats.rst
+++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst
@@ -283,11 +283,6 @@ image.
pixfmt-y8i
pixfmt-y12i
pixfmt-uv8
- pixfmt-yuyv
- pixfmt-uyvy
- pixfmt-yvyu
- pixfmt-vyuy
- pixfmt-y41p
pixfmt-yuv420
pixfmt-yuv420m
pixfmt-yuv422m
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 09/16] media: doc: pixfmt-packed-yuv: Fill padding bits with '-'
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (7 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 08/16] media: doc: pixfmt-yuv: Move all packed YUV formats to common file Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 10/16] media: doc: pixfmt-packed-yuv: Express 4:4:4 formats in a more compact way Laurent Pinchart
` (6 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
The padding bits are left blank, which look weird in the XYUV format,
and, worse, may lead to the VUYX format to be understand as consuming 3
bytes per pixel. Add '-' for padding bits as we do for RGB formats.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../media/v4l/pixfmt-packed-yuv.rst | 32 +++++++++----------
1 file changed, 16 insertions(+), 16 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
index 08b4361ba879..c4ee8d5ac668 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -246,14 +246,14 @@ full triplet of Y, Cb and Cr values.
- ``V4L2_PIX_FMT_XYUV32``
- 'XYUV'
- -
- -
- -
- -
- -
- -
- -
- -
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
- Y'\ :sub:`7`
- Y'\ :sub:`6`
@@ -355,14 +355,14 @@ full triplet of Y, Cb and Cr values.
- Y'\ :sub:`1`
- Y'\ :sub:`0`
- -
- -
- -
- -
- -
- -
- -
- -
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
.. raw:: latex
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 10/16] media: doc: pixfmt-packed-yuv: Express 4:4:4 formats in a more compact way
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (8 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 09/16] media: doc: pixfmt-packed-yuv: Fill padding bits with '-' Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 11/16] media: doc: pixfmt-packed-yuv: Clarify naming scheme for 4:4:4 formats Laurent Pinchart
` (5 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
The 4:4:4 packed YUV formats are documented with a bit-level
representation, which creates a wide table. Switch to a byte-oriented
representation to make it more compact. This prepares for the addition
of formats with more than 8 bits per component, that would make the
table way too wide.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../media/v4l/pixfmt-packed-yuv.rst | 273 ++++--------------
1 file changed, 56 insertions(+), 217 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
index c4ee8d5ac668..e378309d70f0 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -17,6 +17,14 @@ Similarly to the packed RGB formats, the packed YUV formats store the Y, Cb and
Cr components consecutively in memory. They may apply subsampling to the chroma
components and thus differ in how they interlave the three components.
+.. note::
+
+ - In all the tables that follow, bit 7 is the most significant bit in a byte.
+ - 'Y', 'Cb' and 'Cr' denote bits of the luma, blue chroma (also known as
+ 'U') and red chroma (also known as 'V') components respectively. 'A'
+ denotes bits of the the alpha component (if supported by the format), and
+ '-' denotes padding bits.
+
4:4:4 Subsampling
=================
@@ -30,9 +38,9 @@ full triplet of Y, Cb and Cr values.
\tiny
\setlength{\tabcolsep}{2pt}
-.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|
+.. tabularcolumns:: |p{2.5cm}|p{0.69cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|p{0.31cm}|
-.. flat-table:: Packed YUV 4:4:4 Image Formats
+.. flat-table:: Packed YUV 4:4:4 Image Formats (less than 8bpc)
:header-rows: 2
:stub-columns: 0
@@ -43,10 +51,6 @@ full triplet of Y, Cb and Cr values.
- :cspan:`7` Byte 1
- - :cspan:`7` Byte 2
-
- - :cspan:`7` Byte 3
-
* -
-
- 7
@@ -67,24 +71,6 @@ full triplet of Y, Cb and Cr values.
- 1
- 0
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
-
- - 7
- - 6
- - 5
- - 4
- - 3
- - 2
- - 1
- - 0
-
* .. _V4L2-PIX-FMT-YUV444:
- ``V4L2_PIX_FMT_YUV444``
@@ -108,8 +94,6 @@ full triplet of Y, Cb and Cr values.
- Y'\ :sub:`1`
- Y'\ :sub:`0`
- - :cspan:`15`
-
* .. _V4L2-PIX-FMT-YUV555:
- ``V4L2_PIX_FMT_YUV555``
@@ -133,7 +117,6 @@ full triplet of Y, Cb and Cr values.
- Cb\ :sub:`4`
- Cb\ :sub:`3`
- - :cspan:`15`
* .. _V4L2-PIX-FMT-YUV565:
- ``V4L2_PIX_FMT_YUV565``
@@ -157,229 +140,85 @@ full triplet of Y, Cb and Cr values.
- Cb\ :sub:`4`
- Cb\ :sub:`3`
- - :cspan:`15`
+.. raw:: latex
+
+ \endgroup
+
+.. note::
+
+ For the YUV444 and YUV555 formats, the value of alpha bits is undefined
+ when reading from the driver, ignored when writing to the driver, except
+ when alpha blending has been negotiated for a :ref:`Video Overlay
+ <overlay>` or :ref:`Video Output Overlay <osd>`.
+
+
+.. flat-table:: Packed YUV Image Formats (8bpc)
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - Byte 0
+ - Byte 1
+ - Byte 2
+ - Byte 3
* .. _V4L2-PIX-FMT-YUV32:
- ``V4L2_PIX_FMT_YUV32``
- 'YUV4'
- - a\ :sub:`7`
- - a\ :sub:`6`
- - a\ :sub:`5`
- - a\ :sub:`4`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
-
- - Y'\ :sub:`7`
- - Y'\ :sub:`6`
- - Y'\ :sub:`5`
- - Y'\ :sub:`4`
- - Y'\ :sub:`3`
- - Y'\ :sub:`2`
- - Y'\ :sub:`1`
- - Y'\ :sub:`0`
-
- - Cb\ :sub:`7`
- - Cb\ :sub:`6`
- - Cb\ :sub:`5`
- - Cb\ :sub:`4`
- - Cb\ :sub:`3`
- - Cb\ :sub:`2`
- - Cb\ :sub:`1`
- - Cb\ :sub:`0`
-
- - Cr\ :sub:`7`
- - Cr\ :sub:`6`
- - Cr\ :sub:`5`
- - Cr\ :sub:`4`
- - Cr\ :sub:`3`
- - Cr\ :sub:`2`
- - Cr\ :sub:`1`
- - Cr\ :sub:`0`
+ - A\ :sub:`7-0`
+ - Y'\ :sub:`7-0`
+ - Cb\ :sub:`7-0`
+ - Cr\ :sub:`7-0`
* .. _V4L2-PIX-FMT-AYUV32:
- ``V4L2_PIX_FMT_AYUV32``
- 'AYUV'
- - a\ :sub:`7`
- - a\ :sub:`6`
- - a\ :sub:`5`
- - a\ :sub:`4`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
-
- - Y'\ :sub:`7`
- - Y'\ :sub:`6`
- - Y'\ :sub:`5`
- - Y'\ :sub:`4`
- - Y'\ :sub:`3`
- - Y'\ :sub:`2`
- - Y'\ :sub:`1`
- - Y'\ :sub:`0`
-
- - Cb\ :sub:`7`
- - Cb\ :sub:`6`
- - Cb\ :sub:`5`
- - Cb\ :sub:`4`
- - Cb\ :sub:`3`
- - Cb\ :sub:`2`
- - Cb\ :sub:`1`
- - Cb\ :sub:`0`
-
- - Cr\ :sub:`7`
- - Cr\ :sub:`6`
- - Cr\ :sub:`5`
- - Cr\ :sub:`4`
- - Cr\ :sub:`3`
- - Cr\ :sub:`2`
- - Cr\ :sub:`1`
- - Cr\ :sub:`0`
+ - A\ :sub:`7-0`
+ - Y'\ :sub:`7-0`
+ - Cb\ :sub:`7-0`
+ - Cr\ :sub:`7-0`
* .. _V4L2-PIX-FMT-XYUV32:
- ``V4L2_PIX_FMT_XYUV32``
- 'XYUV'
- - `-`
- - `-`
- - `-`
- - `-`
- - `-`
- - `-`
- - `-`
- - `-`
-
- - Y'\ :sub:`7`
- - Y'\ :sub:`6`
- - Y'\ :sub:`5`
- - Y'\ :sub:`4`
- - Y'\ :sub:`3`
- - Y'\ :sub:`2`
- - Y'\ :sub:`1`
- - Y'\ :sub:`0`
-
- - Cb\ :sub:`7`
- - Cb\ :sub:`6`
- - Cb\ :sub:`5`
- - Cb\ :sub:`4`
- - Cb\ :sub:`3`
- - Cb\ :sub:`2`
- - Cb\ :sub:`1`
- - Cb\ :sub:`0`
-
- - Cr\ :sub:`7`
- - Cr\ :sub:`6`
- - Cr\ :sub:`5`
- - Cr\ :sub:`4`
- - Cr\ :sub:`3`
- - Cr\ :sub:`2`
- - Cr\ :sub:`1`
- - Cr\ :sub:`0`
+ - `-`\ :sub:`7-0`
+ - Y'\ :sub:`7-0`
+ - Cb\ :sub:`7-0`
+ - Cr\ :sub:`7-0`
* .. _V4L2-PIX-FMT-VUYA32:
- ``V4L2_PIX_FMT_VUYA32``
- 'VUYA'
- - Cr\ :sub:`7`
- - Cr\ :sub:`6`
- - Cr\ :sub:`5`
- - Cr\ :sub:`4`
- - Cr\ :sub:`3`
- - Cr\ :sub:`2`
- - Cr\ :sub:`1`
- - Cr\ :sub:`0`
-
- - Cb\ :sub:`7`
- - Cb\ :sub:`6`
- - Cb\ :sub:`5`
- - Cb\ :sub:`4`
- - Cb\ :sub:`3`
- - Cb\ :sub:`2`
- - Cb\ :sub:`1`
- - Cb\ :sub:`0`
-
- - Y'\ :sub:`7`
- - Y'\ :sub:`6`
- - Y'\ :sub:`5`
- - Y'\ :sub:`4`
- - Y'\ :sub:`3`
- - Y'\ :sub:`2`
- - Y'\ :sub:`1`
- - Y'\ :sub:`0`
-
- - a\ :sub:`7`
- - a\ :sub:`6`
- - a\ :sub:`5`
- - a\ :sub:`4`
- - a\ :sub:`3`
- - a\ :sub:`2`
- - a\ :sub:`1`
- - a\ :sub:`0`
+ - Cr\ :sub:`7-0`
+ - Cb\ :sub:`7-0`
+ - Y'\ :sub:`7-0`
+ - A\ :sub:`7-0`
* .. _V4L2-PIX-FMT-VUYX32:
- ``V4L2_PIX_FMT_VUYX32``
- 'VUYX'
- - Cr\ :sub:`7`
- - Cr\ :sub:`6`
- - Cr\ :sub:`5`
- - Cr\ :sub:`4`
- - Cr\ :sub:`3`
- - Cr\ :sub:`2`
- - Cr\ :sub:`1`
- - Cr\ :sub:`0`
-
- - Cb\ :sub:`7`
- - Cb\ :sub:`6`
- - Cb\ :sub:`5`
- - Cb\ :sub:`4`
- - Cb\ :sub:`3`
- - Cb\ :sub:`2`
- - Cb\ :sub:`1`
- - Cb\ :sub:`0`
-
- - Y'\ :sub:`7`
- - Y'\ :sub:`6`
- - Y'\ :sub:`5`
- - Y'\ :sub:`4`
- - Y'\ :sub:`3`
- - Y'\ :sub:`2`
- - Y'\ :sub:`1`
- - Y'\ :sub:`0`
-
- - `-`
- - `-`
- - `-`
- - `-`
- - `-`
- - `-`
- - `-`
- - `-`
-
-.. raw:: latex
-
- \endgroup
+ - Cr\ :sub:`7-0`
+ - Cb\ :sub:`7-0`
+ - Y'\ :sub:`7-0`
+ - `-`\ :sub:`7-0`
.. note::
- #) Bit 7 is the most significant bit;
-
- #) The value of a = alpha bits is undefined when reading from the driver,
- ignored when writing to the driver, except when alpha blending has
- been negotiated for a :ref:`Video Overlay <overlay>` or
- :ref:`Video Output Overlay <osd>` for the formats Y444, YUV555 and
- YUV4. However, for formats AYUV32 and VUYA32, the alpha component is
- expected to contain a meaningful value that can be used by drivers
- and applications. And, the formats XYUV32 and VUYX32 contain undefined
- alpha values that must be ignored by all applications and drivers.
+ - The alpha component is expected to contain a meaningful value that can be
+ used by drivers and applications.
+ - The padding bits contain undefined values that must be ignored by all
+ applications and drivers.
4:2:2 Subsampling
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 11/16] media: doc: pixfmt-packed-yuv: Clarify naming scheme for 4:4:4 formats
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (9 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 10/16] media: doc: pixfmt-packed-yuv: Express 4:4:4 formats in a more compact way Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 12/16] media: doc: pixfmt-yuv: Move all luma-only YUV formats to common file Laurent Pinchart
` (4 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Document the naming scheme for the existing packed YUV 4:4:4 formats, as
previously done for the RGB formats.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../userspace-api/media/v4l/pixfmt-packed-yuv.rst | 14 ++++++++++++++
1 file changed, 14 insertions(+)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
index e378309d70f0..81b95ca25fb7 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -32,6 +32,14 @@ components and thus differ in how they interlave the three components.
These formats do not subsample the chroma components and store each pixels as a
full triplet of Y, Cb and Cr values.
+The next table lists the packed YUV 4:4:4 formats with less than 8 bits per
+component. They are named based on the order of the Y, Cb and Cr components as
+seen in a 16-bit word, which is then stored in memory in little endian byte
+order, and on the number of bits for each component. For instance the YUV565
+format stores a pixel in a 16-bit word [15:0] laid out at as [Y'\ :sub:`4-0`
+Cb\ :sub:`5-0` Cr\ :sub:`4-0`], and stored in memory in two bytes,
+[Cb\ :sub:`2-0` Cr\ :sub:`4-0`] followed by [Y'\ :sub:`4-0` Cb\ :sub:`5-3`].
+
.. raw:: latex
\begingroup
@@ -152,6 +160,12 @@ full triplet of Y, Cb and Cr values.
<overlay>` or :ref:`Video Output Overlay <osd>`.
+The next table lists the packed YUV 4:4:4 formats with 8 bits per component.
+They are named based on the order of the Y, Cb and Cr components as stored in
+memory, and on the total number of bits per pixel. For instance, the VUYX32
+format stores a pixel with Cr\ :sub:`7-0` in the first byte, Cb\ :sub:`7-0` in
+the second byte and Y'\ :sub:`7-0` in the third byte.
+
.. flat-table:: Packed YUV Image Formats (8bpc)
:header-rows: 1
:stub-columns: 0
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 12/16] media: doc: pixfmt-yuv: Move all luma-only YUV formats to common file
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (10 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 11/16] media: doc: pixfmt-packed-yuv: Clarify naming scheme for 4:4:4 formats Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 13/16] media: v4l2: Add 10-, 12- and 16-bpc BGR formats Laurent Pinchart
` (3 subsequent siblings)
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Luma-only pixel formats are documented in separate files. This
duplicates information, as those formats share comon traits. Consolidate
them in a single file and describe them in a single table.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../userspace-api/media/v4l/pixfmt-grey.rst | 51 -------
.../userspace-api/media/v4l/pixfmt-y10.rst | 72 ----------
.../userspace-api/media/v4l/pixfmt-y10b.rst | 40 ------
.../userspace-api/media/v4l/pixfmt-y10p.rst | 50 -------
.../userspace-api/media/v4l/pixfmt-y12.rst | 72 ----------
.../userspace-api/media/v4l/pixfmt-y14.rst | 72 ----------
.../userspace-api/media/v4l/pixfmt-y16-be.rst | 76 ----------
.../userspace-api/media/v4l/pixfmt-y16.rst | 76 ----------
.../media/v4l/pixfmt-yuv-luma.rst | 133 ++++++++++++++++++
.../userspace-api/media/v4l/yuv-formats.rst | 9 +-
10 files changed, 134 insertions(+), 517 deletions(-)
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-grey.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y10.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y10b.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y10p.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y12.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y14.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y16.rst
create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst b/Documentation/userspace-api/media/v4l/pixfmt-grey.rst
deleted file mode 100644
index 7b03db3393be..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst
+++ /dev/null
@@ -1,51 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-GREY:
-
-**************************
-V4L2_PIX_FMT_GREY ('GREY')
-**************************
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image. It is really a degenerate Y'CbCr format
-which simply contains no Cb or Cr data.
-
-**Byte Order.**
-Each cell is one byte.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Y'\ :sub:`00`
- - Y'\ :sub:`01`
- - Y'\ :sub:`02`
- - Y'\ :sub:`03`
- * - start + 4:
- - Y'\ :sub:`10`
- - Y'\ :sub:`11`
- - Y'\ :sub:`12`
- - Y'\ :sub:`13`
- * - start + 8:
- - Y'\ :sub:`20`
- - Y'\ :sub:`21`
- - Y'\ :sub:`22`
- - Y'\ :sub:`23`
- * - start + 12:
- - Y'\ :sub:`30`
- - Y'\ :sub:`31`
- - Y'\ :sub:`32`
- - Y'\ :sub:`33`
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10.rst
deleted file mode 100644
index dfb352ae6784..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst
+++ /dev/null
@@ -1,72 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-Y10:
-
-*************************
-V4L2_PIX_FMT_Y10 ('Y10 ')
-*************************
-
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 10 bits per pixel. Pixels are
-stored in 16-bit words with unused high bits padded with 0. The least
-significant byte is stored at lower memory addresses (little-endian).
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Y'\ :sub:`00low`
- - Y'\ :sub:`00high`
- - Y'\ :sub:`01low`
- - Y'\ :sub:`01high`
- - Y'\ :sub:`02low`
- - Y'\ :sub:`02high`
- - Y'\ :sub:`03low`
- - Y'\ :sub:`03high`
- * - start + 8:
- - Y'\ :sub:`10low`
- - Y'\ :sub:`10high`
- - Y'\ :sub:`11low`
- - Y'\ :sub:`11high`
- - Y'\ :sub:`12low`
- - Y'\ :sub:`12high`
- - Y'\ :sub:`13low`
- - Y'\ :sub:`13high`
- * - start + 16:
- - Y'\ :sub:`20low`
- - Y'\ :sub:`20high`
- - Y'\ :sub:`21low`
- - Y'\ :sub:`21high`
- - Y'\ :sub:`22low`
- - Y'\ :sub:`22high`
- - Y'\ :sub:`23low`
- - Y'\ :sub:`23high`
- * - start + 24:
- - Y'\ :sub:`30low`
- - Y'\ :sub:`30high`
- - Y'\ :sub:`31low`
- - Y'\ :sub:`31high`
- - Y'\ :sub:`32low`
- - Y'\ :sub:`32high`
- - Y'\ :sub:`33low`
- - Y'\ :sub:`33high`
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst
deleted file mode 100644
index b5d89d6d5c52..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-Y10BPACK:
-
-******************************
-V4L2_PIX_FMT_Y10BPACK ('Y10B')
-******************************
-
-Grey-scale image as a bit-packed array
-
-
-Description
-===========
-
-This is a packed grey-scale image format with a depth of 10 bits per
-pixel. Pixels are stored in a bit-packed array of 10bit bits per pixel,
-with no padding between them and with the most significant bits coming
-first from the left.
-
-**Bit-packed representation.**
-
-pixels cross the byte boundary and have a ratio of 5 bytes for each 4
-pixels.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - Y'\ :sub:`00[9:2]`
- - Y'\ :sub:`00[1:0]`\ Y'\ :sub:`01[9:4]`
- - Y'\ :sub:`01[3:0]`\ Y'\ :sub:`02[9:6]`
- - Y'\ :sub:`02[5:0]`\ Y'\ :sub:`03[9:8]`
- - Y'\ :sub:`03[7:0]`
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst b/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst
deleted file mode 100644
index ffb6e1631b78..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst
+++ /dev/null
@@ -1,50 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-Y10P:
-
-******************************
-V4L2_PIX_FMT_Y10P ('Y10P')
-******************************
-
-Grey-scale image as a MIPI RAW10 packed array
-
-
-Description
-===========
-
-This is a packed grey-scale image format with a depth of 10 bits per
-pixel. Every four consecutive pixels are packed into 5 bytes. Each of
-the first 4 bytes contain the 8 high order bits of the pixels, and
-the 5th byte contains the 2 least significants bits of each pixel,
-in the same order.
-
-**Bit-packed representation.**
-
-.. raw:: latex
-
- \small
-
-.. tabularcolumns:: |p{1.2cm}||p{1.2cm}||p{1.2cm}||p{1.2cm}|p{3.2cm}|p{3.2cm}|
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
- :widths: 8 8 8 8 64
-
- * - Y'\ :sub:`00[9:2]`
- - Y'\ :sub:`01[9:2]`
- - Y'\ :sub:`02[9:2]`
- - Y'\ :sub:`03[9:2]`
- - Y'\ :sub:`03[1:0]`\ (bits 7--6) Y'\ :sub:`02[1:0]`\ (bits 5--4)
- Y'\ :sub:`01[1:0]`\ (bits 3--2) Y'\ :sub:`00[1:0]`\ (bits 1--0)
-
-.. raw:: latex
-
- \normalsize
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst b/Documentation/userspace-api/media/v4l/pixfmt-y12.rst
deleted file mode 100644
index 4226c49232de..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst
+++ /dev/null
@@ -1,72 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-Y12:
-
-*************************
-V4L2_PIX_FMT_Y12 ('Y12 ')
-*************************
-
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 12 bits per pixel. Pixels are
-stored in 16-bit words with unused high bits padded with 0. The least
-significant byte is stored at lower memory addresses (little-endian).
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Y'\ :sub:`00low`
- - Y'\ :sub:`00high`
- - Y'\ :sub:`01low`
- - Y'\ :sub:`01high`
- - Y'\ :sub:`02low`
- - Y'\ :sub:`02high`
- - Y'\ :sub:`03low`
- - Y'\ :sub:`03high`
- * - start + 8:
- - Y'\ :sub:`10low`
- - Y'\ :sub:`10high`
- - Y'\ :sub:`11low`
- - Y'\ :sub:`11high`
- - Y'\ :sub:`12low`
- - Y'\ :sub:`12high`
- - Y'\ :sub:`13low`
- - Y'\ :sub:`13high`
- * - start + 16:
- - Y'\ :sub:`20low`
- - Y'\ :sub:`20high`
- - Y'\ :sub:`21low`
- - Y'\ :sub:`21high`
- - Y'\ :sub:`22low`
- - Y'\ :sub:`22high`
- - Y'\ :sub:`23low`
- - Y'\ :sub:`23high`
- * - start + 24:
- - Y'\ :sub:`30low`
- - Y'\ :sub:`30high`
- - Y'\ :sub:`31low`
- - Y'\ :sub:`31high`
- - Y'\ :sub:`32low`
- - Y'\ :sub:`32high`
- - Y'\ :sub:`33low`
- - Y'\ :sub:`33high`
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst b/Documentation/userspace-api/media/v4l/pixfmt-y14.rst
deleted file mode 100644
index d702b6549160..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst
+++ /dev/null
@@ -1,72 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-Y14:
-
-*************************
-V4L2_PIX_FMT_Y14 ('Y14 ')
-*************************
-
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 14 bits per pixel. Pixels are
-stored in 16-bit words with unused high bits padded with 0. The least
-significant byte is stored at lower memory addresses (little-endian).
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Y'\ :sub:`00low`
- - Y'\ :sub:`00high`
- - Y'\ :sub:`01low`
- - Y'\ :sub:`01high`
- - Y'\ :sub:`02low`
- - Y'\ :sub:`02high`
- - Y'\ :sub:`03low`
- - Y'\ :sub:`03high`
- * - start + 8:
- - Y'\ :sub:`10low`
- - Y'\ :sub:`10high`
- - Y'\ :sub:`11low`
- - Y'\ :sub:`11high`
- - Y'\ :sub:`12low`
- - Y'\ :sub:`12high`
- - Y'\ :sub:`13low`
- - Y'\ :sub:`13high`
- * - start + 16:
- - Y'\ :sub:`20low`
- - Y'\ :sub:`20high`
- - Y'\ :sub:`21low`
- - Y'\ :sub:`21high`
- - Y'\ :sub:`22low`
- - Y'\ :sub:`22high`
- - Y'\ :sub:`23low`
- - Y'\ :sub:`23high`
- * - start + 24:
- - Y'\ :sub:`30low`
- - Y'\ :sub:`30high`
- - Y'\ :sub:`31low`
- - Y'\ :sub:`31high`
- - Y'\ :sub:`32low`
- - Y'\ :sub:`32high`
- - Y'\ :sub:`33low`
- - Y'\ :sub:`33high`
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst
deleted file mode 100644
index f4eda7b95b51..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-Y16-BE:
-
-****************************************
-V4L2_PIX_FMT_Y16_BE ('Y16 ' | (1 << 31))
-****************************************
-
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 16 bits per pixel. The most
-significant byte is stored at lower memory addresses (big-endian).
-
-.. note::
-
- The actual sampling precision may be lower than 16 bits, for
- example 10 bits per pixel with values in range 0 to 1023.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Y'\ :sub:`00high`
- - Y'\ :sub:`00low`
- - Y'\ :sub:`01high`
- - Y'\ :sub:`01low`
- - Y'\ :sub:`02high`
- - Y'\ :sub:`02low`
- - Y'\ :sub:`03high`
- - Y'\ :sub:`03low`
- * - start + 8:
- - Y'\ :sub:`10high`
- - Y'\ :sub:`10low`
- - Y'\ :sub:`11high`
- - Y'\ :sub:`11low`
- - Y'\ :sub:`12high`
- - Y'\ :sub:`12low`
- - Y'\ :sub:`13high`
- - Y'\ :sub:`13low`
- * - start + 16:
- - Y'\ :sub:`20high`
- - Y'\ :sub:`20low`
- - Y'\ :sub:`21high`
- - Y'\ :sub:`21low`
- - Y'\ :sub:`22high`
- - Y'\ :sub:`22low`
- - Y'\ :sub:`23high`
- - Y'\ :sub:`23low`
- * - start + 24:
- - Y'\ :sub:`30high`
- - Y'\ :sub:`30low`
- - Y'\ :sub:`31high`
- - Y'\ :sub:`31low`
- - Y'\ :sub:`32high`
- - Y'\ :sub:`32low`
- - Y'\ :sub:`33high`
- - Y'\ :sub:`33low`
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst b/Documentation/userspace-api/media/v4l/pixfmt-y16.rst
deleted file mode 100644
index a092b0a5ff12..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-.. Permission is granted to copy, distribute and/or modify this
-.. document under the terms of the GNU Free Documentation License,
-.. Version 1.1 or any later version published by the Free Software
-.. Foundation, with no Invariant Sections, no Front-Cover Texts
-.. and no Back-Cover Texts. A copy of the license is included at
-.. Documentation/userspace-api/media/fdl-appendix.rst.
-..
-.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
-
-.. _V4L2-PIX-FMT-Y16:
-
-*************************
-V4L2_PIX_FMT_Y16 ('Y16 ')
-*************************
-
-
-Grey-scale image
-
-
-Description
-===========
-
-This is a grey-scale image with a depth of 16 bits per pixel. The least
-significant byte is stored at lower memory addresses (little-endian).
-
-.. note::
-
- The actual sampling precision may be lower than 16 bits, for
- example 10 bits per pixel with values in range 0 to 1023.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start + 0:
- - Y'\ :sub:`00low`
- - Y'\ :sub:`00high`
- - Y'\ :sub:`01low`
- - Y'\ :sub:`01high`
- - Y'\ :sub:`02low`
- - Y'\ :sub:`02high`
- - Y'\ :sub:`03low`
- - Y'\ :sub:`03high`
- * - start + 8:
- - Y'\ :sub:`10low`
- - Y'\ :sub:`10high`
- - Y'\ :sub:`11low`
- - Y'\ :sub:`11high`
- - Y'\ :sub:`12low`
- - Y'\ :sub:`12high`
- - Y'\ :sub:`13low`
- - Y'\ :sub:`13high`
- * - start + 16:
- - Y'\ :sub:`20low`
- - Y'\ :sub:`20high`
- - Y'\ :sub:`21low`
- - Y'\ :sub:`21high`
- - Y'\ :sub:`22low`
- - Y'\ :sub:`22high`
- - Y'\ :sub:`23low`
- - Y'\ :sub:`23high`
- * - start + 24:
- - Y'\ :sub:`30low`
- - Y'\ :sub:`30high`
- - Y'\ :sub:`31low`
- - Y'\ :sub:`31high`
- - Y'\ :sub:`32low`
- - Y'\ :sub:`32high`
- - Y'\ :sub:`33low`
- - Y'\ :sub:`33high`
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
new file mode 100644
index 000000000000..b24947b52cf8
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
@@ -0,0 +1,133 @@
+.. Permission is granted to copy, distribute and/or modify this
+.. document under the terms of the GNU Free Documentation License,
+.. Version 1.1 or any later version published by the Free Software
+.. Foundation, with no Invariant Sections, no Front-Cover Texts
+.. and no Back-Cover Texts. A copy of the license is included at
+.. Documentation/userspace-api/media/fdl-appendix.rst.
+..
+.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
+
+.. _yuv-luma-only:
+
+*****************
+Luma-Only Formats
+*****************
+
+This family of formats only store the luma component of a Y'CbCr image. They
+are often referred to as greyscale formats.
+
+.. note::
+
+ - In all the tables that follow, bit 7 is the most significant bit in a byte.
+ - Formats are described with the minimum number of pixels needed to create a
+ byte-aligned repeating pattern. `...` indicates repetition of the pattern.
+ - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum
+ `x`.
+ - `0` denotes padding bits set to 0.
+
+
+.. flat-table:: Luma-Only Image Formats
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - Byte 0
+ - Byte 1
+ - Byte 2
+ - Byte 3
+ - Byte 4
+
+ * .. _V4L2-PIX-FMT-GREY:
+
+ - ``V4L2_PIX_FMT_GREY``
+ - 'GREY'
+
+ - Y'\ :sub:`0`\ [7:0]
+ - ...
+ - ...
+ - ...
+ - ...
+
+ * .. _V4L2-PIX-FMT-Y10:
+
+ - ``V4L2_PIX_FMT_Y10``
+ - 'Y10 '
+
+ - Y'\ :sub:`0`\ [7:0]
+ - `000000` Y'\ :sub:`0`\ [9:8]
+ - ...
+ - ...
+ - ...
+
+ * .. _V4L2-PIX-FMT-Y10BPACK:
+
+ - ``V4L2_PIX_FMT_Y10BPACK``
+ - 'Y10B'
+
+ - Y'\ :sub:`0`\ [9:2]
+ - Y'\ :sub:`0`\ [1:0] Y'\ :sub:`1`\ [9:4]
+ - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`2`\ [9:6]
+ - Y'\ :sub:`2`\ [5:0] Y'\ :sub:`3`\ [9:8]
+ - Y'\ :sub:`3`\ [7:0]
+
+ * .. _V4L2-PIX-FMT-Y10P:
+
+ - ``V4L2_PIX_FMT_Y10P``
+ - 'Y10P'
+
+ - Y'\ :sub:`0`\ [7:0]
+ - Y'\ :sub:`1`\ [9:8]
+ - Y'\ :sub:`2`\ [9:2]
+ - Y'\ :sub:`3`\ [9:2]
+ - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0]
+
+ * .. _V4L2-PIX-FMT-Y12:
+
+ - ``V4L2_PIX_FMT_Y12``
+ - 'Y12 '
+
+ - Y'\ :sub:`0`\ [7:0]
+ - `0000` Y'\ :sub:`0`\ [11:8]
+ - ...
+ - ...
+ - ...
+
+ * .. _V4L2-PIX-FMT-Y14:
+
+ - ``V4L2_PIX_FMT_Y14``
+ - 'Y14 '
+
+ - Y'\ :sub:`0`\ [7:0]
+ - `00` Y'\ :sub:`0`\ [13:8]
+ - ...
+ - ...
+ - ...
+
+ * .. _V4L2-PIX-FMT-Y16:
+
+ - ``V4L2_PIX_FMT_Y16``
+ - 'Y16 '
+
+ - Y'\ :sub:`0`\ [7:0]
+ - Y'\ :sub:`0`\ [15:8]
+ - ...
+ - ...
+ - ...
+
+ * .. _V4L2-PIX-FMT-Y16-BE:
+
+ - ``V4L2_PIX_FMT_Y16_BE``
+ - 'Y16 ' | (1 << 31)
+
+ - Y'\ :sub:`0`\ [7:0]
+ - Y'\ :sub:`0`\ [15:8]
+ - ...
+ - ...
+ - ...
+
+.. note::
+
+ For the Y16 and Y16_BE formats, the actual sampling precision may be lower
+ than 16 bits. For example, 10 bits per pixel uses values in the range 0 to
+ 1023.
diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst
index afe4f7956e7f..f3321f503568 100644
--- a/Documentation/userspace-api/media/v4l/yuv-formats.rst
+++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst
@@ -272,14 +272,7 @@ image.
:maxdepth: 1
pixfmt-packed-yuv
- pixfmt-grey
- pixfmt-y10
- pixfmt-y12
- pixfmt-y14
- pixfmt-y10b
- pixfmt-y10p
- pixfmt-y16
- pixfmt-y16-be
+ pixfmt-yuv-luma
pixfmt-y8i
pixfmt-y12i
pixfmt-uv8
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 13/16] media: v4l2: Add 10-, 12- and 16-bpc BGR formats
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (11 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 12/16] media: doc: pixfmt-yuv: Move all luma-only YUV formats to common file Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-10-01 13:44 ` Hans Verkuil
2020-09-23 2:43 ` [PATCH/RFC 14/16] media: v4l2: Add a few missing packed YUV 4:4:4 formats Laurent Pinchart
` (2 subsequent siblings)
15 siblings, 1 reply; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Add three new pixel formats that store RGB data in BGR order with 10, 12
and 16 bits per component. They are used by the Xilinx Video Frame
Buffer Read/Write IP cores.
The nomenclature for these new formats follows the 8- and 16-bpp RGB
formats and the DRM format naming conventions, which differs from the
24- and 32-bpp RGB formats in V4L2.
As the number of bits per pixel grows quite large, a table with one
column per bit would be difficult to read. These formats are thus
described with one column per byte.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../userspace-api/media/v4l/pixfmt-rgb.rst | 68 +++++++++++++++++++
include/uapi/linux/videodev2.h | 5 ++
2 files changed, 73 insertions(+)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
index 32bfd68af425..2e81d448177e 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
@@ -1087,6 +1087,74 @@ order of components as seen in a 24- or 32-bit little endian word.
\endgroup
+More Than 8 Bits Per Component
+==============================
+
+These formats store an RGB triplet in four bytes or more. Similarly to the 8-
+and 16-bpp formats, they are named based on the order of the RGB components as
+seen in a word, which is then stored in memory in little endian byte order, and
+on the number of bits for each component.
+
+.. raw:: latex
+
+ \begingroup
+ \tiny
+ \setlength{\tabcolsep}{2pt}
+
+.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|
+
+
+.. flat-table:: RGB Formats With More Than 8 Bits Per Component
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - Byte 0 in memory
+ - Byte 1
+ - Byte 2
+ - Byte 3
+ - Byte 4
+ - Byte 5
+ * .. _V4L2-PIX-FMT-XBGR2101010:
+
+ - ``V4L2_PIX_FMT_XBGR2101010``
+ - 'XB30'
+
+ - R\ :sub:`7-0`
+ - G\ :sub:`5-0` R\ :sub:`9-8`
+ - B\ :sub:`3-0` G\ :sub:`9-6`
+ - `-`\ :sub:`1-0` B\ :sub:`9-4`
+
+ -
+ * .. _V4L2-PIX-FMT-XBGR4121212:
+
+ - ``V4L2_PIX_FMT_XBGR4121212``
+ - 'XB36'
+
+ - R\ :sub:`7-0`
+ - G\ :sub:`3-0` R\ :sub:`11-8`
+ - G\ :sub:`11-4`
+ - B\ :sub:`7-0`
+ - `-`\ :sub:`3-0` B\ :sub:`11-8`
+
+ -
+ * .. _V4L2-PIX-FMT-BGR161616:
+
+ - ``V4L2_PIX_FMT_BGR161616``
+ - 'XB48'
+
+ - R\ :sub:`7-0`
+ - R\ :sub:`15-8`
+ - G\ :sub:`7-0`
+ - G\ :sub:`15-8`
+ - B\ :sub:`7-0`
+ - B\ :sub:`15-8`
+
+.. raw:: latex
+
+ \endgroup
+
+
Deprecated RGB Formats
======================
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 3f5f1cf8d1c0..9181e44c20db 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -561,6 +561,11 @@ struct v4l2_pix_format {
#define V4L2_PIX_FMT_ARGB32 v4l2_fourcc('B', 'A', '2', '4') /* 32 ARGB-8-8-8-8 */
#define V4L2_PIX_FMT_XRGB32 v4l2_fourcc('B', 'X', '2', '4') /* 32 XRGB-8-8-8-8 */
+/* RGB formats (more than 8 bits per component) */
+#define V4L2_PIX_FMT_XBGR2101010 v4l2_fourcc('X', 'B', '3', '0') /* 32 XBGR-2-10-10-10 */
+#define V4L2_PIX_FMT_XBGR4121212 v4l2_fourcc('X', 'B', '3', '6') /* 40 XBGR-4-12-12-12 */
+#define V4L2_PIX_FMT_BGR161616 v4l2_fourcc('X', 'B', '4', '8') /* 48 BGR-16-16-16 */
+
/* Grey formats */
#define V4L2_PIX_FMT_GREY v4l2_fourcc('G', 'R', 'E', 'Y') /* 8 Greyscale */
#define V4L2_PIX_FMT_Y4 v4l2_fourcc('Y', '0', '4', ' ') /* 4 Greyscale */
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 13/16] media: v4l2: Add 10-, 12- and 16-bpc BGR formats
2020-09-23 2:43 ` [PATCH/RFC 13/16] media: v4l2: Add 10-, 12- and 16-bpc BGR formats Laurent Pinchart
@ 2020-10-01 13:44 ` Hans Verkuil
2020-11-01 0:30 ` Laurent Pinchart
0 siblings, 1 reply; 31+ messages in thread
From: Hans Verkuil @ 2020-10-01 13:44 UTC (permalink / raw)
To: Laurent Pinchart, linux-media; +Cc: Sakari Ailus, Dylan Yip, Vishal Sagar
On 23/09/2020 04:43, Laurent Pinchart wrote:
> Add three new pixel formats that store RGB data in BGR order with 10, 12
> and 16 bits per component. They are used by the Xilinx Video Frame
> Buffer Read/Write IP cores.
>
> The nomenclature for these new formats follows the 8- and 16-bpp RGB
> formats and the DRM format naming conventions, which differs from the
> 24- and 32-bpp RGB formats in V4L2.
>
> As the number of bits per pixel grows quite large, a table with one
> column per bit would be difficult to read. These formats are thus
> described with one column per byte.
>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> .../userspace-api/media/v4l/pixfmt-rgb.rst | 68 +++++++++++++++++++
> include/uapi/linux/videodev2.h | 5 ++
> 2 files changed, 73 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> index 32bfd68af425..2e81d448177e 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> @@ -1087,6 +1087,74 @@ order of components as seen in a 24- or 32-bit little endian word.
> \endgroup
>
>
> +More Than 8 Bits Per Component
> +==============================
> +
> +These formats store an RGB triplet in four bytes or more. Similarly to the 8-
> +and 16-bpp formats, they are named based on the order of the RGB components as
> +seen in a word, which is then stored in memory in little endian byte order, and
> +on the number of bits for each component.
> +
> +.. raw:: latex
> +
> + \begingroup
> + \tiny
> + \setlength{\tabcolsep}{2pt}
> +
> +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|
> +
> +
> +.. flat-table:: RGB Formats With More Than 8 Bits Per Component
> + :stub-columns: 0
> +
> + * - Identifier
> + - Code
> + - Byte 0 in memory
> + - Byte 1
> + - Byte 2
> + - Byte 3
> + - Byte 4
> + - Byte 5
> + * .. _V4L2-PIX-FMT-XBGR2101010:
> +
> + - ``V4L2_PIX_FMT_XBGR2101010``
How about naming this: 'X2B10G10R10'. That makes it easier to understand the
number of bits assigned to each pixel component.
An alternative (but more verbose) would be: XBGR_2_10_10_10.
> + - 'XB30'
> +
> + - R\ :sub:`7-0`
> + - G\ :sub:`5-0` R\ :sub:`9-8`
> + - B\ :sub:`3-0` G\ :sub:`9-6`
> + - `-`\ :sub:`1-0` B\ :sub:`9-4`
> +
> + -
> + * .. _V4L2-PIX-FMT-XBGR4121212:
> +
> + - ``V4L2_PIX_FMT_XBGR4121212``
X4B12G12R12
> + - 'XB36'
> +
> + - R\ :sub:`7-0`
> + - G\ :sub:`3-0` R\ :sub:`11-8`
> + - G\ :sub:`11-4`
> + - B\ :sub:`7-0`
> + - `-`\ :sub:`3-0` B\ :sub:`11-8`
> +
> + -
> + * .. _V4L2-PIX-FMT-BGR161616:
> +
> + - ``V4L2_PIX_FMT_BGR161616``
B16G16R16
Regards,
Hans
> + - 'XB48'
> +
> + - R\ :sub:`7-0`
> + - R\ :sub:`15-8`
> + - G\ :sub:`7-0`
> + - G\ :sub:`15-8`
> + - B\ :sub:`7-0`
> + - B\ :sub:`15-8`
> +
> +.. raw:: latex
> +
> + \endgroup
> +
> +
> Deprecated RGB Formats
> ======================
>
> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> index 3f5f1cf8d1c0..9181e44c20db 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -561,6 +561,11 @@ struct v4l2_pix_format {
> #define V4L2_PIX_FMT_ARGB32 v4l2_fourcc('B', 'A', '2', '4') /* 32 ARGB-8-8-8-8 */
> #define V4L2_PIX_FMT_XRGB32 v4l2_fourcc('B', 'X', '2', '4') /* 32 XRGB-8-8-8-8 */
>
> +/* RGB formats (more than 8 bits per component) */
> +#define V4L2_PIX_FMT_XBGR2101010 v4l2_fourcc('X', 'B', '3', '0') /* 32 XBGR-2-10-10-10 */
> +#define V4L2_PIX_FMT_XBGR4121212 v4l2_fourcc('X', 'B', '3', '6') /* 40 XBGR-4-12-12-12 */
> +#define V4L2_PIX_FMT_BGR161616 v4l2_fourcc('X', 'B', '4', '8') /* 48 BGR-16-16-16 */
> +
> /* Grey formats */
> #define V4L2_PIX_FMT_GREY v4l2_fourcc('G', 'R', 'E', 'Y') /* 8 Greyscale */
> #define V4L2_PIX_FMT_Y4 v4l2_fourcc('Y', '0', '4', ' ') /* 4 Greyscale */
>
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 13/16] media: v4l2: Add 10-, 12- and 16-bpc BGR formats
2020-10-01 13:44 ` Hans Verkuil
@ 2020-11-01 0:30 ` Laurent Pinchart
0 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-11-01 0:30 UTC (permalink / raw)
To: Hans Verkuil; +Cc: linux-media, Sakari Ailus, Dylan Yip, Vishal Sagar
Hi Hans,
On Thu, Oct 01, 2020 at 03:44:46PM +0200, Hans Verkuil wrote:
> On 23/09/2020 04:43, Laurent Pinchart wrote:
> > Add three new pixel formats that store RGB data in BGR order with 10, 12
> > and 16 bits per component. They are used by the Xilinx Video Frame
> > Buffer Read/Write IP cores.
> >
> > The nomenclature for these new formats follows the 8- and 16-bpp RGB
> > formats and the DRM format naming conventions, which differs from the
> > 24- and 32-bpp RGB formats in V4L2.
> >
> > As the number of bits per pixel grows quite large, a table with one
> > column per bit would be difficult to read. These formats are thus
> > described with one column per byte.
> >
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> > .../userspace-api/media/v4l/pixfmt-rgb.rst | 68 +++++++++++++++++++
> > include/uapi/linux/videodev2.h | 5 ++
> > 2 files changed, 73 insertions(+)
> >
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > index 32bfd68af425..2e81d448177e 100644
> > --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > @@ -1087,6 +1087,74 @@ order of components as seen in a 24- or 32-bit little endian word.
> > \endgroup
> >
> >
> > +More Than 8 Bits Per Component
> > +==============================
> > +
> > +These formats store an RGB triplet in four bytes or more. Similarly to the 8-
> > +and 16-bpp formats, they are named based on the order of the RGB components as
> > +seen in a word, which is then stored in memory in little endian byte order, and
> > +on the number of bits for each component.
> > +
> > +.. raw:: latex
> > +
> > + \begingroup
> > + \tiny
> > + \setlength{\tabcolsep}{2pt}
> > +
> > +.. tabularcolumns:: |p{2.8cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|p{2.0cm}|
> > +
> > +
> > +.. flat-table:: RGB Formats With More Than 8 Bits Per Component
> > + :stub-columns: 0
> > +
> > + * - Identifier
> > + - Code
> > + - Byte 0 in memory
> > + - Byte 1
> > + - Byte 2
> > + - Byte 3
> > + - Byte 4
> > + - Byte 5
> > + * .. _V4L2-PIX-FMT-XBGR2101010:
> > +
> > + - ``V4L2_PIX_FMT_XBGR2101010``
>
> How about naming this: 'X2B10G10R10'. That makes it easier to understand the
> number of bits assigned to each pixel component.
>
> An alternative (but more verbose) would be: XBGR_2_10_10_10.
Both depart from existing naming conventions, but I think they have
merit. I'm not sure which one to pick though. I'll go for the former,
but if anyone prefers the latter, that's fine too.
> > + - 'XB30'
> > +
> > + - R\ :sub:`7-0`
> > + - G\ :sub:`5-0` R\ :sub:`9-8`
> > + - B\ :sub:`3-0` G\ :sub:`9-6`
> > + - `-`\ :sub:`1-0` B\ :sub:`9-4`
> > +
> > + -
> > + * .. _V4L2-PIX-FMT-XBGR4121212:
> > +
> > + - ``V4L2_PIX_FMT_XBGR4121212``
>
> X4B12G12R12
>
> > + - 'XB36'
> > +
> > + - R\ :sub:`7-0`
> > + - G\ :sub:`3-0` R\ :sub:`11-8`
> > + - G\ :sub:`11-4`
> > + - B\ :sub:`7-0`
> > + - `-`\ :sub:`3-0` B\ :sub:`11-8`
> > +
> > + -
> > + * .. _V4L2-PIX-FMT-BGR161616:
> > +
> > + - ``V4L2_PIX_FMT_BGR161616``
>
> B16G16R16
>
> > + - 'XB48'
> > +
> > + - R\ :sub:`7-0`
> > + - R\ :sub:`15-8`
> > + - G\ :sub:`7-0`
> > + - G\ :sub:`15-8`
> > + - B\ :sub:`7-0`
> > + - B\ :sub:`15-8`
> > +
> > +.. raw:: latex
> > +
> > + \endgroup
> > +
> > +
> > Deprecated RGB Formats
> > ======================
> >
> > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > index 3f5f1cf8d1c0..9181e44c20db 100644
> > --- a/include/uapi/linux/videodev2.h
> > +++ b/include/uapi/linux/videodev2.h
> > @@ -561,6 +561,11 @@ struct v4l2_pix_format {
> > #define V4L2_PIX_FMT_ARGB32 v4l2_fourcc('B', 'A', '2', '4') /* 32 ARGB-8-8-8-8 */
> > #define V4L2_PIX_FMT_XRGB32 v4l2_fourcc('B', 'X', '2', '4') /* 32 XRGB-8-8-8-8 */
> >
> > +/* RGB formats (more than 8 bits per component) */
> > +#define V4L2_PIX_FMT_XBGR2101010 v4l2_fourcc('X', 'B', '3', '0') /* 32 XBGR-2-10-10-10 */
> > +#define V4L2_PIX_FMT_XBGR4121212 v4l2_fourcc('X', 'B', '3', '6') /* 40 XBGR-4-12-12-12 */
> > +#define V4L2_PIX_FMT_BGR161616 v4l2_fourcc('X', 'B', '4', '8') /* 48 BGR-16-16-16 */
> > +
> > /* Grey formats */
> > #define V4L2_PIX_FMT_GREY v4l2_fourcc('G', 'R', 'E', 'Y') /* 8 Greyscale */
> > #define V4L2_PIX_FMT_Y4 v4l2_fourcc('Y', '0', '4', ' ') /* 4 Greyscale */
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH/RFC 14/16] media: v4l2: Add a few missing packed YUV 4:4:4 formats
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (12 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 13/16] media: v4l2: Add 10-, 12- and 16-bpc BGR formats Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 15/16] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats Laurent Pinchart
2020-09-23 2:43 ` [PATCH/RFC 16/16] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing Laurent Pinchart
15 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Add three new formats belonging to the packed YUV 4:4:4 family. They are
used by the Xilinx Video Frame Buffer Read/Write IP cores.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../media/v4l/pixfmt-packed-yuv.rst | 29 +++++++++++++++++++
include/uapi/linux/videodev2.h | 3 ++
2 files changed, 32 insertions(+)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
index 81b95ca25fb7..3c7c8e38b7b7 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -177,6 +177,15 @@ the second byte and Y'\ :sub:`7-0` in the third byte.
- Byte 2
- Byte 3
+ * .. _V4L2-PIX-FMT-YUV24:
+
+ - ``V4L2_PIX_FMT_YUV24``
+ - 'YUV3'
+
+ - Y'\ :sub:`7-0`
+ - Cb\ :sub:`7-0`
+ - Cr\ :sub:`7-0`
+
* .. _V4L2-PIX-FMT-YUV32:
- ``V4L2_PIX_FMT_YUV32``
@@ -227,6 +236,26 @@ the second byte and Y'\ :sub:`7-0` in the third byte.
- Y'\ :sub:`7-0`
- `-`\ :sub:`7-0`
+ * .. _V4L2-PIX-FMT-YUVA32:
+
+ - ``V4L2_PIX_FMT_YUVA32``
+ - 'YUVA'
+
+ - Y'\ :sub:`7-0`
+ - Cb\ :sub:`7-0`
+ - Cr\ :sub:`7-0`
+ - `-`\ :sub:`7-0`
+
+ * .. _V4L2-PIX-FMT-YUVX32:
+
+ - ``V4L2_PIX_FMT_YUVX32``
+ - 'YUVX'
+
+ - Y'\ :sub:`7-0`
+ - Cb\ :sub:`7-0`
+ - Cr\ :sub:`7-0`
+ - `-`\ :sub:`7-0`
+
.. note::
- The alpha component is expected to contain a meaningful value that can be
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 9181e44c20db..503a938ea98c 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -596,11 +596,14 @@ struct v4l2_pix_format {
#define V4L2_PIX_FMT_YUV444 v4l2_fourcc('Y', '4', '4', '4') /* 16 xxxxyyyy uuuuvvvv */
#define V4L2_PIX_FMT_YUV555 v4l2_fourcc('Y', 'U', 'V', 'O') /* 16 YUV-5-5-5 */
#define V4L2_PIX_FMT_YUV565 v4l2_fourcc('Y', 'U', 'V', 'P') /* 16 YUV-5-6-5 */
+#define V4L2_PIX_FMT_YUV24 v4l2_fourcc('Y', 'U', 'V', '3') /* 24 YUV-8-8-8 */
#define V4L2_PIX_FMT_YUV32 v4l2_fourcc('Y', 'U', 'V', '4') /* 32 YUV-8-8-8-8 */
#define V4L2_PIX_FMT_AYUV32 v4l2_fourcc('A', 'Y', 'U', 'V') /* 32 AYUV-8-8-8-8 */
#define V4L2_PIX_FMT_XYUV32 v4l2_fourcc('X', 'Y', 'U', 'V') /* 32 XYUV-8-8-8-8 */
#define V4L2_PIX_FMT_VUYA32 v4l2_fourcc('V', 'U', 'Y', 'A') /* 32 VUYA-8-8-8-8 */
#define V4L2_PIX_FMT_VUYX32 v4l2_fourcc('V', 'U', 'Y', 'X') /* 32 VUYX-8-8-8-8 */
+#define V4L2_PIX_FMT_YUVA32 v4l2_fourcc('Y', 'U', 'V', 'A') /* 32 YUVA-8-8-8-8 */
+#define V4L2_PIX_FMT_YUVX32 v4l2_fourcc('Y', 'U', 'V', 'X') /* 32 YUVX-8-8-8-8 */
#define V4L2_PIX_FMT_M420 v4l2_fourcc('M', '4', '2', '0') /* 12 YUV 4:2:0 2 lines y, 1 line uv interleaved */
/* two planes -- one Y, one Cr + Cb interleaved */
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* [PATCH/RFC 15/16] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (13 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 14/16] media: v4l2: Add a few missing packed YUV 4:4:4 formats Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-24 18:24 ` Nicolas Dufresne
2020-09-23 2:43 ` [PATCH/RFC 16/16] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing Laurent Pinchart
15 siblings, 1 reply; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Add three new formats storing packed YUV 4:4:4 in 10-, 12- and 16-bpc
variants, with component order VUY. They are used by the Xilinx Video
Frame Buffer Read/Write IP cores.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../media/v4l/pixfmt-packed-yuv.rst | 55 +++++++++++++++++++
include/uapi/linux/videodev2.h | 3 +
2 files changed, 58 insertions(+)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
index 3c7c8e38b7b7..4753ee8c6b7d 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -264,6 +264,61 @@ the second byte and Y'\ :sub:`7-0` in the third byte.
applications and drivers.
+The next table lists the packed YUV 4:4:4 formats with more than 8 bits per
+component. They are named similarly to the formats with less than 8 bits per
+components, based on the order of the Y, Cb and Cr components as seen in a
+word, which is then stored in memory in little endian byte order, and on the
+number of bits for each component.
+
+.. flat-table:: Packed YUV Image Formats (more than 8bpc)
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - Byte 0
+ - Byte 1
+ - Byte 2
+ - Byte 3
+ - Byte 4
+ - Byte 5
+
+ * .. _V4L2-PIX-FMT-XVUY2101010:
+
+ - ``V4L2_PIX_FMT_XVUY2101010``
+ - 'VY30'
+
+ - Y'\ :sub:`7-0`
+ - Cb\ :sub:`5-0` Y'\ :sub:`9-8`
+ - Cr\ :sub:`3-0` Cb\ :sub:`9-6`
+ - `-`\ :sub:`1-0` Cr\ :sub:`9-4`
+ -
+
+ * .. _V4L2-PIX-FMT-XVUY4121212:
+
+ - ``V4L2_PIX_FMT_XVUY4121212``
+ - 'VY36'
+
+ - Y'\ :sub:`7-0`
+ - Cb\ :sub:`3-0` Y'\ :sub:`11-8`
+ - Cb\ :sub:`11-4`
+ - Cr\ :sub:`7-0`
+ - `-`\ :sub:`3-0` Cr\ :sub:`11-8`
+ -
+
+ * .. _V4L2-PIX-FMT-VUY161616:
+
+ - ``V4L2_PIX_FMT_VUY161616``
+ - 'VY40'
+
+ - Y'\ :sub:`7-0`
+ - Y'\ :sub:`15-8`
+ - Cb\ :sub:`7-0`
+ - Cb\ :sub:`15-8`
+ - Cr\ :sub:`7-0`
+ - Cr\ :sub:`15-8`
+
+
4:2:2 Subsampling
=================
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 503a938ea98c..9b4cab651df7 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -605,6 +605,9 @@ struct v4l2_pix_format {
#define V4L2_PIX_FMT_YUVA32 v4l2_fourcc('Y', 'U', 'V', 'A') /* 32 YUVA-8-8-8-8 */
#define V4L2_PIX_FMT_YUVX32 v4l2_fourcc('Y', 'U', 'V', 'X') /* 32 YUVX-8-8-8-8 */
#define V4L2_PIX_FMT_M420 v4l2_fourcc('M', '4', '2', '0') /* 12 YUV 4:2:0 2 lines y, 1 line uv interleaved */
+#define V4L2_PIX_FMT_XVUY2101010 v4l2_fourcc('V', 'Y', '3', '0') /* 32 XVUY-2-10-10-10 */
+#define V4L2_PIX_FMT_XVUY4121212 v4l2_fourcc('V', 'Y', '3', '6') /* 40 XVUY-4-12-12-12 */
+#define V4L2_PIX_FMT_VUY161616 v4l2_fourcc('V', 'Y', '4', '8') /* 48 VUY-16-16-16 */
/* two planes -- one Y, one Cr + Cb interleaved */
#define V4L2_PIX_FMT_NV12 v4l2_fourcc('N', 'V', '1', '2') /* 12 Y/CbCr 4:2:0 */
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 15/16] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats
2020-09-23 2:43 ` [PATCH/RFC 15/16] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats Laurent Pinchart
@ 2020-09-24 18:24 ` Nicolas Dufresne
2020-11-01 0:38 ` Laurent Pinchart
0 siblings, 1 reply; 31+ messages in thread
From: Nicolas Dufresne @ 2020-09-24 18:24 UTC (permalink / raw)
To: Laurent Pinchart, linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> Add three new formats storing packed YUV 4:4:4 in 10-, 12- and 16-bpc
> variants, with component order VUY. They are used by the Xilinx Video
> Frame Buffer Read/Write IP cores.
>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> .../media/v4l/pixfmt-packed-yuv.rst | 55 +++++++++++++++++++
> include/uapi/linux/videodev2.h | 3 +
> 2 files changed, 58 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> index 3c7c8e38b7b7..4753ee8c6b7d 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> @@ -264,6 +264,61 @@ the second byte and Y'\ :sub:`7-0` in the third byte.
> applications and drivers.
>
>
> +The next table lists the packed YUV 4:4:4 formats with more than 8 bits per
> +component. They are named similarly to the formats with less than 8 bits per
> +components, based on the order of the Y, Cb and Cr components as seen in a
> +word, which is then stored in memory in little endian byte order, and on the
> +number of bits for each component.
> +
> +.. flat-table:: Packed YUV Image Formats (more than 8bpc)
> + :header-rows: 1
> + :stub-columns: 0
> +
> + * - Identifier
> + - Code
> + - Byte 0
> + - Byte 1
> + - Byte 2
> + - Byte 3
> + - Byte 4
> + - Byte 5
> +
> + * .. _V4L2-PIX-FMT-XVUY2101010:
> +
> + - ``V4L2_PIX_FMT_XVUY2101010``
> + - 'VY30'
> +
> + - Y'\ :sub:`7-0`
> + - Cb\ :sub:`5-0` Y'\ :sub:`9-8`
> + - Cr\ :sub:`3-0` Cb\ :sub:`9-6`
> + - `-`\ :sub:`1-0` Cr\ :sub:`9-4`
> + -
> +
> + * .. _V4L2-PIX-FMT-XVUY4121212:
> +
> + - ``V4L2_PIX_FMT_XVUY4121212``
> + - 'VY36'
> +
> + - Y'\ :sub:`7-0`
> + - Cb\ :sub:`3-0` Y'\ :sub:`11-8`
> + - Cb\ :sub:`11-4`
> + - Cr\ :sub:`7-0`
> + - `-`\ :sub:`3-0` Cr\ :sub:`11-8`
> + -
> +
> + * .. _V4L2-PIX-FMT-VUY161616:
> +
> + - ``V4L2_PIX_FMT_VUY161616``
> + - 'VY40'
> +
> + - Y'\ :sub:`7-0`
> + - Y'\ :sub:`15-8`
> + - Cb\ :sub:`7-0`
> + - Cb\ :sub:`15-8`
> + - Cr\ :sub:`7-0`
> + - Cr\ :sub:`15-8`
> +
> +
> 4:2:2 Subsampling
> =================
>
> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> index 503a938ea98c..9b4cab651df7 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -605,6 +605,9 @@ struct v4l2_pix_format {
> #define V4L2_PIX_FMT_YUVA32 v4l2_fourcc('Y', 'U', 'V', 'A') /* 32 YUVA-8-8-8-8 */
> #define V4L2_PIX_FMT_YUVX32 v4l2_fourcc('Y', 'U', 'V', 'X') /* 32 YUVX-8-8-8-8 */
> #define V4L2_PIX_FMT_M420 v4l2_fourcc('M', '4', '2', '0') /* 12 YUV 4:2:0 2 lines y, 1 line uv interleaved */
> +#define V4L2_PIX_FMT_XVUY2101010 v4l2_fourcc('V', 'Y', '3', '0') /* 32 XVUY-2-10-10-10 */
> +#define V4L2_PIX_FMT_XVUY4121212 v4l2_fourcc('V', 'Y', '3', '6') /* 40 XVUY-4-12-12-12 */
> +#define V4L2_PIX_FMT_VUY161616 v4l2_fourcc('V', 'Y', '4', '8') /* 48 VUY-16-16-16 */
That is very hard to read. I'm fine with being more verbose, but I
think it would be nice if it remains human readable. A possible fix
could be:
V4L2_PIX_FMT_XVUY_2_10_10_10
Another approach is a bit-per-component and pixel size approach. That
one would be XYUV10_32. It is more cryptic, and you need more doc to
understand.
That brings me to endianness, I believe it does matter for these
unaligned component, so that should be documented (little).
>
> /* two planes -- one Y, one Cr + Cb interleaved */
> #define V4L2_PIX_FMT_NV12 v4l2_fourcc('N', 'V', '1', '2') /* 12 Y/CbCr 4:2:0 */
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 15/16] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats
2020-09-24 18:24 ` Nicolas Dufresne
@ 2020-11-01 0:38 ` Laurent Pinchart
2020-11-02 20:39 ` Nicolas Dufresne
0 siblings, 1 reply; 31+ messages in thread
From: Laurent Pinchart @ 2020-11-01 0:38 UTC (permalink / raw)
To: Nicolas Dufresne
Cc: linux-media, Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Hi Nicolas,
On Thu, Sep 24, 2020 at 02:24:44PM -0400, Nicolas Dufresne wrote:
> Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> > Add three new formats storing packed YUV 4:4:4 in 10-, 12- and 16-bpc
> > variants, with component order VUY. They are used by the Xilinx Video
> > Frame Buffer Read/Write IP cores.
> >
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> > .../media/v4l/pixfmt-packed-yuv.rst | 55 +++++++++++++++++++
> > include/uapi/linux/videodev2.h | 3 +
> > 2 files changed, 58 insertions(+)
> >
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> > index 3c7c8e38b7b7..4753ee8c6b7d 100644
> > --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> > @@ -264,6 +264,61 @@ the second byte and Y'\ :sub:`7-0` in the third byte.
> > applications and drivers.
> >
> >
> > +The next table lists the packed YUV 4:4:4 formats with more than 8 bits per
> > +component. They are named similarly to the formats with less than 8 bits per
> > +components, based on the order of the Y, Cb and Cr components as seen in a
> > +word, which is then stored in memory in little endian byte order, and on the
> > +number of bits for each component.
> > +
> > +.. flat-table:: Packed YUV Image Formats (more than 8bpc)
> > + :header-rows: 1
> > + :stub-columns: 0
> > +
> > + * - Identifier
> > + - Code
> > + - Byte 0
> > + - Byte 1
> > + - Byte 2
> > + - Byte 3
> > + - Byte 4
> > + - Byte 5
> > +
> > + * .. _V4L2-PIX-FMT-XVUY2101010:
> > +
> > + - ``V4L2_PIX_FMT_XVUY2101010``
> > + - 'VY30'
> > +
> > + - Y'\ :sub:`7-0`
> > + - Cb\ :sub:`5-0` Y'\ :sub:`9-8`
> > + - Cr\ :sub:`3-0` Cb\ :sub:`9-6`
> > + - `-`\ :sub:`1-0` Cr\ :sub:`9-4`
> > + -
> > +
> > + * .. _V4L2-PIX-FMT-XVUY4121212:
> > +
> > + - ``V4L2_PIX_FMT_XVUY4121212``
> > + - 'VY36'
> > +
> > + - Y'\ :sub:`7-0`
> > + - Cb\ :sub:`3-0` Y'\ :sub:`11-8`
> > + - Cb\ :sub:`11-4`
> > + - Cr\ :sub:`7-0`
> > + - `-`\ :sub:`3-0` Cr\ :sub:`11-8`
> > + -
> > +
> > + * .. _V4L2-PIX-FMT-VUY161616:
> > +
> > + - ``V4L2_PIX_FMT_VUY161616``
> > + - 'VY40'
> > +
> > + - Y'\ :sub:`7-0`
> > + - Y'\ :sub:`15-8`
> > + - Cb\ :sub:`7-0`
> > + - Cb\ :sub:`15-8`
> > + - Cr\ :sub:`7-0`
> > + - Cr\ :sub:`15-8`
> > +
> > +
> > 4:2:2 Subsampling
> > =================
> >
> > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > index 503a938ea98c..9b4cab651df7 100644
> > --- a/include/uapi/linux/videodev2.h
> > +++ b/include/uapi/linux/videodev2.h
> > @@ -605,6 +605,9 @@ struct v4l2_pix_format {
> > #define V4L2_PIX_FMT_YUVA32 v4l2_fourcc('Y', 'U', 'V', 'A') /* 32 YUVA-8-8-8-8 */
> > #define V4L2_PIX_FMT_YUVX32 v4l2_fourcc('Y', 'U', 'V', 'X') /* 32 YUVX-8-8-8-8 */
> > #define V4L2_PIX_FMT_M420 v4l2_fourcc('M', '4', '2', '0') /* 12 YUV 4:2:0 2 lines y, 1 line uv interleaved */
> > +#define V4L2_PIX_FMT_XVUY2101010 v4l2_fourcc('V', 'Y', '3', '0') /* 32 XVUY-2-10-10-10 */
> > +#define V4L2_PIX_FMT_XVUY4121212 v4l2_fourcc('V', 'Y', '3', '6') /* 40 XVUY-4-12-12-12 */
> > +#define V4L2_PIX_FMT_VUY161616 v4l2_fourcc('V', 'Y', '4', '8') /* 48 VUY-16-16-16 */
>
> That is very hard to read. I'm fine with being more verbose, but I
> think it would be nice if it remains human readable. A possible fix
> could be:
>
> V4L2_PIX_FMT_XVUY_2_10_10_10
Hans has proposed an interleave naming scheme in the review of 13/16.
This would become X2V10U10Y10. He also mentioned an alternative option
that would match your proposal above. I don't have a strong preference.
Can you and Hans agree on the best option ?
> Another approach is a bit-per-component and pixel size approach. That
> one would be XYUV10_32. It is more cryptic, and you need more doc to
> understand.
>
> That brings me to endianness, I believe it does matter for these
> unaligned component, so that should be documented (little).
That's already documented in
Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst.
> > /* two planes -- one Y, one Cr + Cb interleaved */
> > #define V4L2_PIX_FMT_NV12 v4l2_fourcc('N', 'V', '1', '2') /* 12 Y/CbCr 4:2:0 */
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 15/16] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats
2020-11-01 0:38 ` Laurent Pinchart
@ 2020-11-02 20:39 ` Nicolas Dufresne
2020-11-02 22:08 ` Laurent Pinchart
0 siblings, 1 reply; 31+ messages in thread
From: Nicolas Dufresne @ 2020-11-02 20:39 UTC (permalink / raw)
To: Laurent Pinchart
Cc: linux-media, Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Le dimanche 01 novembre 2020 à 02:38 +0200, Laurent Pinchart a écrit :
> Hi Nicolas,
>
> On Thu, Sep 24, 2020 at 02:24:44PM -0400, Nicolas Dufresne wrote:
> > Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> > > Add three new formats storing packed YUV 4:4:4 in 10-, 12- and 16-bpc
> > > variants, with component order VUY. They are used by the Xilinx Video
> > > Frame Buffer Read/Write IP cores.
> > >
> > > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > > ---
> > > .../media/v4l/pixfmt-packed-yuv.rst | 55 +++++++++++++++++++
> > > include/uapi/linux/videodev2.h | 3 +
> > > 2 files changed, 58 insertions(+)
> > >
> > > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> > > index 3c7c8e38b7b7..4753ee8c6b7d 100644
> > > --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> > > +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> > > @@ -264,6 +264,61 @@ the second byte and Y'\ :sub:`7-0` in the third byte.
> > > applications and drivers.
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > > +The next table lists the packed YUV 4:4:4 formats with more than 8 bits per
> > > +component. They are named similarly to the formats with less than 8 bits per
> > > +components, based on the order of the Y, Cb and Cr components as seen in a
> > > +word, which is then stored in memory in little endian byte order, and on the
> > > +number of bits for each component.
> > > +
> > > +.. flat-table:: Packed YUV Image Formats (more than 8bpc)
> > > + :header-rows: 1
> > > + :stub-columns: 0
> > > +
> > > + * - Identifier
> > > + - Code
> > > + - Byte 0
> > > + - Byte 1
> > > + - Byte 2
> > > + - Byte 3
> > > + - Byte 4
> > > + - Byte 5
> > > +
> > > + * .. _V4L2-PIX-FMT-XVUY2101010:
> > > +
> > > + - ``V4L2_PIX_FMT_XVUY2101010``
> > > + - 'VY30'
> > > +
> > > + - Y'\ :sub:`7-0`
> > > + - Cb\ :sub:`5-0` Y'\ :sub:`9-8`
> > > + - Cr\ :sub:`3-0` Cb\ :sub:`9-6`
> > > + - `-`\ :sub:`1-0` Cr\ :sub:`9-4`
> > > + -
> > > +
> > > + * .. _V4L2-PIX-FMT-XVUY4121212:
> > > +
> > > + - ``V4L2_PIX_FMT_XVUY4121212``
> > > + - 'VY36'
> > > +
> > > + - Y'\ :sub:`7-0`
> > > + - Cb\ :sub:`3-0` Y'\ :sub:`11-8`
> > > + - Cb\ :sub:`11-4`
> > > + - Cr\ :sub:`7-0`
> > > + - `-`\ :sub:`3-0` Cr\ :sub:`11-8`
> > > + -
> > > +
> > > + * .. _V4L2-PIX-FMT-VUY161616:
> > > +
> > > + - ``V4L2_PIX_FMT_VUY161616``
> > > + - 'VY40'
> > > +
> > > + - Y'\ :sub:`7-0`
> > > + - Y'\ :sub:`15-8`
> > > + - Cb\ :sub:`7-0`
> > > + - Cb\ :sub:`15-8`
> > > + - Cr\ :sub:`7-0`
> > > + - Cr\ :sub:`15-8`
> > > +
> > > +
> > > 4:2:2 Subsampling
> > > =================
> > >
> > >
> > >
> > >
> > > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > > index 503a938ea98c..9b4cab651df7 100644
> > > --- a/include/uapi/linux/videodev2.h
> > > +++ b/include/uapi/linux/videodev2.h
> > > @@ -605,6 +605,9 @@ struct v4l2_pix_format {
> > > #define V4L2_PIX_FMT_YUVA32 v4l2_fourcc('Y', 'U', 'V', 'A') /* 32 YUVA-8-8-8-8 */
> > > #define V4L2_PIX_FMT_YUVX32 v4l2_fourcc('Y', 'U', 'V', 'X') /* 32 YUVX-8-8-8-8 */
> > > #define V4L2_PIX_FMT_M420 v4l2_fourcc('M', '4', '2', '0') /* 12 YUV 4:2:0 2 lines y, 1 line uv interleaved */
> > > +#define V4L2_PIX_FMT_XVUY2101010 v4l2_fourcc('V', 'Y', '3', '0') /* 32 XVUY-2-10-10-10 */
> > > +#define V4L2_PIX_FMT_XVUY4121212 v4l2_fourcc('V', 'Y', '3', '6') /* 40 XVUY-4-12-12-12 */
> > > +#define V4L2_PIX_FMT_VUY161616 v4l2_fourcc('V', 'Y', '4', '8') /* 48 VUY-16-16-16 */
> >
> > That is very hard to read. I'm fine with being more verbose, but I
> > think it would be nice if it remains human readable. A possible fix
> > could be:
> >
> > V4L2_PIX_FMT_XVUY_2_10_10_10
>
> Hans has proposed an interleave naming scheme in the review of 13/16.
> This would become X2V10U10Y10. He also mentioned an alternative option
> that would match your proposal above. I don't have a strong preference.
> Can you and Hans agree on the best option ?
Not that I have a strong preference, they equally describe the format.
1. V4L2_PIX_FMT_X2V10U10Y10:
This is more compact and more likely to fit 80 to 100 chars when
coding.
2. V4L2_PIX_FMT_XVUY_2_10_10_10:
It splits the component order and leave the component size easy to
read. It is overall easier to identify on first read.
I read more code then I write, so my obvious preference would be 2.,
but I'm fine with any.
> > Another approach is a bit-per-component and pixel size approach. That
> > one would be XYUV10_32. It is more cryptic, and you need more doc to
> > understand.
> >
> > That brings me to endianness, I believe it does matter for these
> > unaligned component, so that should be documented (little).
>
> That's already documented in
> Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst.
Ack.
>
> > > /* two planes -- one Y, one Cr + Cb interleaved */
> > > #define V4L2_PIX_FMT_NV12 v4l2_fourcc('N', 'V', '1', '2') /* 12 Y/CbCr 4:2:0 */
>
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 15/16] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats
2020-11-02 20:39 ` Nicolas Dufresne
@ 2020-11-02 22:08 ` Laurent Pinchart
0 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:08 UTC (permalink / raw)
To: Nicolas Dufresne
Cc: linux-media, Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Hi Nicolas,
On Mon, Nov 02, 2020 at 03:39:25PM -0500, Nicolas Dufresne wrote:
> Le dimanche 01 novembre 2020 à 02:38 +0200, Laurent Pinchart a écrit :
> > On Thu, Sep 24, 2020 at 02:24:44PM -0400, Nicolas Dufresne wrote:
> > > Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> > > > Add three new formats storing packed YUV 4:4:4 in 10-, 12- and 16-bpc
> > > > variants, with component order VUY. They are used by the Xilinx Video
> > > > Frame Buffer Read/Write IP cores.
> > > >
> > > > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > > > ---
> > > > .../media/v4l/pixfmt-packed-yuv.rst | 55 +++++++++++++++++++
> > > > include/uapi/linux/videodev2.h | 3 +
> > > > 2 files changed, 58 insertions(+)
> > > >
> > > > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> > > > index 3c7c8e38b7b7..4753ee8c6b7d 100644
> > > > --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> > > > +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> > > > @@ -264,6 +264,61 @@ the second byte and Y'\ :sub:`7-0` in the third byte.
> > > > applications and drivers.
> > > >
> > > > +The next table lists the packed YUV 4:4:4 formats with more than 8 bits per
> > > > +component. They are named similarly to the formats with less than 8 bits per
> > > > +components, based on the order of the Y, Cb and Cr components as seen in a
> > > > +word, which is then stored in memory in little endian byte order, and on the
> > > > +number of bits for each component.
> > > > +
> > > > +.. flat-table:: Packed YUV Image Formats (more than 8bpc)
> > > > + :header-rows: 1
> > > > + :stub-columns: 0
> > > > +
> > > > + * - Identifier
> > > > + - Code
> > > > + - Byte 0
> > > > + - Byte 1
> > > > + - Byte 2
> > > > + - Byte 3
> > > > + - Byte 4
> > > > + - Byte 5
> > > > +
> > > > + * .. _V4L2-PIX-FMT-XVUY2101010:
> > > > +
> > > > + - ``V4L2_PIX_FMT_XVUY2101010``
> > > > + - 'VY30'
> > > > +
> > > > + - Y'\ :sub:`7-0`
> > > > + - Cb\ :sub:`5-0` Y'\ :sub:`9-8`
> > > > + - Cr\ :sub:`3-0` Cb\ :sub:`9-6`
> > > > + - `-`\ :sub:`1-0` Cr\ :sub:`9-4`
> > > > + -
> > > > +
> > > > + * .. _V4L2-PIX-FMT-XVUY4121212:
> > > > +
> > > > + - ``V4L2_PIX_FMT_XVUY4121212``
> > > > + - 'VY36'
> > > > +
> > > > + - Y'\ :sub:`7-0`
> > > > + - Cb\ :sub:`3-0` Y'\ :sub:`11-8`
> > > > + - Cb\ :sub:`11-4`
> > > > + - Cr\ :sub:`7-0`
> > > > + - `-`\ :sub:`3-0` Cr\ :sub:`11-8`
> > > > + -
> > > > +
> > > > + * .. _V4L2-PIX-FMT-VUY161616:
> > > > +
> > > > + - ``V4L2_PIX_FMT_VUY161616``
> > > > + - 'VY40'
> > > > +
> > > > + - Y'\ :sub:`7-0`
> > > > + - Y'\ :sub:`15-8`
> > > > + - Cb\ :sub:`7-0`
> > > > + - Cb\ :sub:`15-8`
> > > > + - Cr\ :sub:`7-0`
> > > > + - Cr\ :sub:`15-8`
> > > > +
> > > > +
> > > > 4:2:2 Subsampling
> > > > =================
> > > >
> > > >
> > > >
> > > >
> > > > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > > > index 503a938ea98c..9b4cab651df7 100644
> > > > --- a/include/uapi/linux/videodev2.h
> > > > +++ b/include/uapi/linux/videodev2.h
> > > > @@ -605,6 +605,9 @@ struct v4l2_pix_format {
> > > > #define V4L2_PIX_FMT_YUVA32 v4l2_fourcc('Y', 'U', 'V', 'A') /* 32 YUVA-8-8-8-8 */
> > > > #define V4L2_PIX_FMT_YUVX32 v4l2_fourcc('Y', 'U', 'V', 'X') /* 32 YUVX-8-8-8-8 */
> > > > #define V4L2_PIX_FMT_M420 v4l2_fourcc('M', '4', '2', '0') /* 12 YUV 4:2:0 2 lines y, 1 line uv interleaved */
> > > > +#define V4L2_PIX_FMT_XVUY2101010 v4l2_fourcc('V', 'Y', '3', '0') /* 32 XVUY-2-10-10-10 */
> > > > +#define V4L2_PIX_FMT_XVUY4121212 v4l2_fourcc('V', 'Y', '3', '6') /* 40 XVUY-4-12-12-12 */
> > > > +#define V4L2_PIX_FMT_VUY161616 v4l2_fourcc('V', 'Y', '4', '8') /* 48 VUY-16-16-16 */
> > >
> > > That is very hard to read. I'm fine with being more verbose, but I
> > > think it would be nice if it remains human readable. A possible fix
> > > could be:
> > >
> > > V4L2_PIX_FMT_XVUY_2_10_10_10
> >
> > Hans has proposed an interleave naming scheme in the review of 13/16.
> > This would become X2V10U10Y10. He also mentioned an alternative option
> > that would match your proposal above. I don't have a strong preference.
> > Can you and Hans agree on the best option ?
>
> Not that I have a strong preference, they equally describe the format.
>
> 1. V4L2_PIX_FMT_X2V10U10Y10:
>
> This is more compact and more likely to fit 80 to 100 chars when
> coding.
>
> 2. V4L2_PIX_FMT_XVUY_2_10_10_10:
>
> It splits the component order and leave the component size easy to
> read. It is overall easier to identify on first read.
>
> I read more code then I write, so my obvious preference would be 2.,
> but I'm fine with any.
I had already updated the patches with the first option, so I'll send a
v2 with that, while waiting for Hans to comment on his preference. If he
doesn't mind much either way, I'll update to the second option and send
a v3.
> > > Another approach is a bit-per-component and pixel size approach. That
> > > one would be XYUV10_32. It is more cryptic, and you need more doc to
> > > understand.
> > >
> > > That brings me to endianness, I believe it does matter for these
> > > unaligned component, so that should be documented (little).
> >
> > That's already documented in
> > Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst.
>
> Ack.
>
> > > > /* two planes -- one Y, one Cr + Cb interleaved */
> > > > #define V4L2_PIX_FMT_NV12 v4l2_fourcc('N', 'V', '1', '2') /* 12 Y/CbCr 4:2:0 */
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH/RFC 16/16] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing
2020-09-23 2:43 [PATCH/RFC 00/16] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (14 preceding siblings ...)
2020-09-23 2:43 ` [PATCH/RFC 15/16] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats Laurent Pinchart
@ 2020-09-23 2:43 ` Laurent Pinchart
2020-09-24 18:27 ` Nicolas Dufresne
15 siblings, 1 reply; 31+ messages in thread
From: Laurent Pinchart @ 2020-09-23 2:43 UTC (permalink / raw)
To: linux-media; +Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Add two new formats storing luma only in 10- and 12-bpc variants, with
linear packing. They are used by the Xilinx Video Frame Buffer
Read/Write IP cores.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../media/v4l/pixfmt-yuv-luma.rst | 23 +++++++++++++++++++
include/uapi/linux/videodev2.h | 2 ++
2 files changed, 25 insertions(+)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
index b24947b52cf8..3e2a7af5ed67 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
@@ -24,6 +24,7 @@ are often referred to as greyscale formats.
- Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum
`x`.
- `0` denotes padding bits set to 0.
+ - `-` denotes padding bits with undefined values.
.. flat-table:: Luma-Only Image Formats
@@ -82,6 +83,17 @@ are often referred to as greyscale formats.
- Y'\ :sub:`3`\ [9:2]
- Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0]
+ * .. _V4L2-PIX-FMT-Y10X:
+
+ - ``V4L2_PIX_FMT_Y10X``
+ - 'Y10X'
+
+ - Y'\ :sub:`0`\ [7:0]
+ - Y'\ :sub:`1`\ [5:0] Y'\ :sub:`0`\ [9:8]
+ - Y'\ :sub:`2`\ [3:0] Y'\ :sub:`1`\ [9:6]
+ - `- -` Y'\ :sub:`2`\ [9:4]
+ - ...
+
* .. _V4L2-PIX-FMT-Y12:
- ``V4L2_PIX_FMT_Y12``
@@ -93,6 +105,17 @@ are often referred to as greyscale formats.
- ...
- ...
+ * .. _V4L2-PIX-FMT-Y12X:
+
+ - ``V4L2_PIX_FMT_Y12X``
+ - 'Y12X'
+
+ - Y'\ :sub:`0`\ [7:0]
+ - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`0`\ [11:8]
+ - Y'\ :sub:`1`\ [11:4]
+ - Y'\ :sub:`2`\ [7:0]
+ - `- - - -` Y'\ :sub:`2`\ [11:8]
+
* .. _V4L2-PIX-FMT-Y14:
- ``V4L2_PIX_FMT_Y14``
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index 9b4cab651df7..3d137a020cdb 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -579,6 +579,8 @@ struct v4l2_pix_format {
/* Grey bit-packed formats */
#define V4L2_PIX_FMT_Y10BPACK v4l2_fourcc('Y', '1', '0', 'B') /* 10 Greyscale bit-packed */
#define V4L2_PIX_FMT_Y10P v4l2_fourcc('Y', '1', '0', 'P') /* 10 Greyscale, MIPI RAW10 packed */
+#define V4L2_PIX_FMT_Y10X v4l2_fourcc('Y', '1', '0', 'X') /* 10 Greyscale, 3 pixels in 4 bytes */
+#define V4L2_PIX_FMT_Y12X v4l2_fourcc('Y', '1', '2', 'X') /* 12 Greyscale, 4 pixels in 5 bytes */
/* Palette formats */
#define V4L2_PIX_FMT_PAL8 v4l2_fourcc('P', 'A', 'L', '8') /* 8 8-bit palette */
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 16/16] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing
2020-09-23 2:43 ` [PATCH/RFC 16/16] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing Laurent Pinchart
@ 2020-09-24 18:27 ` Nicolas Dufresne
2020-11-01 0:42 ` Laurent Pinchart
0 siblings, 1 reply; 31+ messages in thread
From: Nicolas Dufresne @ 2020-09-24 18:27 UTC (permalink / raw)
To: Laurent Pinchart, linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> Add two new formats storing luma only in 10- and 12-bpc variants, with
> linear packing. They are used by the Xilinx Video Frame Buffer
> Read/Write IP cores.
>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---
> .../media/v4l/pixfmt-yuv-luma.rst | 23 +++++++++++++++++++
> include/uapi/linux/videodev2.h | 2 ++
> 2 files changed, 25 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> index b24947b52cf8..3e2a7af5ed67 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> @@ -24,6 +24,7 @@ are often referred to as greyscale formats.
> - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum
> `x`.
> - `0` denotes padding bits set to 0.
> + - `-` denotes padding bits with undefined values.
>
>
> .. flat-table:: Luma-Only Image Formats
> @@ -82,6 +83,17 @@ are often referred to as greyscale formats.
> - Y'\ :sub:`3`\ [9:2]
> - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0]
>
> + * .. _V4L2-PIX-FMT-Y10X:
That's interesting, you are using a different convention here. If I
refer to the XYUV_2101010 one, usign that convention instead would be
XY10X10V10. It's not much more readable, and you have to deduce the 2
bits, just like you have to deduce that X here is 6bits. Perhaps we can
find a compromises that makes it consistent ? YX_10_2 ?
> +
> + - ``V4L2_PIX_FMT_Y10X``
> + - 'Y10X'
> +
> + - Y'\ :sub:`0`\ [7:0]
> + - Y'\ :sub:`1`\ [5:0] Y'\ :sub:`0`\ [9:8]
> + - Y'\ :sub:`2`\ [3:0] Y'\ :sub:`1`\ [9:6]
> + - `- -` Y'\ :sub:`2`\ [9:4]
> + - ...
> +
> * .. _V4L2-PIX-FMT-Y12:
>
> - ``V4L2_PIX_FMT_Y12``
> @@ -93,6 +105,17 @@ are often referred to as greyscale formats.
> - ...
> - ...
>
> + * .. _V4L2-PIX-FMT-Y12X:
> +
> + - ``V4L2_PIX_FMT_Y12X``
> + - 'Y12X'
> +
> + - Y'\ :sub:`0`\ [7:0]
> + - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`0`\ [11:8]
> + - Y'\ :sub:`1`\ [11:4]
> + - Y'\ :sub:`2`\ [7:0]
> + - `- - - -` Y'\ :sub:`2`\ [11:8]
> +
> * .. _V4L2-PIX-FMT-Y14:
>
> - ``V4L2_PIX_FMT_Y14``
> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> index 9b4cab651df7..3d137a020cdb 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -579,6 +579,8 @@ struct v4l2_pix_format {
> /* Grey bit-packed formats */
> #define V4L2_PIX_FMT_Y10BPACK v4l2_fourcc('Y', '1', '0', 'B') /* 10 Greyscale bit-packed */
> #define V4L2_PIX_FMT_Y10P v4l2_fourcc('Y', '1', '0', 'P') /* 10 Greyscale, MIPI RAW10 packed */
> +#define V4L2_PIX_FMT_Y10X v4l2_fourcc('Y', '1', '0', 'X') /* 10 Greyscale, 3 pixels in 4 bytes */
> +#define V4L2_PIX_FMT_Y12X v4l2_fourcc('Y', '1', '2', 'X') /* 12 Greyscale, 4 pixels in 5 bytes */
>
> /* Palette formats */
> #define V4L2_PIX_FMT_PAL8 v4l2_fourcc('P', 'A', 'L', '8') /* 8 8-bit palette */
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 16/16] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing
2020-09-24 18:27 ` Nicolas Dufresne
@ 2020-11-01 0:42 ` Laurent Pinchart
2020-11-02 20:45 ` Nicolas Dufresne
0 siblings, 1 reply; 31+ messages in thread
From: Laurent Pinchart @ 2020-11-01 0:42 UTC (permalink / raw)
To: Nicolas Dufresne
Cc: linux-media, Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Hi Nicolas,
On Thu, Sep 24, 2020 at 02:27:58PM -0400, Nicolas Dufresne wrote:
> Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> > Add two new formats storing luma only in 10- and 12-bpc variants, with
> > linear packing. They are used by the Xilinx Video Frame Buffer
> > Read/Write IP cores.
> >
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> > .../media/v4l/pixfmt-yuv-luma.rst | 23 +++++++++++++++++++
> > include/uapi/linux/videodev2.h | 2 ++
> > 2 files changed, 25 insertions(+)
> >
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> > index b24947b52cf8..3e2a7af5ed67 100644
> > --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> > @@ -24,6 +24,7 @@ are often referred to as greyscale formats.
> > - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum
> > `x`.
> > - `0` denotes padding bits set to 0.
> > + - `-` denotes padding bits with undefined values.
> >
> >
> > .. flat-table:: Luma-Only Image Formats
> > @@ -82,6 +83,17 @@ are often referred to as greyscale formats.
> > - Y'\ :sub:`3`\ [9:2]
> > - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0]
> >
> > + * .. _V4L2-PIX-FMT-Y10X:
>
> That's interesting, you are using a different convention here. If I
> refer to the XYUV_2101010 one, usign that convention instead would be
> XY10X10V10. It's not much more readable, and you have to deduce the 2
> bits, just like you have to deduce that X here is 6bits. Perhaps we can
> find a compromises that makes it consistent ? YX_10_2 ?
I'm not sure to follow you. This is a greyscale format, it only stores
the luma component, so XY10X10V10 doesn't match (and I assume you meant
XY10U10V10).
> > +
> > + - ``V4L2_PIX_FMT_Y10X``
> > + - 'Y10X'
> > +
> > + - Y'\ :sub:`0`\ [7:0]
> > + - Y'\ :sub:`1`\ [5:0] Y'\ :sub:`0`\ [9:8]
> > + - Y'\ :sub:`2`\ [3:0] Y'\ :sub:`1`\ [9:6]
> > + - `- -` Y'\ :sub:`2`\ [9:4]
> > + - ...
> > +
> > * .. _V4L2-PIX-FMT-Y12:
> >
> > - ``V4L2_PIX_FMT_Y12``
> > @@ -93,6 +105,17 @@ are often referred to as greyscale formats.
> > - ...
> > - ...
> >
> > + * .. _V4L2-PIX-FMT-Y12X:
> > +
> > + - ``V4L2_PIX_FMT_Y12X``
> > + - 'Y12X'
> > +
> > + - Y'\ :sub:`0`\ [7:0]
> > + - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`0`\ [11:8]
> > + - Y'\ :sub:`1`\ [11:4]
> > + - Y'\ :sub:`2`\ [7:0]
> > + - `- - - -` Y'\ :sub:`2`\ [11:8]
> > +
> > * .. _V4L2-PIX-FMT-Y14:
> >
> > - ``V4L2_PIX_FMT_Y14``
> > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > index 9b4cab651df7..3d137a020cdb 100644
> > --- a/include/uapi/linux/videodev2.h
> > +++ b/include/uapi/linux/videodev2.h
> > @@ -579,6 +579,8 @@ struct v4l2_pix_format {
> > /* Grey bit-packed formats */
> > #define V4L2_PIX_FMT_Y10BPACK v4l2_fourcc('Y', '1', '0', 'B') /* 10 Greyscale bit-packed */
> > #define V4L2_PIX_FMT_Y10P v4l2_fourcc('Y', '1', '0', 'P') /* 10 Greyscale, MIPI RAW10 packed */
> > +#define V4L2_PIX_FMT_Y10X v4l2_fourcc('Y', '1', '0', 'X') /* 10 Greyscale, 3 pixels in 4 bytes */
> > +#define V4L2_PIX_FMT_Y12X v4l2_fourcc('Y', '1', '2', 'X') /* 12 Greyscale, 4 pixels in 5 bytes */
> >
> > /* Palette formats */
> > #define V4L2_PIX_FMT_PAL8 v4l2_fourcc('P', 'A', 'L', '8') /* 8 8-bit palette */
>
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 16/16] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing
2020-11-01 0:42 ` Laurent Pinchart
@ 2020-11-02 20:45 ` Nicolas Dufresne
2020-11-02 22:14 ` Laurent Pinchart
0 siblings, 1 reply; 31+ messages in thread
From: Nicolas Dufresne @ 2020-11-02 20:45 UTC (permalink / raw)
To: Laurent Pinchart
Cc: linux-media, Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Le dimanche 01 novembre 2020 à 02:42 +0200, Laurent Pinchart a écrit :
> Hi Nicolas,
>
> On Thu, Sep 24, 2020 at 02:27:58PM -0400, Nicolas Dufresne wrote:
> > Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> > > Add two new formats storing luma only in 10- and 12-bpc variants, with
> > > linear packing. They are used by the Xilinx Video Frame Buffer
> > > Read/Write IP cores.
> > >
> > > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > > ---
> > > .../media/v4l/pixfmt-yuv-luma.rst | 23 +++++++++++++++++++
> > > include/uapi/linux/videodev2.h | 2 ++
> > > 2 files changed, 25 insertions(+)
> > >
> > > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> > > index b24947b52cf8..3e2a7af5ed67 100644
> > > --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> > > +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> > > @@ -24,6 +24,7 @@ are often referred to as greyscale formats.
> > > - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum
> > > `x`.
> > > - `0` denotes padding bits set to 0.
> > > + - `-` denotes padding bits with undefined values.
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > > .. flat-table:: Luma-Only Image Formats
> > > @@ -82,6 +83,17 @@ are often referred to as greyscale formats.
> > > - Y'\ :sub:`3`\ [9:2]
> > > - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0]
> > >
> > >
> > >
> > >
> > > + * .. _V4L2-PIX-FMT-Y10X:
> >
> > That's interesting, you are using a different convention here. If I
> > refer to the XYUV_2101010 one, usign that convention instead would be
> > XY10X10V10. It's not much more readable, and you have to deduce the 2
> > bits, just like you have to deduce that X here is 6bits. Perhaps we can
> > find a compromises that makes it consistent ? YX_10_2 ?
>
> I'm not sure to follow you. This is a greyscale format, it only stores
> the luma component, so XY10X10V10 doesn't match (and I assume you meant
> XY10U10V10).
I might have screwed up that comment ;-P I think what I wanted to say
is that the size of X is not descriptive in the name and perhaps it
should be. Y10X, where X is 6bit ?
>
> > > +#
> > > + - ``V4L2_PIX_FMT_Y10X``
> > > + - 'Y10X'
> > > +
> > > + - Y'\ :sub:`0`\ [7:0]
> > > + - Y'\ :sub:`1`\ [5:0] Y'\ :sub:`0`\ [9:8]
> > > + - Y'\ :sub:`2`\ [3:0] Y'\ :sub:`1`\ [9:6]
> > > + - `- -` Y'\ :sub:`2`\ [9:4]
> > > + - ...
> > > +
> > > * .. _V4L2-PIX-FMT-Y12:
> > >
> > >
> > >
> > >
> > > - ``V4L2_PIX_FMT_Y12``
> > > @@ -93,6 +105,17 @@ are often referred to as greyscale formats.
> > > - ...
> > > - ...
> > >
> > >
> > >
> > >
> > > + * .. _V4L2-PIX-FMT-Y12X:
> > > +
> > > + - ``V4L2_PIX_FMT_Y12X``
> > > + - 'Y12X'
> > > +
> > > + - Y'\ :sub:`0`\ [7:0]
> > > + - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`0`\ [11:8]
> > > + - Y'\ :sub:`1`\ [11:4]
> > > + - Y'\ :sub:`2`\ [7:0]
> > > + - `- - - -` Y'\ :sub:`2`\ [11:8]
> > > +
> > > * .. _V4L2-PIX-FMT-Y14:
> > >
> > >
> > >
> > >
> > > - ``V4L2_PIX_FMT_Y14``
> > > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > > index 9b4cab651df7..3d137a020cdb 100644
> > > --- a/include/uapi/linux/videodev2.h
> > > +++ b/include/uapi/linux/videodev2.h
> > > @@ -579,6 +579,8 @@ struct v4l2_pix_format {
> > > /* Grey bit-packed formats */
> > > #define V4L2_PIX_FMT_Y10BPACK v4l2_fourcc('Y', '1', '0', 'B') /* 10 Greyscale bit-packed */
> > > #define V4L2_PIX_FMT_Y10P v4l2_fourcc('Y', '1', '0', 'P') /* 10 Greyscale, MIPI RAW10 packed */
> > > +#define V4L2_PIX_FMT_Y10X v4l2_fourcc('Y', '1', '0', 'X') /* 10 Greyscale, 3 pixels in 4 bytes */
> > > +#define V4L2_PIX_FMT_Y12X v4l2_fourcc('Y', '1', '2', 'X') /* 12 Greyscale, 4 pixels in 5 bytes */
> > >
> > >
> > >
> > >
> > > /* Palette formats */
> > > #define V4L2_PIX_FMT_PAL8 v4l2_fourcc('P', 'A', 'L', '8') /* 8 8-bit palette */
> >
>
^ permalink raw reply [flat|nested] 31+ messages in thread* Re: [PATCH/RFC 16/16] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing
2020-11-02 20:45 ` Nicolas Dufresne
@ 2020-11-02 22:14 ` Laurent Pinchart
0 siblings, 0 replies; 31+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:14 UTC (permalink / raw)
To: Nicolas Dufresne
Cc: linux-media, Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar
Hi Nicolas,
On Mon, Nov 02, 2020 at 03:45:46PM -0500, Nicolas Dufresne wrote:
> Le dimanche 01 novembre 2020 à 02:42 +0200, Laurent Pinchart a écrit :
> > On Thu, Sep 24, 2020 at 02:27:58PM -0400, Nicolas Dufresne wrote:
> > > Le mercredi 23 septembre 2020 à 05:43 +0300, Laurent Pinchart a écrit :
> > > > Add two new formats storing luma only in 10- and 12-bpc variants, with
> > > > linear packing. They are used by the Xilinx Video Frame Buffer
> > > > Read/Write IP cores.
> > > >
> > > > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > > > ---
> > > > .../media/v4l/pixfmt-yuv-luma.rst | 23 +++++++++++++++++++
> > > > include/uapi/linux/videodev2.h | 2 ++
> > > > 2 files changed, 25 insertions(+)
> > > >
> > > > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> > > > index b24947b52cf8..3e2a7af5ed67 100644
> > > > --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> > > > +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> > > > @@ -24,6 +24,7 @@ are often referred to as greyscale formats.
> > > > - Y'\ :sub:`x`\ [9:2] denotes bits 9 to 2 of the Y' value for pixel at colum
> > > > `x`.
> > > > - `0` denotes padding bits set to 0.
> > > > + - `-` denotes padding bits with undefined values.
> > > >
> > > >
> > > > .. flat-table:: Luma-Only Image Formats
> > > > @@ -82,6 +83,17 @@ are often referred to as greyscale formats.
> > > > - Y'\ :sub:`3`\ [9:2]
> > > > - Y'\ :sub:`3`\ [1:0] Y'\ :sub:`2`\ [1:0] Y'\ :sub:`1`\ [1:0] Y'\ :sub:`0`\ [1:0]
> > > >
> > > > + * .. _V4L2-PIX-FMT-Y10X:
> > >
> > > That's interesting, you are using a different convention here. If I
> > > refer to the XYUV_2101010 one, usign that convention instead would be
> > > XY10X10V10. It's not much more readable, and you have to deduce the 2
> > > bits, just like you have to deduce that X here is 6bits. Perhaps we can
> > > find a compromises that makes it consistent ? YX_10_2 ?
> >
> > I'm not sure to follow you. This is a greyscale format, it only stores
> > the luma component, so XY10X10V10 doesn't match (and I assume you meant
> > XY10U10V10).
>
> I might have screwed up that comment ;-P I think what I wanted to say
> is that the size of X is not descriptive in the name and perhaps it
> should be. Y10X, where X is 6bit ?
It's a bit of a weird format in the sense that it packs 3 pixels in 4
bytes with two bits of padding in bits 31:30. I can imaging someone later creating a
packed format with 6 pixels packed in 8 bytes, with 4 bits of padding in
bits 63:60 (for platforms whose DMA controller operates on 64-bit
bursts), of a format with 8 pixels packed in 10 bytes with no padding
(to avoid wasting memory when the DMA engine implements repacking). I'm
really not sure how to name these properly, so I went for the Xilinx
downstream 4CC name for lack of a better option. We could use a more
explicit naming scheme, for instance Y10_3_4 to describe that 3 pixels
are packed in 4 bytes. This could also be written Y10_3P_4B. There are
endless bikeshedding opportunities :-) I don't mind much personally, if
someone has a preference, I'm all ears.
> > > > +#
> > > > + - ``V4L2_PIX_FMT_Y10X``
> > > > + - 'Y10X'
> > > > +
> > > > + - Y'\ :sub:`0`\ [7:0]
> > > > + - Y'\ :sub:`1`\ [5:0] Y'\ :sub:`0`\ [9:8]
> > > > + - Y'\ :sub:`2`\ [3:0] Y'\ :sub:`1`\ [9:6]
> > > > + - `- -` Y'\ :sub:`2`\ [9:4]
> > > > + - ...
> > > > +
> > > > * .. _V4L2-PIX-FMT-Y12:
> > > >
> > > > - ``V4L2_PIX_FMT_Y12``
> > > > @@ -93,6 +105,17 @@ are often referred to as greyscale formats.
> > > > - ...
> > > > - ...
> > > >
> > > > + * .. _V4L2-PIX-FMT-Y12X:
> > > > +
> > > > + - ``V4L2_PIX_FMT_Y12X``
> > > > + - 'Y12X'
> > > > +
> > > > + - Y'\ :sub:`0`\ [7:0]
> > > > + - Y'\ :sub:`1`\ [3:0] Y'\ :sub:`0`\ [11:8]
> > > > + - Y'\ :sub:`1`\ [11:4]
> > > > + - Y'\ :sub:`2`\ [7:0]
> > > > + - `- - - -` Y'\ :sub:`2`\ [11:8]
> > > > +
> > > > * .. _V4L2-PIX-FMT-Y14:
> > > >
> > > >
> > > >
> > > >
> > > > - ``V4L2_PIX_FMT_Y14``
> > > > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> > > > index 9b4cab651df7..3d137a020cdb 100644
> > > > --- a/include/uapi/linux/videodev2.h
> > > > +++ b/include/uapi/linux/videodev2.h
> > > > @@ -579,6 +579,8 @@ struct v4l2_pix_format {
> > > > /* Grey bit-packed formats */
> > > > #define V4L2_PIX_FMT_Y10BPACK v4l2_fourcc('Y', '1', '0', 'B') /* 10 Greyscale bit-packed */
> > > > #define V4L2_PIX_FMT_Y10P v4l2_fourcc('Y', '1', '0', 'P') /* 10 Greyscale, MIPI RAW10 packed */
> > > > +#define V4L2_PIX_FMT_Y10X v4l2_fourcc('Y', '1', '0', 'X') /* 10 Greyscale, 3 pixels in 4 bytes */
> > > > +#define V4L2_PIX_FMT_Y12X v4l2_fourcc('Y', '1', '2', 'X') /* 12 Greyscale, 4 pixels in 5 bytes */
> > > >
> > > > /* Palette formats */
> > > > #define V4L2_PIX_FMT_PAL8 v4l2_fourcc('P', 'A', 'L', '8') /* 8 8-bit palette */
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 31+ messages in thread