* [PATCH v2 01/19] media: videodev2.h: Remove unneeded comment about 4CC value
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 02/19] media: videodev2.h: Move HI240 format to vendor-specific section Laurent Pinchart
` (18 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 534eaa4d39bc..4cbc02bd8b72 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -526,12 +526,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] 35+ messages in thread* [PATCH v2 02/19] media: videodev2.h: Move HI240 format to vendor-specific section
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 01/19] media: videodev2.h: Remove unneeded comment about 4CC value Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 03/19] media: videodev2.h: Move HM12 format to YUV semi-planar section Laurent Pinchart
` (17 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 4cbc02bd8b72..2d34a9ec293b 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -591,7 +591,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 */
@@ -734,6 +733,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] 35+ messages in thread* [PATCH v2 03/19] media: videodev2.h: Move HM12 format to YUV semi-planar section
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 01/19] media: videodev2.h: Remove unneeded comment about 4CC value Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 02/19] media: videodev2.h: Move HI240 format to vendor-specific section Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 04/19] media: doc: pixfmt-rgb: Remove layout table for packed RGB formats Laurent Pinchart
` (16 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 2d34a9ec293b..8775aebb3b6b 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -591,7 +591,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 */
@@ -601,6 +600,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] 35+ messages in thread* [PATCH v2 04/19] media: doc: pixfmt-rgb: Remove layout table for packed RGB formats
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (2 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 03/19] media: videodev2.h: Move HM12 format to YUV semi-planar section Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 05/19] media: doc: pixfmt-rgb: Add title for deprecated formats Laurent Pinchart
` (15 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 9d827097c1d9..731bde23e055 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
@@ -999,77 +999,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] 35+ messages in thread* [PATCH v2 05/19] media: doc: pixfmt-rgb: Add title for deprecated formats
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (3 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 04/19] media: doc: pixfmt-rgb: Remove layout table for packed RGB formats Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats Laurent Pinchart
` (14 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 731bde23e055..5045895e85e1 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
@@ -1000,12 +1000,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] 35+ messages in thread* [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (4 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 05/19] media: doc: pixfmt-rgb: Add title for deprecated formats Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-16 11:51 ` Hans Verkuil
2020-11-02 22:40 ` [PATCH v2 07/19] media: doc: pixfmt-yuv: Document subsampling in more details Laurent Pinchart
` (13 subsequent siblings)
19 siblings, 1 reply; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 led 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>
---
Changes since v1:
- Clarify padding and padding requirements
- Fix typo
---
.../userspace-api/media/v4l/pixfmt-rgb.rst | 195 ++++++++++++------
include/uapi/linux/videodev2.h | 4 +-
2 files changed, 140 insertions(+), 59 deletions(-)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
index 5045895e85e1..405d6f032078 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
@@ -6,13 +6,62 @@
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 and 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 additional padding bits.
+
+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 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
@@ -20,10 +69,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
@@ -31,8 +80,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
@@ -52,24 +99,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``
@@ -544,6 +573,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``
@@ -973,40 +1078,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 8775aebb3b6b..54b9fe3b7636 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -517,7 +517,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 */
@@ -542,6 +542,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] 35+ messages in thread* Re: [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-11-02 22:40 ` [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats Laurent Pinchart
@ 2020-11-16 11:51 ` Hans Verkuil
2020-11-16 11:58 ` Hans Verkuil
2020-11-16 17:26 ` Laurent Pinchart
0 siblings, 2 replies; 35+ messages in thread
From: Hans Verkuil @ 2020-11-16 11:51 UTC (permalink / raw)
To: Laurent Pinchart, linux-media
Cc: Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
On 02/11/2020 23:40, 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 led 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>
> ---
> Changes since v1:
>
> - Clarify padding and padding requirements
> - Fix typo
> ---
> .../userspace-api/media/v4l/pixfmt-rgb.rst | 195 ++++++++++++------
> include/uapi/linux/videodev2.h | 4 +-
> 2 files changed, 140 insertions(+), 59 deletions(-)
>
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> index 5045895e85e1..405d6f032078 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> @@ -6,13 +6,62 @@
> 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 and 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 additional padding bits.
> +
> +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 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
>
> @@ -20,10 +69,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
>
> @@ -31,8 +80,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
> @@ -52,24 +99,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``
> @@ -544,6 +573,82 @@ next to each other in memory.
> - b\ :sub:`1`
> - b\ :sub:`0`
> -
> +
> +.. raw:: latex
> +
> + \endgroup
> +
> +
> +24 or 32 Bits Per Pixel
Wouldn't it be better to call this "8 Bits Per Component"? Since we'll later get
a section called "More Than 8 Bits Per Component".
Regards,
Hans
> +=======================
> +
> +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``
> @@ -973,40 +1078,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 8775aebb3b6b..54b9fe3b7636 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -517,7 +517,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 */
> @@ -542,6 +542,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] 35+ messages in thread* Re: [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-11-16 11:51 ` Hans Verkuil
@ 2020-11-16 11:58 ` Hans Verkuil
2020-11-16 17:29 ` Laurent Pinchart
2020-11-16 17:26 ` Laurent Pinchart
1 sibling, 1 reply; 35+ messages in thread
From: Hans Verkuil @ 2020-11-16 11:58 UTC (permalink / raw)
To: Laurent Pinchart, linux-media
Cc: Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
On 16/11/2020 12:51, Hans Verkuil wrote:
> On 02/11/2020 23:40, 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 led 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>
>> ---
>> Changes since v1:
>>
>> - Clarify padding and padding requirements
>> - Fix typo
>> ---
>> .../userspace-api/media/v4l/pixfmt-rgb.rst | 195 ++++++++++++------
>> include/uapi/linux/videodev2.h | 4 +-
>> 2 files changed, 140 insertions(+), 59 deletions(-)
>>
>> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
>> index 5045895e85e1..405d6f032078 100644
>> --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
>> +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
>> @@ -6,13 +6,62 @@
>> 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 and 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 additional padding bits.
>> +
>> +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 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
>>
>> @@ -20,10 +69,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
>>
>> @@ -31,8 +80,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
>> @@ -52,24 +99,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``
>> @@ -544,6 +573,82 @@ next to each other in memory.
>> - b\ :sub:`1`
>> - b\ :sub:`0`
>> -
>> +
>> +.. raw:: latex
>> +
>> + \endgroup
>> +
>> +
>> +24 or 32 Bits Per Pixel
>
> Wouldn't it be better to call this "8 Bits Per Component"? Since we'll later get
> a section called "More Than 8 Bits Per Component".
Also, wouldn't it make sense to express these formats in a more compact way, just
like YCbCr 4:4:4? (See patch 10/19)
Regards,
Hans
>
> Regards,
>
> Hans
>
>> +=======================
>> +
>> +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``
>> @@ -973,40 +1078,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 8775aebb3b6b..54b9fe3b7636 100644
>> --- a/include/uapi/linux/videodev2.h
>> +++ b/include/uapi/linux/videodev2.h
>> @@ -517,7 +517,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 */
>> @@ -542,6 +542,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] 35+ messages in thread* Re: [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-11-16 11:58 ` Hans Verkuil
@ 2020-11-16 17:29 ` Laurent Pinchart
0 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-16 17:29 UTC (permalink / raw)
To: Hans Verkuil
Cc: linux-media, Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Hi Hans,
On Mon, Nov 16, 2020 at 12:58:51PM +0100, Hans Verkuil wrote:
> On 16/11/2020 12:51, Hans Verkuil wrote:
> > On 02/11/2020 23:40, 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 led 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>
> >> ---
> >> Changes since v1:
> >>
> >> - Clarify padding and padding requirements
> >> - Fix typo
> >> ---
> >> .../userspace-api/media/v4l/pixfmt-rgb.rst | 195 ++++++++++++------
> >> include/uapi/linux/videodev2.h | 4 +-
> >> 2 files changed, 140 insertions(+), 59 deletions(-)
> >>
> >> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> >> index 5045895e85e1..405d6f032078 100644
> >> --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> >> +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> >> @@ -6,13 +6,62 @@
> >> 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 and 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 additional padding bits.
> >> +
> >> +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 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
> >>
> >> @@ -20,10 +69,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
> >>
> >> @@ -31,8 +80,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
> >> @@ -52,24 +99,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``
> >> @@ -544,6 +573,82 @@ next to each other in memory.
> >> - b\ :sub:`1`
> >> - b\ :sub:`0`
> >> -
> >> +
> >> +.. raw:: latex
> >> +
> >> + \endgroup
> >> +
> >> +
> >> +24 or 32 Bits Per Pixel
> >
> > Wouldn't it be better to call this "8 Bits Per Component"? Since we'll later get
> > a section called "More Than 8 Bits Per Component".
>
> Also, wouldn't it make sense to express these formats in a more compact way, just
> like YCbCr 4:4:4? (See patch 10/19)
Yes, I think it's a good idea. I'll do so in a separate patch though, as
it's out of scope for the commit message of this patch.
> >> +=======================
> >> +
> >> +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``
> >> @@ -973,40 +1078,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 8775aebb3b6b..54b9fe3b7636 100644
> >> --- a/include/uapi/linux/videodev2.h
> >> +++ b/include/uapi/linux/videodev2.h
> >> @@ -517,7 +517,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 */
> >> @@ -542,6 +542,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] 35+ messages in thread
* Re: [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-11-16 11:51 ` Hans Verkuil
2020-11-16 11:58 ` Hans Verkuil
@ 2020-11-16 17:26 ` Laurent Pinchart
2020-11-16 17:35 ` Laurent Pinchart
1 sibling, 1 reply; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-16 17:26 UTC (permalink / raw)
To: Hans Verkuil
Cc: linux-media, Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Hi Hans,
On Mon, Nov 16, 2020 at 12:51:19PM +0100, Hans Verkuil wrote:
> On 02/11/2020 23:40, 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 led 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>
> > ---
> > Changes since v1:
> >
> > - Clarify padding and padding requirements
> > - Fix typo
> > ---
> > .../userspace-api/media/v4l/pixfmt-rgb.rst | 195 ++++++++++++------
> > include/uapi/linux/videodev2.h | 4 +-
> > 2 files changed, 140 insertions(+), 59 deletions(-)
> >
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > index 5045895e85e1..405d6f032078 100644
> > --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > @@ -6,13 +6,62 @@
> > 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 and 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 additional padding bits.
> > +
> > +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 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
> >
> > @@ -20,10 +69,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
> >
> > @@ -31,8 +80,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
> > @@ -52,24 +99,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``
> > @@ -544,6 +573,82 @@ next to each other in memory.
> > - b\ :sub:`1`
> > - b\ :sub:`0`
> > -
> > +
> > +.. raw:: latex
> > +
> > + \endgroup
> > +
> > +
> > +24 or 32 Bits Per Pixel
>
> Wouldn't it be better to call this "8 Bits Per Component"? Since we'll later get
> a section called "More Than 8 Bits Per Component".
The previous section is named "8 and 16 bits per pixel", so there will
be a mismatch on one side or the other :-) I will change it here.
> > +=======================
> > +
> > +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``
> > @@ -973,40 +1078,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 8775aebb3b6b..54b9fe3b7636 100644
> > --- a/include/uapi/linux/videodev2.h
> > +++ b/include/uapi/linux/videodev2.h
> > @@ -517,7 +517,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 */
> > @@ -542,6 +542,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] 35+ messages in thread* Re: [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-11-16 17:26 ` Laurent Pinchart
@ 2020-11-16 17:35 ` Laurent Pinchart
2020-11-16 18:20 ` Hans Verkuil
0 siblings, 1 reply; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-16 17:35 UTC (permalink / raw)
To: Hans Verkuil
Cc: linux-media, Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Hi Hans,
On Mon, Nov 16, 2020 at 07:26:07PM +0200, Laurent Pinchart wrote:
> On Mon, Nov 16, 2020 at 12:51:19PM +0100, Hans Verkuil wrote:
> > On 02/11/2020 23:40, 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 led 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>
> > > ---
> > > Changes since v1:
> > >
> > > - Clarify padding and padding requirements
> > > - Fix typo
> > > ---
> > > .../userspace-api/media/v4l/pixfmt-rgb.rst | 195 ++++++++++++------
> > > include/uapi/linux/videodev2.h | 4 +-
> > > 2 files changed, 140 insertions(+), 59 deletions(-)
> > >
> > > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > > index 5045895e85e1..405d6f032078 100644
> > > --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > > +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > > @@ -6,13 +6,62 @@
> > > 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 and 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 additional padding bits.
> > > +
> > > +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 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
> > >
> > > @@ -20,10 +69,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
> > >
> > > @@ -31,8 +80,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
> > > @@ -52,24 +99,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``
> > > @@ -544,6 +573,82 @@ next to each other in memory.
> > > - b\ :sub:`1`
> > > - b\ :sub:`0`
> > > -
> > > +
> > > +.. raw:: latex
> > > +
> > > + \endgroup
> > > +
> > > +
> > > +24 or 32 Bits Per Pixel
> >
> > Wouldn't it be better to call this "8 Bits Per Component"? Since we'll later get
> > a section called "More Than 8 Bits Per Component".
>
> The previous section is named "8 and 16 bits per pixel", so there will
> be a mismatch on one side or the other :-) I will change it here.
There's one issue though, V4L2_PIX_FMT_BGR666 has less than 8 bits per
component. I can move it to the previous section (which should then be
renamed to "less than 8 bits per component"), but it will be only format
with more than two bytes in that table. Is that OK with you ?
> > > +=======================
> > > +
> > > +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``
> > > @@ -973,40 +1078,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 8775aebb3b6b..54b9fe3b7636 100644
> > > --- a/include/uapi/linux/videodev2.h
> > > +++ b/include/uapi/linux/videodev2.h
> > > @@ -517,7 +517,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 */
> > > @@ -542,6 +542,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] 35+ messages in thread* Re: [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
2020-11-16 17:35 ` Laurent Pinchart
@ 2020-11-16 18:20 ` Hans Verkuil
0 siblings, 0 replies; 35+ messages in thread
From: Hans Verkuil @ 2020-11-16 18:20 UTC (permalink / raw)
To: Laurent Pinchart
Cc: linux-media, Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
On 16/11/2020 18:35, Laurent Pinchart wrote:
> Hi Hans,
>
> On Mon, Nov 16, 2020 at 07:26:07PM +0200, Laurent Pinchart wrote:
>> On Mon, Nov 16, 2020 at 12:51:19PM +0100, Hans Verkuil wrote:
>>> On 02/11/2020 23:40, 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 led 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>
>>>> ---
>>>> Changes since v1:
>>>>
>>>> - Clarify padding and padding requirements
>>>> - Fix typo
>>>> ---
>>>> .../userspace-api/media/v4l/pixfmt-rgb.rst | 195 ++++++++++++------
>>>> include/uapi/linux/videodev2.h | 4 +-
>>>> 2 files changed, 140 insertions(+), 59 deletions(-)
>>>>
>>>> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
>>>> index 5045895e85e1..405d6f032078 100644
>>>> --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
>>>> +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
>>>> @@ -6,13 +6,62 @@
>>>> 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 and 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 additional padding bits.
>>>> +
>>>> +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 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
>>>>
>>>> @@ -20,10 +69,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
>>>>
>>>> @@ -31,8 +80,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
>>>> @@ -52,24 +99,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``
>>>> @@ -544,6 +573,82 @@ next to each other in memory.
>>>> - b\ :sub:`1`
>>>> - b\ :sub:`0`
>>>> -
>>>> +
>>>> +.. raw:: latex
>>>> +
>>>> + \endgroup
>>>> +
>>>> +
>>>> +24 or 32 Bits Per Pixel
>>>
>>> Wouldn't it be better to call this "8 Bits Per Component"? Since we'll later get
>>> a section called "More Than 8 Bits Per Component".
>>
>> The previous section is named "8 and 16 bits per pixel", so there will
>> be a mismatch on one side or the other :-) I will change it here.
>
> There's one issue though, V4L2_PIX_FMT_BGR666 has less than 8 bits per
> component. I can move it to the previous section (which should then be
> renamed to "less than 8 bits per component"), but it will be only format
> with more than two bytes in that table. Is that OK with you ?
That sounds good.
Regards,
Hans
^ permalink raw reply [flat|nested] 35+ messages in thread
* [PATCH v2 07/19] media: doc: pixfmt-yuv: Document subsampling in more details
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (5 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 08/19] media: doc: pixfmt-yuv: Move all packed YUV formats to common file Laurent Pinchart
` (12 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 13cf36a8cd5c..c01a949e7c11 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-m420.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-m420.rst
@@ -67,60 +67,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 dd2f38129fe6..692117bf83ad 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst
@@ -72,58 +72,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 250f8b977605..002b361d5a9b 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst
@@ -84,61 +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-nv16.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst
index 22295fc0c359..e6307843d848 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst
@@ -80,74 +80,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 812bf2ccabf0..58e97205d41f 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst
@@ -84,74 +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
- * -
- -
- - 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 bae975fb14f6..1abc3066b712 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst
@@ -66,45 +66,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 aff8588b67a9..4fd0630a83a4 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst
@@ -66,43 +66,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 d14cedf8f317..bb83eb6db3e5 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst
@@ -89,63 +89,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 de2e519adc60..d79cd46d5055 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst
@@ -68,60 +68,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 998aa9b1328f..8a70eeca8d83 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst
@@ -76,40 +76,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 f1c7baf32685..a36ec8d6d8a4 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst
@@ -77,67 +77,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 cd20a57e0621..c2cf17b9743c 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst
@@ -86,67 +86,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 32bf15e1426e..f92b54853fc9 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst
@@ -97,45 +97,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 b178be558361..33e6b923e325 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst
@@ -85,45 +85,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 90bdee2e2b0d..7c03cc5b07d9 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst
@@ -107,35 +107,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 ca073a5098a9..4d5773922ba1 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst
@@ -69,50 +69,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 81ebec525ae5..14b56b611349 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst
@@ -66,43 +66,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 4a05a105a9e6..79a4fda566c6 100644
--- a/Documentation/userspace-api/media/v4l/yuv-formats.rst
+++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst
@@ -14,11 +14,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] 35+ messages in thread* [PATCH v2 08/19] media: doc: pixfmt-yuv: Move all packed YUV formats to common file
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (6 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 07/19] media: doc: pixfmt-yuv: Document subsampling in more details Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 09/19] media: doc: pixfmt-packed-yuv: Fill padding bits with '-' Laurent Pinchart
` (11 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 | 70 ---------
.../userspace-api/media/v4l/pixfmt-vyuy.rst | 70 ---------
.../userspace-api/media/v4l/pixfmt-y41p.rst | 93 -----------
.../userspace-api/media/v4l/pixfmt-yuyv.rst | 73 ---------
.../userspace-api/media/v4l/pixfmt-yvyu.rst | 70 ---------
.../userspace-api/media/v4l/yuv-formats.rst | 5 -
7 files changed, 140 insertions(+), 388 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 84262208dd1c..8ed1a6aff3a6 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -6,12 +6,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
@@ -19,11 +23,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
@@ -371,3 +373,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 1abc3066b712..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-uyvy.rst
+++ /dev/null
@@ -1,70 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 4fd0630a83a4..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-vyuy.rst
+++ /dev/null
@@ -1,70 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 bb83eb6db3e5..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y41p.rst
+++ /dev/null
@@ -1,93 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 4d5773922ba1..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuyv.rst
+++ /dev/null
@@ -1,73 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 14b56b611349..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yvyu.rst
+++ /dev/null
@@ -1,70 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 79a4fda566c6..a5b17040679e 100644
--- a/Documentation/userspace-api/media/v4l/yuv-formats.rst
+++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst
@@ -276,11 +276,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] 35+ messages in thread* [PATCH v2 09/19] media: doc: pixfmt-packed-yuv: Fill padding bits with '-'
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (7 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 08/19] media: doc: pixfmt-yuv: Move all packed YUV formats to common file Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 10/19] media: doc: pixfmt-packed-yuv: Express 4:4:4 formats in a more compact way Laurent Pinchart
` (10 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 8ed1a6aff3a6..38f3d564c134 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -239,14 +239,14 @@ full triplet of Y, Cb and Cr values.
- ``V4L2_PIX_FMT_XYUV32``
- 'XYUV'
- -
- -
- -
- -
- -
- -
- -
- -
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
+ - `-`
- Y'\ :sub:`7`
- Y'\ :sub:`6`
@@ -348,14 +348,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] 35+ messages in thread* [PATCH v2 10/19] media: doc: pixfmt-packed-yuv: Express 4:4:4 formats in a more compact way
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (8 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 09/19] media: doc: pixfmt-packed-yuv: Fill padding bits with '-' Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 11/19] media: doc: pixfmt-packed-yuv: Clarify naming scheme for 4:4:4 formats Laurent Pinchart
` (9 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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>
---
Changes since v1:
- Fix typo
---
.../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 38f3d564c134..3792035b4604 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -10,6 +10,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 alpha component (if supported by the format), and '-'
+ denotes padding bits.
+
4:4:4 Subsampling
=================
@@ -23,9 +31,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
@@ -36,10 +44,6 @@ full triplet of Y, Cb and Cr values.
- :cspan:`7` Byte 1
- - :cspan:`7` Byte 2
-
- - :cspan:`7` Byte 3
-
* -
-
- 7
@@ -60,24 +64,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``
@@ -101,8 +87,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``
@@ -126,7 +110,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``
@@ -150,229 +133,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] 35+ messages in thread* [PATCH v2 11/19] media: doc: pixfmt-packed-yuv: Clarify naming scheme for 4:4:4 formats
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (9 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 10/19] media: doc: pixfmt-packed-yuv: Express 4:4:4 formats in a more compact way Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 12/19] media: doc: pixfmt-yuv: Move all luma-only YUV formats to common file Laurent Pinchart
` (8 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 3792035b4604..8f0f1405bfe3 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -25,6 +25,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
@@ -145,6 +153,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] 35+ messages in thread* [PATCH v2 12/19] media: doc: pixfmt-yuv: Move all luma-only YUV formats to common file
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (10 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 11/19] media: doc: pixfmt-packed-yuv: Clarify naming scheme for 4:4:4 formats Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-03 12:05 ` Sakari Ailus
2020-11-02 22:40 ` [PATCH v2 13/19] media: doc: pixfmt-yuv: Move all semi-planar " Laurent Pinchart
` (7 subsequent siblings)
19 siblings, 1 reply; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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>
---
Changes since v1:
- Use SPDX license header
---
.../userspace-api/media/v4l/pixfmt-grey.rst | 44 ------
.../userspace-api/media/v4l/pixfmt-y10.rst | 65 ---------
.../userspace-api/media/v4l/pixfmt-y10b.rst | 33 -----
.../userspace-api/media/v4l/pixfmt-y10p.rst | 43 ------
.../userspace-api/media/v4l/pixfmt-y12.rst | 65 ---------
.../userspace-api/media/v4l/pixfmt-y14.rst | 65 ---------
.../userspace-api/media/v4l/pixfmt-y16-be.rst | 69 ----------
.../userspace-api/media/v4l/pixfmt-y16.rst | 69 ----------
.../media/v4l/pixfmt-yuv-luma.rst | 126 ++++++++++++++++++
.../userspace-api/media/v4l/yuv-formats.rst | 9 +-
10 files changed, 127 insertions(+), 461 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 121365b03c57..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst
+++ /dev/null
@@ -1,44 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 05f018dd883f..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 38d353b37df9..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst
+++ /dev/null
@@ -1,33 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 dd20d3438732..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 20e12a18da72..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 2a4826b77105..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 6d70cd78cbf6..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst
+++ /dev/null
@@ -1,69 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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 398ad8ba5d64..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst
+++ /dev/null
@@ -1,69 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _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..ba8cd895cb0b
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
@@ -0,0 +1,126 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. _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 a5b17040679e..7179d715f8a7 100644
--- a/Documentation/userspace-api/media/v4l/yuv-formats.rst
+++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst
@@ -265,14 +265,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] 35+ messages in thread* Re: [PATCH v2 12/19] media: doc: pixfmt-yuv: Move all luma-only YUV formats to common file
2020-11-02 22:40 ` [PATCH v2 12/19] media: doc: pixfmt-yuv: Move all luma-only YUV formats to common file Laurent Pinchart
@ 2020-11-03 12:05 ` Sakari Ailus
0 siblings, 0 replies; 35+ messages in thread
From: Sakari Ailus @ 2020-11-03 12:05 UTC (permalink / raw)
To: Laurent Pinchart
Cc: linux-media, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Hi Laurent,
On Tue, Nov 03, 2020 at 12:40:55AM +0200, Laurent Pinchart wrote:
> 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>
> ---
> Changes since v1:
>
> - Use SPDX license header
> ---
> .../userspace-api/media/v4l/pixfmt-grey.rst | 44 ------
> .../userspace-api/media/v4l/pixfmt-y10.rst | 65 ---------
> .../userspace-api/media/v4l/pixfmt-y10b.rst | 33 -----
> .../userspace-api/media/v4l/pixfmt-y10p.rst | 43 ------
> .../userspace-api/media/v4l/pixfmt-y12.rst | 65 ---------
> .../userspace-api/media/v4l/pixfmt-y14.rst | 65 ---------
> .../userspace-api/media/v4l/pixfmt-y16-be.rst | 69 ----------
> .../userspace-api/media/v4l/pixfmt-y16.rst | 69 ----------
> .../media/v4l/pixfmt-yuv-luma.rst | 126 ++++++++++++++++++
> .../userspace-api/media/v4l/yuv-formats.rst | 9 +-
> 10 files changed, 127 insertions(+), 461 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 121365b03c57..000000000000
> --- a/Documentation/userspace-api/media/v4l/pixfmt-grey.rst
> +++ /dev/null
> @@ -1,44 +0,0 @@
> -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> -
> -.. _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 05f018dd883f..000000000000
> --- a/Documentation/userspace-api/media/v4l/pixfmt-y10.rst
> +++ /dev/null
> @@ -1,65 +0,0 @@
> -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> -
> -.. _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 38d353b37df9..000000000000
> --- a/Documentation/userspace-api/media/v4l/pixfmt-y10b.rst
> +++ /dev/null
> @@ -1,33 +0,0 @@
> -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> -
> -.. _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 dd20d3438732..000000000000
> --- a/Documentation/userspace-api/media/v4l/pixfmt-y10p.rst
> +++ /dev/null
> @@ -1,43 +0,0 @@
> -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> -
> -.. _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 20e12a18da72..000000000000
> --- a/Documentation/userspace-api/media/v4l/pixfmt-y12.rst
> +++ /dev/null
> @@ -1,65 +0,0 @@
> -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> -
> -.. _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 2a4826b77105..000000000000
> --- a/Documentation/userspace-api/media/v4l/pixfmt-y14.rst
> +++ /dev/null
> @@ -1,65 +0,0 @@
> -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> -
> -.. _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 6d70cd78cbf6..000000000000
> --- a/Documentation/userspace-api/media/v4l/pixfmt-y16-be.rst
> +++ /dev/null
> @@ -1,69 +0,0 @@
> -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> -
> -.. _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 398ad8ba5d64..000000000000
> --- a/Documentation/userspace-api/media/v4l/pixfmt-y16.rst
> +++ /dev/null
> @@ -1,69 +0,0 @@
> -.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> -
> -.. _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..ba8cd895cb0b
> --- /dev/null
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
> @@ -0,0 +1,126 @@
> +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
> +
> +.. _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)
1U << 31
> +
> + - Y'\ :sub:`0`\ [7:0]
> + - Y'\ :sub:`0`\ [15:8]
The order is the same as for the LE version. Shouldn't it be inverted?
> + - ...
> + - ...
> + - ...
> +
> +.. 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 a5b17040679e..7179d715f8a7 100644
> --- a/Documentation/userspace-api/media/v4l/yuv-formats.rst
> +++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst
> @@ -265,14 +265,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,
Sakari Ailus
^ permalink raw reply [flat|nested] 35+ messages in thread
* [PATCH v2 13/19] media: doc: pixfmt-yuv: Move all semi-planar YUV formats to common file
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (11 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 12/19] media: doc: pixfmt-yuv: Move all luma-only YUV formats to common file Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 14/19] media: doc: pixfmt-yuv: Move all planar " Laurent Pinchart
` (6 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Semi-planar pixel formats are documented in separate files. This
duplicates information, as those formats share comon traits. Consolidate
them in a single file and summarize their descriptions in a single
table.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../userspace-api/media/v4l/pixfmt-nv12.rst | 76 ---
.../userspace-api/media/v4l/pixfmt-nv12m.rst | 88 ----
.../userspace-api/media/v4l/pixfmt-nv12mt.rst | 60 ---
.../userspace-api/media/v4l/pixfmt-nv16.rst | 84 ----
.../userspace-api/media/v4l/pixfmt-nv16m.rst | 88 ----
.../userspace-api/media/v4l/pixfmt-nv24.rst | 95 ----
.../media/v4l/pixfmt-yuv-planar.rst | 463 ++++++++++++++++++
.../userspace-api/media/v4l/yuv-formats.rst | 7 +-
8 files changed, 464 insertions(+), 497 deletions(-)
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv12.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv16.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-nv24.rst
create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst
deleted file mode 100644
index 692117bf83ad..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv12.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-NV12:
-.. _V4L2-PIX-FMT-NV21:
-
-******************************************************
-V4L2_PIX_FMT_NV12 ('NV12'), V4L2_PIX_FMT_NV21 ('NV21')
-******************************************************
-
-
-V4L2_PIX_FMT_NV21
-Formats with ½ horizontal and vertical chroma resolution, also known as
-YUV 4:2:0. One luminance and one chrominance plane with alternating
-chroma samples as opposed to ``V4L2_PIX_FMT_YVU420``
-
-
-Description
-===========
-
-These are two-plane versions of the YUV 4:2:0 format. The three
-components are separated into two sub-images or planes. The Y plane is
-first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV12``, a
-combined CbCr plane immediately follows the Y plane in memory. The CbCr
-plane is the same width, in bytes, as the Y plane (and of the image),
-but is half as tall in pixels. Each CbCr pair belongs to four pixels.
-For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`,
-Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`. ``V4L2_PIX_FMT_NV21`` is
-the same except the Cb and Cr bytes are swapped, the CrCb plane starts
-with a Cr byte.
-
-If the Y plane has pad bytes after each row, then the CbCr plane has as
-many pad bytes after its rows.
-
-**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`
- * - start + 16:
- - Cb\ :sub:`00`
- - Cr\ :sub:`00`
- - Cb\ :sub:`01`
- - Cr\ :sub:`01`
- * - start + 20:
- - Cb\ :sub:`10`
- - Cr\ :sub:`10`
- - Cb\ :sub:`11`
- - Cr\ :sub:`11`
-
-
-**Color Sample Location:**
-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
deleted file mode 100644
index 002b361d5a9b..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst
+++ /dev/null
@@ -1,88 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-NV12M:
-.. _v4l2-pix-fmt-nv12mt-16x16:
-.. _V4L2-PIX-FMT-NV21M:
-
-***********************************************************************************
-V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16
-***********************************************************************************
-
-
-V4L2_PIX_FMT_NV21M
-V4L2_PIX_FMT_NV12MT_16X16
-Variation of ``V4L2_PIX_FMT_NV12`` and ``V4L2_PIX_FMT_NV21`` with planes
-non contiguous in memory.
-
-
-Description
-===========
-
-This is a multi-planar, two-plane version of the YUV 4:2:0 format. The
-three components are separated into two sub-images or planes.
-``V4L2_PIX_FMT_NV12M`` differs from ``V4L2_PIX_FMT_NV12`` in that the
-two planes are non-contiguous in memory, i.e. the chroma plane do not
-necessarily immediately follows the luma plane. The luminance data
-occupies the first plane. The Y plane has one byte per pixel. In the
-second plane there is a chrominance data with alternating chroma
-samples. The CbCr plane is the same width, in bytes, as the Y plane (and
-of the image), but is half as tall in pixels. Each CbCr pair belongs to
-four pixels. For example, Cb\ :sub:`0`/Cr\ :sub:`0` belongs to
-Y'\ :sub:`00`, Y'\ :sub:`01`, Y'\ :sub:`10`, Y'\ :sub:`11`.
-``V4L2_PIX_FMT_NV12MT_16X16`` is the tiled version of
-``V4L2_PIX_FMT_NV12M`` with 16x16 macroblock tiles. Here pixels are
-arranged in 16x16 2D tiles and tiles are arranged in linear order in
-memory. ``V4L2_PIX_FMT_NV21M`` is the same as ``V4L2_PIX_FMT_NV12M``
-except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr
-byte.
-
-``V4L2_PIX_FMT_NV12M`` is intended to be used only in drivers and
-applications that support the multi-planar API, described in
-:ref:`planar-apis`.
-
-If the Y plane has pad bytes after each row, then the CbCr plane has as
-many pad bytes after its rows.
-
-**Byte Order.**
-Each cell is one byte.
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start0 + 0:
- - Y'\ :sub:`00`
- - Y'\ :sub:`01`
- - Y'\ :sub:`02`
- - Y'\ :sub:`03`
- * - start0 + 4:
- - Y'\ :sub:`10`
- - Y'\ :sub:`11`
- - Y'\ :sub:`12`
- - Y'\ :sub:`13`
- * - start0 + 8:
- - Y'\ :sub:`20`
- - Y'\ :sub:`21`
- - Y'\ :sub:`22`
- - Y'\ :sub:`23`
- * - start0 + 12:
- - Y'\ :sub:`30`
- - Y'\ :sub:`31`
- - Y'\ :sub:`32`
- - Y'\ :sub:`33`
- * -
- * - start1 + 0:
- - Cb\ :sub:`00`
- - Cr\ :sub:`00`
- - Cb\ :sub:`01`
- - Cr\ :sub:`01`
- * - start1 + 4:
- - Cb\ :sub:`10`
- - Cr\ :sub:`10`
- - Cb\ :sub:`11`
- - Cr\ :sub:`11`
-
-
-**Color Sample Location:**
-Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
-horizontally and vertically.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst
deleted file mode 100644
index 46f63d793ec5..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-NV12MT:
-
-****************************
-V4L2_PIX_FMT_NV12MT ('TM12')
-****************************
-
-Formats with ½ horizontal and vertical chroma resolution. This format
-has two planes - one for luminance and one for chrominance. Chroma
-samples are interleaved. The difference to ``V4L2_PIX_FMT_NV12`` is the
-memory layout. Pixels are grouped in macroblocks of 64x32 size. The
-order of macroblocks in memory is also not standard.
-
-
-Description
-===========
-
-This is the two-plane versions of the YUV 4:2:0 format where data is
-grouped into 64x32 macroblocks. The three components are separated into
-two sub-images or planes. The Y plane has one byte per pixel and pixels
-are grouped into 64x32 macroblocks. The CbCr plane has the same width,
-in bytes, as the Y plane (and the image), but is half as tall in pixels.
-The chroma plane is also grouped into 64x32 macroblocks.
-
-Width of the buffer has to be aligned to the multiple of 128, and height
-alignment is 32. Every four adjacent buffers - two horizontally and two
-vertically are grouped together and are located in memory in Z or
-flipped Z order.
-
-Layout of macroblocks in memory is presented in the following figure.
-
-
-.. _nv12mt:
-
-.. kernel-figure:: nv12mt.svg
- :alt: nv12mt.svg
- :align: center
-
- V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout
-
-The requirement that width is multiple of 128 is implemented because,
-the Z shape cannot be cut in half horizontally. In case the vertical
-resolution of macroblocks is odd then the last row of macroblocks is
-arranged in a linear order.
-
-In case of chroma the layout is identical. Cb and Cr samples are
-interleaved. Height of the buffer is aligned to 32.
-
-
-.. _nv12mt_ex:
-
-.. kernel-figure:: nv12mt_example.svg
- :alt: nv12mt_example.svg
- :align: center
-
- Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
-
-Memory layout of macroblocks of ``V4L2_PIX_FMT_NV12MT`` format in most
-extreme case.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst
deleted file mode 100644
index e6307843d848..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv16.rst
+++ /dev/null
@@ -1,84 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-NV16:
-.. _V4L2-PIX-FMT-NV61:
-
-******************************************************
-V4L2_PIX_FMT_NV16 ('NV16'), V4L2_PIX_FMT_NV61 ('NV61')
-******************************************************
-
-V4L2_PIX_FMT_NV61
-Formats with ½ horizontal chroma resolution, also known as YUV 4:2:2.
-One luminance and one chrominance plane with alternating chroma samples
-as opposed to ``V4L2_PIX_FMT_YVU420``
-
-
-Description
-===========
-
-These are two-plane versions of the YUV 4:2:2 format. The three
-components are separated into two sub-images or planes. The Y plane is
-first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_NV16``, a
-combined CbCr plane immediately follows the Y plane in memory. The CbCr
-plane is the same width and height, in bytes, as the Y plane (and of the
-image). Each CbCr pair belongs to two pixels. For example,
-Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`.
-``V4L2_PIX_FMT_NV61`` is the same except the Cb and Cr bytes are
-swapped, the CrCb plane starts with a Cr byte.
-
-If the Y plane has pad bytes after each row, then the CbCr plane has as
-many pad bytes after its rows.
-
-**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`
- * - start + 16:
- - Cb\ :sub:`00`
- - Cr\ :sub:`00`
- - Cb\ :sub:`01`
- - Cr\ :sub:`01`
- * - start + 20:
- - Cb\ :sub:`10`
- - Cr\ :sub:`10`
- - Cb\ :sub:`11`
- - Cr\ :sub:`11`
- * - start + 24:
- - Cb\ :sub:`20`
- - Cr\ :sub:`20`
- - Cb\ :sub:`21`
- - Cr\ :sub:`21`
- * - start + 28:
- - Cb\ :sub:`30`
- - Cr\ :sub:`30`
- - Cb\ :sub:`31`
- - 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-nv16m.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst
deleted file mode 100644
index 58e97205d41f..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst
+++ /dev/null
@@ -1,88 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-NV16M:
-.. _v4l2-pix-fmt-nv61m:
-
-********************************************************
-V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61')
-********************************************************
-
-V4L2_PIX_FMT_NV61M
-Variation of ``V4L2_PIX_FMT_NV16`` and ``V4L2_PIX_FMT_NV61`` with planes
-non contiguous in memory.
-
-
-Description
-===========
-
-This is a multi-planar, two-plane version of the YUV 4:2:2 format. The
-three components are separated into two sub-images or planes.
-``V4L2_PIX_FMT_NV16M`` differs from ``V4L2_PIX_FMT_NV16`` in that the
-two planes are non-contiguous in memory, i.e. the chroma plane does not
-necessarily immediately follow the luma plane. The luminance data
-occupies the first plane. The Y plane has one byte per pixel. In the
-second plane there is chrominance data with alternating chroma samples.
-The CbCr plane is the same width and height, in bytes, as the Y plane.
-Each CbCr pair belongs to two pixels. For example,
-Cb\ :sub:`0`/Cr\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`.
-``V4L2_PIX_FMT_NV61M`` is the same as ``V4L2_PIX_FMT_NV16M`` except the
-Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.
-
-``V4L2_PIX_FMT_NV16M`` and ``V4L2_PIX_FMT_NV61M`` are intended to be
-used only in drivers and applications that support the multi-planar API,
-described in :ref:`planar-apis`.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start0 + 0:
- - Y'\ :sub:`00`
- - Y'\ :sub:`01`
- - Y'\ :sub:`02`
- - Y'\ :sub:`03`
- * - start0 + 4:
- - Y'\ :sub:`10`
- - Y'\ :sub:`11`
- - Y'\ :sub:`12`
- - Y'\ :sub:`13`
- * - start0 + 8:
- - Y'\ :sub:`20`
- - Y'\ :sub:`21`
- - Y'\ :sub:`22`
- - Y'\ :sub:`23`
- * - start0 + 12:
- - Y'\ :sub:`30`
- - Y'\ :sub:`31`
- - Y'\ :sub:`32`
- - Y'\ :sub:`33`
- * -
- * - start1 + 0:
- - Cb\ :sub:`00`
- - Cr\ :sub:`00`
- - Cb\ :sub:`02`
- - Cr\ :sub:`02`
- * - start1 + 4:
- - Cb\ :sub:`10`
- - Cr\ :sub:`10`
- - Cb\ :sub:`12`
- - Cr\ :sub:`12`
- * - start1 + 8:
- - Cb\ :sub:`20`
- - Cr\ :sub:`20`
- - Cb\ :sub:`22`
- - Cr\ :sub:`22`
- * - start1 + 12:
- - Cb\ :sub:`30`
- - Cr\ :sub:`30`
- - Cb\ :sub:`32`
- - Cr\ :sub:`32`
-
-
-**Color Sample Location:**
-Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
-horizontally.
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst b/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst
deleted file mode 100644
index bf1b94062fc2..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-nv24.rst
+++ /dev/null
@@ -1,95 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-NV24:
-.. _V4L2-PIX-FMT-NV42:
-
-******************************************************
-V4L2_PIX_FMT_NV24 ('NV24'), V4L2_PIX_FMT_NV42 ('NV42')
-******************************************************
-
-V4L2_PIX_FMT_NV42
-Formats with full horizontal and vertical chroma resolutions, also known
-as YUV 4:4:4. One luminance and one chrominance plane with alternating
-chroma samples as opposed to ``V4L2_PIX_FMT_YVU420``
-
-
-Description
-===========
-
-These are two-plane versions of the YUV 4:4:4 format. The three
-components are separated into two sub-images or planes. The Y plane is
-first, with each Y sample stored in one byte per pixel. For
-``V4L2_PIX_FMT_NV24``, a combined CbCr plane immediately follows the Y
-plane in memory. The CbCr plane has the same width and height, in
-pixels, as the Y plane (and the image). Each line contains one CbCr pair
-per pixel, with each Cb and Cr sample stored in one byte.
-``V4L2_PIX_FMT_NV42`` is the same except that the Cb and Cr samples are
-swapped, the CrCb plane starts with a Cr sample.
-
-If the Y plane has pad bytes after each row, then the CbCr plane has
-twice as many pad bytes after its rows.
-
-**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`
- * - start + 16:
- - Cb\ :sub:`00`
- - Cr\ :sub:`00`
- - Cb\ :sub:`01`
- - Cr\ :sub:`01`
- - Cb\ :sub:`02`
- - Cr\ :sub:`02`
- - Cb\ :sub:`03`
- - Cr\ :sub:`03`
- * - start + 24:
- - Cb\ :sub:`10`
- - Cr\ :sub:`10`
- - Cb\ :sub:`11`
- - Cr\ :sub:`11`
- - Cb\ :sub:`12`
- - Cr\ :sub:`12`
- - Cb\ :sub:`13`
- - Cr\ :sub:`13`
- * - start + 32:
- - Cb\ :sub:`20`
- - Cr\ :sub:`20`
- - Cb\ :sub:`21`
- - Cr\ :sub:`21`
- - Cb\ :sub:`22`
- - Cr\ :sub:`22`
- - Cb\ :sub:`23`
- - Cr\ :sub:`23`
- * - start + 40:
- - Cb\ :sub:`30`
- - Cr\ :sub:`30`
- - Cb\ :sub:`31`
- - Cr\ :sub:`31`
- - Cb\ :sub:`32`
- - Cr\ :sub:`32`
- - Cb\ :sub:`33`
- - Cr\ :sub:`33`
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
new file mode 100644
index 000000000000..0ca01270bde5
--- /dev/null
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
@@ -0,0 +1,463 @@
+.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+
+.. planar-yuv:
+
+******************
+Planar YUV formats
+******************
+
+Planar formats split luma and chroma data in separate memory regions. They
+exist in two variants:
+
+- Semi-planar formats use two planes. The first plane is the luma plane and
+ stores the Y components. The second plane is the chroma plane and stores the
+ Cb and Cr components interleaved.
+
+- Fully planar formats use three planes to store the Y, Cb and Cr components
+ separately.
+
+Within a plane, components are stored in pixel order, which may be linear or
+tiled. Padding may be supported at the end of the lines, and the line stride of
+the chroma planes may be constrained by the line stride of the luma plane.
+
+Some planar formats allow planes to be placed in independent memory locations.
+They are identified by an 'M' suffix in their name (such as in
+``V4L2_PIX_FMT_NV12M``). Those formats are intended to be used only in drivers
+and applications that support the multi-planar API, described in
+:ref:`planar-apis`. Unless explicitly documented as supporting non-contiguous
+planes, formats require the planes to follow each other immediately in memory.
+
+
+Semi-Planar YUV Formats
+=======================
+
+These formats are commonly referred to as NV formats (NV12, NV16, ...). They
+use two planes, and store the luma components in the first plane and the chroma
+components in the second plane. The Cb and Cr components are interleaved in the
+chroma plane, with Cb and Cr always stored in pairs. The chroma order is
+exposed as different formats.
+
+For memory contiguous formats, the number of padding pixels at the end of the
+chroma lines is identical to the padding of the luma lines. Without horizontal
+subsampling, the chroma line stride (in bytes) is thus equal to twice the luma
+line stride. With horizontal subsampling by 2, the chroma line stride is equal
+to the luma line stride. Vertical subsampling doesn't affect the line stride.
+
+For non-contiguous formats, no constraints are enforced by the format on the
+relationship between the luma and chroma line padding and stride.
+
+All components are stored with the same number of bits per component.
+
+.. flat-table:: Overview of Semi-Planar YUV Formats
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - Bits per component
+ - Subsampling
+ - Chroma order [1]_
+ - Contiguous [2]_
+ - Tiling [3]_
+ * - V4L2_PIX_FMT_NV12
+ - 'NV12'
+ - 8
+ - 4:2:0
+ - Cb, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV21
+ - 'NV21'
+ - 8
+ - 4:2:0
+ - Cr, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV12M
+ - 'NM12'
+ - 8
+ - 4:2:0
+ - Cb, Cr
+ - No
+ - Linear
+ * - V4L2_PIX_FMT_NV21M
+ - 'NM21'
+ - 8
+ - 4:2:0
+ - Cr, Cr
+ - No
+ - Linear
+ * - V4L2_PIX_FMT_NV12MT
+ - 'TM12'
+ - 8
+ - 4:2:0
+ - Cb, Cr
+ - No
+ - 64x32 macroblocks
+
+ Horizontal Z order
+ * - V4L2_PIX_FMT_NV12MT_16X16
+ - 'VM12'
+ - 8
+ - 4:2:2
+ - Cb, Cr
+ - No
+ - 16x16 macroblocks
+ * - V4L2_PIX_FMT_NV16
+ - 'NV16'
+ - 8
+ - 4:2:2
+ - Cb, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV61
+ - 'NV61'
+ - 8
+ - 4:2:2
+ - Cr, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV16M
+ - 'NM16'
+ - 8
+ - 4:2:2
+ - Cb, Cr
+ - No
+ - Linear
+ * - V4L2_PIX_FMT_NV61M
+ - 'NM61'
+ - 8
+ - 4:2:2
+ - Cr, Cr
+ - No
+ - Linear
+ * - V4L2_PIX_FMT_NV24
+ - 'NV24'
+ - 8
+ - 4:4:4
+ - Cb, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV42
+ - 'NV42'
+ - 8
+ - 4:4:4
+ - Cr, Cr
+ - Yes
+ - Linear
+
+.. note::
+
+ .. [1] Order of chroma samples in the second plane
+ .. [2] Indicates if planes have to be contiguous in memory or can be
+ disjoint
+ .. [3] Macroblock size in pixels
+
+
+**Color Sample Location:**
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
+
+
+.. _V4L2-PIX-FMT-NV12:
+.. _V4L2-PIX-FMT-NV21:
+.. _V4L2-PIX-FMT-NV12M:
+.. _V4L2-PIX-FMT-NV21M:
+
+NV12, NV21, NV12M and NV21M
+---------------------------
+
+Semi-planar YUV 4:2:0 formats. The chroma plane is subsampled by 2 in each
+direction. Chroma lines contain half the number of pixels and the same number
+of bytes as luma lines, and the chroma plane contains half the number of lines
+of the luma plane.
+
+.. flat-table:: Sample 4x4 NV12 Image
+ :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`
+ * - start + 16:
+ - Cb\ :sub:`00`
+ - Cr\ :sub:`00`
+ - Cb\ :sub:`01`
+ - Cr\ :sub:`01`
+ * - start + 20:
+ - Cb\ :sub:`10`
+ - Cr\ :sub:`10`
+ - Cb\ :sub:`11`
+ - Cr\ :sub:`11`
+
+.. flat-table:: Sample 4x4 NV12M Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start0 + 0:
+ - Y'\ :sub:`00`
+ - Y'\ :sub:`01`
+ - Y'\ :sub:`02`
+ - Y'\ :sub:`03`
+ * - start0 + 4:
+ - Y'\ :sub:`10`
+ - Y'\ :sub:`11`
+ - Y'\ :sub:`12`
+ - Y'\ :sub:`13`
+ * - start0 + 8:
+ - Y'\ :sub:`20`
+ - Y'\ :sub:`21`
+ - Y'\ :sub:`22`
+ - Y'\ :sub:`23`
+ * - start0 + 12:
+ - Y'\ :sub:`30`
+ - Y'\ :sub:`31`
+ - Y'\ :sub:`32`
+ - Y'\ :sub:`33`
+ * -
+ * - start1 + 0:
+ - Cb\ :sub:`00`
+ - Cr\ :sub:`00`
+ - Cb\ :sub:`01`
+ - Cr\ :sub:`01`
+ * - start1 + 4:
+ - Cb\ :sub:`10`
+ - Cr\ :sub:`10`
+ - Cb\ :sub:`11`
+ - Cr\ :sub:`11`
+
+
+.. _V4L2-PIX-FMT-NV12MT:
+.. _V4L2-PIX-FMT-NV12MT-16X16:
+
+NV12MT and MV12MT_16X16
+-----------------------
+
+Semi-planar YUV 4:2:0 formats, using macroblock tiling. The chroma plane is
+subsampled by 2 in each direction. Chroma lines contain half the number of
+pixels and the same number of bytes as luma lines, and the chroma plane
+contains half the number of lines of the luma plane.
+
+``V4L2_PIX_FMT_NV12MT_16X16`` stores pixel in 2D 16x16 macroblocks, and stores
+macroblocks linearly in memory. The line stride and image height must be
+aligned to a multiple of 16. The layouts of the luma and chroma planes are
+identical.
+
+``V4L2_PIX_FMT_NV12MT`` stores pixels in 2D 64x32 macroblocks, and stores 2x2
+groups of macroblocks in Z-order in memory, alternating Z and mirrored Z shapes
+horizontally. The line stride must be a multiple of 128 pixels to ensure an
+integer number of Z shapes. The image height must be a multiple of 32 pixels.
+If the vertical resolution is an odd number of macroblocks, the last row of
+macroblocks is stored in linear order. The layouts of the luma and chroma
+planes are identical.
+
+.. _nv12mt:
+
+.. kernel-figure:: nv12mt.svg
+ :alt: nv12mt.svg
+ :align: center
+
+ V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout
+
+.. _nv12mt_ex:
+
+.. kernel-figure:: nv12mt_example.svg
+ :alt: nv12mt_example.svg
+ :align: center
+
+ Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
+
+
+.. _V4L2-PIX-FMT-NV16:
+.. _V4L2-PIX-FMT-NV61:
+.. _V4L2-PIX-FMT-NV16M:
+.. _V4L2-PIX-FMT-NV61M:
+
+NV16, NV61, NV16M and NV61M
+---------------------------
+
+Semi-planar YUV 4:2:2 formats. The chroma plane is subsampled by 2 in the
+horizontal direction. Chroma lines contain half the number of pixels and the
+same number of bytes as luma lines, and the chroma plane contains the same
+number of lines as the luma plane.
+
+.. flat-table:: Sample 4x4 NV16 Image
+ :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`
+ * - start + 16:
+ - Cb\ :sub:`00`
+ - Cr\ :sub:`00`
+ - Cb\ :sub:`01`
+ - Cr\ :sub:`01`
+ * - start + 20:
+ - Cb\ :sub:`10`
+ - Cr\ :sub:`10`
+ - Cb\ :sub:`11`
+ - Cr\ :sub:`11`
+ * - start + 24:
+ - Cb\ :sub:`20`
+ - Cr\ :sub:`20`
+ - Cb\ :sub:`21`
+ - Cr\ :sub:`21`
+ * - start + 28:
+ - Cb\ :sub:`30`
+ - Cr\ :sub:`30`
+ - Cb\ :sub:`31`
+ - Cr\ :sub:`31`
+
+.. flat-table:: Sample 4x4 NV16M Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start0 + 0:
+ - Y'\ :sub:`00`
+ - Y'\ :sub:`01`
+ - Y'\ :sub:`02`
+ - Y'\ :sub:`03`
+ * - start0 + 4:
+ - Y'\ :sub:`10`
+ - Y'\ :sub:`11`
+ - Y'\ :sub:`12`
+ - Y'\ :sub:`13`
+ * - start0 + 8:
+ - Y'\ :sub:`20`
+ - Y'\ :sub:`21`
+ - Y'\ :sub:`22`
+ - Y'\ :sub:`23`
+ * - start0 + 12:
+ - Y'\ :sub:`30`
+ - Y'\ :sub:`31`
+ - Y'\ :sub:`32`
+ - Y'\ :sub:`33`
+ * -
+ * - start1 + 0:
+ - Cb\ :sub:`00`
+ - Cr\ :sub:`00`
+ - Cb\ :sub:`02`
+ - Cr\ :sub:`02`
+ * - start1 + 4:
+ - Cb\ :sub:`10`
+ - Cr\ :sub:`10`
+ - Cb\ :sub:`12`
+ - Cr\ :sub:`12`
+ * - start1 + 8:
+ - Cb\ :sub:`20`
+ - Cr\ :sub:`20`
+ - Cb\ :sub:`22`
+ - Cr\ :sub:`22`
+ * - start1 + 12:
+ - Cb\ :sub:`30`
+ - Cr\ :sub:`30`
+ - Cb\ :sub:`32`
+ - Cr\ :sub:`32`
+
+
+.. _V4L2-PIX-FMT-NV24:
+.. _V4L2-PIX-FMT-NV42:
+
+NV24 and NV42
+-------------
+
+Semi-planar YUV 4:4:4 formats. The chroma plane is subsampled by 2 in the
+horizontal direction. Chroma lines contain half the number of pixels and the
+same number of bytes as luma lines, and the chroma plane contains the same
+number of lines as the luma plane.
+
+.. flat-table:: Sample 4x4 NV24 Image
+ :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`
+ * - start + 16:
+ - Cb\ :sub:`00`
+ - Cr\ :sub:`00`
+ - Cb\ :sub:`01`
+ - Cr\ :sub:`01`
+ - Cb\ :sub:`02`
+ - Cr\ :sub:`02`
+ - Cb\ :sub:`03`
+ - Cr\ :sub:`03`
+ * - start + 24:
+ - Cb\ :sub:`10`
+ - Cr\ :sub:`10`
+ - Cb\ :sub:`11`
+ - Cr\ :sub:`11`
+ - Cb\ :sub:`12`
+ - Cr\ :sub:`12`
+ - Cb\ :sub:`13`
+ - Cr\ :sub:`13`
+ * - start + 32:
+ - Cb\ :sub:`20`
+ - Cr\ :sub:`20`
+ - Cb\ :sub:`21`
+ - Cr\ :sub:`21`
+ - Cb\ :sub:`22`
+ - Cr\ :sub:`22`
+ - Cb\ :sub:`23`
+ - Cr\ :sub:`23`
+ * - start + 40:
+ - Cb\ :sub:`30`
+ - Cr\ :sub:`30`
+ - Cb\ :sub:`31`
+ - Cr\ :sub:`31`
+ - Cb\ :sub:`32`
+ - Cr\ :sub:`32`
+ - Cb\ :sub:`33`
+ - Cr\ :sub:`33`
diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst
index 7179d715f8a7..517499056f3b 100644
--- a/Documentation/userspace-api/media/v4l/yuv-formats.rst
+++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst
@@ -265,6 +265,7 @@ image.
:maxdepth: 1
pixfmt-packed-yuv
+ pixfmt-yuv-planar
pixfmt-yuv-luma
pixfmt-y8i
pixfmt-y12i
@@ -276,10 +277,4 @@ image.
pixfmt-yuv410
pixfmt-yuv422p
pixfmt-yuv411p
- pixfmt-nv12
- pixfmt-nv12m
- pixfmt-nv12mt
- pixfmt-nv16
- pixfmt-nv16m
- pixfmt-nv24
pixfmt-m420
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PATCH v2 14/19] media: doc: pixfmt-yuv: Move all planar YUV formats to common file
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (12 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 13/19] media: doc: pixfmt-yuv: Move all semi-planar " Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-02 22:40 ` [PATCH v2 15/19] media: v4l2: Add 10-, 12- and 16-bpc BGR formats Laurent Pinchart
` (5 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Planar pixel formats are documented in separate files. This duplicates
information, as those formats share comon traits. Consolidate them in a
single file and summarize their descriptions in a single table.
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
.../media/v4l/pixfmt-yuv-planar.rst | 487 ++++++++++++++++++
.../userspace-api/media/v4l/pixfmt-yuv410.rst | 72 ---
.../media/v4l/pixfmt-yuv411p.rst | 80 ---
.../userspace-api/media/v4l/pixfmt-yuv420.rst | 81 ---
.../media/v4l/pixfmt-yuv420m.rst | 90 ----
.../media/v4l/pixfmt-yuv422m.rst | 101 ----
.../media/v4l/pixfmt-yuv422p.rst | 89 ----
.../media/v4l/pixfmt-yuv444m.rst | 110 ----
.../userspace-api/media/v4l/yuv-formats.rst | 7 -
9 files changed, 487 insertions(+), 630 deletions(-)
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst
delete mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
index 0ca01270bde5..07081ab05419 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
@@ -461,3 +461,490 @@ number of lines as the luma plane.
- Cr\ :sub:`32`
- Cb\ :sub:`33`
- Cr\ :sub:`33`
+
+
+Fully Planar YUV Formats
+========================
+
+These formats store the Y, Cb and Cr components in three separate planes. The
+luma plane comes first, and the order of the two chroma planes varies between
+formats. The two chroma planes always use the same subsampling.
+
+For memory contiguous formats, the number of padding pixels at the end of the
+chroma lines is identical to the padding of the luma lines. The chroma line
+stride (in bytes) is thus equal to the luma line stride divided by the
+horizontal subsampling factor. Vertical subsampling doesn't affect the line
+stride.
+
+For non-contiguous formats, no constraints are enforced by the format on the
+relationship between the luma and chroma line padding and stride.
+
+All components are stored with the same number of bits per component.
+
+.. flat-table:: Overview of Fully Planar YUV Formats
+ :header-rows: 1
+ :stub-columns: 0
+
+ * - Identifier
+ - Code
+ - Bits per component
+ - Subsampling
+ - Planes order [4]_
+ - Contiguous [5]_
+
+ * - V4L2_PIX_FMT_YUV410
+ - 'YUV9'
+ - 8
+ - 4:1:0
+ - Y, Cb, Cr
+ - Yes
+ * - V4L2_PIX_FMT_YVU410
+ - 'YVU9'
+ - 8
+ - 4:1:0
+ - Y, Cr, Cb
+ - Yes
+ * - V4L2_PIX_FMT_YUV411P
+ - '411P'
+ - 8
+ - 4:1:1
+ - Y, Cb, Cr
+ - Yes
+ * - V4L2_PIX_FMT_YUV420M
+ - 'YM12'
+ - 8
+ - 4:2:0
+ - Y, Cb, Cr
+ - No
+ * - V4L2_PIX_FMT_YVU420M
+ - 'YM21'
+ - 8
+ - 4:2:0
+ - Y, Cb, Cr
+ - No
+ * - V4L2_PIX_FMT_YUV420
+ - 'YU12'
+ - 8
+ - 4:2:0
+ - Y, Cb, Cr
+ - Yes
+ * - V4L2_PIX_FMT_YVU420
+ - 'YV12'
+ - 8
+ - 4:2:0
+ - Y, Cr, Cb
+ - Yes
+ * - V4L2_PIX_FMT_YUV422P
+ - '422P'
+ - 8
+ - 4:2:2
+ - Y, Cb, Cr
+ - Yes
+ * - V4L2_PIX_FMT_YUV422M
+ - 'YM16'
+ - 8
+ - 4:2:2
+ - Y, Cb, Cr
+ - No
+ * - V4L2_PIX_FMT_YVU422M
+ - 'YM61'
+ - 8
+ - 4:2:2
+ - Y, Cr, Cb
+ - No
+ * - V4L2_PIX_FMT_YUV444M
+ - 'YM24'
+ - 8
+ - 4:4:4
+ - Y, Cb, Cr
+ - No
+ * - V4L2_PIX_FMT_YVU444M
+ - 'YM42'
+ - 8
+ - 4:4:4
+ - Y, Cb, Cr
+ - No
+
+.. note::
+
+ .. [4] Order of luma and chroma planes
+ .. [5] Indicates if planes have to be contiguous in memory or can be
+ disjoint
+
+
+**Color Sample Location:**
+Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
+horizontally.
+
+.. _V4L2-PIX-FMT-YUV410:
+.. _V4L2-PIX-FMT-YVU410:
+
+YUV410 and YVU410
+-----------------
+
+Planar YUV 4:1:0 formats. The chroma planes are subsampled by 4 in each
+direction. Chroma lines contain a quarter of the number of pixels and bytes of
+the luma lines, and the chroma planes contain a quarter of the number of lines
+of the luma plane.
+
+.. flat-table:: Sample 4x4 YUV410 Image
+ :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`
+ * - start + 16:
+ - Cr\ :sub:`00`
+ * - start + 17:
+ - Cb\ :sub:`00`
+
+
+.. _V4L2-PIX-FMT-YUV411P:
+
+YUV411P
+-------
+
+Planar YUV 4:1:1 formats. The chroma planes are subsampled by 4 in the
+horizontal direction. Chroma lines contain a quarter of the number of pixels
+and bytes of the luma lines, and the chroma planes contain the same number of
+lines as the luma plane.
+
+.. flat-table:: Sample 4x4 YUV411P Image
+ :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`
+ * - start + 16:
+ - Cb\ :sub:`00`
+ * - start + 17:
+ - Cb\ :sub:`10`
+ * - start + 18:
+ - Cb\ :sub:`20`
+ * - start + 19:
+ - Cb\ :sub:`30`
+ * - start + 20:
+ - Cr\ :sub:`00`
+ * - start + 21:
+ - Cr\ :sub:`10`
+ * - start + 22:
+ - Cr\ :sub:`20`
+ * - start + 23:
+ - Cr\ :sub:`30`
+
+
+.. _V4L2-PIX-FMT-YUV420:
+.. _V4L2-PIX-FMT-YVU420:
+.. _V4L2-PIX-FMT-YUV420M:
+.. _V4L2-PIX-FMT-YVU420M:
+
+YUV420, YVU420, YUV420M and YVU420M
+-----------------------------------
+
+Planar YUV 4:2:0 formats. The chroma planes are subsampled by 2 in each
+direction. Chroma lines contain half of the number of pixels and bytes of the
+luma lines, and the chroma planes contain half of the number of lines of the
+luma plane.
+
+.. flat-table:: Sample 4x4 YUV420 Image
+ :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`
+ * - start + 16:
+ - Cr\ :sub:`00`
+ - Cr\ :sub:`01`
+ * - start + 18:
+ - Cr\ :sub:`10`
+ - Cr\ :sub:`11`
+ * - start + 20:
+ - Cb\ :sub:`00`
+ - Cb\ :sub:`01`
+ * - start + 22:
+ - Cb\ :sub:`10`
+ - Cb\ :sub:`11`
+
+.. flat-table:: Sample 4x4 YUV420M Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start0 + 0:
+ - Y'\ :sub:`00`
+ - Y'\ :sub:`01`
+ - Y'\ :sub:`02`
+ - Y'\ :sub:`03`
+ * - start0 + 4:
+ - Y'\ :sub:`10`
+ - Y'\ :sub:`11`
+ - Y'\ :sub:`12`
+ - Y'\ :sub:`13`
+ * - start0 + 8:
+ - Y'\ :sub:`20`
+ - Y'\ :sub:`21`
+ - Y'\ :sub:`22`
+ - Y'\ :sub:`23`
+ * - start0 + 12:
+ - Y'\ :sub:`30`
+ - Y'\ :sub:`31`
+ - Y'\ :sub:`32`
+ - Y'\ :sub:`33`
+ * -
+ * - start1 + 0:
+ - Cb\ :sub:`00`
+ - Cb\ :sub:`01`
+ * - start1 + 2:
+ - Cb\ :sub:`10`
+ - Cb\ :sub:`11`
+ * -
+ * - start2 + 0:
+ - Cr\ :sub:`00`
+ - Cr\ :sub:`01`
+ * - start2 + 2:
+ - Cr\ :sub:`10`
+ - Cr\ :sub:`11`
+
+
+.. _V4L2-PIX-FMT-YUV422P:
+.. _V4L2-PIX-FMT-YUV422M:
+.. _V4L2-PIX-FMT-YVU422M:
+
+YUV422P, YUV422M and YVU422M
+----------------------------
+
+Planar YUV 4:2:2 formats. The chroma planes are subsampled by 2 in the
+horizontal direction. Chroma lines contain half of the number of pixels and
+bytes of the luma lines, and the chroma planes contain the same number of lines
+as the luma plane.
+
+.. flat-table:: Sample 4x4 YUV422P Image
+ :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`
+ * - start + 16:
+ - Cb\ :sub:`00`
+ - Cb\ :sub:`01`
+ * - start + 18:
+ - Cb\ :sub:`10`
+ - Cb\ :sub:`11`
+ * - start + 20:
+ - Cb\ :sub:`20`
+ - Cb\ :sub:`21`
+ * - start + 22:
+ - Cb\ :sub:`30`
+ - Cb\ :sub:`31`
+ * - start + 24:
+ - Cr\ :sub:`00`
+ - Cr\ :sub:`01`
+ * - start + 26:
+ - Cr\ :sub:`10`
+ - Cr\ :sub:`11`
+ * - start + 28:
+ - Cr\ :sub:`20`
+ - Cr\ :sub:`21`
+ * - start + 30:
+ - Cr\ :sub:`30`
+ - Cr\ :sub:`31`
+
+.. flat-table:: Sample 4x4 YUV422M Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start0 + 0:
+ - Y'\ :sub:`00`
+ - Y'\ :sub:`01`
+ - Y'\ :sub:`02`
+ - Y'\ :sub:`03`
+ * - start0 + 4:
+ - Y'\ :sub:`10`
+ - Y'\ :sub:`11`
+ - Y'\ :sub:`12`
+ - Y'\ :sub:`13`
+ * - start0 + 8:
+ - Y'\ :sub:`20`
+ - Y'\ :sub:`21`
+ - Y'\ :sub:`22`
+ - Y'\ :sub:`23`
+ * - start0 + 12:
+ - Y'\ :sub:`30`
+ - Y'\ :sub:`31`
+ - Y'\ :sub:`32`
+ - Y'\ :sub:`33`
+ * -
+ * - start1 + 0:
+ - Cb\ :sub:`00`
+ - Cb\ :sub:`01`
+ * - start1 + 2:
+ - Cb\ :sub:`10`
+ - Cb\ :sub:`11`
+ * - start1 + 4:
+ - Cb\ :sub:`20`
+ - Cb\ :sub:`21`
+ * - start1 + 6:
+ - Cb\ :sub:`30`
+ - Cb\ :sub:`31`
+ * -
+ * - start2 + 0:
+ - Cr\ :sub:`00`
+ - Cr\ :sub:`01`
+ * - start2 + 2:
+ - Cr\ :sub:`10`
+ - Cr\ :sub:`11`
+ * - start2 + 4:
+ - Cr\ :sub:`20`
+ - Cr\ :sub:`21`
+ * - start2 + 6:
+ - Cr\ :sub:`30`
+ - Cr\ :sub:`31`
+
+
+.. _V4L2-PIX-FMT-YUV444M:
+.. _V4L2-PIX-FMT-YVU444M:
+
+YUV444M and YVU444M
+-------------------
+
+Planar YUV 4:4:4 formats. The chroma planes are no subsampled. Chroma lines
+contain the same number of pixels and bytes of the luma lines, and the chroma
+planes contain the same number of lines as the luma plane.
+
+.. flat-table:: Sample 4x4 YUV444M Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start0 + 0:
+ - Y'\ :sub:`00`
+ - Y'\ :sub:`01`
+ - Y'\ :sub:`02`
+ - Y'\ :sub:`03`
+ * - start0 + 4:
+ - Y'\ :sub:`10`
+ - Y'\ :sub:`11`
+ - Y'\ :sub:`12`
+ - Y'\ :sub:`13`
+ * - start0 + 8:
+ - Y'\ :sub:`20`
+ - Y'\ :sub:`21`
+ - Y'\ :sub:`22`
+ - Y'\ :sub:`23`
+ * - start0 + 12:
+ - Y'\ :sub:`30`
+ - Y'\ :sub:`31`
+ - Y'\ :sub:`32`
+ - Y'\ :sub:`33`
+ * -
+ * - start1 + 0:
+ - Cb\ :sub:`00`
+ - Cb\ :sub:`01`
+ - Cb\ :sub:`02`
+ - Cb\ :sub:`03`
+ * - start1 + 4:
+ - Cb\ :sub:`10`
+ - Cb\ :sub:`11`
+ - Cb\ :sub:`12`
+ - Cb\ :sub:`13`
+ * - start1 + 8:
+ - Cb\ :sub:`20`
+ - Cb\ :sub:`21`
+ - Cb\ :sub:`22`
+ - Cb\ :sub:`23`
+ * - start1 + 12:
+ - Cb\ :sub:`20`
+ - Cb\ :sub:`21`
+ - Cb\ :sub:`32`
+ - Cb\ :sub:`33`
+ * -
+ * - start2 + 0:
+ - Cr\ :sub:`00`
+ - Cr\ :sub:`01`
+ - Cr\ :sub:`02`
+ - Cr\ :sub:`03`
+ * - start2 + 4:
+ - Cr\ :sub:`10`
+ - Cr\ :sub:`11`
+ - Cr\ :sub:`12`
+ - Cr\ :sub:`13`
+ * - start2 + 8:
+ - Cr\ :sub:`20`
+ - Cr\ :sub:`21`
+ - Cr\ :sub:`22`
+ - Cr\ :sub:`23`
+ * - start2 + 12:
+ - Cr\ :sub:`30`
+ - Cr\ :sub:`31`
+ - Cr\ :sub:`32`
+ - Cr\ :sub:`33`
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst
deleted file mode 100644
index d79cd46d5055..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv410.rst
+++ /dev/null
@@ -1,72 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-YVU410:
-.. _v4l2-pix-fmt-yuv410:
-
-**********************************************************
-V4L2_PIX_FMT_YVU410 ('YVU9'), V4L2_PIX_FMT_YUV410 ('YUV9')
-**********************************************************
-
-
-V4L2_PIX_FMT_YUV410
-Planar formats with ¼ horizontal and vertical chroma resolution, also
-known as YUV 4:1:0
-
-
-Description
-===========
-
-These are planar formats, as opposed to a packed format. The three
-components are separated into three sub-images or planes. The Y plane is
-first. The Y plane has one byte per pixel. For ``V4L2_PIX_FMT_YVU410``,
-the Cr plane immediately follows the Y plane in memory. The Cr plane is
-¼ the width and ¼ the height of the Y plane (and of the image). Each Cr
-belongs to 16 pixels, a four-by-four square of the image. Following the
-Cr plane is the Cb plane, just like the Cr plane.
-``V4L2_PIX_FMT_YUV410`` is the same, except the Cb plane comes first,
-then the Cr plane.
-
-If the Y plane has pad bytes after each row, then the Cr and Cb planes
-have ¼ as many pad bytes after their rows. In other words, four Cx rows
-(including padding) are exactly as long as one Y row (including
-padding).
-
-**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`
- * - start + 16:
- - Cr\ :sub:`00`
- * - start + 17:
- - Cb\ :sub:`00`
-
-
-**Color Sample Location:**
-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
deleted file mode 100644
index 8a70eeca8d83..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv411p.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-YUV411P:
-
-*****************************
-V4L2_PIX_FMT_YUV411P ('411P')
-*****************************
-
-
-Format with ¼ horizontal chroma resolution, also known as YUV 4:1:1.
-Planar layout as opposed to ``V4L2_PIX_FMT_Y41P``
-
-
-Description
-===========
-
-This format is not commonly used. This is a planar format similar to the
-4:2:2 planar format except with half as many chroma. The three
-components are separated into three sub-images or planes. The Y plane is
-first. The Y plane has one byte per pixel. The Cb plane immediately
-follows the Y plane in memory. The Cb plane is ¼ the width of the Y
-plane (and of the image). Each Cb belongs to 4 pixels all on the same
-row. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
-Y'\ :sub:`02` and Y'\ :sub:`03`. Following the Cb plane is the Cr plane,
-just like the Cb plane.
-
-If the Y plane has pad bytes after each row, then the Cr and Cb planes
-have ¼ as many pad bytes after their rows. In other words, four C x rows
-(including padding) is exactly as long as one Y row (including padding).
-
-**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`
- * - start + 16:
- - Cb\ :sub:`00`
- * - start + 17:
- - Cb\ :sub:`10`
- * - start + 18:
- - Cb\ :sub:`20`
- * - start + 19:
- - Cb\ :sub:`30`
- * - start + 20:
- - Cr\ :sub:`00`
- * - start + 21:
- - Cr\ :sub:`10`
- * - start + 22:
- - Cr\ :sub:`20`
- * - start + 23:
- - Cr\ :sub:`30`
-
-
-**Color Sample Location:**
-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
deleted file mode 100644
index a36ec8d6d8a4..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420.rst
+++ /dev/null
@@ -1,81 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-YVU420:
-.. _V4L2-PIX-FMT-YUV420:
-
-**********************************************************
-V4L2_PIX_FMT_YVU420 ('YV12'), V4L2_PIX_FMT_YUV420 ('YU12')
-**********************************************************
-
-
-V4L2_PIX_FMT_YUV420
-Planar formats with ½ horizontal and vertical chroma resolution, also
-known as YUV 4:2:0
-
-
-Description
-===========
-
-These are planar formats, as opposed to a packed format. The three
-components are separated into three sub- images or planes. The Y plane
-is first. The Y plane has one byte per pixel. For
-``V4L2_PIX_FMT_YVU420``, the Cr plane immediately follows the Y plane in
-memory. The Cr plane is half the width and half the height of the Y
-plane (and of the image). Each Cr belongs to four pixels, a two-by-two
-square of the image. For example, Cr\ :sub:`0` belongs to Y'\ :sub:`00`,
-Y'\ :sub:`01`, Y'\ :sub:`10`, and Y'\ :sub:`11`. Following the Cr plane
-is the Cb plane, just like the Cr plane. ``V4L2_PIX_FMT_YUV420`` is the
-same except the Cb plane comes first, then the Cr plane.
-
-If the Y plane has pad bytes after each row, then the Cr and Cb planes
-have half as many pad bytes after their rows. In other words, two Cx
-rows (including padding) is exactly as long as one Y row (including
-padding).
-
-**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`
- * - start + 16:
- - Cr\ :sub:`00`
- - Cr\ :sub:`01`
- * - start + 18:
- - Cr\ :sub:`10`
- - Cr\ :sub:`11`
- * - start + 20:
- - Cb\ :sub:`00`
- - Cb\ :sub:`01`
- * - start + 22:
- - Cb\ :sub:`10`
- - Cb\ :sub:`11`
-
-
-**Color Sample Location:**
-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
deleted file mode 100644
index c2cf17b9743c..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv420m.rst
+++ /dev/null
@@ -1,90 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-YUV420M:
-.. _v4l2-pix-fmt-yvu420m:
-
-************************************************************
-V4L2_PIX_FMT_YUV420M ('YM12'), V4L2_PIX_FMT_YVU420M ('YM21')
-************************************************************
-
-
-V4L2_PIX_FMT_YVU420M
-Variation of ``V4L2_PIX_FMT_YUV420`` and ``V4L2_PIX_FMT_YVU420`` with
-planes non contiguous in memory.
-
-
-Description
-===========
-
-This is a multi-planar format, as opposed to a packed format. The three
-components are separated into three sub-images or planes.
-
-The Y plane is first. The Y plane has one byte per pixel. For
-``V4L2_PIX_FMT_YUV420M`` the Cb data constitutes the second plane which
-is half the width and half the height of the Y plane (and of the image).
-Each Cb belongs to four pixels, a two-by-two square of the image. For
-example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`, Y'\ :sub:`01`,
-Y'\ :sub:`10`, and Y'\ :sub:`11`. The Cr data, just like the Cb plane,
-is in the third plane.
-
-``V4L2_PIX_FMT_YVU420M`` is the same except the Cr data is stored in the
-second plane and the Cb data in the third plane.
-
-If the Y plane has pad bytes after each row, then the Cb and Cr planes
-have half as many pad bytes after their rows. In other words, two Cx
-rows (including padding) is exactly as long as one Y row (including
-padding).
-
-``V4L2_PIX_FMT_YUV420M`` and ``V4L2_PIX_FMT_YVU420M`` are intended to be
-used only in drivers and applications that support the multi-planar API,
-described in :ref:`planar-apis`.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start0 + 0:
- - Y'\ :sub:`00`
- - Y'\ :sub:`01`
- - Y'\ :sub:`02`
- - Y'\ :sub:`03`
- * - start0 + 4:
- - Y'\ :sub:`10`
- - Y'\ :sub:`11`
- - Y'\ :sub:`12`
- - Y'\ :sub:`13`
- * - start0 + 8:
- - Y'\ :sub:`20`
- - Y'\ :sub:`21`
- - Y'\ :sub:`22`
- - Y'\ :sub:`23`
- * - start0 + 12:
- - Y'\ :sub:`30`
- - Y'\ :sub:`31`
- - Y'\ :sub:`32`
- - Y'\ :sub:`33`
- * -
- * - start1 + 0:
- - Cb\ :sub:`00`
- - Cb\ :sub:`01`
- * - start1 + 2:
- - Cb\ :sub:`10`
- - Cb\ :sub:`11`
- * -
- * - start2 + 0:
- - Cr\ :sub:`00`
- - Cr\ :sub:`01`
- * - start2 + 2:
- - Cr\ :sub:`10`
- - Cr\ :sub:`11`
-
-
-**Color Sample Location:**
-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
deleted file mode 100644
index f92b54853fc9..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422m.rst
+++ /dev/null
@@ -1,101 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-YUV422M:
-.. _v4l2-pix-fmt-yvu422m:
-
-************************************************************
-V4L2_PIX_FMT_YUV422M ('YM16'), V4L2_PIX_FMT_YVU422M ('YM61')
-************************************************************
-
-
-V4L2_PIX_FMT_YVU422M
-Planar formats with ½ horizontal resolution, also known as YUV and YVU
-4:2:2
-
-
-Description
-===========
-
-This is a multi-planar format, as opposed to a packed format. The three
-components are separated into three sub-images or planes.
-
-The Y plane is first. The Y plane has one byte per pixel. For
-``V4L2_PIX_FMT_YUV422M`` the Cb data constitutes the second plane which
-is half the width of the Y plane (and of the image). Each Cb belongs to
-two pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`,
-Y'\ :sub:`01`. The Cr data, just like the Cb plane, is in the third
-plane.
-
-``V4L2_PIX_FMT_YVU422M`` is the same except the Cr data is stored in the
-second plane and the Cb data in the third plane.
-
-If the Y plane has pad bytes after each row, then the Cb and Cr planes
-have half as many pad bytes after their rows. In other words, two Cx
-rows (including padding) is exactly as long as one Y row (including
-padding).
-
-``V4L2_PIX_FMT_YUV422M`` and ``V4L2_PIX_FMT_YVU422M`` are intended to be
-used only in drivers and applications that support the multi-planar API,
-described in :ref:`planar-apis`.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start0 + 0:
- - Y'\ :sub:`00`
- - Y'\ :sub:`01`
- - Y'\ :sub:`02`
- - Y'\ :sub:`03`
- * - start0 + 4:
- - Y'\ :sub:`10`
- - Y'\ :sub:`11`
- - Y'\ :sub:`12`
- - Y'\ :sub:`13`
- * - start0 + 8:
- - Y'\ :sub:`20`
- - Y'\ :sub:`21`
- - Y'\ :sub:`22`
- - Y'\ :sub:`23`
- * - start0 + 12:
- - Y'\ :sub:`30`
- - Y'\ :sub:`31`
- - Y'\ :sub:`32`
- - Y'\ :sub:`33`
- * -
- * - start1 + 0:
- - Cb\ :sub:`00`
- - Cb\ :sub:`01`
- * - start1 + 2:
- - Cb\ :sub:`10`
- - Cb\ :sub:`11`
- * - start1 + 4:
- - Cb\ :sub:`20`
- - Cb\ :sub:`21`
- * - start1 + 6:
- - Cb\ :sub:`30`
- - Cb\ :sub:`31`
- * -
- * - start2 + 0:
- - Cr\ :sub:`00`
- - Cr\ :sub:`01`
- * - start2 + 2:
- - Cr\ :sub:`10`
- - Cr\ :sub:`11`
- * - start2 + 4:
- - Cr\ :sub:`20`
- - Cr\ :sub:`21`
- * - start2 + 6:
- - Cr\ :sub:`30`
- - 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-yuv422p.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst
deleted file mode 100644
index 33e6b923e325..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv422p.rst
+++ /dev/null
@@ -1,89 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-YUV422P:
-
-*****************************
-V4L2_PIX_FMT_YUV422P ('422P')
-*****************************
-
-
-Format with ½ horizontal chroma resolution, also known as YUV 4:2:2.
-Planar layout as opposed to ``V4L2_PIX_FMT_YUYV``
-
-
-Description
-===========
-
-This format is not commonly used. This is a planar version of the YUYV
-format. The three components are separated into three sub-images or
-planes. The Y plane is first. The Y plane has one byte per pixel. The Cb
-plane immediately follows the Y plane in memory. The Cb plane is half
-the width of the Y plane (and of the image). Each Cb belongs to two
-pixels. For example, Cb\ :sub:`0` belongs to Y'\ :sub:`00`,
-Y'\ :sub:`01`. Following the Cb plane is the Cr plane, just like the Cb
-plane.
-
-If the Y plane has pad bytes after each row, then the Cr and Cb planes
-have half as many pad bytes after their rows. In other words, two Cx
-rows (including padding) is exactly as long as one Y row (including
-padding).
-
-**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`
- * - start + 16:
- - Cb\ :sub:`00`
- - Cb\ :sub:`01`
- * - start + 18:
- - Cb\ :sub:`10`
- - Cb\ :sub:`11`
- * - start + 20:
- - Cb\ :sub:`20`
- - Cb\ :sub:`21`
- * - start + 22:
- - Cb\ :sub:`30`
- - Cb\ :sub:`31`
- * - start + 24:
- - Cr\ :sub:`00`
- - Cr\ :sub:`01`
- * - start + 26:
- - Cr\ :sub:`10`
- - Cr\ :sub:`11`
- * - start + 28:
- - Cr\ :sub:`20`
- - Cr\ :sub:`21`
- * - start + 30:
- - Cr\ :sub:`30`
- - 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-yuv444m.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst
deleted file mode 100644
index 7c03cc5b07d9..000000000000
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv444m.rst
+++ /dev/null
@@ -1,110 +0,0 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
-
-.. _V4L2-PIX-FMT-YUV444M:
-.. _v4l2-pix-fmt-yvu444m:
-
-************************************************************
-V4L2_PIX_FMT_YUV444M ('YM24'), V4L2_PIX_FMT_YVU444M ('YM42')
-************************************************************
-
-
-V4L2_PIX_FMT_YVU444M
-Planar formats with full horizontal resolution, also known as YUV and
-YVU 4:4:4
-
-
-Description
-===========
-
-This is a multi-planar format, as opposed to a packed format. The three
-components are separated into three sub-images or planes.
-
-The Y plane is first. The Y plane has one byte per pixel. For
-``V4L2_PIX_FMT_YUV444M`` the Cb data constitutes the second plane which
-is the same width and height as the Y plane (and as the image). The Cr
-data, just like the Cb plane, is in the third plane.
-
-``V4L2_PIX_FMT_YVU444M`` is the same except the Cr data is stored in the
-second plane and the Cb data in the third plane.
-
-If the Y plane has pad bytes after each row, then the Cb and Cr planes
-have the same number of pad bytes after their rows.
-
-``V4L2_PIX_FMT_YUV444M`` and ``V4L2_PIX_FMT_YUV444M`` are intended to be
-used only in drivers and applications that support the multi-planar API,
-described in :ref:`planar-apis`.
-
-**Byte Order.**
-Each cell is one byte.
-
-
-.. flat-table::
- :header-rows: 0
- :stub-columns: 0
-
- * - start0 + 0:
- - Y'\ :sub:`00`
- - Y'\ :sub:`01`
- - Y'\ :sub:`02`
- - Y'\ :sub:`03`
- * - start0 + 4:
- - Y'\ :sub:`10`
- - Y'\ :sub:`11`
- - Y'\ :sub:`12`
- - Y'\ :sub:`13`
- * - start0 + 8:
- - Y'\ :sub:`20`
- - Y'\ :sub:`21`
- - Y'\ :sub:`22`
- - Y'\ :sub:`23`
- * - start0 + 12:
- - Y'\ :sub:`30`
- - Y'\ :sub:`31`
- - Y'\ :sub:`32`
- - Y'\ :sub:`33`
- * -
- * - start1 + 0:
- - Cb\ :sub:`00`
- - Cb\ :sub:`01`
- - Cb\ :sub:`02`
- - Cb\ :sub:`03`
- * - start1 + 4:
- - Cb\ :sub:`10`
- - Cb\ :sub:`11`
- - Cb\ :sub:`12`
- - Cb\ :sub:`13`
- * - start1 + 8:
- - Cb\ :sub:`20`
- - Cb\ :sub:`21`
- - Cb\ :sub:`22`
- - Cb\ :sub:`23`
- * - start1 + 12:
- - Cb\ :sub:`20`
- - Cb\ :sub:`21`
- - Cb\ :sub:`32`
- - Cb\ :sub:`33`
- * -
- * - start2 + 0:
- - Cr\ :sub:`00`
- - Cr\ :sub:`01`
- - Cr\ :sub:`02`
- - Cr\ :sub:`03`
- * - start2 + 4:
- - Cr\ :sub:`10`
- - Cr\ :sub:`11`
- - Cr\ :sub:`12`
- - Cr\ :sub:`13`
- * - start2 + 8:
- - Cr\ :sub:`20`
- - Cr\ :sub:`21`
- - Cr\ :sub:`22`
- - Cr\ :sub:`23`
- * - start2 + 12:
- - Cr\ :sub:`30`
- - Cr\ :sub:`31`
- - Cr\ :sub:`32`
- - Cr\ :sub:`33`
-
-
-**Color Sample Location:**
-Chroma samples are :ref:`co-sited<yuv-chroma-cosited>`.
diff --git a/Documentation/userspace-api/media/v4l/yuv-formats.rst b/Documentation/userspace-api/media/v4l/yuv-formats.rst
index 517499056f3b..24b34cdfa6fe 100644
--- a/Documentation/userspace-api/media/v4l/yuv-formats.rst
+++ b/Documentation/userspace-api/media/v4l/yuv-formats.rst
@@ -270,11 +270,4 @@ image.
pixfmt-y8i
pixfmt-y12i
pixfmt-uv8
- pixfmt-yuv420
- pixfmt-yuv420m
- pixfmt-yuv422m
- pixfmt-yuv444m
- pixfmt-yuv410
- pixfmt-yuv422p
- pixfmt-yuv411p
pixfmt-m420
--
Regards,
Laurent Pinchart
^ permalink raw reply related [flat|nested] 35+ messages in thread* [PATCH v2 15/19] media: v4l2: Add 10-, 12- and 16-bpc BGR formats
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (13 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 14/19] media: doc: pixfmt-yuv: Move all planar " Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-16 12:03 ` Hans Verkuil
2020-11-02 22:40 ` [PATCH v2 16/19] media: v4l2: Add a few missing packed YUV 4:4:4 formats Laurent Pinchart
` (4 subsequent siblings)
19 siblings, 1 reply; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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>
---
Changes since v1:
- Interleave component names and number of bits
---
.../userspace-api/media/v4l/pixfmt-rgb.rst | 69 +++++++++++++++++++
include/uapi/linux/videodev2.h | 5 ++
2 files changed, 74 insertions(+)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
index 405d6f032078..846d307624fc 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
@@ -1079,6 +1079,75 @@ 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. The component names and the
+corresponding number of bits are interleaved for clarity.
+
+.. 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-X2B10G10R10:
+
+ - ``V4L2_PIX_FMT_X2B10G10R10``
+ - '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-X4B12G12R12:
+
+ - ``V4L2_PIX_FMT_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-B16G16R16:
+
+ - ``V4L2_PIX_FMT_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 54b9fe3b7636..fab1dbb1a618 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -558,6 +558,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_X2B10G10R10 v4l2_fourcc('X', 'B', '3', '0') /* 32 XBGR-2-10-10-10 */
+#define V4L2_PIX_FMT_X4B12G12R12 v4l2_fourcc('X', 'B', '3', '6') /* 40 XBGR-4-12-12-12 */
+#define V4L2_PIX_FMT_B16G16R16 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] 35+ messages in thread* Re: [PATCH v2 15/19] media: v4l2: Add 10-, 12- and 16-bpc BGR formats
2020-11-02 22:40 ` [PATCH v2 15/19] media: v4l2: Add 10-, 12- and 16-bpc BGR formats Laurent Pinchart
@ 2020-11-16 12:03 ` Hans Verkuil
2020-11-16 18:10 ` Laurent Pinchart
0 siblings, 1 reply; 35+ messages in thread
From: Hans Verkuil @ 2020-11-16 12:03 UTC (permalink / raw)
To: Laurent Pinchart, linux-media
Cc: Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
On 02/11/2020 23:40, 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>
> ---
> Changes since v1:
>
> - Interleave component names and number of bits
> ---
> .../userspace-api/media/v4l/pixfmt-rgb.rst | 69 +++++++++++++++++++
> include/uapi/linux/videodev2.h | 5 ++
> 2 files changed, 74 insertions(+)
>
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> index 405d6f032078..846d307624fc 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> @@ -1079,6 +1079,75 @@ 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. The component names and the
> +corresponding number of bits are interleaved for clarity.
> +
> +.. 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-X2B10G10R10:
> +
> + - ``V4L2_PIX_FMT_X2B10G10R10``
> + - '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`
Hmm, this is hard to read and understand.
The problem here is the use of '-' to indicate padding (unused) bits.
I was wondering whether it wouldn't be clearer to replace '-' by 'x' (for
an unused bit) or 'X' (for an unused byte) throughout these docs.
So this then becomes: X\ :sub:`1-0`.
It would also nicely correspond to the use of 'X' in the format name.
Regards,
Hans
> +
> + -
> + * .. _V4L2-PIX-FMT-X4B12G12R12:
> +
> + - ``V4L2_PIX_FMT_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-B16G16R16:
> +
> + - ``V4L2_PIX_FMT_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 54b9fe3b7636..fab1dbb1a618 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -558,6 +558,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_X2B10G10R10 v4l2_fourcc('X', 'B', '3', '0') /* 32 XBGR-2-10-10-10 */
> +#define V4L2_PIX_FMT_X4B12G12R12 v4l2_fourcc('X', 'B', '3', '6') /* 40 XBGR-4-12-12-12 */
> +#define V4L2_PIX_FMT_B16G16R16 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] 35+ messages in thread* Re: [PATCH v2 15/19] media: v4l2: Add 10-, 12- and 16-bpc BGR formats
2020-11-16 12:03 ` Hans Verkuil
@ 2020-11-16 18:10 ` Laurent Pinchart
0 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-16 18:10 UTC (permalink / raw)
To: Hans Verkuil
Cc: linux-media, Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Hi Hans,
On Mon, Nov 16, 2020 at 01:03:31PM +0100, Hans Verkuil wrote:
> On 02/11/2020 23:40, 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>
> > ---
> > Changes since v1:
> >
> > - Interleave component names and number of bits
> > ---
> > .../userspace-api/media/v4l/pixfmt-rgb.rst | 69 +++++++++++++++++++
> > include/uapi/linux/videodev2.h | 5 ++
> > 2 files changed, 74 insertions(+)
> >
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > index 405d6f032078..846d307624fc 100644
> > --- a/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt-rgb.rst
> > @@ -1079,6 +1079,75 @@ 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. The component names and the
> > +corresponding number of bits are interleaved for clarity.
> > +
> > +.. 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-X2B10G10R10:
> > +
> > + - ``V4L2_PIX_FMT_X2B10G10R10``
> > + - '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`
>
> Hmm, this is hard to read and understand.
>
> The problem here is the use of '-' to indicate padding (unused) bits.
>
> I was wondering whether it wouldn't be clearer to replace '-' by 'x' (for
> an unused bit) or 'X' (for an unused byte) throughout these docs.
>
> So this then becomes: X\ :sub:`1-0`.
>
> It would also nicely correspond to the use of 'X' in the format name.
OK, I'll do so.
> > +
> > + -
> > + * .. _V4L2-PIX-FMT-X4B12G12R12:
> > +
> > + - ``V4L2_PIX_FMT_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-B16G16R16:
> > +
> > + - ``V4L2_PIX_FMT_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 54b9fe3b7636..fab1dbb1a618 100644
> > --- a/include/uapi/linux/videodev2.h
> > +++ b/include/uapi/linux/videodev2.h
> > @@ -558,6 +558,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_X2B10G10R10 v4l2_fourcc('X', 'B', '3', '0') /* 32 XBGR-2-10-10-10 */
> > +#define V4L2_PIX_FMT_X4B12G12R12 v4l2_fourcc('X', 'B', '3', '6') /* 40 XBGR-4-12-12-12 */
> > +#define V4L2_PIX_FMT_B16G16R16 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] 35+ messages in thread
* [PATCH v2 16/19] media: v4l2: Add a few missing packed YUV 4:4:4 formats
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (14 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 15/19] media: v4l2: Add 10-, 12- and 16-bpc BGR formats Laurent Pinchart
@ 2020-11-02 22:40 ` Laurent Pinchart
2020-11-16 12:25 ` Hans Verkuil
2020-11-02 22:41 ` [PATCH v2 17/19] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats Laurent Pinchart
` (3 subsequent siblings)
19 siblings, 1 reply; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:40 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 8f0f1405bfe3..6824898122aa 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -170,6 +170,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``
@@ -220,6 +229,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 fab1dbb1a618..afe3619bc77c 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -593,11 +593,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] 35+ messages in thread* Re: [PATCH v2 16/19] media: v4l2: Add a few missing packed YUV 4:4:4 formats
2020-11-02 22:40 ` [PATCH v2 16/19] media: v4l2: Add a few missing packed YUV 4:4:4 formats Laurent Pinchart
@ 2020-11-16 12:25 ` Hans Verkuil
0 siblings, 0 replies; 35+ messages in thread
From: Hans Verkuil @ 2020-11-16 12:25 UTC (permalink / raw)
To: Laurent Pinchart, linux-media
Cc: Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
On 02/11/2020 23:40, Laurent Pinchart wrote:
> 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 8f0f1405bfe3..6824898122aa 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
> @@ -170,6 +170,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``
> @@ -220,6 +229,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`
'-' should be A here.
Regards,
Hans
> +
> + * .. _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 fab1dbb1a618..afe3619bc77c 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -593,11 +593,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 */
>
^ permalink raw reply [flat|nested] 35+ messages in thread
* [PATCH v2 17/19] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (15 preceding siblings ...)
2020-11-02 22:40 ` [PATCH v2 16/19] media: v4l2: Add a few missing packed YUV 4:4:4 formats Laurent Pinchart
@ 2020-11-02 22:41 ` Laurent Pinchart
2020-11-02 22:41 ` [PATCH v2 18/19] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing Laurent Pinchart
` (2 subsequent siblings)
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:41 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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>
---
Changes since v1:
- Interleave component names and number of bits
---
.../media/v4l/pixfmt-packed-yuv.rst | 56 +++++++++++++++++++
include/uapi/linux/videodev2.h | 3 +
2 files changed, 59 insertions(+)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
index 6824898122aa..7f66d5ba8cfa 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst
@@ -257,6 +257,62 @@ 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. The component names and the corresponding
+number of bits are interleaved for clarity.
+
+.. 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-X2V10U10Y10:
+
+ - ``V4L2_PIX_FMT_X2V10U10Y10``
+ - '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-X4V12U12Y12:
+
+ - ``V4L2_PIX_FMT_X4V12U12Y12``
+ - '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-V16U16Y16:
+
+ - ``V4L2_PIX_FMT_V16U16Y16``
+ - '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 afe3619bc77c..5cdbd1a2fddb 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -602,6 +602,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_X2V10U10Y10 v4l2_fourcc('V', 'Y', '3', '0') /* 32 XVUY-2-10-10-10 */
+#define V4L2_PIX_FMT_X4V12U12Y12 v4l2_fourcc('V', 'Y', '3', '6') /* 40 XVUY-4-12-12-12 */
+#define V4L2_PIX_FMT_V16U16Y16 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] 35+ messages in thread* [PATCH v2 18/19] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (16 preceding siblings ...)
2020-11-02 22:41 ` [PATCH v2 17/19] media: v4l2: Add 10-, 12- and 16-bpc 4:4:4 packed VUY formats Laurent Pinchart
@ 2020-11-02 22:41 ` Laurent Pinchart
2020-11-02 22:41 ` [PATCH v2 19/19] media: v4l2: Add 10-, 12- and 16-bpc 4:2:0 and 4:2:2 semi-planar YUV formats Laurent Pinchart
2020-11-03 8:57 ` [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Sakari Ailus
19 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:41 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
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 ba8cd895cb0b..7c65d58d9e25 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst
@@ -17,6 +17,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
@@ -75,6 +76,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``
@@ -86,6 +98,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 5cdbd1a2fddb..cf9288d270c6 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -576,6 +576,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] 35+ messages in thread* [PATCH v2 19/19] media: v4l2: Add 10-, 12- and 16-bpc 4:2:0 and 4:2:2 semi-planar YUV formats
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (17 preceding siblings ...)
2020-11-02 22:41 ` [PATCH v2 18/19] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing Laurent Pinchart
@ 2020-11-02 22:41 ` Laurent Pinchart
2020-11-16 12:10 ` Hans Verkuil
2020-11-16 12:17 ` Hans Verkuil
2020-11-03 8:57 ` [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Sakari Ailus
19 siblings, 2 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-02 22:41 UTC (permalink / raw)
To: linux-media
Cc: Sakari Ailus, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Add semi-planar YUV formats with 10, 12 and 16 bits per components, in
both 4:2:0 (NV12) and 4:2:2 (NV16) subsampling, and with both chroma
orderings. 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-planar.rst | 564 +++++++++++++++++-
include/uapi/linux/videodev2.h | 12 +
2 files changed, 575 insertions(+), 1 deletion(-)
diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
index 07081ab05419..7f0fe2e4b668 100644
--- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
+++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
@@ -48,6 +48,11 @@ relationship between the luma and chroma line padding and stride.
All components are stored with the same number of bits per component.
+Formats with more than 8 bits per component pack, within each plane, multiple
+samples in a word (padded as necessary to reach a multiple of 8 bits), which is
+then stored in memory in little endian byte order. They are named with a suffix
+indicating the number of bits per component and the number of samples per word.
+
.. flat-table:: Overview of Semi-Planar YUV Formats
:header-rows: 1
:stub-columns: 0
@@ -145,6 +150,90 @@ All components are stored with the same number of bits per component.
- Cr, Cr
- Yes
- Linear
+ * - V4L2_PIX_FMT_NV12_10_3
+ - 'N012'
+ - 10
+ - 4:2:0
+ - Cb, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV21_10_3
+ - 'N061'
+ - 10
+ - 4:2:0
+ - Cr, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV16_10_3
+ - 'N016'
+ - 10
+ - 4:2:2
+ - Cb, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV61_10_3
+ - 'N061'
+ - 10
+ - 4:2:2
+ - Cr, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV12_12_2
+ - 'N212'
+ - 12
+ - 4:2:0
+ - Cb, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV21_12_2
+ - 'N261'
+ - 12
+ - 4:2:0
+ - Cr, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV16_12_2
+ - 'N216'
+ - 12
+ - 4:2:2
+ - Cb, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV61_12_2
+ - 'N261'
+ - 12
+ - 4:2:2
+ - Cr, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV12_16_1
+ - 'N612'
+ - 16
+ - 4:2:0
+ - Cb, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV21_16_1
+ - 'N661'
+ - 16
+ - 4:2:0
+ - Cr, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV16_16_1
+ - 'N616'
+ - 16
+ - 4:2:2
+ - Cb, Cr
+ - Yes
+ - Linear
+ * - V4L2_PIX_FMT_NV61_16_1
+ - 'N661'
+ - 16
+ - 4:2:2
+ - Cr, Cr
+ - Yes
+ - Linear
.. note::
@@ -153,7 +242,6 @@ All components are stored with the same number of bits per component.
disjoint
.. [3] Macroblock size in pixels
-
**Color Sample Location:**
Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
horizontally.
@@ -463,6 +551,480 @@ number of lines as the luma plane.
- Cr\ :sub:`33`
+.. _V4L2-PIX-FMT-NV12-10-3:
+.. _V4L2-PIX-FMT-NV21-10-3:
+.. _V4L2-PIX-FMT-NV16-10-3:
+.. _V4L2-PIX-FMT-NV61-10-3:
+
+NV12_10_3, NV21_10_3, NV16_10_3 and NV61_10_3
+---------------------------------------------
+
+Semi-planar YUV 4:2:0 and 4:2:2 formats with 10 bits per component, stored with
+3 samples packed in 4 bytes.
+
+Within a plane, 3 samples are packed in a 32-bit word, with 2 padding bits.
+The bits are organized as follows for the first three samples of a luma line
+and a chroma line.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - 31:30
+ - 29:20
+ - 19:10
+ - 9:0
+ * - `-`\ [1:0]
+ - Y'\ :sub:`2`\ [9:0]
+ - Y'\ :sub:`1`\ [9:0]
+ - Y'\ :sub:`0`\ [9:0]
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - 31:30
+ - 29:20
+ - 19:10
+ - 9:0
+ * - `-`\ [1:0]
+ - Cb\ :sub:`2`\ [9:0]
+ - Cr\ :sub:`0`\ [9:0]
+ - Cb\ :sub:`0`\ [9:0]
+
+Words are then stored in memory in little endian format. Due to a chroma word
+storing an odd number of samples, the image width must be a multiple of 6
+pixels.
+
+.. flat-table:: Sample 6x4 NV12_10_3 Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start + 0:
+ - Y'\ :sub:`00`\ [7:0]
+ - Y'\ :sub:`01`\ [5:0] Y'\ :sub:`00`\ [9:8]
+ - Y'\ :sub:`02`\ [3:0] Y'\ :sub:`01`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`02`\ [9:4]
+ - Y'\ :sub:`03`\ [7:0]
+ - Y'\ :sub:`04`\ [5:0] Y'\ :sub:`04`\ [9:8]
+ - Y'\ :sub:`05`\ [3:0] Y'\ :sub:`05`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`05`\ [9:4]
+ * - start + 8:
+ - Y'\ :sub:`10`\ [7:0]
+ - Y'\ :sub:`11`\ [5:0] Y'\ :sub:`10`\ [9:8]
+ - Y'\ :sub:`12`\ [3:0] Y'\ :sub:`11`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`12`\ [9:4]
+ - Y'\ :sub:`13`\ [7:0]
+ - Y'\ :sub:`14`\ [5:0] Y'\ :sub:`14`\ [9:8]
+ - Y'\ :sub:`15`\ [3:0] Y'\ :sub:`15`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`15`\ [9:4]
+ * - start + 16:
+ - Y'\ :sub:`20`\ [7:0]
+ - Y'\ :sub:`21`\ [5:0] Y'\ :sub:`20`\ [9:8]
+ - Y'\ :sub:`22`\ [3:0] Y'\ :sub:`21`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`22`\ [9:4]
+ - Y'\ :sub:`23`\ [7:0]
+ - Y'\ :sub:`24`\ [5:0] Y'\ :sub:`24`\ [9:8]
+ - Y'\ :sub:`25`\ [3:0] Y'\ :sub:`25`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`25`\ [9:4]
+ * - start + 24:
+ - Y'\ :sub:`20`\ [7:0]
+ - Y'\ :sub:`21`\ [5:0] Y'\ :sub:`20`\ [9:8]
+ - Y'\ :sub:`22`\ [3:0] Y'\ :sub:`21`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`22`\ [9:4]
+ - Y'\ :sub:`23`\ [7:0]
+ - Y'\ :sub:`24`\ [5:0] Y'\ :sub:`24`\ [9:8]
+ - Y'\ :sub:`25`\ [3:0] Y'\ :sub:`25`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`25`\ [9:4]
+ * - start + 32:
+ - Cb\ :sub:`00`\ [7:0]
+ - Cr\ :sub:`00`\ [5:0] Cb\ :sub:`00`\ [9:8]
+ - Cb\ :sub:`02`\ [3:0] Cr\ :sub:`00`\ [9:6]
+ - `-`\ [1:0] Cb\ :sub:`02`\ [9:4]
+ - Cr\ :sub:`02`\ [7:0]
+ - Cb\ :sub:`04`\ [5:0] Cr\ :sub:`02`\ [9:8]
+ - Cr\ :sub:`04`\ [3:0] Cb\ :sub:`04`\ [9:6]
+ - `-`\ [1:0] Cr\ :sub:`04`\ [9:4]
+ * - start + 40:
+ - Cb\ :sub:`20`\ [7:0]
+ - Cr\ :sub:`20`\ [5:0] Cb\ :sub:`20`\ [9:8]
+ - Cb\ :sub:`22`\ [3:0] Cr\ :sub:`20`\ [9:6]
+ - `-`\ [1:0] Cb\ :sub:`22`\ [9:4]
+ - Cr\ :sub:`22`\ [7:0]
+ - Cb\ :sub:`24`\ [5:0] Cr\ :sub:`22`\ [9:8]
+ - Cr\ :sub:`24`\ [3:0] Cb\ :sub:`24`\ [9:6]
+ - `-`\ [1:0] Cr\ :sub:`24`\ [9:4]
+
+.. flat-table:: Sample 6x4 NV16_10_3 Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start + 0:
+ - Y'\ :sub:`00`\ [7:0]
+ - Y'\ :sub:`01`\ [5:0] Y'\ :sub:`00`\ [9:8]
+ - Y'\ :sub:`02`\ [3:0] Y'\ :sub:`01`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`02`\ [9:4]
+ - Y'\ :sub:`03`\ [7:0]
+ - Y'\ :sub:`04`\ [5:0] Y'\ :sub:`04`\ [9:8]
+ - Y'\ :sub:`05`\ [3:0] Y'\ :sub:`05`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`05`\ [9:4]
+ * - start + 8:
+ - Y'\ :sub:`10`\ [7:0]
+ - Y'\ :sub:`11`\ [5:0] Y'\ :sub:`10`\ [9:8]
+ - Y'\ :sub:`12`\ [3:0] Y'\ :sub:`11`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`12`\ [9:4]
+ - Y'\ :sub:`13`\ [7:0]
+ - Y'\ :sub:`14`\ [5:0] Y'\ :sub:`14`\ [9:8]
+ - Y'\ :sub:`15`\ [3:0] Y'\ :sub:`15`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`15`\ [9:4]
+ * - start + 16:
+ - Y'\ :sub:`20`\ [7:0]
+ - Y'\ :sub:`21`\ [5:0] Y'\ :sub:`20`\ [9:8]
+ - Y'\ :sub:`22`\ [3:0] Y'\ :sub:`21`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`22`\ [9:4]
+ - Y'\ :sub:`23`\ [7:0]
+ - Y'\ :sub:`24`\ [5:0] Y'\ :sub:`24`\ [9:8]
+ - Y'\ :sub:`25`\ [3:0] Y'\ :sub:`25`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`25`\ [9:4]
+ * - start + 24:
+ - Y'\ :sub:`20`\ [7:0]
+ - Y'\ :sub:`21`\ [5:0] Y'\ :sub:`20`\ [9:8]
+ - Y'\ :sub:`22`\ [3:0] Y'\ :sub:`21`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`22`\ [9:4]
+ - Y'\ :sub:`23`\ [7:0]
+ - Y'\ :sub:`24`\ [5:0] Y'\ :sub:`24`\ [9:8]
+ - Y'\ :sub:`25`\ [3:0] Y'\ :sub:`25`\ [9:6]
+ - `-`\ [1:0] Y'\ :sub:`25`\ [9:4]
+ * - start + 32:
+ - Cb\ :sub:`00`\ [7:0]
+ - Cr\ :sub:`00`\ [5:0] Cb\ :sub:`00`\ [9:8]
+ - Cb\ :sub:`02`\ [3:0] Cr\ :sub:`00`\ [9:6]
+ - `-`\ [1:0] Cb\ :sub:`02`\ [9:4]
+ - Cr\ :sub:`02`\ [7:0]
+ - Cb\ :sub:`04`\ [5:0] Cr\ :sub:`02`\ [9:8]
+ - Cr\ :sub:`04`\ [3:0] Cb\ :sub:`04`\ [9:6]
+ - `-`\ [1:0] Cr\ :sub:`04`\ [9:4]
+ * - start + 40:
+ - Cb\ :sub:`10`\ [7:0]
+ - Cr\ :sub:`10`\ [5:0] Cb\ :sub:`10`\ [9:8]
+ - Cb\ :sub:`12`\ [3:0] Cr\ :sub:`10`\ [9:6]
+ - `-`\ [1:0] Cb\ :sub:`12`\ [9:4]
+ - Cr\ :sub:`12`\ [7:0]
+ - Cb\ :sub:`14`\ [5:0] Cr\ :sub:`12`\ [9:8]
+ - Cr\ :sub:`14`\ [3:0] Cb\ :sub:`14`\ [9:6]
+ - `-`\ [1:0] Cr\ :sub:`14`\ [9:4]
+ * - start + 48:
+ - Cb\ :sub:`20`\ [7:0]
+ - Cr\ :sub:`20`\ [5:0] Cb\ :sub:`20`\ [9:8]
+ - Cb\ :sub:`22`\ [3:0] Cr\ :sub:`20`\ [9:6]
+ - `-`\ [1:0] Cb\ :sub:`22`\ [9:4]
+ - Cr\ :sub:`22`\ [7:0]
+ - Cb\ :sub:`24`\ [5:0] Cr\ :sub:`22`\ [9:8]
+ - Cr\ :sub:`24`\ [3:0] Cb\ :sub:`24`\ [9:6]
+ - `-`\ [1:0] Cr\ :sub:`24`\ [9:4]
+ * - start + 56:
+ - Cb\ :sub:`30`\ [7:0]
+ - Cr\ :sub:`30`\ [5:0] Cb\ :sub:`30`\ [9:8]
+ - Cb\ :sub:`32`\ [3:0] Cr\ :sub:`30`\ [9:6]
+ - `-`\ [1:0] Cb\ :sub:`32`\ [9:4]
+ - Cr\ :sub:`32`\ [7:0]
+ - Cb\ :sub:`34`\ [5:0] Cr\ :sub:`32`\ [9:8]
+ - Cr\ :sub:`34`\ [3:0] Cb\ :sub:`34`\ [9:6]
+ - `-`\ [1:0] Cr\ :sub:`34`\ [9:4]
+
+
+.. _V4L2-PIX-FMT-NV12-12-2:
+.. _V4L2-PIX-FMT-NV21-12-2:
+.. _V4L2-PIX-FMT-NV16-12-2:
+.. _V4L2-PIX-FMT-NV61-12-2:
+
+NV12_12_2, NV21_12_2, NV16_12_2 and NV61_12_2
+---------------------------------------------
+
+Semi-planar YUV 4:2:0 and 4:2:2 formats with 12 bits per component, stored with
+2 samples packed in 3 bytes.
+
+Within a plane, 2 samples are packed in a 24-bit word, with no padding bits.
+The bits are organized as follows for the first two samples of a luma line
+and a chroma line.
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - 23:12
+ - 11:0
+ * - Y'\ :sub:`1`\ [11:0]
+ - Y'\ :sub:`0`\ [11:0]
+
+.. flat-table::
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - 23:12
+ - 11:0
+ * - Cr\ :sub:`0`\ [11:0]
+ - Cb\ :sub:`0`\ [11:0]
+
+Words are then stored in memory in little endian format.
+
+.. flat-table:: Sample 4x4 NV12_12_2 Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start + 0:
+ - Y'\ :sub:`00`\ [7:0]
+ - Y'\ :sub:`01`\ [3:0] Y'\ :sub:`00`\ [11:8]
+ - Y'\ :sub:`01`\ [11:4]
+ - Y'\ :sub:`02`\ [7:0]
+ - Y'\ :sub:`03`\ [3:0] Y'\ :sub:`02`\ [11:8]
+ - Y'\ :sub:`03`\ [11:4]
+ * - start + 6:
+ - Y'\ :sub:`10`\ [7:0]
+ - Y'\ :sub:`11`\ [3:0] Y'\ :sub:`10`\ [11:8]
+ - Y'\ :sub:`11`\ [11:4]
+ - Y'\ :sub:`12`\ [7:0]
+ - Y'\ :sub:`13`\ [3:0] Y'\ :sub:`12`\ [11:8]
+ - Y'\ :sub:`13`\ [11:4]
+ * - start + 12:
+ - Y'\ :sub:`20`\ [7:0]
+ - Y'\ :sub:`21`\ [3:0] Y'\ :sub:`20`\ [11:8]
+ - Y'\ :sub:`21`\ [11:4]
+ - Y'\ :sub:`22`\ [7:0]
+ - Y'\ :sub:`23`\ [3:0] Y'\ :sub:`22`\ [11:8]
+ - Y'\ :sub:`23`\ [11:4]
+ * - start + 18:
+ - Y'\ :sub:`30`\ [7:0]
+ - Y'\ :sub:`31`\ [3:0] Y'\ :sub:`30`\ [11:8]
+ - Y'\ :sub:`31`\ [11:4]
+ - Y'\ :sub:`32`\ [7:0]
+ - Y'\ :sub:`33`\ [3:0] Y'\ :sub:`32`\ [11:8]
+ - Y'\ :sub:`33`\ [11:4]
+ * - start + 24:
+ - Cb\ :sub:`00`\ [7:0]
+ - Cr\ :sub:`00`\ [3:0] Cb\ :sub:`00`\ [11:8]
+ - Cr\ :sub:`00`\ [11:4]
+ - Cb\ :sub:`02`\ [7:0]
+ - Cr\ :sub:`02`\ [3:0] Cb\ :sub:`02`\ [11:8]
+ - Cr\ :sub:`02`\ [11:4]
+ * - start + 30:
+ - Cb\ :sub:`20`\ [7:0]
+ - Cr\ :sub:`20`\ [3:0] Cb\ :sub:`20`\ [11:8]
+ - Cr\ :sub:`20`\ [11:4]
+ - Cb\ :sub:`22`\ [7:0]
+ - Cr\ :sub:`22`\ [3:0] Cb\ :sub:`22`\ [11:8]
+ - Cr\ :sub:`22`\ [11:4]
+
+.. flat-table:: Sample 4x4 NV16_12_2 Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start + 0:
+ - Y'\ :sub:`00`\ [7:0]
+ - Y'\ :sub:`01`\ [3:0] Y'\ :sub:`00`\ [11:8]
+ - Y'\ :sub:`01`\ [11:4]
+ - Y'\ :sub:`02`\ [7:0]
+ - Y'\ :sub:`03`\ [3:0] Y'\ :sub:`02`\ [11:8]
+ - Y'\ :sub:`03`\ [11:4]
+ * - start + 6:
+ - Y'\ :sub:`10`\ [7:0]
+ - Y'\ :sub:`11`\ [3:0] Y'\ :sub:`10`\ [11:8]
+ - Y'\ :sub:`11`\ [11:4]
+ - Y'\ :sub:`12`\ [7:0]
+ - Y'\ :sub:`13`\ [3:0] Y'\ :sub:`12`\ [11:8]
+ - Y'\ :sub:`13`\ [11:4]
+ * - start + 12:
+ - Y'\ :sub:`20`\ [7:0]
+ - Y'\ :sub:`21`\ [3:0] Y'\ :sub:`20`\ [11:8]
+ - Y'\ :sub:`21`\ [11:4]
+ - Y'\ :sub:`22`\ [7:0]
+ - Y'\ :sub:`23`\ [3:0] Y'\ :sub:`22`\ [11:8]
+ - Y'\ :sub:`23`\ [11:4]
+ * - start + 18:
+ - Y'\ :sub:`30`\ [7:0]
+ - Y'\ :sub:`31`\ [3:0] Y'\ :sub:`30`\ [11:8]
+ - Y'\ :sub:`31`\ [11:4]
+ - Y'\ :sub:`32`\ [7:0]
+ - Y'\ :sub:`33`\ [3:0] Y'\ :sub:`32`\ [11:8]
+ - Y'\ :sub:`33`\ [11:4]
+ * - start + 24:
+ - Cb\ :sub:`00`\ [7:0]
+ - Cr\ :sub:`00`\ [3:0] Cb\ :sub:`00`\ [11:8]
+ - Cr\ :sub:`00`\ [11:4]
+ - Cb\ :sub:`02`\ [7:0]
+ - Cr\ :sub:`02`\ [3:0] Cb\ :sub:`02`\ [11:8]
+ - Cr\ :sub:`02`\ [11:4]
+ * - start + 30:
+ - Cb\ :sub:`10`\ [7:0]
+ - Cr\ :sub:`10`\ [3:0] Cb\ :sub:`10`\ [11:8]
+ - Cr\ :sub:`10`\ [11:4]
+ - Cb\ :sub:`12`\ [7:0]
+ - Cr\ :sub:`12`\ [3:0] Cb\ :sub:`12`\ [11:8]
+ - Cr\ :sub:`12`\ [11:4]
+ * - start + 36:
+ - Cb\ :sub:`20`\ [7:0]
+ - Cr\ :sub:`20`\ [3:0] Cb\ :sub:`20`\ [11:8]
+ - Cr\ :sub:`20`\ [11:4]
+ - Cb\ :sub:`22`\ [7:0]
+ - Cr\ :sub:`22`\ [3:0] Cb\ :sub:`22`\ [11:8]
+ - Cr\ :sub:`22`\ [11:4]
+ * - start + 42:
+ - Cb\ :sub:`30`\ [7:0]
+ - Cr\ :sub:`30`\ [3:0] Cb\ :sub:`30`\ [11:8]
+ - Cr\ :sub:`30`\ [11:4]
+ - Cb\ :sub:`32`\ [7:0]
+ - Cr\ :sub:`32`\ [3:0] Cb\ :sub:`32`\ [11:8]
+ - Cr\ :sub:`32`\ [11:4]
+
+
+.. _V4L2-PIX-FMT-NV12-16-1:
+.. _V4L2-PIX-FMT-NV21-16-1:
+.. _V4L2-PIX-FMT-NV16-16-1:
+.. _V4L2-PIX-FMT-NV61-16-1:
+
+NV12_16_1, NV21_16_1, NV16_16_1 and NV61_16_1
+---------------------------------------------
+
+Semi-planar YUV 4:2:0 and 4:2:2 formats with 16 bits per component. 16-bit
+samples are stored in memory in little endian format.
+
+.. flat-table:: Sample 4x4 NV12_16_1 Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start + 0:
+ - Y'\ :sub:`00`\ [7:0]
+ - Y'\ :sub:`00`\ [15:8]
+ - Y'\ :sub:`01`\ [7:0]
+ - Y'\ :sub:`01`\ [15:8]
+ - Y'\ :sub:`02`\ [7:0]
+ - Y'\ :sub:`02`\ [15:8]
+ - Y'\ :sub:`03`\ [7:0]
+ - Y'\ :sub:`03`\ [15:8]
+ * - start + 8:
+ - Y'\ :sub:`10`\ [7:0]
+ - Y'\ :sub:`10`\ [15:8]
+ - Y'\ :sub:`11`\ [7:0]
+ - Y'\ :sub:`11`\ [15:8]
+ - Y'\ :sub:`12`\ [7:0]
+ - Y'\ :sub:`12`\ [15:8]
+ - Y'\ :sub:`13`\ [7:0]
+ - Y'\ :sub:`13`\ [15:8]
+ * - start + 16:
+ - Y'\ :sub:`20`\ [7:0]
+ - Y'\ :sub:`20`\ [15:8]
+ - Y'\ :sub:`21`\ [7:0]
+ - Y'\ :sub:`21`\ [15:8]
+ - Y'\ :sub:`22`\ [7:0]
+ - Y'\ :sub:`22`\ [15:8]
+ - Y'\ :sub:`23`\ [7:0]
+ - Y'\ :sub:`23`\ [15:8]
+ * - start + 24:
+ - Y'\ :sub:`30`\ [7:0]
+ - Y'\ :sub:`30`\ [15:8]
+ - Y'\ :sub:`31`\ [7:0]
+ - Y'\ :sub:`31`\ [15:8]
+ - Y'\ :sub:`32`\ [7:0]
+ - Y'\ :sub:`32`\ [15:8]
+ - Y'\ :sub:`33`\ [7:0]
+ - Y'\ :sub:`33`\ [15:8]
+ * - start + 32:
+ - Cb\ :sub:`00`\ [7:0]
+ - Cb\ :sub:`00`\ [15:8]
+ - Cr\ :sub:`00`\ [7:0]
+ - Cr\ :sub:`00`\ [15:8]
+ - Cb\ :sub:`02`\ [7:0]
+ - Cb\ :sub:`02`\ [15:8]
+ - Cr\ :sub:`02`\ [7:0]
+ - Cr\ :sub:`02`\ [15:8]
+ * - start + 40:
+ - Cb\ :sub:`20`\ [7:0]
+ - Cb\ :sub:`20`\ [15:8]
+ - Cr\ :sub:`20`\ [7:0]
+ - Cr\ :sub:`20`\ [15:8]
+ - Cb\ :sub:`22`\ [7:0]
+ - Cb\ :sub:`22`\ [15:8]
+ - Cr\ :sub:`22`\ [7:0]
+ - Cr\ :sub:`22`\ [15:8]
+
+.. flat-table:: Sample 4x4 NV16_16_1 Image
+ :header-rows: 0
+ :stub-columns: 0
+
+ * - start + 0:
+ - Y'\ :sub:`00`\ [7:0]
+ - Y'\ :sub:`00`\ [15:8]
+ - Y'\ :sub:`01`\ [7:0]
+ - Y'\ :sub:`01`\ [15:8]
+ - Y'\ :sub:`02`\ [7:0]
+ - Y'\ :sub:`02`\ [15:8]
+ - Y'\ :sub:`03`\ [7:0]
+ - Y'\ :sub:`03`\ [15:8]
+ * - start + 8:
+ - Y'\ :sub:`10`\ [7:0]
+ - Y'\ :sub:`10`\ [15:8]
+ - Y'\ :sub:`11`\ [7:0]
+ - Y'\ :sub:`11`\ [15:8]
+ - Y'\ :sub:`12`\ [7:0]
+ - Y'\ :sub:`12`\ [15:8]
+ - Y'\ :sub:`13`\ [7:0]
+ - Y'\ :sub:`13`\ [15:8]
+ * - start + 16:
+ - Y'\ :sub:`20`\ [7:0]
+ - Y'\ :sub:`20`\ [15:8]
+ - Y'\ :sub:`21`\ [7:0]
+ - Y'\ :sub:`21`\ [15:8]
+ - Y'\ :sub:`22`\ [7:0]
+ - Y'\ :sub:`22`\ [15:8]
+ - Y'\ :sub:`23`\ [7:0]
+ - Y'\ :sub:`23`\ [15:8]
+ * - start + 24:
+ - Y'\ :sub:`30`\ [7:0]
+ - Y'\ :sub:`30`\ [15:8]
+ - Y'\ :sub:`31`\ [7:0]
+ - Y'\ :sub:`31`\ [15:8]
+ - Y'\ :sub:`32`\ [7:0]
+ - Y'\ :sub:`32`\ [15:8]
+ - Y'\ :sub:`33`\ [7:0]
+ - Y'\ :sub:`33`\ [15:8]
+ * - start + 32:
+ - Cb\ :sub:`00`\ [7:0]
+ - Cb\ :sub:`00`\ [15:8]
+ - Cr\ :sub:`00`\ [7:0]
+ - Cr\ :sub:`00`\ [15:8]
+ - Cb\ :sub:`02`\ [7:0]
+ - Cb\ :sub:`02`\ [15:8]
+ - Cr\ :sub:`02`\ [7:0]
+ - Cr\ :sub:`02`\ [15:8]
+ * - start + 40:
+ - Cb\ :sub:`10`\ [7:0]
+ - Cb\ :sub:`10`\ [15:8]
+ - Cr\ :sub:`10`\ [7:0]
+ - Cr\ :sub:`10`\ [15:8]
+ - Cb\ :sub:`12`\ [7:0]
+ - Cb\ :sub:`12`\ [15:8]
+ - Cr\ :sub:`12`\ [7:0]
+ - Cr\ :sub:`12`\ [15:8]
+ * - start + 48:
+ - Cb\ :sub:`20`\ [7:0]
+ - Cb\ :sub:`20`\ [15:8]
+ - Cr\ :sub:`20`\ [7:0]
+ - Cr\ :sub:`20`\ [15:8]
+ - Cb\ :sub:`22`\ [7:0]
+ - Cb\ :sub:`22`\ [15:8]
+ - Cr\ :sub:`22`\ [7:0]
+ - Cr\ :sub:`22`\ [15:8]
+ * - start + 56:
+ - Cb\ :sub:`30`\ [7:0]
+ - Cb\ :sub:`30`\ [15:8]
+ - Cr\ :sub:`30`\ [7:0]
+ - Cr\ :sub:`30`\ [15:8]
+ - Cb\ :sub:`32`\ [7:0]
+ - Cb\ :sub:`32`\ [15:8]
+ - Cr\ :sub:`32`\ [7:0]
+ - Cr\ :sub:`32`\ [15:8]
+
+
Fully Planar YUV Formats
========================
diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
index cf9288d270c6..3c4609ff83d6 100644
--- a/include/uapi/linux/videodev2.h
+++ b/include/uapi/linux/videodev2.h
@@ -616,6 +616,18 @@ struct v4l2_pix_format {
#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 */
+#define V4L2_PIX_FMT_NV12_10_3 v4l2_fourcc('N', '0', '1', '2') /* 16 Y/CbCr 4:2:0 10b */
+#define V4L2_PIX_FMT_NV21_10_3 v4l2_fourcc('N', '0', '2', '1') /* 16 Y/CrCb 4:2:0 10b */
+#define V4L2_PIX_FMT_NV16_10_3 v4l2_fourcc('N', '0', '1', '6') /* 64/3 Y/CbCr 4:2:2 10b */
+#define V4L2_PIX_FMT_NV61_10_3 v4l2_fourcc('N', '0', '6', '1') /* 64/3 Y/CrCb 4:2:2 10b */
+#define V4L2_PIX_FMT_NV12_12_2 v4l2_fourcc('N', '2', '1', '2') /* 18 Y/CbCr 4:2:0 12b */
+#define V4L2_PIX_FMT_NV21_12_2 v4l2_fourcc('N', '2', '2', '1') /* 18 Y/CrCb 4:2:0 12b */
+#define V4L2_PIX_FMT_NV16_12_2 v4l2_fourcc('N', '2', '1', '6') /* 24 Y/CbCr 4:2:2 12b */
+#define V4L2_PIX_FMT_NV61_12_2 v4l2_fourcc('N', '2', '6', '1') /* 24 Y/CrCb 4:2:2 12b */
+#define V4L2_PIX_FMT_NV12_16_1 v4l2_fourcc('N', '6', '1', '2') /* 24 Y/CbCr 4:2:0 16b */
+#define V4L2_PIX_FMT_NV21_16_1 v4l2_fourcc('N', '6', '2', '1') /* 24 Y/CrCb 4:2:0 16b */
+#define V4L2_PIX_FMT_NV16_16_1 v4l2_fourcc('N', '6', '1', '6') /* 32 Y/CbCr 4:2:2 16b */
+#define V4L2_PIX_FMT_NV61_16_1 v4l2_fourcc('N', '6', '6', '1') /* 32 Y/CrCb 4:2:2 16b */
/* 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] 35+ messages in thread* Re: [PATCH v2 19/19] media: v4l2: Add 10-, 12- and 16-bpc 4:2:0 and 4:2:2 semi-planar YUV formats
2020-11-02 22:41 ` [PATCH v2 19/19] media: v4l2: Add 10-, 12- and 16-bpc 4:2:0 and 4:2:2 semi-planar YUV formats Laurent Pinchart
@ 2020-11-16 12:10 ` Hans Verkuil
2020-11-16 12:17 ` Hans Verkuil
1 sibling, 0 replies; 35+ messages in thread
From: Hans Verkuil @ 2020-11-16 12:10 UTC (permalink / raw)
To: Laurent Pinchart, linux-media
Cc: Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
On 02/11/2020 23:41, Laurent Pinchart wrote:
> Add semi-planar YUV formats with 10, 12 and 16 bits per components, in
> both 4:2:0 (NV12) and 4:2:2 (NV16) subsampling, and with both chroma
> orderings. 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-planar.rst | 564 +++++++++++++++++-
> include/uapi/linux/videodev2.h | 12 +
> 2 files changed, 575 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> index 07081ab05419..7f0fe2e4b668 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> @@ -48,6 +48,11 @@ relationship between the luma and chroma line padding and stride.
>
> All components are stored with the same number of bits per component.
>
> +Formats with more than 8 bits per component pack, within each plane, multiple
> +samples in a word (padded as necessary to reach a multiple of 8 bits), which is
> +then stored in memory in little endian byte order. They are named with a suffix
> +indicating the number of bits per component and the number of samples per word.
> +
> .. flat-table:: Overview of Semi-Planar YUV Formats
> :header-rows: 1
> :stub-columns: 0
> @@ -145,6 +150,90 @@ All components are stored with the same number of bits per component.
> - Cr, Cr
> - Yes
> - Linear
> + * - V4L2_PIX_FMT_NV12_10_3
> + - 'N012'
> + - 10
> + - 4:2:0
> + - Cb, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV21_10_3
> + - 'N061'
> + - 10
> + - 4:2:0
> + - Cr, Cr
Should be: Cr, Cb
This happens in several places, just do a search-and-replace.
Regards,
Hans
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV16_10_3
> + - 'N016'
> + - 10
> + - 4:2:2
> + - Cb, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV61_10_3
> + - 'N061'
> + - 10
> + - 4:2:2
> + - Cr, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV12_12_2
> + - 'N212'
> + - 12
> + - 4:2:0
> + - Cb, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV21_12_2
> + - 'N261'
> + - 12
> + - 4:2:0
> + - Cr, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV16_12_2
> + - 'N216'
> + - 12
> + - 4:2:2
> + - Cb, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV61_12_2
> + - 'N261'
> + - 12
> + - 4:2:2
> + - Cr, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV12_16_1
> + - 'N612'
> + - 16
> + - 4:2:0
> + - Cb, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV21_16_1
> + - 'N661'
> + - 16
> + - 4:2:0
> + - Cr, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV16_16_1
> + - 'N616'
> + - 16
> + - 4:2:2
> + - Cb, Cr
> + - Yes
> + - Linear
> + * - V4L2_PIX_FMT_NV61_16_1
> + - 'N661'
> + - 16
> + - 4:2:2
> + - Cr, Cr
> + - Yes
> + - Linear
>
> .. note::
>
> @@ -153,7 +242,6 @@ All components are stored with the same number of bits per component.
> disjoint
> .. [3] Macroblock size in pixels
>
> -
> **Color Sample Location:**
> Chroma samples are :ref:`interstitially sited<yuv-chroma-centered>`
> horizontally.
> @@ -463,6 +551,480 @@ number of lines as the luma plane.
> - Cr\ :sub:`33`
>
>
> +.. _V4L2-PIX-FMT-NV12-10-3:
> +.. _V4L2-PIX-FMT-NV21-10-3:
> +.. _V4L2-PIX-FMT-NV16-10-3:
> +.. _V4L2-PIX-FMT-NV61-10-3:
> +
> +NV12_10_3, NV21_10_3, NV16_10_3 and NV61_10_3
> +---------------------------------------------
> +
> +Semi-planar YUV 4:2:0 and 4:2:2 formats with 10 bits per component, stored with
> +3 samples packed in 4 bytes.
> +
> +Within a plane, 3 samples are packed in a 32-bit word, with 2 padding bits.
> +The bits are organized as follows for the first three samples of a luma line
> +and a chroma line.
> +
> +.. flat-table::
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - 31:30
> + - 29:20
> + - 19:10
> + - 9:0
> + * - `-`\ [1:0]
> + - Y'\ :sub:`2`\ [9:0]
> + - Y'\ :sub:`1`\ [9:0]
> + - Y'\ :sub:`0`\ [9:0]
> +
> +.. flat-table::
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - 31:30
> + - 29:20
> + - 19:10
> + - 9:0
> + * - `-`\ [1:0]
> + - Cb\ :sub:`2`\ [9:0]
> + - Cr\ :sub:`0`\ [9:0]
> + - Cb\ :sub:`0`\ [9:0]
> +
> +Words are then stored in memory in little endian format. Due to a chroma word
> +storing an odd number of samples, the image width must be a multiple of 6
> +pixels.
> +
> +.. flat-table:: Sample 6x4 NV12_10_3 Image
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - start + 0:
> + - Y'\ :sub:`00`\ [7:0]
> + - Y'\ :sub:`01`\ [5:0] Y'\ :sub:`00`\ [9:8]
> + - Y'\ :sub:`02`\ [3:0] Y'\ :sub:`01`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`02`\ [9:4]
> + - Y'\ :sub:`03`\ [7:0]
> + - Y'\ :sub:`04`\ [5:0] Y'\ :sub:`04`\ [9:8]
> + - Y'\ :sub:`05`\ [3:0] Y'\ :sub:`05`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`05`\ [9:4]
> + * - start + 8:
> + - Y'\ :sub:`10`\ [7:0]
> + - Y'\ :sub:`11`\ [5:0] Y'\ :sub:`10`\ [9:8]
> + - Y'\ :sub:`12`\ [3:0] Y'\ :sub:`11`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`12`\ [9:4]
> + - Y'\ :sub:`13`\ [7:0]
> + - Y'\ :sub:`14`\ [5:0] Y'\ :sub:`14`\ [9:8]
> + - Y'\ :sub:`15`\ [3:0] Y'\ :sub:`15`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`15`\ [9:4]
> + * - start + 16:
> + - Y'\ :sub:`20`\ [7:0]
> + - Y'\ :sub:`21`\ [5:0] Y'\ :sub:`20`\ [9:8]
> + - Y'\ :sub:`22`\ [3:0] Y'\ :sub:`21`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`22`\ [9:4]
> + - Y'\ :sub:`23`\ [7:0]
> + - Y'\ :sub:`24`\ [5:0] Y'\ :sub:`24`\ [9:8]
> + - Y'\ :sub:`25`\ [3:0] Y'\ :sub:`25`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`25`\ [9:4]
> + * - start + 24:
> + - Y'\ :sub:`20`\ [7:0]
> + - Y'\ :sub:`21`\ [5:0] Y'\ :sub:`20`\ [9:8]
> + - Y'\ :sub:`22`\ [3:0] Y'\ :sub:`21`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`22`\ [9:4]
> + - Y'\ :sub:`23`\ [7:0]
> + - Y'\ :sub:`24`\ [5:0] Y'\ :sub:`24`\ [9:8]
> + - Y'\ :sub:`25`\ [3:0] Y'\ :sub:`25`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`25`\ [9:4]
> + * - start + 32:
> + - Cb\ :sub:`00`\ [7:0]
> + - Cr\ :sub:`00`\ [5:0] Cb\ :sub:`00`\ [9:8]
> + - Cb\ :sub:`02`\ [3:0] Cr\ :sub:`00`\ [9:6]
> + - `-`\ [1:0] Cb\ :sub:`02`\ [9:4]
> + - Cr\ :sub:`02`\ [7:0]
> + - Cb\ :sub:`04`\ [5:0] Cr\ :sub:`02`\ [9:8]
> + - Cr\ :sub:`04`\ [3:0] Cb\ :sub:`04`\ [9:6]
> + - `-`\ [1:0] Cr\ :sub:`04`\ [9:4]
> + * - start + 40:
> + - Cb\ :sub:`20`\ [7:0]
> + - Cr\ :sub:`20`\ [5:0] Cb\ :sub:`20`\ [9:8]
> + - Cb\ :sub:`22`\ [3:0] Cr\ :sub:`20`\ [9:6]
> + - `-`\ [1:0] Cb\ :sub:`22`\ [9:4]
> + - Cr\ :sub:`22`\ [7:0]
> + - Cb\ :sub:`24`\ [5:0] Cr\ :sub:`22`\ [9:8]
> + - Cr\ :sub:`24`\ [3:0] Cb\ :sub:`24`\ [9:6]
> + - `-`\ [1:0] Cr\ :sub:`24`\ [9:4]
> +
> +.. flat-table:: Sample 6x4 NV16_10_3 Image
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - start + 0:
> + - Y'\ :sub:`00`\ [7:0]
> + - Y'\ :sub:`01`\ [5:0] Y'\ :sub:`00`\ [9:8]
> + - Y'\ :sub:`02`\ [3:0] Y'\ :sub:`01`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`02`\ [9:4]
> + - Y'\ :sub:`03`\ [7:0]
> + - Y'\ :sub:`04`\ [5:0] Y'\ :sub:`04`\ [9:8]
> + - Y'\ :sub:`05`\ [3:0] Y'\ :sub:`05`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`05`\ [9:4]
> + * - start + 8:
> + - Y'\ :sub:`10`\ [7:0]
> + - Y'\ :sub:`11`\ [5:0] Y'\ :sub:`10`\ [9:8]
> + - Y'\ :sub:`12`\ [3:0] Y'\ :sub:`11`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`12`\ [9:4]
> + - Y'\ :sub:`13`\ [7:0]
> + - Y'\ :sub:`14`\ [5:0] Y'\ :sub:`14`\ [9:8]
> + - Y'\ :sub:`15`\ [3:0] Y'\ :sub:`15`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`15`\ [9:4]
> + * - start + 16:
> + - Y'\ :sub:`20`\ [7:0]
> + - Y'\ :sub:`21`\ [5:0] Y'\ :sub:`20`\ [9:8]
> + - Y'\ :sub:`22`\ [3:0] Y'\ :sub:`21`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`22`\ [9:4]
> + - Y'\ :sub:`23`\ [7:0]
> + - Y'\ :sub:`24`\ [5:0] Y'\ :sub:`24`\ [9:8]
> + - Y'\ :sub:`25`\ [3:0] Y'\ :sub:`25`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`25`\ [9:4]
> + * - start + 24:
> + - Y'\ :sub:`20`\ [7:0]
> + - Y'\ :sub:`21`\ [5:0] Y'\ :sub:`20`\ [9:8]
> + - Y'\ :sub:`22`\ [3:0] Y'\ :sub:`21`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`22`\ [9:4]
> + - Y'\ :sub:`23`\ [7:0]
> + - Y'\ :sub:`24`\ [5:0] Y'\ :sub:`24`\ [9:8]
> + - Y'\ :sub:`25`\ [3:0] Y'\ :sub:`25`\ [9:6]
> + - `-`\ [1:0] Y'\ :sub:`25`\ [9:4]
> + * - start + 32:
> + - Cb\ :sub:`00`\ [7:0]
> + - Cr\ :sub:`00`\ [5:0] Cb\ :sub:`00`\ [9:8]
> + - Cb\ :sub:`02`\ [3:0] Cr\ :sub:`00`\ [9:6]
> + - `-`\ [1:0] Cb\ :sub:`02`\ [9:4]
> + - Cr\ :sub:`02`\ [7:0]
> + - Cb\ :sub:`04`\ [5:0] Cr\ :sub:`02`\ [9:8]
> + - Cr\ :sub:`04`\ [3:0] Cb\ :sub:`04`\ [9:6]
> + - `-`\ [1:0] Cr\ :sub:`04`\ [9:4]
> + * - start + 40:
> + - Cb\ :sub:`10`\ [7:0]
> + - Cr\ :sub:`10`\ [5:0] Cb\ :sub:`10`\ [9:8]
> + - Cb\ :sub:`12`\ [3:0] Cr\ :sub:`10`\ [9:6]
> + - `-`\ [1:0] Cb\ :sub:`12`\ [9:4]
> + - Cr\ :sub:`12`\ [7:0]
> + - Cb\ :sub:`14`\ [5:0] Cr\ :sub:`12`\ [9:8]
> + - Cr\ :sub:`14`\ [3:0] Cb\ :sub:`14`\ [9:6]
> + - `-`\ [1:0] Cr\ :sub:`14`\ [9:4]
> + * - start + 48:
> + - Cb\ :sub:`20`\ [7:0]
> + - Cr\ :sub:`20`\ [5:0] Cb\ :sub:`20`\ [9:8]
> + - Cb\ :sub:`22`\ [3:0] Cr\ :sub:`20`\ [9:6]
> + - `-`\ [1:0] Cb\ :sub:`22`\ [9:4]
> + - Cr\ :sub:`22`\ [7:0]
> + - Cb\ :sub:`24`\ [5:0] Cr\ :sub:`22`\ [9:8]
> + - Cr\ :sub:`24`\ [3:0] Cb\ :sub:`24`\ [9:6]
> + - `-`\ [1:0] Cr\ :sub:`24`\ [9:4]
> + * - start + 56:
> + - Cb\ :sub:`30`\ [7:0]
> + - Cr\ :sub:`30`\ [5:0] Cb\ :sub:`30`\ [9:8]
> + - Cb\ :sub:`32`\ [3:0] Cr\ :sub:`30`\ [9:6]
> + - `-`\ [1:0] Cb\ :sub:`32`\ [9:4]
> + - Cr\ :sub:`32`\ [7:0]
> + - Cb\ :sub:`34`\ [5:0] Cr\ :sub:`32`\ [9:8]
> + - Cr\ :sub:`34`\ [3:0] Cb\ :sub:`34`\ [9:6]
> + - `-`\ [1:0] Cr\ :sub:`34`\ [9:4]
> +
> +
> +.. _V4L2-PIX-FMT-NV12-12-2:
> +.. _V4L2-PIX-FMT-NV21-12-2:
> +.. _V4L2-PIX-FMT-NV16-12-2:
> +.. _V4L2-PIX-FMT-NV61-12-2:
> +
> +NV12_12_2, NV21_12_2, NV16_12_2 and NV61_12_2
> +---------------------------------------------
> +
> +Semi-planar YUV 4:2:0 and 4:2:2 formats with 12 bits per component, stored with
> +2 samples packed in 3 bytes.
> +
> +Within a plane, 2 samples are packed in a 24-bit word, with no padding bits.
> +The bits are organized as follows for the first two samples of a luma line
> +and a chroma line.
> +
> +.. flat-table::
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - 23:12
> + - 11:0
> + * - Y'\ :sub:`1`\ [11:0]
> + - Y'\ :sub:`0`\ [11:0]
> +
> +.. flat-table::
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - 23:12
> + - 11:0
> + * - Cr\ :sub:`0`\ [11:0]
> + - Cb\ :sub:`0`\ [11:0]
> +
> +Words are then stored in memory in little endian format.
> +
> +.. flat-table:: Sample 4x4 NV12_12_2 Image
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - start + 0:
> + - Y'\ :sub:`00`\ [7:0]
> + - Y'\ :sub:`01`\ [3:0] Y'\ :sub:`00`\ [11:8]
> + - Y'\ :sub:`01`\ [11:4]
> + - Y'\ :sub:`02`\ [7:0]
> + - Y'\ :sub:`03`\ [3:0] Y'\ :sub:`02`\ [11:8]
> + - Y'\ :sub:`03`\ [11:4]
> + * - start + 6:
> + - Y'\ :sub:`10`\ [7:0]
> + - Y'\ :sub:`11`\ [3:0] Y'\ :sub:`10`\ [11:8]
> + - Y'\ :sub:`11`\ [11:4]
> + - Y'\ :sub:`12`\ [7:0]
> + - Y'\ :sub:`13`\ [3:0] Y'\ :sub:`12`\ [11:8]
> + - Y'\ :sub:`13`\ [11:4]
> + * - start + 12:
> + - Y'\ :sub:`20`\ [7:0]
> + - Y'\ :sub:`21`\ [3:0] Y'\ :sub:`20`\ [11:8]
> + - Y'\ :sub:`21`\ [11:4]
> + - Y'\ :sub:`22`\ [7:0]
> + - Y'\ :sub:`23`\ [3:0] Y'\ :sub:`22`\ [11:8]
> + - Y'\ :sub:`23`\ [11:4]
> + * - start + 18:
> + - Y'\ :sub:`30`\ [7:0]
> + - Y'\ :sub:`31`\ [3:0] Y'\ :sub:`30`\ [11:8]
> + - Y'\ :sub:`31`\ [11:4]
> + - Y'\ :sub:`32`\ [7:0]
> + - Y'\ :sub:`33`\ [3:0] Y'\ :sub:`32`\ [11:8]
> + - Y'\ :sub:`33`\ [11:4]
> + * - start + 24:
> + - Cb\ :sub:`00`\ [7:0]
> + - Cr\ :sub:`00`\ [3:0] Cb\ :sub:`00`\ [11:8]
> + - Cr\ :sub:`00`\ [11:4]
> + - Cb\ :sub:`02`\ [7:0]
> + - Cr\ :sub:`02`\ [3:0] Cb\ :sub:`02`\ [11:8]
> + - Cr\ :sub:`02`\ [11:4]
> + * - start + 30:
> + - Cb\ :sub:`20`\ [7:0]
> + - Cr\ :sub:`20`\ [3:0] Cb\ :sub:`20`\ [11:8]
> + - Cr\ :sub:`20`\ [11:4]
> + - Cb\ :sub:`22`\ [7:0]
> + - Cr\ :sub:`22`\ [3:0] Cb\ :sub:`22`\ [11:8]
> + - Cr\ :sub:`22`\ [11:4]
> +
> +.. flat-table:: Sample 4x4 NV16_12_2 Image
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - start + 0:
> + - Y'\ :sub:`00`\ [7:0]
> + - Y'\ :sub:`01`\ [3:0] Y'\ :sub:`00`\ [11:8]
> + - Y'\ :sub:`01`\ [11:4]
> + - Y'\ :sub:`02`\ [7:0]
> + - Y'\ :sub:`03`\ [3:0] Y'\ :sub:`02`\ [11:8]
> + - Y'\ :sub:`03`\ [11:4]
> + * - start + 6:
> + - Y'\ :sub:`10`\ [7:0]
> + - Y'\ :sub:`11`\ [3:0] Y'\ :sub:`10`\ [11:8]
> + - Y'\ :sub:`11`\ [11:4]
> + - Y'\ :sub:`12`\ [7:0]
> + - Y'\ :sub:`13`\ [3:0] Y'\ :sub:`12`\ [11:8]
> + - Y'\ :sub:`13`\ [11:4]
> + * - start + 12:
> + - Y'\ :sub:`20`\ [7:0]
> + - Y'\ :sub:`21`\ [3:0] Y'\ :sub:`20`\ [11:8]
> + - Y'\ :sub:`21`\ [11:4]
> + - Y'\ :sub:`22`\ [7:0]
> + - Y'\ :sub:`23`\ [3:0] Y'\ :sub:`22`\ [11:8]
> + - Y'\ :sub:`23`\ [11:4]
> + * - start + 18:
> + - Y'\ :sub:`30`\ [7:0]
> + - Y'\ :sub:`31`\ [3:0] Y'\ :sub:`30`\ [11:8]
> + - Y'\ :sub:`31`\ [11:4]
> + - Y'\ :sub:`32`\ [7:0]
> + - Y'\ :sub:`33`\ [3:0] Y'\ :sub:`32`\ [11:8]
> + - Y'\ :sub:`33`\ [11:4]
> + * - start + 24:
> + - Cb\ :sub:`00`\ [7:0]
> + - Cr\ :sub:`00`\ [3:0] Cb\ :sub:`00`\ [11:8]
> + - Cr\ :sub:`00`\ [11:4]
> + - Cb\ :sub:`02`\ [7:0]
> + - Cr\ :sub:`02`\ [3:0] Cb\ :sub:`02`\ [11:8]
> + - Cr\ :sub:`02`\ [11:4]
> + * - start + 30:
> + - Cb\ :sub:`10`\ [7:0]
> + - Cr\ :sub:`10`\ [3:0] Cb\ :sub:`10`\ [11:8]
> + - Cr\ :sub:`10`\ [11:4]
> + - Cb\ :sub:`12`\ [7:0]
> + - Cr\ :sub:`12`\ [3:0] Cb\ :sub:`12`\ [11:8]
> + - Cr\ :sub:`12`\ [11:4]
> + * - start + 36:
> + - Cb\ :sub:`20`\ [7:0]
> + - Cr\ :sub:`20`\ [3:0] Cb\ :sub:`20`\ [11:8]
> + - Cr\ :sub:`20`\ [11:4]
> + - Cb\ :sub:`22`\ [7:0]
> + - Cr\ :sub:`22`\ [3:0] Cb\ :sub:`22`\ [11:8]
> + - Cr\ :sub:`22`\ [11:4]
> + * - start + 42:
> + - Cb\ :sub:`30`\ [7:0]
> + - Cr\ :sub:`30`\ [3:0] Cb\ :sub:`30`\ [11:8]
> + - Cr\ :sub:`30`\ [11:4]
> + - Cb\ :sub:`32`\ [7:0]
> + - Cr\ :sub:`32`\ [3:0] Cb\ :sub:`32`\ [11:8]
> + - Cr\ :sub:`32`\ [11:4]
> +
> +
> +.. _V4L2-PIX-FMT-NV12-16-1:
> +.. _V4L2-PIX-FMT-NV21-16-1:
> +.. _V4L2-PIX-FMT-NV16-16-1:
> +.. _V4L2-PIX-FMT-NV61-16-1:
> +
> +NV12_16_1, NV21_16_1, NV16_16_1 and NV61_16_1
> +---------------------------------------------
> +
> +Semi-planar YUV 4:2:0 and 4:2:2 formats with 16 bits per component. 16-bit
> +samples are stored in memory in little endian format.
> +
> +.. flat-table:: Sample 4x4 NV12_16_1 Image
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - start + 0:
> + - Y'\ :sub:`00`\ [7:0]
> + - Y'\ :sub:`00`\ [15:8]
> + - Y'\ :sub:`01`\ [7:0]
> + - Y'\ :sub:`01`\ [15:8]
> + - Y'\ :sub:`02`\ [7:0]
> + - Y'\ :sub:`02`\ [15:8]
> + - Y'\ :sub:`03`\ [7:0]
> + - Y'\ :sub:`03`\ [15:8]
> + * - start + 8:
> + - Y'\ :sub:`10`\ [7:0]
> + - Y'\ :sub:`10`\ [15:8]
> + - Y'\ :sub:`11`\ [7:0]
> + - Y'\ :sub:`11`\ [15:8]
> + - Y'\ :sub:`12`\ [7:0]
> + - Y'\ :sub:`12`\ [15:8]
> + - Y'\ :sub:`13`\ [7:0]
> + - Y'\ :sub:`13`\ [15:8]
> + * - start + 16:
> + - Y'\ :sub:`20`\ [7:0]
> + - Y'\ :sub:`20`\ [15:8]
> + - Y'\ :sub:`21`\ [7:0]
> + - Y'\ :sub:`21`\ [15:8]
> + - Y'\ :sub:`22`\ [7:0]
> + - Y'\ :sub:`22`\ [15:8]
> + - Y'\ :sub:`23`\ [7:0]
> + - Y'\ :sub:`23`\ [15:8]
> + * - start + 24:
> + - Y'\ :sub:`30`\ [7:0]
> + - Y'\ :sub:`30`\ [15:8]
> + - Y'\ :sub:`31`\ [7:0]
> + - Y'\ :sub:`31`\ [15:8]
> + - Y'\ :sub:`32`\ [7:0]
> + - Y'\ :sub:`32`\ [15:8]
> + - Y'\ :sub:`33`\ [7:0]
> + - Y'\ :sub:`33`\ [15:8]
> + * - start + 32:
> + - Cb\ :sub:`00`\ [7:0]
> + - Cb\ :sub:`00`\ [15:8]
> + - Cr\ :sub:`00`\ [7:0]
> + - Cr\ :sub:`00`\ [15:8]
> + - Cb\ :sub:`02`\ [7:0]
> + - Cb\ :sub:`02`\ [15:8]
> + - Cr\ :sub:`02`\ [7:0]
> + - Cr\ :sub:`02`\ [15:8]
> + * - start + 40:
> + - Cb\ :sub:`20`\ [7:0]
> + - Cb\ :sub:`20`\ [15:8]
> + - Cr\ :sub:`20`\ [7:0]
> + - Cr\ :sub:`20`\ [15:8]
> + - Cb\ :sub:`22`\ [7:0]
> + - Cb\ :sub:`22`\ [15:8]
> + - Cr\ :sub:`22`\ [7:0]
> + - Cr\ :sub:`22`\ [15:8]
> +
> +.. flat-table:: Sample 4x4 NV16_16_1 Image
> + :header-rows: 0
> + :stub-columns: 0
> +
> + * - start + 0:
> + - Y'\ :sub:`00`\ [7:0]
> + - Y'\ :sub:`00`\ [15:8]
> + - Y'\ :sub:`01`\ [7:0]
> + - Y'\ :sub:`01`\ [15:8]
> + - Y'\ :sub:`02`\ [7:0]
> + - Y'\ :sub:`02`\ [15:8]
> + - Y'\ :sub:`03`\ [7:0]
> + - Y'\ :sub:`03`\ [15:8]
> + * - start + 8:
> + - Y'\ :sub:`10`\ [7:0]
> + - Y'\ :sub:`10`\ [15:8]
> + - Y'\ :sub:`11`\ [7:0]
> + - Y'\ :sub:`11`\ [15:8]
> + - Y'\ :sub:`12`\ [7:0]
> + - Y'\ :sub:`12`\ [15:8]
> + - Y'\ :sub:`13`\ [7:0]
> + - Y'\ :sub:`13`\ [15:8]
> + * - start + 16:
> + - Y'\ :sub:`20`\ [7:0]
> + - Y'\ :sub:`20`\ [15:8]
> + - Y'\ :sub:`21`\ [7:0]
> + - Y'\ :sub:`21`\ [15:8]
> + - Y'\ :sub:`22`\ [7:0]
> + - Y'\ :sub:`22`\ [15:8]
> + - Y'\ :sub:`23`\ [7:0]
> + - Y'\ :sub:`23`\ [15:8]
> + * - start + 24:
> + - Y'\ :sub:`30`\ [7:0]
> + - Y'\ :sub:`30`\ [15:8]
> + - Y'\ :sub:`31`\ [7:0]
> + - Y'\ :sub:`31`\ [15:8]
> + - Y'\ :sub:`32`\ [7:0]
> + - Y'\ :sub:`32`\ [15:8]
> + - Y'\ :sub:`33`\ [7:0]
> + - Y'\ :sub:`33`\ [15:8]
> + * - start + 32:
> + - Cb\ :sub:`00`\ [7:0]
> + - Cb\ :sub:`00`\ [15:8]
> + - Cr\ :sub:`00`\ [7:0]
> + - Cr\ :sub:`00`\ [15:8]
> + - Cb\ :sub:`02`\ [7:0]
> + - Cb\ :sub:`02`\ [15:8]
> + - Cr\ :sub:`02`\ [7:0]
> + - Cr\ :sub:`02`\ [15:8]
> + * - start + 40:
> + - Cb\ :sub:`10`\ [7:0]
> + - Cb\ :sub:`10`\ [15:8]
> + - Cr\ :sub:`10`\ [7:0]
> + - Cr\ :sub:`10`\ [15:8]
> + - Cb\ :sub:`12`\ [7:0]
> + - Cb\ :sub:`12`\ [15:8]
> + - Cr\ :sub:`12`\ [7:0]
> + - Cr\ :sub:`12`\ [15:8]
> + * - start + 48:
> + - Cb\ :sub:`20`\ [7:0]
> + - Cb\ :sub:`20`\ [15:8]
> + - Cr\ :sub:`20`\ [7:0]
> + - Cr\ :sub:`20`\ [15:8]
> + - Cb\ :sub:`22`\ [7:0]
> + - Cb\ :sub:`22`\ [15:8]
> + - Cr\ :sub:`22`\ [7:0]
> + - Cr\ :sub:`22`\ [15:8]
> + * - start + 56:
> + - Cb\ :sub:`30`\ [7:0]
> + - Cb\ :sub:`30`\ [15:8]
> + - Cr\ :sub:`30`\ [7:0]
> + - Cr\ :sub:`30`\ [15:8]
> + - Cb\ :sub:`32`\ [7:0]
> + - Cb\ :sub:`32`\ [15:8]
> + - Cr\ :sub:`32`\ [7:0]
> + - Cr\ :sub:`32`\ [15:8]
> +
> +
> Fully Planar YUV Formats
> ========================
>
> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h
> index cf9288d270c6..3c4609ff83d6 100644
> --- a/include/uapi/linux/videodev2.h
> +++ b/include/uapi/linux/videodev2.h
> @@ -616,6 +616,18 @@ struct v4l2_pix_format {
> #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 */
> +#define V4L2_PIX_FMT_NV12_10_3 v4l2_fourcc('N', '0', '1', '2') /* 16 Y/CbCr 4:2:0 10b */
> +#define V4L2_PIX_FMT_NV21_10_3 v4l2_fourcc('N', '0', '2', '1') /* 16 Y/CrCb 4:2:0 10b */
> +#define V4L2_PIX_FMT_NV16_10_3 v4l2_fourcc('N', '0', '1', '6') /* 64/3 Y/CbCr 4:2:2 10b */
> +#define V4L2_PIX_FMT_NV61_10_3 v4l2_fourcc('N', '0', '6', '1') /* 64/3 Y/CrCb 4:2:2 10b */
> +#define V4L2_PIX_FMT_NV12_12_2 v4l2_fourcc('N', '2', '1', '2') /* 18 Y/CbCr 4:2:0 12b */
> +#define V4L2_PIX_FMT_NV21_12_2 v4l2_fourcc('N', '2', '2', '1') /* 18 Y/CrCb 4:2:0 12b */
> +#define V4L2_PIX_FMT_NV16_12_2 v4l2_fourcc('N', '2', '1', '6') /* 24 Y/CbCr 4:2:2 12b */
> +#define V4L2_PIX_FMT_NV61_12_2 v4l2_fourcc('N', '2', '6', '1') /* 24 Y/CrCb 4:2:2 12b */
> +#define V4L2_PIX_FMT_NV12_16_1 v4l2_fourcc('N', '6', '1', '2') /* 24 Y/CbCr 4:2:0 16b */
> +#define V4L2_PIX_FMT_NV21_16_1 v4l2_fourcc('N', '6', '2', '1') /* 24 Y/CrCb 4:2:0 16b */
> +#define V4L2_PIX_FMT_NV16_16_1 v4l2_fourcc('N', '6', '1', '6') /* 32 Y/CbCr 4:2:2 16b */
> +#define V4L2_PIX_FMT_NV61_16_1 v4l2_fourcc('N', '6', '6', '1') /* 32 Y/CrCb 4:2:2 16b */
>
> /* 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 */
>
^ permalink raw reply [flat|nested] 35+ messages in thread* Re: [PATCH v2 19/19] media: v4l2: Add 10-, 12- and 16-bpc 4:2:0 and 4:2:2 semi-planar YUV formats
2020-11-02 22:41 ` [PATCH v2 19/19] media: v4l2: Add 10-, 12- and 16-bpc 4:2:0 and 4:2:2 semi-planar YUV formats Laurent Pinchart
2020-11-16 12:10 ` Hans Verkuil
@ 2020-11-16 12:17 ` Hans Verkuil
2020-11-16 18:41 ` Laurent Pinchart
1 sibling, 1 reply; 35+ messages in thread
From: Hans Verkuil @ 2020-11-16 12:17 UTC (permalink / raw)
To: Laurent Pinchart, linux-media
Cc: Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
On 02/11/2020 23:41, Laurent Pinchart wrote:
> Add semi-planar YUV formats with 10, 12 and 16 bits per components, in
> both 4:2:0 (NV12) and 4:2:2 (NV16) subsampling, and with both chroma
> orderings. 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-planar.rst | 564 +++++++++++++++++-
> include/uapi/linux/videodev2.h | 12 +
> 2 files changed, 575 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> index 07081ab05419..7f0fe2e4b668 100644
> --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
<snip>
> Fully Planar YUV Formats
> ========================
>
I found a mistake in the "Overview of Fully Planar YUV Formats" table:
For formats V4L2_PIX_FMT_YVU420M and V4L2_PIX_FMT_YVU444M it gives "Y, Cb, Cr" as the
planes order, this should be "Y, Cr, Cb". Can you fix that in a new patch?
Regards,
Hans
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v2 19/19] media: v4l2: Add 10-, 12- and 16-bpc 4:2:0 and 4:2:2 semi-planar YUV formats
2020-11-16 12:17 ` Hans Verkuil
@ 2020-11-16 18:41 ` Laurent Pinchart
0 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-16 18:41 UTC (permalink / raw)
To: Hans Verkuil
Cc: linux-media, Sakari Ailus, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Hi Hans,
On Mon, Nov 16, 2020 at 01:17:10PM +0100, Hans Verkuil wrote:
> On 02/11/2020 23:41, Laurent Pinchart wrote:
> > Add semi-planar YUV formats with 10, 12 and 16 bits per components, in
> > both 4:2:0 (NV12) and 4:2:2 (NV16) subsampling, and with both chroma
> > orderings. 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-planar.rst | 564 +++++++++++++++++-
> > include/uapi/linux/videodev2.h | 12 +
> > 2 files changed, 575 insertions(+), 1 deletion(-)
> >
> > diff --git a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> > index 07081ab05419..7f0fe2e4b668 100644
> > --- a/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
> > +++ b/Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst
>
> <snip>
>
> > Fully Planar YUV Formats
> > ========================
> >
>
> I found a mistake in the "Overview of Fully Planar YUV Formats" table:
>
> For formats V4L2_PIX_FMT_YVU420M and V4L2_PIX_FMT_YVU444M it gives "Y, Cb, Cr" as the
> planes order, this should be "Y, Cr, Cb". Can you fix that in a new patch?
Thanks for spotting this. I'll fix it in v3 of "[PATCH v2 14/19] media:
doc: pixfmt-yuv: Move all planar YUV formats to common file", as that's
where the error was introduced.
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf
2020-11-02 22:40 [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Laurent Pinchart
` (18 preceding siblings ...)
2020-11-02 22:41 ` [PATCH v2 19/19] media: v4l2: Add 10-, 12- and 16-bpc 4:2:0 and 4:2:2 semi-planar YUV formats Laurent Pinchart
@ 2020-11-03 8:57 ` Sakari Ailus
2020-11-03 10:25 ` Laurent Pinchart
19 siblings, 1 reply; 35+ messages in thread
From: Sakari Ailus @ 2020-11-03 8:57 UTC (permalink / raw)
To: Laurent Pinchart
Cc: linux-media, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Hi Laurent,
On Tue, Nov 03, 2020 at 12:40:43AM +0200, Laurent Pinchart wrote:
> Hello,
>
> This patch series adds a set of new pixel formats needed for the Xilinx
> Video Frame Buffer Read/Write IP cores (see [1]).
>
> Compared to v1, the series has been extended to include semi-planar YUV
> formats. The code is now based on v5.10-rc2, which uses SPDX license
> headers for the media documentation, so new files have been switched to
> do so as well. Review comments have also been incorported, thank you
> Hans and Nicolas for providing feedback on v1.
>
> Documentation of the pixel formats has grown organically in V4L2, and
> while it is fairly complete and detailed, it also duplicates lots of
> information. I've thus decided to bite the bullet, and try to
> consolidate the documentation first before adding new formats.
>
> The first three patches address minor issues in videodev2.h, removing a
> comment that belongs to a commit message instead (01/19) and moving two
> misplaced formats to where they belong (02/19 and 03/19).
>
> The next three patches refactor documentation for the RGB formats. Patch
> 04/19 removes a confusing table (that likely made sense when it was
> added, but not anymore), 05/19 adds a section title for the deprecated
> RGB formats to increase clarity, and patch 06/19 documents the naming
> scheme followed by our RGB formats. There are two separate naming
> schemes, used by 8- and 16-bit formats on one side, and 24- and 32-bit
> formats on the other side. The former matches the naming conventions of
> DRM, while the latter doesn't, which has often led to confusion and
> errors. This can't be changed, but it's now clearly documented.
The patches look nice but it'd be useful to see the resulting
documentation. Would you be able to upload that somewhere for reviewers to
access?
Thanks.
--
Regards,
Sakari Ailus
^ permalink raw reply [flat|nested] 35+ messages in thread* Re: [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf
2020-11-03 8:57 ` [PATCH v2 00/19] media: Add new pixel formats for Xilinx v-frmbuf Sakari Ailus
@ 2020-11-03 10:25 ` Laurent Pinchart
0 siblings, 0 replies; 35+ messages in thread
From: Laurent Pinchart @ 2020-11-03 10:25 UTC (permalink / raw)
To: Sakari Ailus
Cc: linux-media, Hans Verkuil, Dylan Yip, Vishal Sagar, Nicolas Dufresne
Hi Sakari,
On Tue, Nov 03, 2020 at 10:57:52AM +0200, Sakari Ailus wrote:
> On Tue, Nov 03, 2020 at 12:40:43AM +0200, Laurent Pinchart wrote:
> > Hello,
> >
> > This patch series adds a set of new pixel formats needed for the Xilinx
> > Video Frame Buffer Read/Write IP cores (see [1]).
> >
> > Compared to v1, the series has been extended to include semi-planar YUV
> > formats. The code is now based on v5.10-rc2, which uses SPDX license
> > headers for the media documentation, so new files have been switched to
> > do so as well. Review comments have also been incorported, thank you
> > Hans and Nicolas for providing feedback on v1.
> >
> > Documentation of the pixel formats has grown organically in V4L2, and
> > while it is fairly complete and detailed, it also duplicates lots of
> > information. I've thus decided to bite the bullet, and try to
> > consolidate the documentation first before adding new formats.
> >
> > The first three patches address minor issues in videodev2.h, removing a
> > comment that belongs to a commit message instead (01/19) and moving two
> > misplaced formats to where they belong (02/19 and 03/19).
> >
> > The next three patches refactor documentation for the RGB formats. Patch
> > 04/19 removes a confusing table (that likely made sense when it was
> > added, but not anymore), 05/19 adds a section title for the deprecated
> > RGB formats to increase clarity, and patch 06/19 documents the naming
> > scheme followed by our RGB formats. There are two separate naming
> > schemes, used by 8- and 16-bit formats on one side, and 24- and 32-bit
> > formats on the other side. The former matches the naming conventions of
> > DRM, while the latter doesn't, which has often led to confusion and
> > errors. This can't be changed, but it's now clearly documented.
>
> The patches look nice but it'd be useful to see the resulting
> documentation. Would you be able to upload that somewhere for reviewers to
> access?
Sure. Here you are: https://www.ideasonboard.org/media/uapi/v4l/pixfmt.html
--
Regards,
Laurent Pinchart
^ permalink raw reply [flat|nested] 35+ messages in thread