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

.. _image-class:

Image Class
============


.. rubric:: Description
  :class: sectiontitle

All oneIPL image processing functions operate with images. The oneIPL image
defines 2D shared image data and supports 
:ref:`ROI<image-regions-of-interest>` feature, extended format and
Unified Shared Memory.

The oneIPL image class is a wrapper over image classes using :ref:`image memory <image-image-class>` 
or :ref:`USM memory <usm-image-class>`. The base image class may depend on 
the image format: the image class using image memory must only be used with ``oneapi::ipl::formats::rgba`` 
image format. For other formats, the USM-based image class shall be used.

Library shall provide type aliases to control memory allocation. 
USM memory can be allocated as host, device and shared.
Type aliases shall work according to table below:

.. list-table::
  :header-rows: 1
  :widths: 15 10 20 25 30

  * -     \ **Allocator/Tag**\
    -     \ **Memory**\
    -     \ **Formats**\
    -     \ **Default Implementation**\
    -     \ **Object of class**\
  * -     host_allocator
    -     Host Memory
    -     All
    -     usm_allocator (host)
    -     image<..., host_allocator>
  * -     device_allocator
    -     USM
    -     All
    -     Device allocator based on malloc_device
    -     image<..., device_allocator>
  * -     shared_allocator
    -     USM
    -     All
    -     usm_allocator (shared)
    -     image<..., shared_allocator>
  * -     image_allocator
    -     Image
    -     Only 4-component, 8,16,32-bit
    -     Image is allocated by runtime, image_allocator is allocator, which is used for host allocation only
    -     image<..., image_allocator>

Image constructors from existing memory shall take pointers. 
Depending on what kind of pointer is provided memory shall be 
either allocated and copied or just mapped.
The most efficient way is to void the copy operation and that shall be implemented 
as close to the table below as possible:

.. list-table::
  :header-rows: 1

  * -     \ **Pointer/Image**\
    -     \ **Host Image**\
    -     \ **Device Image**\
    -     \ **Shared Image**\
    -     \ **Image (Image memory)**\
  * -     Host pointer
    -     Zero-copy
    -     Copy
    -     Copy
    -     Copy
  * -     USM Device pointer
    -     Copy
    -     Zero-copy
    -     Copy
    -     Copy/Zero copy for some formats is possible
  * -     USM Shared pointer
    -     Zero-copy
    -     Zero-copy
    -     Zero-copy
    -     Copy/Zero copy for some formats is possible
  * -     Image
    -     Copy/Zero copy for some formats is possible
    -     Copy/Zero copy for some formats is possible
    -     Copy/Zero copy for some formats is possible
    -     Zero-copy



.. rubric:: Include Files
  :class: sectiontitle

``oneapi/ipl.hpp``


.. rubric:: Domain Dependencies
  :class: sectiontitle

Headers: ``oneapi/ipl.hpp``

Libraries: ``oneipl.lib``


.. rubric:: Syntax
   :class: sectiontitle

.. doxygenclass:: oneapi::ipl::image
  :project: oneIPL
  :members:


.. rubric:: Possible combinations for DataT and not subsampled Formats:
  :class: sectiontitle

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

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

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

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

  v,v


Library shall provide subset of combinations supported by image class 
in each computational function.


The code example below demonstrates how to use the
``oneapi::ipl::image`` with USM memory and ROI

.. code-block:: cpp

  #include <oneapi/ipl.hpp>
  
  using namespace oneapi::ipl;

  const roi_rect roi_rect{ image_size / 6, image_size / 3 };
  
  // Create queue
  sycl::queue queue{};
  
  // Create allocator
  shared_usm_allocator_t allocator{ queue };
  
  // RGB image (usm_image)
  image<formats::rgb, std::uint8_t> usm_image{ queue, image_data_pointer, image_size, allocator };
  // RGB image ROI (usm_image)
  image<formats::rgb, std::uint8_t> usm_image_roi{ usm_image, roi_rect };


.. toctree::

   image-image-class
   usm-image-class