Developer Reference

  • 2020
  • 10/21/2020
  • Public Content
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.
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 when
srcStep
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

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804