.. SPDX-FileCopyrightText: 2021 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _copy:

Copy Operations
================


Copy and convert image pixel values from one data type to another.


.. rubric:: Description
  :class: sectiontitle

This function converts pixel values in the source image to the
different data type and writes them to the destination image.
This function can operate with ROI (see :ref:`image-regions-of-interest`).


The result of integer operations is always saturated to the
destination data type range. It means that if the value of the source
pixel is out of the data range of the destination image, the value of
the corresponding destination pixel is set to the value of the lower
or upper bound (minimum or maximum) of the destination data range like following pseudocode:

.. code-block:: cpp

  x = src_image(i,j)
  if (x > MAX_VAL) x = MAX_VAL
  if (x < MIN_VAL) x = MIN_VAL
  dst_image(i,j) = (CASTING)x


When converting from floating-point to integer type, default ``SYCL`` rounding mode is applied
(rounding to nearest even), and the result is saturated to the destination data type range.


.. rubric:: Application Notes
  :class: sectiontitle

When data is converted from the signed integer to the corresponding
unsigned integer and vice versa, the pixel
information may be lost because all negative values will be set to
zero (signed-unsigned conversion), or unsigned values from the high
half of the range will be set to the maximum value of the signed
range (unsigned - signed conversion).


.. rubric:: Headers
  :class: sectiontitle

``oneapi/ipl/misc/copy.hpp``


.. rubric:: Syntax
  :class: sectiontitle


**Case 1: Copy**


.. doxygenfunction:: oneapi::ipl::copy(sycl::queue&, image<Format, DataT, SrcAllocatorT>&, image<Format, DataT, DstAllocatorT>&, const std::vector<sycl::event> &)
  :project: oneIPL


**Case 2: Copy with type conversion**

.. doxygenfunction:: oneapi::ipl::copy(sycl::queue&, image<Format, SrcDataT, SrcAllocatorT>&, image<Format, DstDataT, DstAllocatorT>&, const std::vector<sycl::event> &)
  :project: oneIPL


.. rubric:: Supported combinations for SrcDataT/DstDataT/Formats:
  :class: sectiontitle

.. csv-table::
  :align: center
  :header: **SrcDataT/DstDataT/Formats**,**plane**,**rgb/bgr**,**rgba/bgra**,**rgbp**

  **std::uint8_t** ,v,v,v,x
  **std::int8_t**  ,v,v,v,x
  **std::uint16_t**,v,v,v,x
  **std::int16_t** ,v,v,v,x
  **std::uint32_t**,v,v,v,x
  **std::int32_t** ,v,v,v,x
  **float**        ,v,v,v,x
  **double**       ,v,v,v,x


.. rubric:: Supported values for subsampled Format (only for SrcDataT/DstDataT = ``std::uint8_t``):
  :class: sectiontitle

.. csv-table::
  :align: center
  :header: **nv12**,**i420**

  x,x


.. 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::copy``:


.. code-block:: cpp


  // Create queue
  sycl::queue queue{};
  
  image<formats::rgba, std::uint8_t> src_image{ src_data_pointer, src_size };
  image<formats::rgba, std::uint8_t> dst_image{ src_size };
  
  (void)copy(queue, src_image, dst_image);