Copy Operations

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/copy.hpp

Syntax

Case 1: Copy

template<typename ComputeT = float, formats Format, typename DataT, typename SrcAllocatorT, typename DstAllocatorT>
sycl::event oneapi::ipl::copy(sycl::queue &queue, image<Format, DataT, SrcAllocatorT> &src, image<Format, DataT, DstAllocatorT> &dst, const std::vector<sycl::event> &dependencies = {})

Copy image without type conversion.

Template Parameters

  • ComputeT – The type in which all calculations will be performed

  • Format – Source and destination image format

  • DataT – Data type

  • SrcAllocatorT – Source image allocator type

  • DstAllocatorT – Destination image allocator type

Parameters

  • queue – SYCL queue

  • src – source image

  • dst – destination image

  • dependencies – dependencies

Returns

SYCL event

Case 2: Copy with type conversion

template<formats Format, typename SrcDataT, typename SrcAllocatorT, typename DstDataT, typename DstAllocatorT>
sycl::event oneapi::ipl::copy(sycl::queue &queue, image<Format, SrcDataT, SrcAllocatorT> &src, image<Format, DstDataT, DstAllocatorT> &dst, const std::vector<sycl::event> &dependencies = {})

Copy image with type conversion.

Template Parameters

  • Format – Source and destination image format

  • SrcDataT – Source image data type

  • DstDataT – Destination image data type

  • SrcAllocatorT – Source image allocator type

  • DstAllocatorT – Destination image allocator type

Parameters

  • queue – SYCL queue

  • src – source image

  • dst – destination image

  • dependencies – dependencies

Returns

SYCL event

Supported combinations for SrcDataT/DstDataT/Formats:

SrcDataT/DstDataT/Formats

plane

rgb/bgr

rgba/bgra

rgbp

std::uint8_t

v

v

v

x

std::int8_t

v

v

v

x

std::uint16_t

v

v

v

x

std::int16_t

v

v

v

x

std::uint32_t

v

v

v

x

std::int32_t

v

v

v

x

float

v

v

v

x

double

v

v

v

x

Supported values for subsampled Format (only for SrcDataT/DstDataT = std::uint8_t):

nv12

i420

x

x

Errors

compile-time format check

Indicates an error when image format 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 to use the oneapi::ipl::copy:

// Create queue
sycl::queue queue{};

image<formats::rgba, std::uint8_t> src_image{ src_data_pointer, src_size };
image<formats::rgba, std::uint8_t> dst_image{ src_size };

(void)copy(queue, src_image, dst_image);

previous

Miscellaneous Operations

next

Normalization