.. _rgb-nv12-conversion:

RGB/RGBA to NV12 Color Conversion
==================================


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


.. rubric:: Description
  :class: sectiontitle

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

This function performs conversion from gamma-corrected RGB or RGBA image to NV12 image
using formulas:

  | ``Y' = 0.257 * R' + 0.504 * G' + 0.098 * B' + 16``
  | ``Cb' = -0.148 * R' - 0.291 * G' + 0.439 * B + 128'``
  | ``Cr' = 0.439 * R' - 0.368 * G' - 0.071 * B' + 128``

Conversion also performs `4:2:0` downsampling for the converted image with `Cb` and `Cr`
channels interleaved. Two plane `Y'Cb'Cr'` image with `4:2:0` sampling and
interleaved `Cb` and `Cr` components in respected order is also known as NV12 format.
In case of RGBA source image format, alpha channel is ignored and it's values are lost.
Source and destination image width and height must be even.


.. rubric:: Headers
  :class: sectiontitle

``oneapi/ipl/convert.hpp``


.. rubric:: Syntax
   :class: sectiontitle


.. doxygenfunction:: oneapi::ipl::convert(sycl::queue&, image<SrcFormat, SrcDataT, SrcAllocatorT>&, image<formats::nv12, 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 SrcFormat:


.. 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 RGBA to NV12 conversion:


.. code-block:: cpp


  // Create queue
  sycl::queue queue{};
  
  shared_usm_allocator_t usm_allocator{ queue };
  
  // Source rgba image data (image_image)
  image<formats::rgba, std::uint8_t> src_image{ src_data_pointer, src_size };
  
  // Destination NV12 image data (usm_image)
  image<formats::nv12, std::uint8_t> nv12_image{ src_size, usm_allocator };
  
  (void)convert(queue, src_image, nv12_image);