Conv

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

Download PDF

ID 790148

Date 3/22/2024

Version

Public

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

Visible to Intel only — GUID: GUID-F26546FF-2F62-4CC2-888E-9849C8D0DE78

View Details

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:

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
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.

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

Parent topic: Convolution

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

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

Conv

Syntax

Include Files

Domain Dependencies

Parameters

Description

Return Values

Example

See Also