VPI - Vision Programming Interface

3.0 Release

Fast Fourier Transform

Operations that applies the Fast Fourier Transform and its inverse to 2D images. More...

Functions

VPIStatus vpiCreateFFT (uint64_t backends, int32_t inputWidth, int32_t inputHeight, const VPIImageFormat inFormat, const VPIImageFormat outFormat, VPIPayload *payload)
 Creates payload for direct Fast Fourier Transform algorithm. More...
 
VPIStatus vpiSubmitFFT (VPIStream stream, uint64_t backend, VPIPayload payload, VPIImage input, VPIImage output, uint64_t flags)
 Runs the direct Fast Fourier Transform on single image. More...
 
VPIStatus vpiCreateIFFT (uint64_t backends, int32_t outputWidth, int32_t outputHeight, const VPIImageFormat inFormat, const VPIImageFormat outFormat, VPIPayload *payload)
 Creates payload for inverse Fast Fourier Transform algorithm. More...
 
VPIStatus vpiSubmitIFFT (VPIStream stream, uint64_t backend, VPIPayload payload, VPIImage input, VPIImage output, uint64_t flags)
 Runs the inverse Fast Fourier Transform on single image. More...
 

Detailed Description

Operations that applies the Fast Fourier Transform and its inverse to 2D images.

Refer to FFT for more details and usage examples regarding FFT.

Refer to Inverse FFT for more details and usage examples regarding IFFT.

Both FFT and inverse FFT need a payload created during application initialization phase, where image dimensions, input and output formats are defined. The payload then can be used to submit operations on different images, as long as their dimensions and formats match what was defined during payload creation.

Function Documentation

◆ vpiCreateFFT()

VPIStatus vpiCreateFFT ( uint64_t  backends,
int32_t  inputWidth,
int32_t  inputHeight,
const VPIImageFormat  inFormat,
const VPIImageFormat  outFormat,
VPIPayload payload 
)

#include </opt/nvidia/vpi3/include/vpi/algo/FFT.h>

Creates payload for direct Fast Fourier Transform algorithm.

The created payload can then be used with vpiSubmitFFT.

Attention
For this function to succeed, it is required that the library libcufft.so.10 is installed in the system.
Parameters
[in]backendsVPI backend that will execute the algorithm.
[in]inputWidth,inputHeightDimensions of the input/output images to be used.
  • Must be >= 1x1.
  • With CPU backend, image width must be even.
[in]inFormatInput image format.
[in]outFormatOutput image format.
[out]payloadPointer to the payload variable that receives the created handle.
Return values
VPI_ERROR_INVALID_ARGUMENTpayload is NULL.
VPI_ERROR_INVALID_ARGUMENTinputWidth or inputHeight outside valid range.
VPI_ERROR_INVALID_ARGUMENTbackend refers to an invalid backend.
VPI_ERROR_NOT_IMPLEMENTEDFFT algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXTCurrent context is destroyed.
VPI_IMAGE_FORMAT_INVALIDoutFormat is not supported.
VPI_ERROR_OUT_OF_MEMORYCannot allocate required resources.
VPI_ERROR_INVALID_OPERATIONBackend isn't enabled in current context.
VPI_ERROR_INVALID_OPERATIONLibrary libcufft.so.10 isn't installed in the system.
VPI_SUCCESSOperation executed successfully.

◆ vpiSubmitFFT()

VPIStatus vpiSubmitFFT ( VPIStream  stream,
uint64_t  backend,
VPIPayload  payload,
VPIImage  input,
VPIImage  output,
uint64_t  flags 
)

#include </opt/nvidia/vpi3/include/vpi/algo/FFT.h>

Runs the direct Fast Fourier Transform on single image.

Parameters
[in]streamThe stream where the operation will be queued in.
  • Must not be NULL.
  • Stream must have enabled the backends that will execute the algorithm.
[in]backendBackend that will execute the algorithm.
  • Must be the backend specified during payload creation or 0 as a shorthand to use this backend.
[in]payloadPayload created with vpiCreateFFT
[in]inputInput image in space domain.
  • Must not be NULL.
  • Must have same format and dimensions as the one specified during payload creation.
  • Image must have enabled the backends that will execute the algorithm.
  • When using the CPU backend, input rows must be aligned to 4 bytes.
[out]outputImage where the result in frequency domain will be written to. The top left pixel of the output represents the DC (0 Hz) component.
  • Must not be NULL.
  • Must have same format as the one specified during payload creation.
  • Image must have enabled the backends that will execute the algorithm.
  • When using the CPU backend, output rows must be aligned to 4 bytes.
  • Output dimensions depends on input's based on input's format, as shown below:
    Input Format Output Size
    VPI_IMAGE_FORMAT_2F32 W x H
    VPI_IMAGE_FORMAT_F32 floor(W/2)+1 x H
  • When input is real, output contains only the left half of the full Hermitian (symmetric-conjugate).
[in]flagsControl flags.
  • Currently it must be 0.
Return values
VPI_ERROR_INVALID_ARGUMENTstream is NULL.
VPI_ERROR_INVALID_ARGUMENTinput or output are NULL.
VPI_ERROR_INVALID_ARGUMENTpayload is not created using vpiCreateFFT.
VPI_ERROR_INVALID_ARGUMENTinput image dimension and format does not match the ones associated with payload.
VPI_ERROR_INVALID_ARGUMENToutput image format does not match the one associated with payload.
VPI_ERROR_INVALID_ARGUMENTNon-supported flags.
VPI_ERROR_INVALID_ARGUMENToutput dimensions are non-conformant with input's.
VPI_ERROR_INVALID_PAYLOAD_TYPEpayload is invalid.
VPI_ERROR_INVALID_OPERATIONThe needed backends aren't enabled in stream, input or output.
VPI_SUCCESSOperation executed successfully.

◆ vpiCreateIFFT()

VPIStatus vpiCreateIFFT ( uint64_t  backends,
int32_t  outputWidth,
int32_t  outputHeight,
const VPIImageFormat  inFormat,
const VPIImageFormat  outFormat,
VPIPayload payload 
)

#include </opt/nvidia/vpi3/include/vpi/algo/FFT.h>

Creates payload for inverse Fast Fourier Transform algorithm.

The created payload can then be used with vpiSubmitIFFT.

Attention
For this function to succeed, it is required that the library libcufft.so.10 is installed in the system.
Parameters
[in]backendsVPI backend that will execute the algorithm.
[in]outputWidth,outputHeightOutput image dimensions.
  • Must be >= 1.
[in]inFormatInput image format.
[in]outFormatOutput image format.
  • Must have same format as the one specified during payload creation.
  • With CPU backend, output width must be even.
  • Supported formats:
[out]payloadPointer to the payload variable that receives the created handle.
Return values
VPI_ERROR_INVALID_ARGUMENTpayload is NULL.
VPI_ERROR_INVALID_ARGUMENToutputWidth or outputHeight outside valid range.
VPI_ERROR_INVALID_ARGUMENTbackends refers to an invalid backend.
VPI_ERROR_NOT_IMPLEMENTEDIFFT algorithm is not supported by given backend.
VPI_ERROR_INVALID_CONTEXTCurrent context is destroyed.
VPI_IMAGE_FORMAT_INVALIDoutFormat is not supported.
VPI_ERROR_OUT_OF_MEMORYCannot allocate required resources.
VPI_ERROR_INVALID_OPERATIONBackend isn't enabled in current context.
VPI_ERROR_INVALID_OPERATIONLibrary libcufft.so.10 isn't installed in the system.
VPI_SUCCESSOperation executed successfully.

◆ vpiSubmitIFFT()

VPIStatus vpiSubmitIFFT ( VPIStream  stream,
uint64_t  backend,
VPIPayload  payload,
VPIImage  input,
VPIImage  output,
uint64_t  flags 
)

#include </opt/nvidia/vpi3/include/vpi/algo/FFT.h>

Runs the inverse Fast Fourier Transform on single image.

Parameters
[in]streamA stream handle where the operation will be queued in.
  • Must not be NULL.
  • Stream must have enabled the backends that will execute the algorithm.
[in]backendBackend that will execute the algorithm.
  • Must be the backend specified during payload creation or 0 as a shorthand to use this backend.
[in]payloadPayload created with vpiCreateIFFT
[in]inputInput image in frequency domain. The top left pixel of the input represents the DC (0 Hz) component.
  • Must not be NULL.
  • Must have same format and dimensions as the one specified during payload creation.
  • Image must have enabled the backends that will execute the algorithm.
  • When using the CPU backend, input rows must be aligned to 4 bytes.
  • When output is real, input contains only the left half of the full Hermitian (symmetric-conjugate).
  • Input dimensions depends on output's based on output's format, as shown below:
    Output Format Input Size
    VPI_IMAGE_FORMAT_2F32 W x H
    VPI_IMAGE_FORMAT_F32 floor(W/2)+1 x H
[out]outputImage where the result in space domain will be written to.
  • Must not be NULL.
  • Must have same format as the one specified during payload creation.
  • Image must have enabled the backends that will execute the algorithm.
  • When using the CPU backend, output rows must be aligned to 4 bytes.
[in]flagsControl flags.
  • Valid values are a combination of one or more of the following flags:
    • 0 for default processing, where output scaled.
    • VPI_DENORMALIZED_OUTPUT : Output is left denormalized. This leads to faster execution as normalization isn't usually needed. Absence of this flag will scale the output, dividing it by the total pixel count. This makes the output the exact inverse of direct Fast Fourier Transform.
Return values
VPI_ERROR_INVALID_ARGUMENTstream is NULL.
VPI_ERROR_INVALID_ARGUMENTinput or output are NULL.
VPI_ERROR_INVALID_ARGUMENTpayload is not created using vpiCreateIFFT.
VPI_ERROR_INVALID_ARGUMENTinput image dimension and format does not match the ones associated with payload.
VPI_ERROR_INVALID_ARGUMENToutput image format does not match the one associated with payload.
VPI_ERROR_INVALID_ARGUMENTflags includes a non-supported flag.
VPI_ERROR_INVALID_ARGUMENToutput dimensions are non-conformant with input's.
VPI_ERROR_INVALID_PAYLOAD_TYPEpayload is invalid.
VPI_ERROR_INVALID_OPERATIONThe needed backends aren't enabled in stream, input or output.
VPI_SUCCESSOperation executed successfully.