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#

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.

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.

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 Synchronization for more details.

  • std::vector<sycl::event> - Vector of SYCL events for input events synchronization in oneIPL routines with USM pointers. See Synchronization for more details.

oneIPL Defined Data Types#

oneIPL uses the scoped enum type for image layouts.

Each enumeration value shall come with plural noun.

enum class oneapi::ipl::layouts#

Image layouts supported by oneIPL.

Values:

enumerator plane#

single plane, single channel

enumerator channel3#

3 channel interleaved

enumerator channel4#

4 channel interleaved

enumerator plane3#

3 planes

enumerator sub420#

subsampled 420 YYYYYYYY UU VV per pixel, 3 planes

enumerator sub420i#

subsampled 420 interleaved YYYYYYYY UVUV per pixel, 2 planes

Image Memory Layouts Support and Definitions#

oneIPL supports a variety of image formats. Format is defined by memory layout and data type combination. The data mapped to this layout also has a type, which defines a color component of a pixel. There is no color components information in image. Currently, the majority of the functions support multi-channel interleaved layouts (channel3, channel4) and single channel layout (plane). Some functions has support for subsampled layouts (sub420/sub420i) and multiple planes layout (plane3). Potential combinations are provided in the table below, but the particular supported subset is in the function specification pages. Data type is also restricted by hardware capabilities, so half and double data types might be device specific depending on what is supported by device.

Data types/Layouts

plane

channel3(RGB)

channel4(RGBA)

plane3(RGBP)

sub420i(NV12)

sub420(YUV420)

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

half

v

v

v

v

x

x

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

namespace oneapi {
namespace ipl {

  /// Wrapper class for different image implementations (using image memory or USM).
  template <layouts Layout, typename DataT, typename AllocatorT = select_image_allocator_t<Layout, DataT>>
  class image final;
}
}

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.

Supported values for ComputeT:

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:

namespace oneapi {
namespace ipl {
  template <typename ComputeT = float,
            typename SrcImageT,
            typename DstImageT>
  sycl::event algorithm(sycl::queue&                          queue,
              SrcImageT&                                      src,
              DstImageT&                                      dst,
              const algorithm_spec<SrcImageT, DstImageT>&     spec         = {},
              const std::vector<sycl::event>&                 dependencies = {});
}
}