.. SPDX-FileCopyrightText: 2021 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _pixel-and-planar-image-formats:

Pixel and Planar Image Formats
==============================


Data storage for an image can be pixel-oriented or planar-oriented
(planar). For images in pixel order, all channel values for each pixel
are clustered and stored consecutively. Their layout depends on the
color model and downsampling scheme.


:ref:`Table “Pixel-Order Image Formats” <pixel-order-image-formats>` lists all pixel-order
image formats that are supported by the oneIPL color conversion
functions and shows the corresponding channel values order (here, group
of underlined symbols represents one pixel and symbol ``A`` denotes
alpha-channel value). The last column of this table gives an example of
an oneIPL color conversion function that uses the respective image
format.
oneIPL supports only 3- and 4-channel pixel formats. Gray-scale images are represented using pixel format with one component.

.. _pixel-order-image-formats:
.. list-table::
  :header-rows: 1

  * -  Format
    -  Number of Channels
    -  Channel Values Order
  * -     ``formats::plane``
    -     1
    -     P0 P1 P2 P3 P4 ...
  * -     ``formats::rgb``
    -     3
    -     R0 G0 B0 R1 G1 B1 R2 G2 B2
  * -     ``formats::rgba``
    -     4
    -     R0 G0 B0 A0 R1 G1 B1 A1
  * -     ``formats::bgr``
    -     3
    -     B0 G0 R0 B1 G1 R1 B2 G2 R2
  * -     ``formats::bgra``
    -     4
    -     B0 G0 R0 A0 B1 G1 R1 A1


Planar image formats supported by the oneIPL color conversion
functions are listed in :ref:`Table “Planar Image Formats” <planar-image-formats>` along with examples
of the oneIPL functions using that format. Planes layout and their
relative sizes are shown in :ref:`Figure "Plane Size and Layout: 3-planes
Images" <3planes-example>` and :ref:`Figure "Plane Size and Layout: 2-planes
Images" <2planes-example>`.
oneIPL supports only RGP and 4:2:0 subsampling formats in some functions.

.. _planar-image-formats:
.. list-table::
  :header-rows: 1

  * -     Format
    -     Number of Planes
    -     Planes Layout 1
    -     Planes Layout 2
    -     Planes Layout 3
    -     Further Explanation
  * -     ``formats::rgbp``
    -     3
    -     R
    -     G
    -     B
    -     see :ref:`Figure below <3planes-example>`, a
  * -     ``formats::i420``
    -     3
    -     Y
    -     U
    -     V
    -     see :ref:`Figure below <3planes-example>`, d
  * -     ``formats::nv12``
    -     2
    -     Y
    -     UV
    -     -
    -     see :ref:`Figure below for 2-planes images <2planes-example>`,    b


.. _3planes-example:
.. figure:: ./GUID-DB046318-CFAF-41BB-8B52-BE65AFB1FC01-low.jpg
   :scale: 100%
   :align: center

.. _2planes-example:
.. figure:: ./GUID-7E07B34F-E9C9-4119-9DB3-0B64F431E60C-low.jpg
   :scale: 100%
   :align: center