code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _V4L2-PIX-FMT-Y8I:

*************************
V4L2_PIX_FMT_Y8I ('Y8I ')
*************************

Interleaved grey-scale image, e.g. from a stereo-pair

Description
===========

This is a grey-scale image with a depth of 8 bits per pixel, but with
pixels from 2 sources interleaved. Each pixel is stored in a 16-bit
word. E.g. the R200 RealSense camera stores pixel from the left sensor
in lower and from the right sensor in the higher 8 bits.

**Byte Order.**
Each cell is one byte.

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - start + 0:
      - Y'\ :sub:`00left`
      - Y'\ :sub:`00right`
      - Y'\ :sub:`01left`
      - Y'\ :sub:`01right`
      - Y'\ :sub:`02left`
      - Y'\ :sub:`02right`
      - Y'\ :sub:`03left`
      - Y'\ :sub:`03right`
    * - start + 8:
      - Y'\ :sub:`10left`
      - Y'\ :sub:`10right`
      - Y'\ :sub:`11left`
      - Y'\ :sub:`11right`
      - Y'\ :sub:`12left`
      - Y'\ :sub:`12right`
      - Y'\ :sub:`13left`
      - Y'\ :sub:`13right`
    * - start + 16:
      - Y'\ :sub:`20left`
      - Y'\ :sub:`20right`
      - Y'\ :sub:`21left`
      - Y'\ :sub:`21right`
      - Y'\ :sub:`22left`
      - Y'\ :sub:`22right`
      - Y'\ :sub:`23left`
      - Y'\ :sub:`23right`
    * - start + 24:
      - Y'\ :sub:`30left`
      - Y'\ :sub:`30right`
      - Y'\ :sub:`31left`
      - Y'\ :sub:`31right`
      - Y'\ :sub:`32left`
      - Y'\ :sub:`32right`
      - Y'\ :sub:`33left`
      - Y'\ :sub:`33right`


code:
.. 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.

.. raw:: latex

    \scriptsize

.. tabularcolumns:: |p{3.6cm}|p{3.0cm}|p{1.3cm}|p{2.6cm}|p{1.3cm}|p{1.3cm}|p{1.3cm}|

.. 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-IPU3-Y10:

      - ``V4L2_PIX_FMT_IPU3_Y10``
      - 'ip3y'

      - 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:`3`\ [1:0] Y'\ :sub:`2`\ [9:4]
      - Y'\ :sub:`3`\ [9:2]

    * .. _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`\ [9:2]
      - Y'\ :sub:`1`\ [9:2]
      - 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 ' | (1U << 31)

      - Y'\ :sub:`0`\ [15:8]
      - Y'\ :sub:`0`\ [7:0]
      - ...
      - ...
      - ...

.. raw:: latex

    \normalsize

.. 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. For the IPU3_Y10 format 25 pixels are packed into 32 bytes, which
    leaves the 6 most significant bits of the last byte padded with 0.

repo_name: angery/linux


code:
.. 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.

.. raw:: latex

    \footnotesize

.. tabularcolumns:: |p{5.2cm}|p{1.0cm}|p{1.5cm}|p{1.9cm}|p{1.2cm}|p{1.8cm}|p{2.7cm}|

.. 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, Cb
      - 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, Cb
      - No
      - Linear
    * - V4L2_PIX_FMT_NV12MT
      - 'TM12'
      - 8
      - 4:2:0
      - Cb, Cr
      - No
      - 64x32 tiles

        Horizontal Z order
    * - V4L2_PIX_FMT_NV12MT_16X16
      - 'VM12'
      - 8
      - 4:2:2
      - Cb, Cr
      - No
      - 16x16 tiles
    * - V4L2_PIX_FMT_P010
      - 'P010'
      - 10
      - 4:2:0
      - Cb, Cr
      - Yes
      - Linear
    * - V4L2_PIX_FMT_P010_4L4
      - 'T010'
      - 10
      - 4:2:0
      - Cb, Cr
      - Yes
      - 4x4 tiles
    * - V4L2_PIX_FMT_NV16
      - 'NV16'
      - 8
      - 4:2:2
      - Cb, Cr
      - Yes
      - Linear
    * - V4L2_PIX_FMT_NV61
      - 'NV61'
      - 8
      - 4:2:2
      - Cr, Cb
      - 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, Cb
      - 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, Cb
      - Yes
      - Linear

.. raw:: latex

    \normalsize

.. [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:
.. _V4L2-PIX-FMT-P010:

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:
.. _V4L2-PIX-FMT-NV12-4L4:
.. _V4L2-PIX-FMT-NV12-16L16:
.. _V4L2-PIX-FMT-NV12-32L32:
.. _V4L2-PIX-FMT-NV12M-8L128:
.. _V4L2-PIX-FMT-NV12-8L128:
.. _V4L2-PIX-FMT-NV12M-10BE-8L128:
.. _V4L2-PIX-FMT-NV12-10BE-8L128:
.. _V4L2-PIX-FMT-MM21:

Tiled NV12
----------

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. Each tile follows the
previous one linearly in memory (from left to right, top to bottom).

``V4L2_PIX_FMT_NV12MT_16X16`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores
pixels in 2D 16x16 tiles, and stores tiles 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`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores
pixels in 2D 64x32 tiles, and stores 2x2 groups of tiles 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 tiles, the last row of
tiles is stored in linear order. The layouts of the luma and chroma
planes are identical.

``V4L2_PIX_FMT_NV12_4L4`` stores pixels in 4x4 tiles, and stores
tiles linearly in memory. The line stride and image height must be
aligned to a multiple of 4. The layouts of the luma and chroma planes are
identical.

``V4L2_PIX_FMT_NV12_16L16`` stores pixels in 16x16 tiles, and stores
tiles 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_NV12_32L32`` stores pixels in 32x32 tiles, and stores
tiles linearly in memory. The line stride and image height must be
aligned to a multiple of 32. The layouts of the luma and chroma planes are
identical.

``V4L2_PIX_FMT_NV12M_8L128`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores
pixels in 2D 8x128 tiles, and stores tiles linearly in memory.
The image height must be aligned to a multiple of 128.
The layouts of the luma and chroma planes are identical.

``V4L2_PIX_FMT_NV12_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_8L128`` but stores
two planes in one memory.

``V4L2_PIX_FMT_NV12M_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M`` but stores
10 bits pixels in 2D 8x128 tiles, and stores tiles linearly in memory.
the data is arranged in big endian order.
The image height must be aligned to a multiple of 128.
The layouts of the luma and chroma planes are identical.
Note the tile size is 8bytes multiplied by 128 bytes,
it means that the low bits and high bits of one pixel may be in different tiles.
The 10 bit pixels are packed, so 5 bytes contain 4 10-bit pixels layout like
this (for luma):
byte 0: Y0(bits 9-2)
byte 1: Y0(bits 1-0) Y1(bits 9-4)
byte 2: Y1(bits 3-0) Y2(bits 9-6)
byte 3: Y2(bits 5-0) Y3(bits 9-8)
byte 4: Y3(bits 7-0)

``V4L2_PIX_FMT_NV12_10BE_8L128`` is similar to ``V4L2_PIX_FMT_NV12M_10BE_8L128`` but stores
two planes in one memory.

``V4L2_PIX_FMT_MM21`` store luma pixel in 16x32 tiles, and chroma pixels
in 16x16 tiles. The line stride must be aligned to a multiple of 16 and the
image height must be aligned to a multiple of 32. The number of luma and chroma
tiles are identical, even though the tile size differ. The image is formed of
two non-contiguous planes.

.. _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 tiles

.. _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 not subsampled.
Chroma lines contain the same number of pixels and twice the
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`

.. _V4L2_PIX_FMT_P010:
.. _V4L2-PIX-FMT-P010-4L4:

P010 and tiled P010
-------------------

P010 is like NV12 with 10 bits per component, expanded to 16 bits.
Data in the 10 high bits, zeros in the 6 low bits, arranged in little endian order.

.. flat-table:: Sample 4x4 P010 Image
    :header-rows:  0
    :stub-columns: 0

    * - start + 0:
      - Y'\ :sub:`00`
      - Y'\ :sub:`01`
      - Y'\ :sub:`02`
      - Y'\ :sub:`03`
    * - start + 8:
      - Y'\ :sub:`10`
      - Y'\ :sub:`11`
      - Y'\ :sub:`12`
      - Y'\ :sub:`13`
    * - start + 16:
      - Y'\ :sub:`20`
      - Y'\ :sub:`21`
      - Y'\ :sub:`22`
      - Y'\ :sub:`23`
    * - start + 24:
      - Y'\ :sub:`30`
      - Y'\ :sub:`31`
      - Y'\ :sub:`32`
      - Y'\ :sub:`33`
    * - start + 32:
      - Cb\ :sub:`00`
      - Cr\ :sub:`00`
      - Cb\ :sub:`01`
      - Cr\ :sub:`01`
    * - start + 40:
      - Cb\ :sub:`10`
      - Cr\ :sub:`10`
      - Cb\ :sub:`11`
      - Cr\ :sub:`11`

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.

``V4L2_PIX_FMT_P010_4L4`` stores pixels in 4x4 tiles, and stores tiles linearly
in memory. The line stride must be aligned to multiple of 8 and image height to
a multiple of 4. The layouts of the luma and chroma planes are identical.

.. raw:: latex

    \small

.. tabularcolumns:: |p{5.0cm}|p{1.1cm}|p{1.5cm}|p{2.2cm}|p{1.2cm}|p{3.7cm}|

.. 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, Cr, Cb
      - 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, Cr, Cb
      - No

.. raw:: latex

    \normalsize

.. [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`


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _V4L2-PIX-FMT-Z16:

*************************
V4L2_PIX_FMT_Z16 ('Z16 ')
*************************

16-bit depth data with distance values at each pixel

Description
===========

This is a 16-bit format, representing depth data. Each pixel is a
distance to the respective point in the image coordinates. Distance unit
can vary and has to be negotiated with the device separately. Each pixel
is stored in a 16-bit word in the little endian byte order.

**Byte Order.**
Each cell is one byte.

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - start + 0:
      - Z\ :sub:`00low`
      - Z\ :sub:`00high`
      - Z\ :sub:`01low`
      - Z\ :sub:`01high`
      - Z\ :sub:`02low`
      - Z\ :sub:`02high`
      - Z\ :sub:`03low`
      - Z\ :sub:`03high`
    * - start + 8:
      - Z\ :sub:`10low`
      - Z\ :sub:`10high`
      - Z\ :sub:`11low`
      - Z\ :sub:`11high`
      - Z\ :sub:`12low`
      - Z\ :sub:`12high`
      - Z\ :sub:`13low`
      - Z\ :sub:`13high`
    * - start + 16:
      - Z\ :sub:`20low`
      - Z\ :sub:`20high`
      - Z\ :sub:`21low`
      - Z\ :sub:`21high`
      - Z\ :sub:`22low`
      - Z\ :sub:`22high`
      - Z\ :sub:`23low`
      - Z\ :sub:`23high`
    * - start + 24:
      - Z\ :sub:`30low`
      - Z\ :sub:`30high`
      - Z\ :sub:`31low`
      - Z\ :sub:`31high`
      - Z\ :sub:`32low`
      - Z\ :sub:`32high`
      - Z\ :sub:`33low`
      - Z\ :sub:`33high`


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _pixfmt:

#############
Image Formats
#############
The V4L2 API was primarily designed for devices exchanging image data
with applications. The struct :c:type:`v4l2_pix_format` and
struct :c:type:`v4l2_pix_format_mplane` structures define the
format and layout of an image in memory. The former is used with the
single-planar API, while the latter is used with the multi-planar
version (see :ref:`planar-apis`). Image formats are negotiated with
the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. (The explanations here
focus on video capturing and output, for overlay frame buffer formats
see also :ref:`VIDIOC_G_FBUF <VIDIOC_G_FBUF>`.)

.. toctree::
    :maxdepth: 1

    pixfmt-v4l2
    pixfmt-v4l2-mplane
    pixfmt-intro
    pixfmt-indexed
    pixfmt-rgb
    pixfmt-bayer
    yuv-formats
    hsv-formats
    depth-formats
    pixfmt-compressed
    sdr-formats
    tch-formats
    meta-formats
    pixfmt-reserved
    colorspaces
    colorspaces-defs
    colorspaces-details


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _planar-apis:

*****************************
Single- and multi-planar APIs
*****************************

Some devices require data for each input or output video frame to be
placed in discontiguous memory buffers. In such cases, one video frame
has to be addressed using more than one memory address, i.e. one pointer
per "plane". A plane is a sub-buffer of the current frame. For examples
of such formats see :ref:`pixfmt`.

Initially, V4L2 API did not support multi-planar buffers and a set of
extensions has been introduced to handle them. Those extensions
constitute what is being referred to as the "multi-planar API".

Some of the V4L2 API calls and structures are interpreted differently,
depending on whether single- or multi-planar API is being used. An
application can choose whether to use one or the other by passing a
corresponding buffer type to its ioctl calls. Multi-planar versions of
buffer types are suffixed with an ``_MPLANE`` string. For a list of
available multi-planar buffer types see enum
:c:type:`v4l2_buf_type`.

Multi-planar formats
====================

Multi-planar API introduces new multi-planar formats. Those formats use
a separate set of FourCC codes. It is important to distinguish between
the multi-planar API and a multi-planar format. Multi-planar API calls
can handle all single-planar formats as well (as long as they are passed
in multi-planar API structures), while the single-planar API cannot
handle multi-planar formats.

Calls that distinguish between single and multi-planar APIs
===========================================================

:ref:`VIDIOC_QUERYCAP <VIDIOC_QUERYCAP>`
    Two additional multi-planar capabilities are added. They can be set
    together with non-multi-planar ones for devices that handle both
    single- and multi-planar formats.

:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`
    New structures for describing multi-planar formats are added: struct
    :c:type:`v4l2_pix_format_mplane` and
    struct :c:type:`v4l2_plane_pix_format`.
    Drivers may define new multi-planar formats, which have distinct
    FourCC codes from the existing single-planar ones.

:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`
    A new struct :c:type:`v4l2_plane` structure for
    describing planes is added. Arrays of this structure are passed in
    the new ``m.planes`` field of struct
    :c:type:`v4l2_buffer`.

:ref:`VIDIOC_REQBUFS <VIDIOC_REQBUFS>`
    Will allocate multi-planar buffers as requested.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _querycap:

*********************
Querying Capabilities
*********************

Because V4L2 covers a wide variety of devices not all aspects of the API
are equally applicable to all types of devices. Furthermore devices of
the same type have different capabilities and this specification permits
the omission of a few complicated and less important parts of the API.

The :ref:`VIDIOC_QUERYCAP` ioctl is available to
check if the kernel device is compatible with this specification, and to
query the :ref:`functions <devices>` and :ref:`I/O methods <io>`
supported by the device.

Starting with kernel version 3.1, :ref:`VIDIOC_QUERYCAP`
will return the V4L2 API version used by the driver, with generally
matches the Kernel version. There's no need of using
:ref:`VIDIOC_QUERYCAP` to check if a specific ioctl
is supported, the V4L2 core now returns ``ENOTTY`` if a driver doesn't
provide support for an ioctl.

Other features can be queried by calling the respective ioctl, for
example :ref:`VIDIOC_ENUMINPUT` to learn about the
number, types and names of video connectors on the device. Although
abstraction is a major objective of this API, the
:ref:`VIDIOC_QUERYCAP` ioctl also allows driver
specific applications to reliably identify the driver.

All V4L2 drivers must support :ref:`VIDIOC_QUERYCAP`.
Applications should always call this ioctl after opening the device.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _rw:

**********
Read/Write
**********

Input and output devices support the :c:func:`read()` and
:c:func:`write()` function, respectively, when the
``V4L2_CAP_READWRITE`` flag in the ``capabilities`` field of struct
:c:type:`v4l2_capability` returned by the
:ref:`VIDIOC_QUERYCAP` ioctl is set.

Drivers may need the CPU to copy the data, but they may also support DMA
to or from user memory, so this I/O method is not necessarily less
efficient than other methods merely exchanging buffer pointers. It is
considered inferior though because no meta-information like frame
counters or timestamps are passed. This information is necessary to
recognize frame dropping and to synchronize with other data streams.
However this is also the simplest I/O method, requiring little or no
setup to exchange data. It permits command line stunts like this (the
vidctrl tool is fictitious):

.. code-block:: none

    $ vidctrl /dev/video --input=0 --format=YUYV --size=352x288
    $ dd if=/dev/video of=myimage.422 bs=202752 count=1

To read from the device applications use the :c:func:`read()`
function, to write the :c:func:`write()` function. Drivers
must implement one I/O method if they exchange data with applications,
but it need not be this. [#f1]_ When reading or writing is supported, the
driver must also support the :c:func:`select()` and
:c:func:`poll()` function. [#f2]_

.. [#f1]
   It would be desirable if applications could depend on drivers
   supporting all I/O interfaces, but as much as the complex memory
   mapping I/O can be inadequate for some devices we have no reason to
   require this interface, which is most useful for simple applications
   capturing still images.

.. [#f2]
   At the driver level :c:func:`select()` and :c:func:`poll()` are
   the same, and :c:func:`select()` is too important to be optional.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _sdr-formats:

***********
SDR Formats
***********

These formats are used for :ref:`SDR <sdr>` interface only.

.. toctree::
    :maxdepth: 1

    pixfmt-sdr-cu08
    pixfmt-sdr-cu16le
    pixfmt-sdr-cs08
    pixfmt-sdr-cs14le
    pixfmt-sdr-ru12le
    pixfmt-sdr-pcu16be
    pixfmt-sdr-pcu18be
    pixfmt-sdr-pcu20be


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

*************
Configuration
*************

Applications can use the :ref:`selection API <VIDIOC_G_SELECTION>` to
select an area in a video signal or a buffer, and to query for default
settings and hardware limits.

Video hardware can have various cropping, composing and scaling
limitations. It may only scale up or down, support only discrete scaling
factors, or have different scaling abilities in the horizontal and
vertical directions. Also it may not support scaling at all. At the same
time the cropping/composing rectangles may have to be aligned, and both
the source and the sink may have arbitrary upper and lower size limits.
Therefore, as usual, drivers are expected to adjust the requested
parameters and return the actual values selected. An application can
control the rounding behaviour using
:ref:`constraint flags <v4l2-selection-flags>`.

Configuration of video capture
==============================

See figure :ref:`sel-targets-capture` for examples of the selection
targets available for a video capture device. It is recommended to
configure the cropping targets before to the composing targets.

The range of coordinates of the top left corner, width and height of
areas that can be sampled is given by the ``V4L2_SEL_TGT_CROP_BOUNDS``
target. It is recommended for the driver developers to put the top/left
corner at position ``(0,0)``. The rectangle's coordinates are expressed
in pixels.

The top left corner, width and height of the source rectangle, that is
the area actually sampled, is given by the ``V4L2_SEL_TGT_CROP`` target.
It uses the same coordinate system as ``V4L2_SEL_TGT_CROP_BOUNDS``. The
active cropping area must lie completely inside the capture boundaries.
The driver may further adjust the requested size and/or position
according to hardware limitations.

Each capture device has a default source rectangle, given by the
``V4L2_SEL_TGT_CROP_DEFAULT`` target. This rectangle shall cover what the
driver writer considers the complete picture. Drivers shall set the
active crop rectangle to the default when the driver is first loaded,
but not later.

The composing targets refer to a memory buffer. The limits of composing
coordinates are obtained using ``V4L2_SEL_TGT_COMPOSE_BOUNDS``. All
coordinates are expressed in pixels. The rectangle's top/left corner
must be located at position ``(0,0)``. The width and height are equal to
the image size set by :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`.

The part of a buffer into which the image is inserted by the hardware is
controlled by the ``V4L2_SEL_TGT_COMPOSE`` target. The rectangle's
coordinates are also expressed in the same coordinate system as the
bounds rectangle. The composing rectangle must lie completely inside
bounds rectangle. The driver must adjust the composing rectangle to fit
to the bounding limits. Moreover, the driver can perform other
adjustments according to hardware limitations. The application can
control rounding behaviour using
:ref:`constraint flags <v4l2-selection-flags>`.

For capture devices the default composing rectangle is queried using
``V4L2_SEL_TGT_COMPOSE_DEFAULT``. It is usually equal to the bounding
rectangle.

The part of a buffer that is modified by the hardware is given by
``V4L2_SEL_TGT_COMPOSE_PADDED``. It contains all pixels defined using
``V4L2_SEL_TGT_COMPOSE`` plus all padding data modified by hardware
during insertion process. All pixels outside this rectangle *must not*
be changed by the hardware. The content of pixels that lie inside the
padded area but outside active area is undefined. The application can
use the padded and active rectangles to detect where the rubbish pixels
are located and remove them if needed.

Configuration of video output
=============================

For output devices targets and ioctls are used similarly to the video
capture case. The *composing* rectangle refers to the insertion of an
image into a video signal. The cropping rectangles refer to a memory
buffer. It is recommended to configure the composing targets before to
the cropping targets.

The cropping targets refer to the memory buffer that contains an image
to be inserted into a video signal or graphical screen. The limits of
cropping coordinates are obtained using ``V4L2_SEL_TGT_CROP_BOUNDS``.
All coordinates are expressed in pixels. The top/left corner is always
point ``(0,0)``. The width and height is equal to the image size
specified using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.

The top left corner, width and height of the source rectangle, that is
the area from which image date are processed by the hardware, is given
by the ``V4L2_SEL_TGT_CROP``. Its coordinates are expressed in the
same coordinate system as the bounds rectangle. The active cropping area
must lie completely inside the crop boundaries and the driver may
further adjust the requested size and/or position according to hardware
limitations.

For output devices the default cropping rectangle is queried using
``V4L2_SEL_TGT_CROP_DEFAULT``. It is usually equal to the bounding
rectangle.

The part of a video signal or graphics display where the image is
inserted by the hardware is controlled by ``V4L2_SEL_TGT_COMPOSE``
target. The rectangle's coordinates are expressed in pixels. The
composing rectangle must lie completely inside the bounds rectangle. The
driver must adjust the area to fit to the bounding limits. Moreover, the
driver can perform other adjustments according to hardware limitations.

The device has a default composing rectangle, given by the
``V4L2_SEL_TGT_COMPOSE_DEFAULT`` target. This rectangle shall cover what
the driver writer considers the complete picture. It is recommended for
the driver developers to put the top/left corner at position ``(0,0)``.
Drivers shall set the active composing rectangle to the default one when
the driver is first loaded.

The devices may introduce additional content to video signal other than
an image from memory buffers. It includes borders around an image.
However, such a padded area is driver-dependent feature not covered by
this document. Driver developers are encouraged to keep padded rectangle
equal to active one. The padded target is accessed by the
``V4L2_SEL_TGT_COMPOSE_PADDED`` identifier. It must contain all pixels
from the ``V4L2_SEL_TGT_COMPOSE`` target.

Scaling control
===============

An application can detect if scaling is performed by comparing the width
and the height of rectangles obtained using ``V4L2_SEL_TGT_CROP`` and
``V4L2_SEL_TGT_COMPOSE`` targets. If these are not equal then the
scaling is applied. The application can compute the scaling ratios using
these values.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

********
Examples
********

(A video capture device is assumed; change
``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other devices; change target to
``V4L2_SEL_TGT_COMPOSE_*`` family to configure composing area)

Example: Resetting the cropping parameters
==========================================

.. code-block:: c

	struct v4l2_selection sel = {
	    .type = V4L2_BUF_TYPE_VIDEO_CAPTURE,
	    .target = V4L2_SEL_TGT_CROP_DEFAULT,
	};
	ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
	if (ret)
	    exit(-1);
	sel.target = V4L2_SEL_TGT_CROP;
	ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
	if (ret)
	    exit(-1);

Setting a composing area on output of size of *at most* half of limit
placed at a center of a display.

Example: Simple downscaling
===========================

.. code-block:: c

	struct v4l2_selection sel = {
	    .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
	    .target = V4L2_SEL_TGT_COMPOSE_BOUNDS,
	};
	struct v4l2_rect r;

	ret = ioctl(fd, VIDIOC_G_SELECTION, &sel);
	if (ret)
	    exit(-1);
	/* setting smaller compose rectangle */
	r.width = sel.r.width / 2;
	r.height = sel.r.height / 2;
	r.left = sel.r.width / 4;
	r.top = sel.r.height / 4;
	sel.r = r;
	sel.target = V4L2_SEL_TGT_COMPOSE;
	sel.flags = V4L2_SEL_FLAG_LE;
	ret = ioctl(fd, VIDIOC_S_SELECTION, &sel);
	if (ret)
	    exit(-1);

A video output device is assumed; change ``V4L2_BUF_TYPE_VIDEO_OUTPUT``
for other devices

Example: Querying for scaling factors
=====================================

.. code-block:: c

	struct v4l2_selection compose = {
	    .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
	    .target = V4L2_SEL_TGT_COMPOSE,
	};
	struct v4l2_selection crop = {
	    .type = V4L2_BUF_TYPE_VIDEO_OUTPUT,
	    .target = V4L2_SEL_TGT_CROP,
	};
	double hscale, vscale;

	ret = ioctl(fd, VIDIOC_G_SELECTION, &compose);
	if (ret)
	    exit(-1);
	ret = ioctl(fd, VIDIOC_G_SELECTION, &crop);
	if (ret)
	    exit(-1);

	/* computing scaling factors */
	hscale = (double)compose.r.width / crop.r.width;
	vscale = (double)compose.r.height / crop.r.height;


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

************
Introduction
************

Some video capture devices can sample a subsection of a picture and
shrink or enlarge it to an image of arbitrary size. Next, the devices
can insert the image into larger one. Some video output devices can crop
part of an input image, scale it up or down and insert it at an
arbitrary scan line and horizontal offset into a video signal. We call
these abilities cropping, scaling and composing.

On a video *capture* device the source is a video signal, and the
cropping target determine the area actually sampled. The sink is an
image stored in a memory buffer. The composing area specifies which part
of the buffer is actually written to by the hardware.

On a video *output* device the source is an image in a memory buffer,
and the cropping target is a part of an image to be shown on a display.
The sink is the display or the graphics screen. The application may
select the part of display where the image should be displayed. The size
and position of such a window is controlled by the compose target.

Rectangles for all cropping and composing targets are defined even if
the device does supports neither cropping nor composing. Their size and
position will be fixed in such a case. If the device does not support
scaling then the cropping and composing rectangles have the same size.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

*****************
Selection targets
*****************

.. _sel-targets-capture:

.. kernel-figure:: selection.svg
    :alt:   selection.svg
    :align: center

    Cropping and composing targets

    Targets used by a cropping, composing and scaling process

See :ref:`v4l2-selection-targets` for more information.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _selection-vs-crop:

********************************
Comparison with old cropping API
********************************

The selection API was introduced to cope with deficiencies of the
older :ref:`CROP API <crop>`, that was designed to control simple
capture devices. Later the cropping API was adopted by video output
drivers. The ioctls are used to select a part of the display were the
video signal is inserted. It should be considered as an API abuse
because the described operation is actually the composing. The
selection API makes a clear distinction between composing and cropping
operations by setting the appropriate targets.

The CROP API lacks any support for composing to and cropping from an
image inside a memory buffer. The application could configure a
capture device to fill only a part of an image by abusing V4L2
API. Cropping a smaller image from a larger one is achieved by setting
the field ``bytesperline`` at struct :c:type:`v4l2_pix_format`.
Introducing an image offsets could be done by modifying field
``m_userptr`` at struct :c:type:`v4l2_buffer` before calling
:ref:`VIDIOC_QBUF <VIDIOC_QBUF>`. Those operations should be avoided
because they are not portable (endianness), and do not work for
macroblock and Bayer formats and mmap buffers.

The selection API deals with configuration of buffer
cropping/composing in a clear, intuitive and portable way. Next, with
the selection API the concepts of the padded target and constraints
flags are introduced. Finally, struct :c:type:`v4l2_crop` and struct
:c:type:`v4l2_cropcap` have no reserved fields. Therefore there is no
way to extend their functionality. The new struct
:c:type:`v4l2_selection` provides a lot of place for future
extensions.

Driver developers are encouraged to implement only selection API. The
former cropping API would be simulated using the new one.


code:
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _selection-api:

Cropping, composing and scaling -- the SELECTION API
====================================================

.. toctree::
    :maxdepth: 1

    selection-api-intro.rst
    selection-api-targets.rst
    selection-api-configuration.rst
    selection-api-vs-crop-api.rst
    selection-api-examples.rst