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

Convert

Converts image pixel values from one data type to another.

Syntax

Case 1: Conversion to increase bit depth and change signed to unsigned type

IppStatus ippiConvert_<mod>(const Ipp<srcDatatype>* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize);

Supported values for mod:

8u16u_C1R 8u16s_C1R 8u32s_C1R 8u32f_C1R 8s32s_C1R
8u16u_C3R 8u16s_C3R 8u32s_C3R 8u32f_C3R 8s32s_C3R
8u16u_C4R 8u16s_C4R 8u32s_C4R 8u32f_C4R 8s32s_C4R
8s32f_C1R 16u32s_C1R 16u32f_C1R 16s32s_C1R 16s32f_C1R
8s32f_C3R 16u32s_C3R 16u32f_C3R 16s32s_C3R 16s32f_C3R
8s32f_C4R 16u32s_C4R 16u32f_C4R 16s32s_C4R 16s32f_C4R
8s8u_C1Rs 16s16u_C1Rs 16u32u_C1R 32s32u_C1Rs 32u32f_C1R
8s16u_C1Rs 16s32u_C1Rs 32s32f_C1R
8s16s_C1R
8s32u_C1Rs
8s64f_C1R        

IppStatus ippiConvert_<mod>(const Ipp<srcDatatype>* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize);

Supported values for mod:

8u16u_AC4R 8u16s_AC4R 8u32s_AC4R 8u32f_AC4R 8s32s_AC4R
8s32f_AC4R 16u32s_AC4R 16u32f_AC4R 16s32s_AC4R 16s32f_AC4R

Case 2: Conversion to reduce bit depth and change unsigned to signed type: integer to integer type

IppStatus ippiConvert_<mod>(const Ipp<srcDatatype>* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize);

Supported values for mod:

16u8u_C1R 16s8u_C1R 32s8u_C1R 32s8s_C1R
16u8u_C3R 16s8u_C3R 32s8u_C3R 32s8s_C3R
16u8u_C4R 16s8u_C4R 32s8u_C4R 32s8s_C4R

IppStatus ippiConvert_<mod>(const Ipp<srcDatatype>* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize, IppRoundMode roundMode, int scaleFactor);

Supported values for mod:

8u8s_C1RSfs 16u8s_C1RSfs 32u8u_C1RSfs 32s16u_C1RSfs
16s8s_C1RSfs 32u8s_C1RSfs 32s16s_C1RSfs
16u16s_C1RSfs 32u16u_C1RSfs
32u16s_C1RSfs
32u32s_C1RSfs

IppStatus ippiConvert_<mod>(const Ipp<srcDatatype>* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize);

Supported values for mod:

16u8u_AC4R 16s8u_AC4R 32s8u_AC4R 32s8s_AC4R

Floating point to integer type:

IppStatus ippiConvert_<mod>(const Ipp32f* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize, IppRoundMode roundMode);

Supported values for mod:

32f8u_C1R 32f8s_C1R 32f16u_C1R 32f16s_C1R
32f8u_C3R 32f8s_C3R 32f16u_C3R 32f16s_C3R
32f8u_C4R 32f8s_C4R 32f16u_C4R 32f16s_C4R

IppStatus ippiConvert_<mod>(const Ipp<srcDatatype>* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize, IppRoundMode roundMode, int scaleFactor);

Supported values for mod:

32f8u_C1RSfs 32f8s_C1RSfs 32f16u_C1RSfs 32f16s_C1RSfs 32f32u_C1RSfs 32f32s_C1RSfs
64f8u_C1RSfs 64f8s_C1RSfs 64f16u_C1RSfs 64f16s_C1RSfs    

IppStatus ippiConvert_32f32u_C1IRSfs(Ipp32u* pSrcDst, int srcDstStep, IppiSize roiSize, IppRoundMode roundMode, int scaleFactor);

IppStatus ippiConvert_<mod>(const Ipp32f* pSrc, int srcStep, Ipp<dstDatatype>* pDst, int dstStep, IppiSize roiSize, IppRoundMode roundMode);

Supported values for mod:

32f8u_AC4R 32f8s_AC4R 32f16u_AC4R 32f16s_AC4R

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 the starting points of consecutive lines in the source image.

pDst

Pointer to the destination image ROI.

pSrcDst

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

dstStep

Distance, in bytes, between the starting points of consecutive lines in the destination image.

srcDstStep

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

roiSize

Size of the source and destination ROI in pixels.

scaleFactor

Scale factor (see Integer Result Scaling).

roundMode

Rounding mode, the following values are possible:

ippRndZero

specifies that floating-point values are truncated to zero,

ippRndNear

specifies that floating-point values are rounded to the nearest even integer when the fractional part equals 0.5; otherwise they are rounded to the nearest integer,

ippRndFinancial

specifies that floating-point values are rounded down to the nearest integer when the fractional part is less than 0.5, or rounded up to the nearest integer if the fractional part is equal or greater than 0.5.

Description

This function operates with ROI.

This function converts pixel values in the source image ROI pSrc to a different data type and writes them to the destination image ROI pDst.

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:

x = pSrc[i,j]

if (x > MAX_VAL) x = MAX_VAL

if (x < MIN_VAL) x = MIN_VAL

pDst[i,j] = (CASTING)x

If you want to shift data from the signed range to the unsigned range and vice-versa, see "Application Notes" below.

The function flavors with the Sfs descriptor in their names perform scaling of the internally computed results in accordance with the scaleFactor parameter.

When converting from floating-point to integer type, rounding defined by roundMode is performed, and the result is saturated to the destination data type range.

NOTE:

The bit order of each byte in the source image is inverse to the pixel order. It means that the first pixel in a row represents the last (seventh) bit of the first byte in a row.

Application Notes

When data is converted from the signed integer to the corresponding unsigned integer and vice versa (8s -->8u, 16u --> 16s), 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).

If you need just to shift the data from the signed range to the unsigned range and vice versa, use the function ippiXorC with the parameter value specified in such a way that the most significant bit is set to 1, and all other bits are set to 0. For example, if you want to convert pixel values from Ipps16s type to Ipp16u type with the rage shift call the function:

ippiXorC_16u_C1R( (Ipp16u *)pSrc, srcStep, 0x8000, pDst, dstStep, roiSize);

In this case the pixels values are converted as follows:

-32768 --> 0

-32767 --> 1

...

-1 --> 32767

0 --> 32768

1 --> 32769

...

32766 --> 65534

32767 --> 65535

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, with the exception of second mode in Case 4.

ippStsSizeErr

Indicates an error when roiSize has a field with zero or negative value, or srcBitOffset/dstBitOffset is less than zero.

ippStsStepErr

Indicates an error whensrcStep or dstStep has a zero or negative value.

ippStsMemAllocErr

Indicates an error when memory allocation fails.

Example

The code example below shows data conversion without scaling.

      IppStatus convert( void ) {

         IppiSize roi={5,4};
         Ipp32f x[5*4];      
       
         Ipp8u y[5*4];
         ippiSet_32f_C1R( -1.0f, x, 5*sizeof(Ipp32f), roi );
               x[1] = 300; x[2] = 150;

   return ippiConvert_32f8u_C1R( x, 5*sizeof(Ipp32f), y, 5, roi, ippRndNear );
   }

The destination image y contains:

   00 FF 96 00 00
   00 00 00 00 00
   00 00 00 00 00
   00 00 00 00 00