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@xxxxxxxxxxxxxxxx>
>>>> ---
>>>> 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
