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

ID 790148
Date 3/22/2024
Public
Document Table of Contents

FilterBorder

Filters a 3D image using a rectangular filter.

Syntax

IppStatus ipprFilterBorder_8u_C1V(const Ipp8u* pSrc, int srcPlaneStep, int srcStep, Ipp8u* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp8u borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_16s_C1V(const Ipp16s* pSrc, int srcPlaneStep, int srcStep, Ipp16s* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp16s borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_16u_C1V(const Ipp16u* pSrc, int srcPlaneStep, int srcStep, Ipp16u* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp16u borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_32f_C1V(const Ipp32f* pSrc, int srcPlaneStep, int srcStep, Ipp32f* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp32f borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_64f_C1V(const Ipp64f* pSrc, int srcPlaneStep, int srcStep, Ipp64f* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp64f borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

Platform-aware functions

IppStatus ipprFilterBorder_8u_C1V_L(const Ipp8u* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp8u* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp8u borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_16s_C1V_L(const Ipp16s* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp16s* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp16s borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_16u_C1V_L(const Ipp16u* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp16u* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp16u borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_32f_C1V_L(const Ipp32f* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp32f* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp32f borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_64f_C1V_L(const Ipp64f* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp64f* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp64f borderValue[1], const IpprFilterBorderSpec* pSpec, Ipp8u* pBuffer);

Threading Layer (TL) functions based on the Platform Aware API

IppStatus ipprFilterBorder_8u_C1V_LT(const Ipp8u* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp8u* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp8u borderValue[1], const IpprFilterBorderSpec_LT* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_16s_C1V_LT(const Ipp16s* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp16s* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp16s borderValue[1], const IpprFilterBorderSpec_LT* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_16u_C1V_LT(const Ipp16u* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp16u* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp16u borderValue[1], const IpprFilterBorderSpec_LT* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_32f_C1V_LT(const Ipp32f* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp32f* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp32f borderValue[1], const IpprFilterBorderSpec_LT* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_64f_C1V_LT(const Ipp64f* pSrc, IppSizeL srcPlaneStep, IppSizeL srcStep, Ipp64f* pDst, IppSizeL dstPlaneStep, IppSizeL dstStep, IpprVolumeL dstRoiVolume, IpprBorderType borderType, const Ipp64f borderValue[1], const IpprFilterBorderSpec_LT* pSpec, Ipp8u* pBuffer);

Threading Layer (TL) functions based on the Classic API

IppStatus ipprFilterBorder_8u_C1V_T(const Ipp8u* pSrc, int srcPlaneStep, int srcStep, Ipp8u* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp8u borderValue[1], const IpprFilterBorderSpec_T* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_16s_C1V_T(const Ipp16s* pSrc, int srcPlaneStep, int srcStep, Ipp16s* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp16s borderValue[1], const IpprFilterBorderSpec_T* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_16u_C1V_T(const Ipp16u* pSrc, int srcPlaneStep, int srcStep, Ipp16u* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp16u borderValue[1], const IpprFilterBorderSpec_T* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_32f_C1V_T(const Ipp32f* pSrc, int srcPlaneStep, int srcStep, Ipp32f* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp32f borderValue[1], const IpprFilterBorderSpec_T* pSpec, Ipp8u* pBuffer);

IppStatus ipprFilterBorder_64f_C1V_T(const Ipp64f* pSrc, int srcPlaneStep, int srcStep, Ipp64f* pDst, int dstPlaneStep, int dstStep, IpprVolume dstRoiVolume, IpprBorderType borderType, const Ipp64f borderValue[1], const IpprFilterBorderSpec_T* pSpec, Ipp8u* pBuffer);

Include Files

ippi.h

ippi_l.h

ippi_tl.h

Domain Dependencies

Headers: ippcore.h, ippvm.h, ipps.h

Libraries: ippcore.lib, ippvm.lib, ipps.lib

Parameters

pSrc

Array of pointers to the planes in the source volume.

srcStep

Distance, in bytes, between the starting points of consecutive lines in each plane of the source volume.

srcPlaneStep

Distance, in bytes, between the starting points of consecutive images in every plane of the source volume.

pDst

Array of pointers to the planes in the destination volume.

dstStep

Distance, in bytes, between the starting points of consecutive lines in each plane of the destination volume.

dstPlaneStep

Distance, in bytes, between the starting points of consecutive images in every plane of the source volume.

dstRoiVolume

Volume of the destination ROI in pixels.

borderType

Type of the border. Possible values are:

ipprBorderInMem

Border is obtained from the source image pixels in memory.

ipprBorderRepl

Border is replicated from the edge pixels.

ipprBorderConst

Border is replicated from the edge pixels.

borderValue

Constant value to assign to pixels of the constant border.

pSpec

Pointer to the filter specification structure.

pBuffer

Pointer to the work buffer for filtering operations.

Description

Before using this function, you need to initialize the filter specification structure for 3D image processing using the ipprFilterBorderInit function.

This function operates with VOI. This function performs linear filtering on a source image with the volume. Type of the image border is defined by the value of the border parameter.

Return Values

ippStsNoErr

Indicates no error condition. Any other value indicates an error condition.

ippStsStepErr

Indicates an error condition if srcPlaneStep, srcStep, dstPlaneStep, or dstStep has a field with negative value.

ippStsNullPtrErr

Indicates an error condition if the pSrc, pDst, pSpec, or pBuffer pointer is NULL.

ippStsSizeErr

Indicates an error condition if dstRoiVolume has a field with zero or negative value.

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 filtering an image using a general integer rectangular kernel
// implemented with Intel(R) Integrated Performance Primitives (Intel(R) IPP) functions:
//     ipprFilterBorderGetSize
//     ipprFilterBorderInit_16s
//     ipprFilterBorder_8u_C1R


#include <stdio.h>
#include "ipp.h"

#define WIDTH  128  /* image width */
#define HEIGHT  64  /* image height */
#define DEPTH  64  /* image depth */
const Ipp16s kernel[3*3*3] = { 0, 1, 0, 1, 0, 1, 0, 1, 0,
                               0, 1, 0, 1, 0, 1, 0, 1, 0 ,
                               0, 1, 0, 1, 0, 1, 0, 1, 0 };

/* 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;
    Ipp8u* pSrc = NULL, *pDst = NULL;     /* Pointers to source/destination images */
    IppSizeL srcPlaneStep =0, srcStep = 0, dstPlaneStep, dstStep = 0;         /* Steps, in bytes, through the source/destination images */
    IpprVolumeL  roiVolume = { WIDTH, HEIGHT, DEPTH }; /* Size of source/destination ROI in pixels */
    IpprVolumeL  kernelVolume = { 3, 3, 3};
    Ipp8u *pBuffer = NULL;                /* Pointer to the work buffer */
    IpprFilterBorderSpec* pSpec = NULL;   /* context structure */
    IppSizeL iTmpBufSize = 0, iSpecSize = 0;   /* Common work buffer size */
    IpprBorderType borderType = ipprBorderRepl;
    Ipp8u borderValue = 0;
    int numChannels = 1;

    pSrc = ippsMalloc_8u_L(roiVolume.width*roiVolume.height*roiVolume.depth);
    pDst = ippsMalloc_8u_L(roiVolume.width*roiVolume.height*roiVolume.depth);
    srcStep      = roiVolume.width;
    srcPlaneStep = roiVolume.height * srcStep;
    dstStep      = roiVolume.width;
    dstPlaneStep = roiVolume.height * srcStep;

    check_sts( status = ipprFilterBorderGetSize_L(kernelVolume, roiVolume, ipp8u, ipp16s, numChannels, &iSpecSize, &iTmpBufSize) )

    pSpec = (IpprFilterBorderSpec *)ippsMalloc_8u(iSpecSize);
    pBuffer = ippsMalloc_8u_L(iTmpBufSize);

    check_sts( status = ipprFilterBorderInit_16s_L(kernel, kernelVolume, 4, ipp8u, numChannels, pSpec) )

    check_sts(status = ipprFilterBorder_8u_C1V_L(pSrc, srcPlaneStep, srcStep, pDst, dstPlaneStep, dstStep, roiVolume, borderType, &borderValue, pSpec, pBuffer))

EXIT_MAIN
    ippsFree(pBuffer);
    ippsFree(pSpec);
    ippiFree(pSrc);
    ippiFree(pDst);
    printf("Exit status %d (%s)\n", (int)status, ippGetStatusString(status));
    return (int)status;
}

See Also