Intel® Integrated Performance Primitives Developer Guide and Reference

ID 790148
Date 11/07/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

SwapChannels

Copies channels of the source image to the destination image.

Syntax

Case 1: Not-in-place operation

IppStatus ippiSwapChannels_<mod>(const Ipp<datatype>* pSrc, int srcStep, Ipp<datatype>* pDst, int dstStep, IppiSize roiSize, const int dstOrder[3]);

Supported values for mod:

8u_C3R 16u_C3R 16s_C3R 32s_C3R 32f_C3R
8u_AC4R 16u_AC4R 16s_AC4R 32s_AC4R 32f_AC4R

IppStatus ippiSwapChannels_<mod>(const Ipp<datatype>* pSrc, int srcStep, Ipp<datatype>* pDst, int dstStep, IppiSize roiSize, const int dstOrder[4]);

Supported values for mod:

8u_C4R 16u_C4R 16s_C4R 32s_C4R 32f_C4R

Case 2: In-place operation

IppStatus ippiSwapChannels_8u_C3IR(Ipp8u* pSrcDst, int srcDstStep, IppiSize roiSize, const int dstOrder[3]);

IppStatus ippiSwapChannels_8u_C4IR(Ipp8u* pSrcDst, int srcDstStep, IppiSize roiSize, const int dstOrder[4]);

Case 3: Operation with converting 3-channel image to the 4-channel image

IppStatus ippiSwapChannels_<mod>(const Ipp<datatype>* pSrc, int srcStep, Ipp<datatype>* pDst, int dstStep, IppiSize roiSize, const int dstOrder[4], Ipp<datatype> val);

Supported values for mod:

8u_C3C4R 16u_C3C4R 16s_C3C4R 32s_C3C4R 32f_C3C4R

Case 4: Operation with converting 4-channel image to the 3-channel image

IppStatus ippiSwapChannels_<mod>(const Ipp<datatype>* pSrc, int srcStep, Ipp<datatype>* pDst, int dstStep, IppiSize roiSize, const int dstOrder[3]);

Supported values for mod:

8u_C4C3R 16u_C4C3R 16s_C4C3R 32s_C4C3R 32f_C4C3R

Include Files

ippi.h

Domain Dependencies

Headers: ippcore.h, ippvm.h, ipps.h

Libraries: ippcore.lib, ippvm.lib, ipps.lib

Parameters

pSrc

Pointer to the source image ROI.

srcStep

Distance in bytes between starts of consecutive lines in the source image.

pDst

Pointer to the destination image ROI.

dstStep

Distance in bytes between starts of consecutive lines in the destination image.

pSrcDst

Pointer to the source and destination ROI for in-place operation.

srcDstStep

Distance in bytes between starts of consecutive lines in the source and destination image for the in-place operation.

roiSize

Size of the source and destination ROI in pixels.

dstOrder

Order of channels in the destination image.

val

Constant value.

Description

This function operates with ROI (see Regions of Interest in Intel IPP).

This function copies the data from specified channels of the source image ROI pSrc to the specified channels of the destination image ROI pDst.

The first channel in the destination image is determined by the first component of dstOrder. Its value lies in the range [0..2] for a 3-channel image, and [0..3] for a 4-channel image, and indicates the corresponding channel number of the source image. Other channels are specified in the similar way. For example, if the sequence of channels in the source 3-channel image is A, B, C, and dstOrder[0]=2, dstOrder[1]=0, dstOrder[2]=1, then the order of channels in the 3-channel destination image is C, A, B. Some or all components of dstOrder may have the same values. It means that data from a certain channel of the source image may be copied to several channels of the destination image.

Some functions flavors convert a 3-channel source image to the 4-channel destination image (see Case 3). In this case an additional channel contains data from any specified source channel, or its pixel values are set to the specified constant value val (corresponding component dstOrder[n] should be set to 3), or its pixel values are not set at all (corresponding component dstOrder[n] should be set to an arbitrary value greater than 3). For example, the sequence of channels in the source 3-channel image is A, B, C, if dstOrder[0]=1, dstOrder[1]=0, dstOrder[2]=1, dstOrder[3]=2, then the order of channels in the 4-channel destination image will be B, A, B, C; if dstOrder[0]=4, dstOrder[1]=0, dstOrder[2]=1, dstOrder[3]=2, then the order of channels in the 4-channel destination image will be D, A, B, C, where D is a channel whose pixel values are not set.

The function flavors that support image with the alpha channel do not perform operation on it.

This function supports negative step values.

Return Values

ippStsNoErr

Indicates no error. Any other value indicates an error or a warning.

ippStsNullPtrErr

Indicates an error when any of the specified pointers is NULL.

ippStsSizeErr

Indicates an error condition if roiSize has a field with zero or negative value.

ippStsStepErr

Indicates an error condition if srcStep or dstStep has a zero value.

Example

The code example below shows how to use the function ippiSwapChannels_8u_C3R.

Ipp8u src[12*3] = { 255, 0,  0, 255, 0,  0, 255, 0,  0, 255, 0,  0,
                     0, 255, 0,  0, 255, 0,  0, 255, 0,  0, 255, 0, 
                     0,  0, 255, 0,  0, 255, 0,  0, 255, 0,  0, 255};
Ipp8u dst[12*3];
IppiSize roiSize = { 4, 3 };
int order[3] = { 2, 1, 0 }
		
ippiSwapChannels_8u_C3R ( src, 12, dst, 12, roiSize, order );
		
	
Result:   
src    [rgb]
		
255 0  0 255 0  0 255 0  0 255 0  0
0  255 0  0 255 0  0 255 0  0 255 0
0   0 255 0  0 255 0  0 255 0  0 255
		
dst    [bgr]
		
0   0 255 0  0 255 0  0 255 0  0 255
0  255 0  0 255 0  0 255 0  0 255 0
255 0  0 255 0  0 255 0  0 255 0  0