.. _rgb-plane-conversion:

RGB/RGBA to Plane Grayscale Color Conversion
=============================================


Converts an image from RGB or RGBA format to plane grayscale format.


.. rubric:: Description
  :class: sectiontitle

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

This function performs conversion from RGB or RGBA image to plane grayscale image
using following basic equation to compute luma from nonlinear gamma-corrected red,
green and blue values:

  ``Y' = 0.299 * R' + 0.587 * G' + 0.114 * B'``

Note that the transform coefficients conform to the standard for the NTSC red,
green, and blue CRT phosphors.
In case of RGBA source image format, alpha channel is ignored and its values are lost.


.. rubric:: Headers
  :class: sectiontitle

``oneapi/ipl/convert.hpp``


.. rubric:: Syntax
   :class: sectiontitle


.. doxygenfunction:: oneapi::ipl::convert(sycl::queue&, image<SrcFormat, SrcDataT, SrcAllocatorT>&, image<formats::plane, 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 plane grayscale 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 gray image data (usm_image)
  image<formats::plane, std::uint8_t> dst_image{ src_size, usm_allocator };
  
  (void)convert(queue, src_image, dst_image);
  
  return dst_image;