API Design#
This section documents the general features of the oneIPL API design. In particular, it covers the use of namespaces and data types from C++, from DPC++, and new ones introduced in this oneIPL specification.
oneIPL Namespaces#
All oneIPL objects and functions 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 are C++ fixed-size integer types (
std::intN_t
,std::uintN_t
).Standard floating-point types are
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 functions with USM pointers. See Synchronization for more details.std::vector<sycl::event>
- Vector of SYCL events for input events synchronization in oneIPL functions with USM pointers. See Synchronization for more details.
oneIPL Defined Data Types#
oneIPL uses the scoped enum type for image layouts.
Each enumeration value comes with a 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
-
enumerator plane#
Image Memory Layouts Support and Definitions#
oneIPL supports a variety of image formats. The 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 component
information in the image format. Currently, the majority of the functions support multi-channel interleaved layouts
(channel3, channel4
) and the single-channel layout (plane
). Some functions have support for subsampled layouts
(sub420/sub420i
) and the multiple-planes layout (plane3
).
The Color Models shall be mapped to corresponding memory layouts, mapping example is in the table:
plane |
channel3 |
channel4 |
plane3 |
sub420i |
sub420 |
---|---|---|---|---|---|
GRAYSCALE |
RGB/BGR |
RGBA/SMYK |
RGB(P) |
YUV/YCbCr |
YUV/YCbCr |
Potential combinations are provided in the table below, but the particular supported subset can be found in each function’s specification page. Data types are also restricted by hardware capabilities, for instance, half and double data types might not be supported on all devices.
Data Types / Layouts |
plane |
channel3 |
channel4 |
plane3 |
---|---|---|---|---|
std::uint8_t |
✓ |
✓ |
✓ |
✓ |
std::int8_t |
✓ |
✓ |
✓ |
✓ |
std::uint16_t |
✓ |
✓ |
✓ |
✓ |
std::int16_t |
✓ |
✓ |
✓ |
✓ |
std::uint32_t |
✓ |
✓ |
✓ |
✓ |
std::int32_t |
✓ |
✓ |
✓ |
✓ |
float |
✓ |
✓ |
✓ |
✓ |
double |
✓ |
✓ |
✓ |
✓ |
As extra subsampled layouts the sub420i (NV12) and sub420 (YUV420) are specified pre API. The data type for the subsmapled formats is only std::uint8_t.
API support for a particular layout and type must be defined during compilation via template parameters. oneIPL uses a 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 |
---|---|---|
✓ |
✓ |
✗ |
The API must take
ComputeT
as a template parameter.Compile-time checks must restrict APIs as much as possible using SFINAE constructs.
The API targeting to device must take a device
queue_t
, source data, and destination data.The API may optionally take
spec
with additional algorithmic parameters anddependencies
to other asynchronous calls (generic list ofsycl::event
objects).Default values for
spec
anddependencies
must be in the API declaration to make them optional.
The generic oneIPL API has the following syntax:
namespace oneapi {
namespace ipl {
// API with no arguments dependend on metadata
template <typename ComputeT = float,
typename SrcImageT,
typename DstImageT>
sycl::event algorithm1(sycl::queue& queue,
SrcImageT& src,
DstImageT& dst,
const algorithm1_spec<ComputeT>& spec = {},
const std::vector<sycl::event>& dependencies = {});
// API with argument dependend on metadata
template <typename ComputeT = float,
typename SrcImageT,
typename DstImageT>
sycl::event algorithm2(sycl::queue& queue,
SrcImageT& src,
DstImageT& dst,
const algorithm2_spec<ComputeT>& spec = {},
const typename SrcImageT::pixel_t& dependend_arg = {},
const std::vector<sycl::event>& dependencies = {});
// API with no dependency on computational type
template <typename SrcImageT,
typename DstImageT>
sycl::event algorithm3(sycl::queue& queue,
SrcImageT& src,
DstImageT& dst,
const algorithm3_spec& spec = {},
const std::vector<sycl::event>& dependencies = {})
}
}