Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference

ID 790148
Date 3/22/2024
Public

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

Document Table of 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

    • Mh = Mf + Mg - 1

      where

      • Mf is the number of rows in the first source image matrix f

      • Mg is the number of rows in the second source image matrix g

    • Nh = Nf + Ng - 1

      where

      • Nf is the number of columns in the first source image matrix f

      • Ng is the number of columns in the second source image matrix g

    • 0 i < Mh, 0 i < Nh

  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

    • Mh = | Mf - Mg| + 1

      where

      • Mf is the number of rows in the first source image matrix f

      • Mg is the number of rows in the second source image matrix g

    • Nh = |Nf - Ng| + 1

      where

      • Nf is the number of columns in the first source image matrix f

      • Ng is the number of columns in the second source image matrix g

    • 0 i < Mh, 0 i < Nh

    This case assumes that MfMg and NfNg. In case when Mf < Mg and Nf < Ng, 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.

    NOTE:

    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 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;
}

See Also