.. _plane-rgb-conversion:

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


Converts an image from plane grayscale 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 plane grayscale to RGB or RGBA image
by copying luminance component to color components.
If destination format is RGBA, ``alpha_value`` from ``spec`` shall be be used to fill alpha channel.

.. rubric:: Headers
  :class: sectiontitle

Headers: ``oneapi/ipl/convert.hpp``


.. rubric:: Syntax
   :class: sectiontitle

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


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.
   * -     ``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 plane grayscale to rgba conversion:


.. code-block:: cpp


  // Create queue
  sycl::queue queue{};
  
  shared_usm_allocator_t usm_allocator{ queue };
  
  // Source gray image data (usm_image)
  image<formats::plane, std::uint8_t> src_image{ queue, src_data_pointer, 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);