.. _i420-rgb-conversion:

I420 to RGB/RGBA Color Conversion
==================================


Converts an image from I420 format to RGB or RGBA format.


.. rubric:: Description
  :class: sectiontitle

This function can operate with ROI (see :ref:`image-regions-of-interest`).

This function performs conversion from I420 image to gamma-corrected RGB or RGBA image
according to formulae:

  | ``R' = 1.164 * (Y' - 16) + 1.596 * (Cr' - 128)``
  | ``G' = 1.164 * (Y' - 16) - 0.183 * (Cr' - 128) - 0.392 * (Cb' - 128)``
  | ``B' = 1.164 * (Y' - 16) + 2.017 * (Cb' - 128)``

Source and destination image width and height should be even.
If destination format is RGBA, ``alpha_value`` from ``spec`` shall be used to fill alpha channel.
Source and destination image width and height should be even.


.. rubric:: Headers
  :class: sectiontitle

``oneapi/ipl/convert.hpp``


.. rubric:: Syntax
   :class: sectiontitle

.. doxygenfunction:: oneapi::ipl::convert(sycl::queue&, image<formats::i420, SrcDataT, SrcAllocatorT>&, image<DstFormat, DstDataT, DstAllocatorT>&, const convert_spec<DstDataT>&, const std::vector<sycl::event>&)
  :project: oneIPL


Supported values for ComputeT:


.. list-table::
    :header-rows: 0

    * -     ``float``
    * -     ``double``


Supported values for DstFormat:


.. list-table::
    :header-rows: 0

    * -     ``rgb``
    * -     ``rgba``


.. rubric:: Parameters
   :class: sectiontitle

See :ref:`spec-conversion`.


.. rubric:: Errors
   :class: sectiontitle

.. list-table::
   :header-rows: 0

   * -     compile-time format check
     -  Indicates an error when image format is not supported.
   * -     compile-time data type check
     -  Indicates an error when image data type is not supported.
   * -     compile-time compute data type check
     -  Indicates an error when compute data type is not supported.
   * -     ``invalid_argument`` exception
     -  Indicates an error when ROI sizes of the source image and the destination image are not equal.
   * -     ``invalid_argument`` exception
     -  Indicates an error when one of the pitch values is not divisible by size of component data type in bytes.


The code example below demonstrates how to use the
``oneapi::ipl::convert`` for I420 to RGBA conversion:


.. code-block:: cpp


  #include <vector>
  
  // std::vector with data for source image
  std::vector<std::uint8_t> src_image_data{
      236, 236, 236, 236,
      236, 236, 236, 236,
      236, 236, 236, 236,
      236, 236, 236, 236,
      128, 128, 128, 128,
      128, 128, 128, 128
  };
  
  // Create queue
  sycl::queue queue{};
  
  shared_usm_allocator_t usm_allocator{ queue };
  
  // Source i420 image data (usm_image)
  image<formats::i420, std::uint8_t> src_image{ queue, src_image_data.data(), src_size, usm_allocator };
  // Destination rgba image data (image_image)
  image<formats::rgba, std::uint8_t> dst_image{ src_size };
  
  (void)convert(queue, src_image, dst_image);