VPI - Vision Programming Interface

1.0 Release

Convert Image Format

Converts the image contents to the desired format, with optional pixel value scaling and offset. More...

Data Structures

struct  VPIConvertImageFormatParams
 Parameters for customizing image format conversion. More...


enum  VPIConversionPolicy
 Policy used when converting between image types. More...


VPIStatus vpiInitConvertImageFormatParams (VPIConvertImageFormatParams *params)
 Initialize VPIConvertImageFormatParams with default values. More...
VPIStatus vpiSubmitConvertImageFormat (VPIStream stream, uint32_t backend, VPIImage input, VPIImage output, const VPIConvertImageFormatParams *params)
 Converts the image contents to the desired format, with optional scaling and offset. More...

Detailed Description

Converts the image contents to the desired format, with optional pixel value scaling and offset.

Data Structure Documentation

◆ VPIConvertImageFormatParams

struct VPIConvertImageFormatParams

Parameters for customizing image format conversion.

These parameters are used to customize how the conversion will be made. Make sure to call vpiInitConvertImageFormatParams to initialize this structure before updating its attributes. This guarantees that new attributes added in future versions will have a suitable default value assigned.

Definition at line 84 of file ConvertImageFormat.h.

+ Collaboration diagram for VPIConvertImageFormatParams:
Data Fields
VPIInterpolationType chromaDownFilter Interpolation to use for chroma downsampling.
Currently all backends support VPI_INTERP_NEAREST only. Different values will be silently ignored.
VPIInterpolationType chromaUpFilter Interpolation to use for chroma upsampling.
VIC backend on Jetson Nano devices doesn't allow choosing of chroma upsampling filter. It will only use VPI_INTERP_NEAREST, no matter what value is chosen here.
uint32_t flags
float offset Offset factor.

Pass 0 for no offset. Control flags. Valid values:

  • 0: default, negation of all other flags.
  • VPI_PRECISE : precise, potentially slower implementation.
VPIConversionPolicy policy Conversion policy to be used.
float scale Scaling factor.

Pass 1 for no scaling.

Enumeration Type Documentation

◆ VPIConversionPolicy

#include <vpi/Types.h>

Policy used when converting between image types.


Clamps input to output's type range.

Overflows and underflows are mapped to the output type's maximum and minimum representable value, respectively. When output type is floating point, clamp behaves like cast.


Casts input to the output type.

Overflows and underflows are handled as per C specification, including situations of undefined behavior.


Invalid conversion.

Definition at line 229 of file Types.h.

Function Documentation

◆ vpiInitConvertImageFormatParams()

VPIStatus vpiInitConvertImageFormatParams ( VPIConvertImageFormatParams params)

#include <vpi/algo/ConvertImageFormat.h>

Initialize VPIConvertImageFormatParams with default values.

The following parameters are set:

  • scale: 1
  • offset: 0
  • flags: 0
  • chromaUpFilter: VPI_INTERP_LINEAR
  • chromaDownFilter: VPI_INTERP_LINEAR
[out]paramsPointer to structure to be filled. Must not be NULL.
An error code if params is NULL, VPI_SUCCESS otherwise.

◆ vpiSubmitConvertImageFormat()

VPIStatus vpiSubmitConvertImageFormat ( VPIStream  stream,
uint32_t  backend,
VPIImage  input,
VPIImage  output,
const VPIConvertImageFormatParams params 

#include <vpi/algo/ConvertImageFormat.h>

Converts the image contents to the desired format, with optional scaling and offset.

The input and output types are inferred from the corresponding images passed as parameters. When scaling and offset are fractional, input is converted to 32-bit floating point prior conversion takes place. The formula that relates input and output pixels is:

\[ out(x,y) = clamp_{[\mathsf{min_{out}},\mathsf{max_{out}}]}(in(x,y)*\alpha + \beta) \]


  • \(\mathsf{min_{out}}\) and \(\mathsf{max_{out}}\) are the minimum and maximum representable value by output image format. Exception is for floating point types, where limits are \([-\infty,\infty]\), i.e., no clamping is done.
  • \(\alpha\) is the scaling.
  • \(\beta\) is the offset.

float to integer conversion does returns the nearest integer number, rounding halfway cases away from zero.

When passing NULL as params argument, it'll use default values as the ones set by vpiInitConvertImageFormatParams.

[in]streamA stream handle where the operation will be queued into.
[in]backendBackend that will execute the algorithm.
[in]inputInput image to be converted.
[out]outputOutput image where result will be written to, with the desired type.
[in]paramsOptional parameters. Pass NULL for default.
an error code on failure else VPI_SUCCESS