Commit da785536 authored by Laurent Pinchart's avatar Laurent Pinchart Committed by Mauro Carvalho Chehab
Browse files

media: doc: pixfmt-yuv: Move all semi-planar YUV formats to common file 



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: default avatarLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: default avatarHans Verkuil <hverkuil-cisco@xs4all.nl>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent af4f4505

Documentation/userspace-api/media/v4l/pixfmt-nv12.rst

deleted100644 → 0
+0 −76
Original line number Diff line number Diff line 
.. 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.

Documentation/userspace-api/media/v4l/pixfmt-nv12m.rst

deleted100644 → 0
+0 −88
Original line number Diff line number Diff line 
.. 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.

Documentation/userspace-api/media/v4l/pixfmt-nv12mt.rst

deleted100644 → 0
+0 −60
Original line number Diff line number Diff line 
.. 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.

Documentation/userspace-api/media/v4l/pixfmt-nv16.rst

deleted100644 → 0
+0 −84
Original line number Diff line number Diff line 
.. 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.

Documentation/userspace-api/media/v4l/pixfmt-nv16m.rst

deleted100644 → 0
+0 −88
Original line number Diff line number Diff line 
.. 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.