SwapChannels Operation#

Duplicates a source image while permuting its channels (e.g. RGB->GRB). The result may have more channels than its source by copying the same source channel to multiple destination channels.

Description

The swapchannels function operates on multi-channel image data to modify its channel order and copy into a result image. Its behavior is governed by an input permutation array, denoted as P, which consists of 3 or 4 elements, corresponding to channel indices of the source image.

  • If P has 3 elements, the output will be a 3-channel image, with channels rearranged as per the indices in P.

  • If P has 4 elements, the output will be a 4-channel image, again with channels rearranged based on P.

Formally, given a source image with channels C[1], C[2], C[3], (and optionally C[4]), and a permutation array P = [p[1], p[2], p[3]] (or [p[1], p[2], p[3], p[4]] for 4 channels):

  • The first channel of the result image will be C[p[1]]

  • The second channel of the result image will be C[p[2]]

  • The third channel of the result image will be C[p[3]]

  • If present, the fourth channel of the result image will be C[p[4]]

Note that the indices of the permutation array P must reference valid channels from the source image (up to 3 or 4 channels).

Special Behavior: When the specification is passed to the swapchannels function operating on a source image of 3 channels to produce a result image of 4 channels, the permutation array P may take on special values to indicate particular behavior:

  • If P[I] is 3, the result channel I will take on a given constant given to swapchannels

  • If P[I] is more than 3, the result channel I will not be written to

Headers

oneapi/ipl/misc/swapchannels.hpp

Syntax

template<typename SrcImageT, typename DstImageT>
sycl::event oneapi::ipl::swapchannels(sycl::queue &queue, SrcImageT &src, DstImageT &dst, const swapchannels_spec &spec, const typename DstImageT::data_t dst_fill_value = max_color_v<typename DstImageT::data_t>, const std::vector<sycl::event> &dependencies = {})#

Swap Channels.

Template Parameters:

  • SrcImageT – Source image type

  • DstImageT – Destination image type

Parameters:

  • queue – [in] SYCL queue

  • src – [in] source image

  • dst – [out] destination image

  • spec – [in] algorithmic specification

  • dst_fill_value – [in] constant to write to specified channels

  • dependencies – [in] other events dependencies

Returns:

SYCL event, that represents a status of an operation it associated with

Supported combinations for DataT/Layouts:

DataT/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 swapchannels_spec#

Swapchannels parameters.

Define a permutation array, P, of 4 integers that maps a destination channel, I, to a source channel, J. Swapchannels will generate a destination image from a source image by copying the source channels to the destination image channels. Formally, given a source image with channels C[1], C[2], C[3], (and optionally C[4]), and the permutation array P = [p[1], p[2], p[3], p[4]]:

  • The first channel of the destination image will be C[p[1]]

  • The second channel of the destination image will be C[p[2]]

  • The third channel of the destination image will be C[p[3]]

  • If present, the fourth channel of the destination image will be C[p[4]]

Special Behavior: When the specification is passed to the swapchannels function operating on a source image of 3 channels to produce a destination image of 4 channels, the permutation array P may take on special values to indicate particular behavior:

  • If P[I] is 3, the destination channel I will take on a given constant given to swapchannels

  • If P[I] is more than 3, the destination channel I will not be written to

Public Functions

swapchannels_spec(const swapchannels_spec &other) = default#

Construct Swapchannels spec from prior Swapchannels spec with default copy.

Parameters:

other – A Swapchannels spec from which to copy into a new Swapchannels spec.

inline swapchannels_spec(const sycl::vec<std::uint8_t, 3> &dst_order)#

Construct Swapchannels specification to generate a three channel image by permutating the channels of a source image.

Parameters:

dst_order – A 3 element array mapping the 3 channels of a destination image to channel numbers of a source image

inline swapchannels_spec(const sycl::vec<std::uint8_t, 4> &dst_order)#

Construct Swapchannels specification to generate a four channel image by permutating the channels of a source image.

Parameters:

dst_order – A 4 element array mapping the 4 channels of a destination image to channel numbers of a source image

const sycl::vec<std::uint8_t, 4> &get_dst_order() const noexcept#

Getter for mapping of each destination image channel number to a source image channel number.

Returns:

An array mapping each destination image channel number to a source image channel number

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.

invalid_argument exception

Indicates an error when the input channel permutation array contains a channel index beyond the number of channels of the source image.

The code example below demonstrates how oneapi::ipl::swapchannels 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 RGBA image data
ipl::image<ipl::layouts::channel4, std::uint8_t> src_image{ queue, p_image_data, image_size, allocator };
// Destination 4-channel image data (to be BGRA version of source)
ipl::image<ipl::layouts::channel4, std::uint8_t> dst_image{ image_size, allocator };

// Permutation argument copies channels to achieve RGBA -> BGRA conversion
const ipl::swapchannels_spec spec{ sycl::vec<std::uint8_t, 4>{ 2, 1, 0, 3 } };

// Apply Swap Channels to whole image
auto event = ipl::swapchannels(queue, src_image, dst_image, spec);