Convert Operation

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

Description

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 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:

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.

Application Notes

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).

Headers

oneapi/ipl/misc/convert.hpp

Syntax

template<typename SrcImageT, typename DstImageT>
sycl::event oneapi::ipl::convert(sycl::queue &queue, SrcImageT &src, DstImageT &dst, const convert_spec &spec = {}, const std::vector<sycl::event> &dependencies = {})

Copy image with type conversion.

Template Parameters:

• SrcImageT – Source image type

• DstImageT – Destination image type

Parameters:

• queue – SYCL queue

• src – source image

• dst – destination image

• spec – algorithmic specification

• dependencies – dependencies

Returns:

SYCL event

Supported combinations for data types and layouts:

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	✓	✓	✓	✗

Supported values for subsampled layout (only for std::uint8_t data type):

sub420	sub420i
✗	✗

Parameters

class convert_spec

Convert specification.

Errors

compile-time memory layout check	Indicates an error when image memory layout 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 oneapi::ipl::convert shall be called:

using namespace oneapi;

sycl::queue                 queue;
ipl::shared_usm_allocator_t allocator{ queue };
const sycl::range<2>        image_size{ height, width };

// Source 4-channel image data
ipl::image<ipl::layouts::channel4, std::uint8_t> src_image{ queue, p_image_data, image_size, allocator };
// Destination 4-channel image data
ipl::image<ipl::layouts::channel4, std::uint16_t> dst_image{ image_size, allocator };

// Convert 4-channel image data type from std::uint8_t to std::uint16_t
auto event = ipl::convert(queue, src_image, dst_image);