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

.. _oneipl_api_design:

API Design
-----------

This section documents the general features of oneIPL API design. 
In particular, it covers the use of namespaces and data types from C++,
from DPC++ and new ones introduced for oneIPL APIs.

.. _oneipl_namespaces:

oneIPL Namespaces
++++++++++++++++++

All oneIPL objects and routines must be contained within 
the ``oneapi::ipl`` C++ namespace. Non-public APIs and headers 
must be contained within the ``detail`` namespace and corresponding folder.

.. _oneipl_cpp_datatypes:

Standard C++ Data Type
+++++++++++++++++++++++

oneIPL uses C++ STL data types for scalars where applicable:

* Integer scalars shall be C++ fixed-size integer types (``std::intN_t``, ``std::uintN_t``).
* Standard floating point types shall be ``float``, ``double``.

.. _oneipl_dpcpp_datatypes:

DPC++ datatype usage
++++++++++++++++++++

oneIPL uses the following DPC++ data types:

* SYCL standard floating point type ``sycl::half`` for fp16.
* Unified Shared Memory (USM) for pointer-based memory access.
* ``sycl::queue`` - SYCL queue for scheduling kernels on a SYCL device.
* ``sycl::buffer`` - SYCL buffer for buffer-based memory access.
* ``sycl::event`` - SYCL event for output event synchronization
  in oneIPL routines with USM pointers. 
  See :ref:`oneipl_synchronization` for more details.
* ``std::vector<sycl::event>`` - Vector of SYCL events 
  for input events synchronization in oneIPL routines with USM pointers. 
  See :ref:`oneipl_synchronization` for more details.

.. _oneipl_datatypes:

oneIPL Defined Data Types
++++++++++++++++++++++++++

oneIPL uses the scoped enum type for  image formats.

Each enumeration value shall come with plural noun. 


.. doxygenenum:: oneapi::ipl::formats
  :project: oneIPL

Image Formats Support and Definitions
++++++++++++++++++++++++++++++++++++++

oneIPL supports a variety of image formats. Format is a memory layout. 
The data mapped to this layout also has a type, which defines a color component
of a pixel. Currently, the majority of the functions support multi-channel interleaved 
formats, and some functions has support for sampled formats (nv12, i420) and 
plane format (rgbp). Potential combinations are provided in the table below, 
but the supported subset is in the function specification pages.

.. csv-table::
  :align: center
  :header: **DataT/Formats**,**plane**,**rgb/bgr**,**rgba/bgra**,**rgbp**,**NV12**,**i420**
  :widths: 10 5 5 5 5 5 5

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


APIs support for particular format and type must be defined during compilation via template parameters.
oneIPL uses custom image type, which is a fundamental class for the data representation:

.. code-block:: cpp

  namespace oneapi {
  namespace ipl {

    /// Wrapper class for different image implementations (using image memory or USM).
    template <formats Format, typename DataT, typename AllocatorT = select_image_allocator_t<Format, DataT>>
    class image final : public detail::image_impl_t<Format, DataT, AllocatorT>;
  }
  }


Internal computations must also be controlled during compilation via the ``ComputeT`` parameter. 
The default value for ``ComputeT`` is ``float``. Potential combinations are provided in the table below,
but the supported subset is in the function specification pages.
Computations in integers may be used in some cases. 
This behavior must be specified explicitly in a function specification.

.. rubric:: Supported values for ``ComputeT``:
  :class: sectiontitle

.. csv-table::
  :align: center
  :header: **float**,**double**,**half**

  v,v,x

* API must take a ``ComputeT`` as template parameter. 
* Compile-time checks must restrict APIs as much as possible using SFINAE constructs.
* API targeting to device must take a device ``queue_t``, source data, destination data. 
* API may optionally take ``spec`` with additional algorithmic parameters and ``dependencies`` to other async calls (generic list of ``sycl::event`` objects). 
* Default values for ``spec`` and ``dependencies`` must be in API declaration to make them optional. 

Generic oneIPL API has the following syntax:


.. code-block:: cpp

  namespace oneapi {
  namespace ipl {
    template <typename ComputeT = float,
              formats SrcFormat,
              typename SrcDataT,
              typename SrcAllocatorT,
              typename DstDataT,
              typename DstAllocatorT>
    sycl::event convert(sycl::queue&                            queue,
                image<SrcFormat, SrcDataT, SrcAllocatorT>&      src,
                image<formats::plane, DstDataT, DstAllocatorT>& dst,
                const convert_spec<DstDataT>&                   spec         = {},
                const std::vector<sycl::event>&                 dependencies = {});
  }
  }