.. _rgbp-rgb-conversion:

RGBP to RGB/RGBA Color Conversion
==================================


Converts an image from RGBP (3 plane RGB) 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 3-plane RGB image to RGB or RGBA image
leaving pixel values unchanged, only changing memory layout from
3 plane 1 channel per plane to 1 plane 3 or 4 channels depending on destination image format.
If destination format is RGBA, ``alpha_value`` from ``spec`` must be used to fill alpha channel.


.. rubric:: Headers
  :class: sectiontitle

``oneapi/ipl/convert.hpp``


.. doxygenfunction:: oneapi::ipl::convert(sycl::queue&, image<formats::rgbp, 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 RGBP to RGBA conversion:


.. code-block:: cpp


  #include <vector>
  
  // std::vector with data for source image
  std::vector<std::uint8_t> src_image_data{
      255, 255,
      255, 255,
      128, 128,
      128, 128,
      0,   0,
      0,   0
  };
  
  // Create queue
  sycl::queue queue{};
  
  shared_usm_allocator_t usm_allocator{ queue };
  
  // Source rgbp image data (usm_image)
  image<formats::rgbp, 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);