Developer Reference

  • 2020
  • 07/15/2020
  • Public Content
Contents

Conv

Performs two-dimensional convolution of two images.

Syntax

Case 1: Operating on integer data
IppStatus ippiConv_<mod>(const Ipp<datatype>*
pSrc1
, int
src1Step
, IppiSize
src1Size
, const Ipp<datatype>*
pSrc2
, int
src2Step
, IppiSize
src2Size
, Ipp<datatype>*
pDst
, int
dstStep
, int
divisor
, IppEnum
algType
, Ipp8u*
pBuffer
);
Supported values for
mod
8u_C1R
16s_C1R
8u_C3R
16s_C3R
8u_C4R
16s_C4R
Case 2: Operating on floating-point data
IppStatus ippiConv_<mod>(const Ipp32f*
pSrc1
, int
src1Step
, IppiSize
src1Size
, const Ipp32f*
pSrc2
, int
src2Step
, IppiSize
src2Size
, Ipp32f*
pDst
, int
dstStep
, IppEnum
algType
, Ipp8u*
pBuffer
);
Supported values for
mod
32f_C1R
32f_C3R
32f_C4R
Include Files
ippi.h
Domain Dependencies
Headers:
ippcore.h
,
ippvm.h
,
ipps.h
Libraries:
ippcore.lib
,
ippvm.lib
,
ipps.lib
Parameters
pSrc1
,
pSrc2
Pointers to the source images ROI.
src1Step
,
src2Step
Distance, in bytes, between the starting points of consecutive lines in the source images.
src1Size
,
src2Size
Size in pixels of the source images.
pDst
Pointer to the destination image ROI.
dstStep
Distance, in bytes, between the starting points of consecutive lines in the destination image.
divisor
The integer value by which the computed result is divided (for operations on integer data only).
algType
Bit-field mask for the algorithm type definition. Possible values are the results of composition of the
IppAlgType
and
IppiROIShape
values.
pBuffer
Pointer to the buffer for internal calculations.
Description
Before using this function, you need to compute the size of the work buffer using the
ippiConvGetBufferSize
function.
The
ippiConv
function operates with ROI. The type of convolution that function performs is defined by the value of the
algType
parameter:
  1. If the
    ippiROIFull
    flag is set, the function performs full two-dimensional finite linear convolution between two source images pointed by the
    pSrc1
    and
    pSrc2
    parameters. The resulting destination image
    h
    [
    i, j
    ] is computed by the following formula:
    where
    • M
      h
      = M
      f
      + M
      g
      - 1
      where
      • M
        f
        is the number of rows in the first source image matrix
        f
      • M
        g
        is the number of rows in the second source image matrix
        g
    • N
      h
      = N
      f
      + N
      g
      - 1
      where
      • N
        f
        is the number of columns in the first source image matrix
        f
      • N
        g
        is the number of columns in the second source image matrix
        g
    • 0
      i
      <
      M
      h
      , 0
      i
      <
      N
      h
  2. If the
    ippiROIValid
    flag is set up, the function performs valid two-dimensional finite linear convolution between two source images pointed by the
    pSrc1
    and
    pSrc2
    parameters. The destination image
    h
    [
    i, j
    ] obtained as a result of the function operation is computed by the following formula:
    where
    • M
      h
      = |
      M
      f
      -
      M
      g
      | + 1
      where
      • M
        f
        is the number of rows in the first source image matrix
        f
      • M
        g
        is the number of rows in the second source image matrix
        g
    • N
      h
      = |
      N
      f
      -
      N
      g
      | + 1
      where
      • N
        f
        is the number of columns in the first source image matrix
        f
      • N
        g
        is the number of columns in the second source image matrix
        g
    • 0
      i
      <
      M
      h
      , 0
      i
      <
      N
      h
    This case assumes that
    M
    f
    M
    g
    and
    N
    f
    N
    g
    . In case when
    M
    f
    <
    M
    g
    and
    N
    f
    <
    N
    g
    , the subscript index
    g
    in this equation must be replaced with the index
    f
    . For any other combination of source image sizes, the function performs no operation.
    The above formula provides the same result as in the case with the
    ippiROIFull
    flag, but produces only the part of the convolution image that is computed without zero-padded values.
Function flavors that accept input data of the
Ipp32f
type use the same summation formula, but without scaling of the result (
divisor
= 1 is assumed).
The following examples illustrate the function operation. For the source images
f
,
g
of size 3 x 5 represented as
with
g
=
f
:
  • for the
    ippiROIFull
    case, the resulting convolution image
    h
    is of size 5 x 9 and contains the following data:
  • for the
    ippiROIValid
    case, the resulting convolution image
    h
    is of size 1 x 1 and contains the following data:
    h
    = [11]
Return Values
ippStsNoErr
Indicates no error. Any other value indicates an error.
ippStsNullPtrErr
Indicates an error when any of the specified pointers is NULL.
ippStsSizeErr
Indicates an error when
src1Size
or
src2Size
has a zero or negative value.
ippStsStepErr
Indicates an error when
src1Step
,
src2Step
, or
dstStep
has a zero or negative value.
ippStsDivisorErr
Indicates an error when
divisor
has a zero value.
ippStsAlgTypeErr
Indicates an error when:
  • the result of the bitwise AND operation between the
    algType
    and
    ippAlgMask
    differs from the
    ippAlgAuto
    ,
    ippAlgDirect
    , or
    ippAlgFFT
    values;
  • the result of the bitwise AND operation between the
    algType
    and
    ippiROIMask
    differs from the
    ippiROIFull
    or
    ippiROIValid
    values.

Example

/******************************************************************************* * Copyright 2015-2020 Intel Corporation. * * This software and the related documents are Intel copyrighted materials, and * your use of them is governed by the express license under which they were * provided to you (License). Unless the License provides otherwise, you may not * use, modify, copy, publish, distribute, disclose or transmit this software or * the related documents without Intel's prior written permission. * * This software and the related documents are provided as is, with no express * or implied warranties, other than those that are expressly stated in the * License. *******************************************************************************/ // A simple example of performing full or valid 2-D convolution of two images using a general integer rectangular kernel // implemented with Intel(R) Integrated Performance Primitives (Intel(R) IPP) functions: // ippiConvGetBufferSize // ippiConv_16s_C1R #include <stdio.h> #include "ipp.h" #define WIDTH_DST 128 /* destination image width */ #define HEIGHT_DST 64 /* destination image height */ #define WIDTH_SRC 16 /* source image width */ #define HEIGHT_SRC 16 /* source image height */ /* Next two defines are created to simplify code reading and understanding */ #define EXIT_MAIN exitLine: /* Label for Exit */ #define check_sts(st) if((st) != ippStsNoErr) goto exitLine; /* Go to Exit if Intel(R) IPP function returned status different from ippStsNoErr */ /* Results of ippMalloc() are not validated because Intel(R) IPP functions perform bad arguments check and will return an appropriate status */ int main(void) { IppStatus status = ippStsNoErr; Ipp16s* pSrc1 = NULL, *pSrc2 = NULL, *pDst = NULL; /* Pointers to source/destination images */ int srcStep1 = 0, srcStep2 = 0, dstStep = 0; /* Steps, in bytes, through the source/destination images */ IppiSize dstSize = { WIDTH_DST, HEIGHT_DST }; /* Size of destination ROI in pixels */ IppiSize src1Size = { WIDTH_SRC, HEIGHT_SRC }; /* Size of destination ROI in pixels */ IppiSize src2Size = { WIDTH_SRC - 1, HEIGHT_SRC - 1 }; /* Size of destination ROI in pixels */ int divisor = 2; /* The integer value by which the computed result is divided */ Ipp8u *pBuffer = NULL; /* Pointer to the work buffer */ int iTmpBufSize = 0; /* Common work buffer size */ int numChannels = 1; IppEnum funCfgFull = (IppEnum)(ippAlgAuto | ippiROIFull | ippiNormNone); pSrc2 = ippiMalloc_16s_C1(src2Size.width, src2Size.height, &srcStep2); pSrc1 = ippiMalloc_16s_C1(src1Size.width, src1Size.height, &srcStep1); pDst = ippiMalloc_16s_C1(dstSize.width, dstSize.height, &dstStep); check_sts( status = ippiConvGetBufferSize(src1Size, src2Size, ipp16s, numChannels, funCfgFull, &iTmpBufSize) ) pBuffer = ippsMalloc_8u(iTmpBufSize); check_sts( status = ippiConv_16s_C1R(pSrc1, srcStep1, src1Size, pSrc2, srcStep2, src2Size, pDst, dstStep, divisor, funCfgFull, pBuffer) ) EXIT_MAIN ippsFree(pBuffer); ippiFree(pSrc1); ippiFree(pSrc2); ippiFree(pDst); printf("Exit status %d (%s)\n", (int)status, ippGetStatusString(status)); return (int)status; }

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