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

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

Functions
VPIStatus	vpiInitConvertImageFormatParams (VPIConvertImageFormatParams *params)
	Initialize VPIConvertImageFormatParams with default values. More...
VPIStatus	vpiSubmitConvertImageFormat (VPIStream stream, uint64_t backend, VPIImage input, VPIImage output, const VPIConvertImageFormatParams *params)
	Converts the image contents to the desired format, with optional scaling and offset. More...
VPIStatus	vpiSubmitConvertImageFormatPyramid (VPIStream stream, uint64_t backend, VPIPyramid input, VPIPyramid output, const VPIConvertImageFormatParams *params)
	Converts the pyramid 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.

Refer to Convert Image Format for more details and usage examples.

---

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 85 of file ConvertImageFormat.h.

Collaboration diagram for VPIConvertImageFormatParams:

Data Fields
VPIConversionPolicy	policy	Conversion policy to be used. VIC backend only supports VPI_CONVERSION_CLAMP.
float	scale	Scaling factor. Pass 1 for no scaling. VIC backend doesn't support scaling, it must be 1.
float	offset	Offset factor. Pass 0 for no offset. VIC backend doesn't support offset, it must be 0.
uint64_t	flags	Control flags. Valid values: 0: default, negation of all other flags. VPI_PRECISE : precise, potentially slower implementation.
VPIInterpolationType	chromaUpFilter	Interpolation to use for chroma upsampling. Valid values: Interpolation type CPU CUDA VIC VPI_INTERP_NEAREST * * 1 VPI_INTERP_LINEAR * VPI_INTERP_CATMULL_ROM * (1) Nearest-neighbor interpolation is currently accepted, but linear is performed instead.
VPIInterpolationType	chromaDownFilter	Interpolation to use for chroma downsampling. Valid values: Interpolation type CPU CUDA VIC VPI_INTERP_NEAREST * * * VPI_INTERP_LINEAR VPI_INTERP_CATMULL_ROM

Enumeration Type Documentation

VPIConversionPolicy

enum VPIConversionPolicy

#include </opt/nvidia/vpi3/include/vpi/Types.h>

Policy used when converting between image types.

Enumerator
VPI_CONVERSION_CLAMP	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.
VPI_CONVERSION_CAST	Casts input to the output type. Overflows and underflows are handled as per C specification, including situations of undefined behavior.
VPI_CONVERSION_INVALID	Invalid conversion.

Definition at line 290 of file Types.h.

Function Documentation

vpiInitConvertImageFormatParams()

VPIStatus vpiInitConvertImageFormatParams

(

VPIConvertImageFormatParams *

params

)

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

Initialize VPIConvertImageFormatParams with default values.

The following parameters are set:

• policy: VPI_CONVERSION_CLAMP
• scale: 1
• offset: 0
• flags: 0
• chromaUpFilter: VPI_INTERP_NEAREST
• chromaDownFilter: VPI_INTERP_NEAREST

Parameters

[out]

params

Pointer to structure to be filled. Must not be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	params is NULL.
VPI_SUCCESS	Operation executed successfully.

vpiSubmitConvertImageFormat()

VPIStatus vpiSubmitConvertImageFormat	(	VPIStream	stream,
		uint64_t	backend,
		VPIImage	input,
		VPIImage	output,
		const VPIConvertImageFormatParams *	params
	)

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

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

The input and output formats 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) \]

where:

• \(\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.

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

Supported format conversions.

• Conversion between image format's marked with an '*' aren't implemented.
• On CPU and CUDA, any pitch-linear format can be converted to itself, provided that scale is 1 and offset is 0.
• Formats within each table below can be converted between themselves.

CPU and CUDA	VIC
VPI_IMAGE_FORMAT_U8	VPI_IMAGE_FORMAT_Y8
VPI_IMAGE_FORMAT_U16	VPI_IMAGE_FORMAT_Y8_BL
VPI_IMAGE_FORMAT_S8	VPI_IMAGE_FORMAT_Y8_ER
VPI_IMAGE_FORMAT_S16	VPI_IMAGE_FORMAT_Y8_ER_BL
VPI_IMAGE_FORMAT_Y8_ER	VPI_IMAGE_FORMAT_NV12
VPI_IMAGE_FORMAT_Y16_ER	VPI_IMAGE_FORMAT_NV12_BL
VPI_IMAGE_FORMAT_NV12_ER*	VPI_IMAGE_FORMAT_NV12_ER
VPI_IMAGE_FORMAT_NV24_ER*	VPI_IMAGE_FORMAT_NV12_ER_BL
VPI_IMAGE_FORMAT_RGB8	VPI_IMAGE_FORMAT_NV24
VPI_IMAGE_FORMAT_BGR8	VPI_IMAGE_FORMAT_NV24_BL
VPI_IMAGE_FORMAT_RGBA8	VPI_IMAGE_FORMAT_NV24_ER
VPI_IMAGE_FORMAT_BGRA8	VPI_IMAGE_FORMAT_NV24_ER_BL
VPI_IMAGE_FORMAT_F32	VPI_IMAGE_FORMAT_YUYV
	VPI_IMAGE_FORMAT_YUYV_BL
	VPI_IMAGE_FORMAT_YUYV_ER
	VPI_IMAGE_FORMAT_YUYV_ER_BL
	VPI_IMAGE_FORMAT_UYVY
	VPI_IMAGE_FORMAT_UYVY_BL
	VPI_IMAGE_FORMAT_UYVY_ER
	VPI_IMAGE_FORMAT_UYVY_ER_BL
	VPI_IMAGE_FORMAT_RGBA8
	VPI_IMAGE_FORMAT_BGRA8

CPU and CUDA	VIC
VPI_IMAGE_FORMAT_2F32	VPI_IMAGE_FORMAT_Y16
	VPI_IMAGE_FORMAT_Y16_BL

VIC
VPI_IMAGE_FORMAT_Y16_ER
VPI_IMAGE_FORMAT_Y16_ER_BL

VIC
VPI_IMAGE_FORMAT_S16
VPI_IMAGE_FORMAT_S16_BL

• Conversions from left format to right and vice-versa are supported.

  CPU and CUDA
  VPI_IMAGE_FORMAT_Y8	VPI_IMAGE_FORMAT_S8
  VPI_IMAGE_FORMAT_Y16	VPI_IMAGE_FORMAT_S16
  	VPI_IMAGE_FORMAT_U8
  	VPI_IMAGE_FORMAT_U16
  	VPI_IMAGE_FORMAT_F32

Conversion among format with extended or studio ranges and non-color formats (i.e. U8, F32, S16, ...) will keep range unchanged, except for clamping or casting specified in VPIConvertImageFormatParams::policy.

Parameters

[in]	stream	A stream handle where the operation will be queued into. Must not be NULL. Stream must have enabled the backends that will execute the algorithm.
[in]	backend	Backend that will execute the algorithm. Valid values: VPI_BACKEND_CPU VPI_BACKEND_CUDA VPI_BACKEND_VIC
[in]	input	Input image to be converted. Must not be NULL. Image must have enabled the backends that will execute the algorithm. On VIC, when converting from format with 4:2:2(R) chroma subsampling to a format isn't YUV or chroma-subsampling is not 4:4:4, the image width must be even (no restriction on height).
[out]	output	Output image where result will be written to, with the desired format. Must not be NULL. Must have same dimensions as input image. Image must have enabled the backends that will execute the algorithm. On VIC, When converting to format with 4:2:0 or 4:2:2(R) chroma subsampling (i.e. YUYV or NV12), the image width and height must be even.
[in]	params	Parameters to fine tune the conversion. Pass NULL to use default values given by vpiInitConvertImageFormatParams.

Return values

VPI_ERROR_INVALID_ARGUMENT	stream is NULL.
VPI_ERROR_INVALID_ARGUMENT	input or output are NULL.
VPI_ERROR_INVALID_ARGUMENT	Invalid flags in params.
VPI_ERROR_INVALID_ARGUMENT	Invalid conversion type in params.
VPI_ERROR_INVALID_ARGUMENT	input and output image dimensions do not match.
VPI_ERROR_INVALID_ARGUMENT	output format can't be used with given image dimensions.
VPI_ERROR_INVALID_IMAGE_FORMAT	Format conversion not supported.
VPI_ERROR_NOT_IMPLEMENTED	Convert Image Format algorithm is not supported by given backend.
VPI_ERROR_INVALID_OPERATION	Hardware backend not available.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream, input or output.
VPI_SUCCESS	Operation executed successfully.

vpiSubmitConvertImageFormatPyramid()

VPIStatus vpiSubmitConvertImageFormatPyramid	(	VPIStream	stream,
		uint64_t	backend,
		VPIPyramid	input,
		VPIPyramid	output,
		const VPIConvertImageFormatParams *	params
	)

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

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

The input and output formats are inferred from the corresponding pyramids 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) \]

where:

• \(\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.

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

Supported format conversions.

• Conversion between image format's marked with an '*' aren't implemented.
• On CPU and CUDA, any pitch-linear format can be converted to itself, provided that scale is 1 and offset is 0.
• Formats within each table below can be converted between themselves.

CPU and CUDA	VIC
VPI_IMAGE_FORMAT_U8	VPI_IMAGE_FORMAT_Y8
VPI_IMAGE_FORMAT_U16	VPI_IMAGE_FORMAT_Y8_BL
VPI_IMAGE_FORMAT_S8	VPI_IMAGE_FORMAT_Y8_ER
VPI_IMAGE_FORMAT_S16	VPI_IMAGE_FORMAT_Y8_ER_BL
VPI_IMAGE_FORMAT_Y8_ER	VPI_IMAGE_FORMAT_NV12
VPI_IMAGE_FORMAT_Y16_ER	VPI_IMAGE_FORMAT_NV12_BL
VPI_IMAGE_FORMAT_NV12_ER*	VPI_IMAGE_FORMAT_NV12_ER
VPI_IMAGE_FORMAT_NV24_ER*	VPI_IMAGE_FORMAT_NV12_ER_BL
VPI_IMAGE_FORMAT_RGB8	VPI_IMAGE_FORMAT_NV24
VPI_IMAGE_FORMAT_BGR8	VPI_IMAGE_FORMAT_NV24_BL
VPI_IMAGE_FORMAT_RGBA8	VPI_IMAGE_FORMAT_NV24_ER
VPI_IMAGE_FORMAT_BGRA8	VPI_IMAGE_FORMAT_NV24_ER_BL
VPI_IMAGE_FORMAT_F32	VPI_IMAGE_FORMAT_YUYV
	VPI_IMAGE_FORMAT_YUYV_BL
	VPI_IMAGE_FORMAT_YUYV_ER
	VPI_IMAGE_FORMAT_YUYV_ER_BL
	VPI_IMAGE_FORMAT_UYVY
	VPI_IMAGE_FORMAT_UYVY_BL
	VPI_IMAGE_FORMAT_UYVY_ER
	VPI_IMAGE_FORMAT_UYVY_ER_BL
	VPI_IMAGE_FORMAT_RGBA8
	VPI_IMAGE_FORMAT_BGRA8

CPU and CUDA	VIC
VPI_IMAGE_FORMAT_2F32	VPI_IMAGE_FORMAT_Y16
	VPI_IMAGE_FORMAT_Y16_BL

VIC
VPI_IMAGE_FORMAT_Y16_ER
VPI_IMAGE_FORMAT_Y16_ER_BL

VIC
VPI_IMAGE_FORMAT_S16
VPI_IMAGE_FORMAT_S16_BL

• Conversions from left format to right and vice-versa are supported.

  CPU and CUDA
  VPI_IMAGE_FORMAT_Y8	VPI_IMAGE_FORMAT_S8
  VPI_IMAGE_FORMAT_Y16	VPI_IMAGE_FORMAT_S16
  	VPI_IMAGE_FORMAT_U8
  	VPI_IMAGE_FORMAT_U16
  	VPI_IMAGE_FORMAT_F32

Conversion among format with extended or studio ranges and non-color formats (i.e. U8, F32, S16, ...) will keep range unchanged, except for clamping or casting specified in VPIConvertImageFormatParams::policy.

Parameters

[in]	stream	A stream handle where the operation will be queued into. Must not be NULL. Stream must have enabled the backends that will execute the algorithm.
[in]	backend	Backend that will execute the algorithm. Valid values: VPI_BACKEND_CPU VPI_BACKEND_CUDA VPI_BACKEND_VIC
[in]	input	Input pyramid to be converted. Must not be NULL. Image must have enabled the backends that will execute the algorithm. On VIC, when converting from format with 4:2:2(R) chroma subsampling to a format isn't YUV or chroma-subsampling is not 4:4:4, the pyramid width in all levels must be even (no restriction on height).
[out]	output	Output pyramid where result will be written to, with the desired format. Must not be NULL. Must have same dimensions as input pyramid. Image must have enabled the backends that will execute the algorithm. On VIC, When converting to format with 4:2:0 or 4:2:2(R) chroma subsampling (i.e. YUYV or NV12), the pyramid width and height in all levels must be even.
[in]	params	Parameters to fine tune the conversion. Pass NULL to use default values given by vpiInitConvertImageFormatParams.

Return values

VPI_ERROR_INVALID_ARGUMENT	stream is NULL.
VPI_ERROR_INVALID_ARGUMENT	input or output are NULL.
VPI_ERROR_INVALID_ARGUMENT	Invalid flags in params.
VPI_ERROR_INVALID_ARGUMENT	Invalid conversion type in params.
VPI_ERROR_INVALID_ARGUMENT	input and output pyramid dimensions or number of levels do not match.
VPI_ERROR_INVALID_ARGUMENT	output format can't be used with given pyramid dimensions.
VPI_ERROR_INVALID_IMAGE_FORMAT	Format conversion not supported.
VPI_ERROR_NOT_IMPLEMENTED	Convert Image Format algorithm is not supported by given backend.
VPI_ERROR_INVALID_OPERATION	Hardware backend not available.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream, input or output.
VPI_SUCCESS	Operation executed successfully.