From: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
To: Hans Verkuil <hverkuil-cisco@xs4all.nl>
Cc: linux-media@vger.kernel.org,
Sakari Ailus <sakari.ailus@linux.intel.com>,
Dylan Yip <dylany@xilinx.com>, Vishal Sagar <vsagar@xilinx.com>,
Nicolas Dufresne <nicolas@ndufresne.ca>
Subject: Re: [PATCH v2 06/19] media: doc: pixfmt-rgb: Clarify naming scheme for RGB formats
Date: Mon, 16 Nov 2020 19:26:06 +0200 [thread overview]
Message-ID: <20201116172606.GS6540@pendragon.ideasonboard.com> (raw)
In-Reply-To: <ae3848f7-9742-53d1-f476-03b4ded32073@xs4all.nl>
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
next prev parent reply other threads:[~2020-11-16 17:26 UTC|newest]
Thread overview: 35+ messages / expand[flat|nested] mbox.gz Atom feed top
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 ` [PATCH v2 03/19] media: videodev2.h: Move HM12 format to YUV semi-planar section Laurent Pinchart
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 ` [PATCH v2 05/19] media: doc: pixfmt-rgb: Add title for deprecated formats Laurent Pinchart
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:29 ` Laurent Pinchart
2020-11-16 17:26 ` Laurent Pinchart [this message]
2020-11-16 17:35 ` Laurent Pinchart
2020-11-16 18:20 ` Hans Verkuil
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 ` [PATCH v2 08/19] media: doc: pixfmt-yuv: Move all packed YUV formats to common file Laurent Pinchart
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 ` [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 ` [PATCH v2 11/19] media: doc: pixfmt-packed-yuv: Clarify naming scheme for 4:4:4 formats 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
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
2020-11-02 22:40 ` [PATCH v2 14/19] media: doc: pixfmt-yuv: Move all planar " Laurent Pinchart
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
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
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 ` [PATCH v2 18/19] media: v4l2: Add 10- and 12-bpc luma-only formats with linear packing 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-16 12:10 ` Hans Verkuil
2020-11-16 12:17 ` Hans Verkuil
2020-11-16 18:41 ` Laurent Pinchart
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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20201116172606.GS6540@pendragon.ideasonboard.com \
--to=laurent.pinchart@ideasonboard.com \
--cc=dylany@xilinx.com \
--cc=hverkuil-cisco@xs4all.nl \
--cc=linux-media@vger.kernel.org \
--cc=nicolas@ndufresne.ca \
--cc=sakari.ailus@linux.intel.com \
--cc=vsagar@xilinx.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).