Image Formats

group NVCV_C_CORE_IMAGETYPE

Pre-defined image formats. An image format defines how image pixels are interpreted. Each image format is defined by the following components:

NVCVColorModel
NVCVColorSpec
NVCVChromaSubsampling method (when applicable)
NVCVMemLayout
NVCVDataKind
NVCVSwizzle
NVCVAlphaType
Number of planes
Format packing of each plane.

These pre-defined formats are guaranteed to work with algorithms that explicitly support them. Image formats can also be user-defined using the nvcvMakeImageFormat family of functions.

Using user-defined image formats with algorithms can lead to undefined behavior (segfaults, etc), but usually it works as expected. Result of algorithms using these image formats must be checked for correctness, as it’s not guaranteed that they will work.

Defines

NVCV_IMAGE_FORMAT_NONE: Denotes a special image format that doesn’t represent any format.

NVCV_IMAGE_FORMAT_U8: Single plane with one 8-bit unsigned integer channel.

NVCV_IMAGE_FORMAT_U8_BL: Single plane with one block-linear 8-bit unsigned integer channel.

NVCV_IMAGE_FORMAT_S8: Single plane with one 8-bit signed integer channel.

NVCV_IMAGE_FORMAT_U16: Single plane with one 16-bit unsigned integer channel.

NVCV_IMAGE_FORMAT_U32: Single plane with one 32-bit unsigned integer channel.

NVCV_IMAGE_FORMAT_S32: Single plane with one 32-bit signed integer channel.

NVCV_IMAGE_FORMAT_S16: Single plane with one 16-bit signed integer channel.

NVCV_IMAGE_FORMAT_S16_BL: Single plane with one block-linear 16-bit signed integer channel.

NVCV_IMAGE_FORMAT_2S16: Single plane with two interleaved 16-bit signed integer channel.

NVCV_IMAGE_FORMAT_2S16_BL: Single plane with two interleaved block-linear 16-bit signed integer channel.

NVCV_IMAGE_FORMAT_F16: Single plane with one 16-bit floating point channel.

NVCV_IMAGE_FORMAT_F32: Single plane with one 32-bit floating point channel.

NVCV_IMAGE_FORMAT_F64: Single plane with one 64-bit floating point channel.

NVCV_IMAGE_FORMAT_2F16: Single plane with two interleaved 16-bit floating point channels.

NVCV_IMAGE_FORMAT_2F32: Single plane with two interleaved 32-bit floating point channels.

NVCV_IMAGE_FORMAT_C64: Single plane with one 64-bit complex floating point channel.

NVCV_IMAGE_FORMAT_2C64: Single plane with two interleaved 64-bit complex floating point channels.

NVCV_IMAGE_FORMAT_C128: Single plane with one 128-bit complex floating point channel.

NVCV_IMAGE_FORMAT_2C128: Single plane with two interleaved 128-bit complex floating point channels.

NVCV_IMAGE_FORMAT_Y8: Single plane with one pitch-linear 8-bit unsigned integer channel with limited-range luma (grayscale) information. Values range from 16 to 235. Below this range is considered black, above is considered white.

NVCV_IMAGE_FORMAT_Y8_BL: Single plane with one block-linear 8-bit unsigned integer channel with limited-range luma (grayscale) information. Values range from 16 to 235. Below this range is considered black, above is considered white.

NVCV_IMAGE_FORMAT_Y8_ER: Single plane with one pitch-linear 8-bit unsigned integer channel with full-range luma (grayscale) information. Values range from 0 to 255.

NVCV_IMAGE_FORMAT_Y8_ER_BL: Single plane with one block-linear 8-bit unsigned integer channel with full-range luma (grayscale) information. Values range from 0 to 255.

NVCV_IMAGE_FORMAT_Y16: Single plane with one pitch-linear 16-bit unsigned integer channel with limited-range luma (grayscale) information. Values range from 4096 to 60160. Below this range is considered black, above is considered white.

NVCV_IMAGE_FORMAT_Y16_BL: Single plane with one block-linear 16-bit unsigned integer channel with limited-range luma (grayscale) information. Values range from 4096 to 60160. Below this range is considered black, above is considered white.

NVCV_IMAGE_FORMAT_Y16_ER: Single plane with one pitch-linear 16-bit unsigned integer channel with full-range luma (grayscale) information. Values range from 0 to 65535.

NVCV_IMAGE_FORMAT_Y16_ER_BL: Single plane with one block-linear 16-bit unsigned integer channel with full-range luma (grayscale) information. Values range from 0 to 65535.

NVCV_IMAGE_FORMAT_NV12

YUV420sp 8-bit pitch-linear format with limited range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 16 to 235.
Two interleaved 8-bit channels with chroma (Cb,Cr). Values range from 16 to 240. Resolution is half of luma plane, both horizontally and vertically. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_NV12_BL

YUV420sp 8-bit block-linear format with limited range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 16 to 235.
Two interleaved 8-bit channels with chroma (Cb,Cr). Values range from 0 to 255. Resolution is half of luma plane, both horizontally and vertically. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_NV12_ER

YUV420sp 8-bit pitch-linear format with full range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 0 to 255.
Two interleaved 8-bit channels with chroma (Cb,Cr). Values range from 0 to 255. Resolution is half of luma plane, both horizontally and vertically. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_NV12_ER_BL

YUV420sp 8-bit block-linear format with full range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 0 to 255.
Two interleaved 8-bit channels with chroma (Cb,Cr). Values range from 0 to 255. Resolution is half of luma plane, both horizontally and vertically. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_NV21

YUV420sp 8-bit block-linear format with limited range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 16 to 255.
Two interleaved 8-bit channels with chroma (Cr,Cb). Values range from 0 to 255. Resolution is half of luma plane, both horizontally and vertically. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_NV21_ER

YUV420sp 8-bit pitch-linear format with full range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 0 to 255.
Two interleaved 8-bit channels with chroma (Cr,Cb). Values range from 0 to 255. Resolution is half of luma plane, both horizontally and vertically. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_NV24

YUV444sp 8-bit pitch-linear format with limited range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 16 to 235.
Two interleaved 8-bit channels with chroma (Cb,Cr). Values range from 16 to 240. It has the same resolution as luma plane. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_NV24_BL

YUV444sp 8-bit block-linear format with limited range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 16 to 235.
Two interleaved 8-bit channels with chroma (Cb,Cr). Values range from 0 to 255. It has the same resolution as luma plane. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_NV24_ER

YUV444sp 8-bit pitch-linear format with full range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 0 to 255.
Two interleaved 8-bit channels with chroma (Cb,Cr). Values range from 0 to 255. It has the same resolution as luma plane. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_NV24_ER_BL

YUV444sp 8-bit block-linear format with full range. Format is composed of two planes:

One 8-bit channel with luma (Y’). Values range from 0 to 255.
Two interleaved 8-bit channels with chroma (Cb,Cr). Values range from 0 to 255. It has the same resolution as luma plane. For a given pixel, Cb channel has lower memory address than Cr.

NVCV_IMAGE_FORMAT_UYVY: YUV422 8-bit pitch-linear format in one plane with UYVY ordering and limited range.

NVCV_IMAGE_FORMAT_UYVY_BL: YUV422 8-bit block-linear format in one plane with UYVY ordering and limited range.

NVCV_IMAGE_FORMAT_UYVY_ER: YUV422 8-bit pitch-linear format in one plane with UYVY ordering and full range.

NVCV_IMAGE_FORMAT_UYVY_ER_BL: YUV422 8-bit block-linear format in one plane with UYVY ordering and full range.

NVCV_IMAGE_FORMAT_YUYV: YUV422 8-bit pitch-linear format in one plane with YUYV ordering and limited range. Also known as YUY2 format.

NVCV_IMAGE_FORMAT_YUYV_BL: YUV422 8-bit block-linear format in one plane with YUYV ordering and limited range. Also known as YUY2 format.

NVCV_IMAGE_FORMAT_YUYV_ER: YUV422 8-bit pitch-linear format in one plane with YUYV ordering and full range. Also known as YUY2 format.

NVCV_IMAGE_FORMAT_YUYV_ER_BL: YUV422 8-bit block-linear format in one plane with YUYV ordering and full range. Also known as YUY2 format.

NVCV_IMAGE_FORMAT_YUV8: Single plane with interleaved YUV 8-bit channel.

NVCV_IMAGE_FORMAT_RGB8: Single plane with interleaved RGB 8-bit channel.

NVCV_IMAGE_FORMAT_BGR8: Single plane with interleaved BGR 8-bit channel.

NVCV_IMAGE_FORMAT_RGBA8: Single plane with interleaved RGBA 8-bit channel.

NVCV_IMAGE_FORMAT_BGRA8: Single plane with interleaved BGRA 8-bit channel.

NVCV_IMAGE_FORMAT_RGB8p: Planar RGB unsigned 8-bit per channel.

NVCV_IMAGE_FORMAT_BGR8p: Planar BGR unsigned 8-bit per channel.

NVCV_IMAGE_FORMAT_RGBA8p: Planar RGBA unsigned 8-bit per channel.

NVCV_IMAGE_FORMAT_BGRA8p: Planar BGRA unsigned 8-bit per channel.

NVCV_IMAGE_FORMAT_RGBf16: Single plane with interleaved RGB float16 channel.

NVCV_IMAGE_FORMAT_BGRf16: Single plane with interleaved BGR float16 channel.

NVCV_IMAGE_FORMAT_RGBAf16: Single plane with interleaved RGBA float16 channel.

NVCV_IMAGE_FORMAT_BGRAf16: Single plane with interleaved BGRA float16 channel.

NVCV_IMAGE_FORMAT_RGBf16p: Planar RGB unsigned float16 per channel.

NVCV_IMAGE_FORMAT_BGRf16p: Planar BGR unsigned float16 per channel.

NVCV_IMAGE_FORMAT_RGBAf16p: Planar RGBA unsigned float16 per channel.

NVCV_IMAGE_FORMAT_BGRAf16p: Planar BGRA unsigned float16 per channel.

NVCV_IMAGE_FORMAT_RGBf32: Single plane with interleaved RGB float32 channel.

NVCV_IMAGE_FORMAT_BGRf32: Single plane with interleaved BGR float32 channel.

NVCV_IMAGE_FORMAT_RGBAf32: Single plane with interleaved RGBA float32 channel.

NVCV_IMAGE_FORMAT_BGRAf32: Single plane with interleaved BGRA float32 channel.

NVCV_IMAGE_FORMAT_RGBf32p: Planar RGB unsigned float32 per channel.

NVCV_IMAGE_FORMAT_BGRf32p: Planar BGR unsigned float32 per channel.

NVCV_IMAGE_FORMAT_RGBAf32p: Planar RGBA unsigned float32 per channel.

NVCV_IMAGE_FORMAT_BGRAf32p: Planar BGRA unsigned float32 per channel.

NVCV_IMAGE_FORMAT_HSV8: Single plane with interleaved HSV 8-bit channel.

NVCV_IMAGE_FORMAT_CMYK8: Single plane with interleaved CMYK 8-bit channel.

NVCV_IMAGE_FORMAT_YCCK8: Single plane with interleaved YCCK 8-bit channel.

NVCV_IMAGE_FORMAT_RGBA8_UNASSOCIATED_ALPHA: Single plane with interleaved RGBA 8-bit channel with alpha channel is unassociated

NVCV_IMAGE_FORMAT_RGB8_1U_U8: Single plane with interleaved RGB 8-bit channel and 1 extra 8-bit unspecified channel

NVCV_IMAGE_FORMAT_RGB8_7U_U8: Single plane with interleaved RGB 8-bit channel and 7 extra 8-bit unspecified channel

NVCV_IMAGE_FORMAT_RGBA8_3U_U16: Single plane with interleaved RGBA 8-bit channels and 3 extra 16-bit unspecified channel

NVCV_IMAGE_FORMAT_RGBA8_3POS3D_U32: Single plane with interleaved RGBA 8-bit channel and 3 extra 32-bit unsigned int 3D position channels

NVCV_IMAGE_FORMAT_RGB8_3D_F32: Single plane with interleaved RGB 8-bit channel and 3 extra 32-bit float depth channels

Typedefs

typedef uint64_t NVCVImageFormat

Functions

NVCV_PUBLIC NVCVStatus nvcvMakeYCbCrImageFormat (NVCVImageFormat *outFormat, NVCVColorSpec colorSpec, NVCVChromaSubsampling chromaSub, NVCVMemLayout memLayout, NVCVDataKind dataKind, NVCVSwizzle swizzle, NVCVPacking packing0, NVCVPacking packing1, NVCVPacking packing2, NVCVPacking packing3, NVCVAlphaType alphaType, const NVCVExtraChannelInfo *exChannelInfo)

Creates a user-defined YCbCr color image format constant.

Example to create a YUV422R ITU-R BT.709 full-range with SMPTE240M transfer function, block-linear format. If there is no alpha channel, the value of alphaType does not matter.

NVCVImageFormat fmt = NVCV_MAKE_YCbCr_IMAGE_FORMAT(NVCV_MAKE_COLOR_SPEC(BT601, SMPTE240M, FULL),
                                                 NVCV_CSS_422R, NVCV_BLOCK_LINEAR, NVCV_DATA_KIND_UNSIGNED, NVCV_SWIZZLE_XYZ0,
                                                 NVCV_ALPHA_ASSOCIATED, 2, NVCV_PACKING_X8, NVCV_PACKING_X8_Y8);

If 4 extra 32-bit floating point Depth type channels are needed in the image then use NVCV_MAKE_YCbCr_IMAGE_EXTRA_CHANNELS_FORMAT macro as follows. Note : extra channels are only supported in non-planar format. Using extra channels with planar format will result in unexpected behavior

NVCVImageFormat fmt = NVCV_MAKE_YCbCr_IMAGE_EXTRA_CHANNELS_FORMAT(NVCV_MAKE_COLOR_SPEC(BT601, SMPTE240M, FULL),
                                                 NVCV_CSS_444, NVCV_BLOCK_LINEAR, NVCV_DATA_KIND_UNSIGNED, NVCV_SWIZZLE_XYZ0,
                                                 NVCV_ALPHA_ASSOCIATED, 4, 32, NVCV_DATA_KIND_FLOAT, NVCV_EXTRA_CHANNEL_D,
                                                 1, NVCV_PACKING_X8_Y8_Z8)

Fourth plane (packing3) must have at most 64bpp.

Example to create a RGB planar ITU-R BT.709 full-range with SMPTE240M encoding, block-linear format.

NVCVImageFormat fmt = NVCV_MAKE_COLOR_IMAGE_FORMAT(NVCV_COLOR_MODEL_RGB, NVCV_MAKE_COLOR_SPEC(BT601, SMPTE240M, FULL),
                                                 NVCV_MEM_LAYOUT_BL, NVCV_DATA_KIND_UNSIGNED, NVCV_SWIZZLE_XYZ0,
                                                 NVCV_ALPHA_ASSOCIATED, 2, NVCV_PACKING_X8, NVCV_PACKING_X8, NVCV_PACKING_Y8);

Similarly to create a RGB interleaved ITU-R BT.709 full-range with SMPTE240M encoding, block-linear format with 3 extra channels of unsigned 16-bit 3D position.

NVCVImageFormat fmt = NVCV_MAKE_COLOR_IMAGE_EXTRA_CHANNELS_FORMAT(NVCV_COLOR_MODEL_RGB, NVCV_MAKE_COLOR_SPEC(BT601, SMPTE240M, FULL),
                                                 NVCV_MEM_LAYOUT_BL, NVCV_DATA_KIND_UNSIGNED, NVCV_SWIZZLE_XYZ0, NVCV_ALPHA_ASSOCIATED,
                                                 3, 16, NVCV_DATA_KIND_UNSIGNED, NVCV_EXTRA_CHANNEL_POS3D,
                                                 1, NVCV_PACKING_X8_Y8_Z8)

If the color model is NVCV_COLOR_MODEL_YCbCr, it’s assumed that the chroma subsampling is 4:4:4, i.e, NVCV_CSS_444.

Example to create 3-plane float block-linear image, 1st: 8-bit, 2nd: 16-bit, 3rd: 32-bit

NVCVImageFormat fmt = NVCV_MAKE_NONCOLOR_IMAGE_FORMAT(NVCV_MEM_LAYOUT_BL, NVCV_DATA_KIND_UNSIGNED,
                                                   3, NVCV_PACKING_X8, NVCV_PACKING_X16, NVCV_PACKING_X32);

Similarly to create a 1-plane float block-linear image with 8-bit unsigned integer data and 2 extra unspecified channels of type 8-bit unsigned integer

NVCVImageFormat fmt = NVCV_MAKE_NONCOLOR_IMAGE_EXTRA_CHANNELS_FORMAT(NVCV_MEM_LAYOUT_BL, NVCV_DATA_KIND_UNSIGNED, NVCV_SWIZZLE_X000,
                                                   NVCV_ALPHA_ASSOCIATED, 2, 8, NVCV_DATA_KIND_UNSIGNED, NVCV_EXTRA_CHANNEL_U,
                                                   1, NVCV_PACKING_X8)

Example to create a RGGB Bayer pattern format:

NVCVImageFormat fmt = NVCV_MAKE_RAW_IMAGE_FORMAT(NVCV_RAW_BAYER_RGGB, NVCV_MEM_LAYOUT_BL,
                                               NVCV_DATA_KIND_UNSIGNED, NVCV_SWIZZLE_X000, NVCV_ALPHA_ASSOCIATED,
                                               1, NVCV_PACKING_X8);

For the same format with 3 extra unspecified channels of datatype 16-bit signed, the following macro should be used

NVCVImageFormat fmt = NVCV_MAKE_RAW_IMAGE_EXTRA_CHANNELS_FORMAT(NVCV_RAW_BAYER_RGGB, NVCV_MEM_LAYOUT_BL,
                                               NVCV_DATA_KIND_UNSIGNED, NVCV_SWIZZLE_X000, NVCV_ALPHA_ASSOCIATED,
                                               3, 16, NVCV_DATA_KIND_SIGNED, NVCV_EXTRA_CHANNEL_U,
                                               1, NVCV_PACKING_X8);

When the pre-defined image formats aren’t enough, user-defined image formats can be created.

Fourth plane (packing3) must have at most 64bpp.

Warning

It’s not guaranteed that algorithms will work correctly with use-defined image formats. It’s recommended to check if the results are correct prior deploying the solution in a production environment.

Parameters:

colorModel – [in] NVCVColorModel to be used.
colorSpec – [in] NVCVColorSpec to be used.
chromaSubsamp – [in] NVCVChromaSubsampling to be used.
memLayout – [in] NVCVMemLayout to be used.
dataKind – [in] NVCVDataKind to be used.
swizzle – [in] NVCVSwizzle operation to be performed on the channels.
alphaType – [in] NVCVAlphaType to be used.
numExtraChannels – [in] Number of extra channels (maximum 7).
extraChannelsBPP – [in] Bits per pixel of the extra channels.
extraChannelDataKind – [in] NVCVDataKind to be used.
extraChannelType – [in] NVCVExtraChannel to be used.
numPlanes – [in] Number of planes this format has.
packing0, packing1, packing2, packing3 – [in] Format packing of each plane. Exactly #numPlanes packings must be passed.
colorModel – [in] NVCVColorModel to be used.
colorSpec – [in] NVCVColorSpec to be used.
memLayout – [in] NVCVMemLayout to be used.
dataKind – [in] NVCVDataKind to be used.
swizzle – [in] NVCVSwizzle operation to be performed on the channels.
alphaType – [in] NVCVAlphaType to be used.
numExtraChannels – [in] Number of extra channels (maximum 7).
extraChannelsBPP – [in] Bits per pixel of the extra channels.
extraChannelDataKind – [in] NVCVDataKind to be used.
extraChannelType – [in] NVCVExtraChannel to be used.
numPlanes – [in] Number of planes this format has.
packing0, packing1, packing2, packing3 – [in] Format packing of each plane. Exactly #numPlanes packings must be passed.
- Fourth plane (packing3), if passed, must have at most 64bpp.
numExtraChannels – [in] Number of extra channels beyond 4 channels.
extraChannelDataKind – [in] NVCVDataKind to be used. Data kind of extra channels
memLayout – [in] NVCVMemLayout to be used.
dataKind – [in] NVCVDataKind to be used.
swizzle – [in] NVCVSwizzle operation to be performed on the channels.
alphaType – [in] NVCVAlphaType to be used.
numExtraChannels – [in] Number of extra channels (maximum 7).
extraChannelsBPP – [in] Bits per pixel of the extra channels.
extraChannelDataKind – [in] NVCVDataKind to be used.
extraChannelType – [in] NVCVExtraChannel to be used.
numPlanes – [in] Number of planes this format has.
packing0, packing1, packing2, packing3 – [in] Format packing of each plane. Exactly #numPlanes packings must be passed.
- Fourth plane (packing3), if passed, must have at most 64bpp.
rawPattern – [in] NVCVRawPattern to be used.
memLayout – [in] NVCVMemLayout to be used.
dataKind – [in] NVCVDataKind to be used.
swizzle – [in] NVCVSwizzle operation to be performed on the channels.
alphaType – [in] NVCVAlphaType to be used.
numExtraChannels – [in] Number of extra channels (maximum 7).
extraChannelsBPP – [in] Bits per pixel of the extra channels.
extraChannelDataKind – [in] NVCVDataKind to be used.
extraChannelType – [in] NVCVExtraChannel to be used.
numPlanes – [in] Number of planes this format has.
packing – [in] Format packing of image plane.
outFormat – [out] The created image format.
- Cannot be NULL.
colorSpec – [in] NVCVColorSpec to be used.
chromaSub – [in] NVCVChromaSubsampling to be used.
memLayout – [in] NVCVMemLayout to be used.
dataKind – [in] NVCVDataKind to be used.
swizzle – [in] NVCVSwizzle operation to be performed on the channels.
packing0, packing1, packing2, packing3 – [in] Format packing of each plane.
- When remaining planes aren’t needed, pass NVCV_PACKING_0 for them.
alphaType – [in] NVCVAlphaType to be used. Default: NVCV_ALPHA_ASSOCIATED.
exChannelInfo – [in] NVCVExtraChannelInfo to be used. Default: NULL.

Returns:

The user-defined image format. Creates a user-defined color image format constant.

Returns:

The user-defined image format. Creates a user-defined non-color image format constant.

Returns:

The user-defined image format. Creates a user-defined raw (Bayer pattern) image format constant.

Returns:

The user-defined image format. Creates a user-defined YCbCr color image format.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvMakeColorImageFormat (NVCVImageFormat *outFormat, NVCVColorModel colorModel, NVCVColorSpec colorSpec, NVCVMemLayout memLayout, NVCVDataKind dataKind, NVCVSwizzle swizzle, NVCVPacking packing0, NVCVPacking packing1, NVCVPacking packing2, NVCVPacking packing3, NVCVAlphaType alphaType, const NVCVExtraChannelInfo *exChannelInfo)

Creates a user-defined color image format.

When the pre-defined image formats aren’t enough, user-defined image formats can be created.

If the color model is

NVCV_COLOR_MODEL_YCbCr, it’s assumed that the chroma subsampling is 4:4:4, i.e, NVCV_CSS_444.

Warning

It’s not guaranteed that algorithms will work correctly with use-defined image formats. It’s recommended to check if the results are correct prior deploying the solution in a production environment.

Parameters:

outFormat – [out] The created image format.
- Cannot be NULL.
colorModel – [in] NVCVColorModel to be used.
colorSpec – [in] NVCVColorSpec to be used.
memLayout – [in] NVCVMemLayout to be used.
dataKind – [in] NVCVDataKind to be used.
swizzle – [in] NVCVSwizzle operation to be performed on the channels.
packing0, packing1, packing2, packing3 – [in] Format packing of each plane.
- When remaining planes aren’t needed, pass NVCV_PACKING_0 for them.
- Fourth plane (packing3) must have at most 64bpp.
alphaType – [in] NVCVAlphaType to be used. Default: NVCV_ALPHA_ASSOCIATED.
exChannelInfo – [in] NVCVExtraChannelInfo to be used. Default: NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvMakeNonColorImageFormat (NVCVImageFormat *outFormat, NVCVMemLayout memLayout, NVCVDataKind dataKind, NVCVSwizzle swizzle, NVCVPacking packing0, NVCVPacking packing1, NVCVPacking packing2, NVCVPacking packing3, NVCVAlphaType alphaType, const NVCVExtraChannelInfo *exChannelInfo)

Creates a user-defined non-color image format.

When the pre-defined non-color image formats aren’t enough, it is possible to define new ones.

Warning

It’s not guaranteed that algorithms will work correctly with use-defined image formats. It’s recommended to check if the results are correct prior deploying the solution in a production environment.

Parameters:

outFormat – [out] The created image format.
- Cannot be NULL.
memLayout – [in] NVCVMemLayout to be used.
dataKind – [in] NVCVDataKind to be used.
swizzle – [in] NVCVSwizzle operation to be performed on the channels.
packing0, packing1, packing2, packing3 – [in] Format packing of each plane.
- When remaining planes aren’t needed, pass NVCV_PACKING_0 for them.
- Fourth plane (packing3) must have at most 64bpp.
alphaType – [in] NVCVAlphaType to be used. Default: NVCV_ALPHA_ASSOCIATED.
exChannelInfo – [in] NVCVExtraChannelInfo to be used. Default: NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvMakeRawImageFormat (NVCVImageFormat *outFormat, NVCVRawPattern rawPattern, NVCVMemLayout memLayout, NVCVDataKind dataKind, NVCVSwizzle swizzle, NVCVPacking packing0, NVCVPacking packing1, NVCVPacking packing2, NVCVPacking packing3, NVCVAlphaType alphaType, const NVCVExtraChannelInfo *exChannelInfo)

Creates a user-defined raw image format.

When the pre-defined raw image formats aren’t enough, it is possible to define new ones.

Warning

It’s not guaranteed that algorithms will work correctly with use-defined image formats. It’s recommended to check if the results are correct prior deploying the solution in a production environment.

Parameters:

outFormat – [out] The created image format.
- Cannot be NULL.
rawPattern – [in] NVCVRawPattern to be used.
memLayout – [in] NVCVMemLayout to be used.
dataKind – [in] NVCVDataKind to be used.
swizzle – [in] NVCVSwizzle operation to be performed on the channels.
packing0, packing1, packing2, packing3 – [in] Format packing of each plane.
- When remaining planes aren’t needed, pass NVCV_PACKING_0 for them.
- Fourth plane (packing3) must have at most 64bpp.
alphaType – [in] NVCVAlphaType to be used. Default: NVCV_ALPHA_ASSOCIATED.
exChannelInfo – [in] NVCVExtraChannelInfo to be used. Default: NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvMakeImageFormatFromFourCC (NVCVImageFormat *outFormat, uint32_t fourcc, NVCVColorSpec colorSpec, NVCVMemLayout memLayout)

Creates a image format from a FourCC code.

See https://www.fourcc.org for more information about FourCC.

Parameters:

outFormat – [out] The image format corresponding to the FourCC code.
- Cannot be NULL.
fourcc – [in] FourCC code.
colorSpec – [in] NVCVColorSpec to be used.
memLayout – [in] NVCVMemLayout to be used.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatToFourCC (NVCVImageFormat fmt, uint32_t *outFourCC)

Returns the FourCC code corresponding to an image format.

Parameters:

fmt – [in] Image format to be queried.
outFourCC – [out] The FourCC code corresponding to the image format.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetPlanePacking (NVCVImageFormat fmt, int32_t plane, NVCVPacking *outPacking)

Get the packing for a given plane of an image format.

Parameters:

fmt – [in] Image format to be queried.
plane – [in] Which plane whose packing must be returned. If plane doesn’t exist, outPacking will be set to NVCV_PACKING_0.
outPacking – [out] The plane’s format packing.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetPlaneSize (NVCVImageFormat fmt, int32_t plane, int32_t imgWidth, int32_t imgHeight, int32_t *outPlaneWidth, int32_t *outPlaneHeight)

Get the plane width of an image with the given image format and width.

Parameters:

fmt – [in] Image format to be queried.
imgWidth, imgHeight – [in] Size of the image.
- Must be >= 1.
plane – [in] Image plane to be queried.
- Must be >= 0 and < the number of planes in the image format.
outPlaneWidth, outPlaneHeight – [out] The size of the image plane. Only the non-NULL parameter will be returned.
- Cannot be both NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatSetSwizzleAndPacking (NVCVImageFormat *fmt, NVCVSwizzle swizzle, NVCVPacking packing0, NVCVPacking packing1, NVCVPacking packing2, NVCVPacking packing3)

Replaces the swizzle and packing of an existing image format.

The number of channels represented by the swizzle must be equal to the sum of the number of channels represented by the packings. For instance, XYZ1 -> X8,X8Y8 is a valid combination with 3 channels. XYZW -> X8,X8Y8 isn’t as swizzle has 4 channels, and X8,X8Y8 represents in total 3 channels.

Parameters:

fmt – [inout] Image format to have its packing replaced.
- Cannot be NULL.
swizzle – [in] The new swizzle.
packing0, packing1, packing2, packing3 – [in] New packing per plane.
- If replacing the fourth packing (packing3), the packing’s bits per pixel must be at most 64.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetPlaneBitsPerPixel (NVCVImageFormat fmt, int32_t plane, int32_t *outBPP)

Get the image format’s plane bits per pixel count.

Parameters:

fmt – [in] Image format to be queried.
plane – [in] Which plane is to be queried.
outBPP – [out] The number of bits per pixel the given format plane has. If plane doesn’t exist (even if >= 4), it returns 0.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatSetDataKind (NVCVImageFormat *fmt, NVCVDataKind dataKind)

Set the image format’s data type.

Parameters:

fmt – [inout] Image format have its data type replaced.
- Cannot be NULL.
dataKind – [in] The new data type.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetDataKind (NVCVImageFormat fmt, NVCVDataKind *outDataKind)

Get the image format’s data type.

Parameters:

fmt – [in] Image format to be queried.
outDataKind – [out] The image format’s data type.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetSwizzle (NVCVImageFormat fmt, NVCVSwizzle *outSwizzle)

Get the image format’s channel swizzle operation.

Parameters:

fmt – [in] Image format to be queried.
outSwizzle – [out] The image format’s swizzle operation.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetPlaneSwizzle (NVCVImageFormat fmt, int32_t plane, NVCVSwizzle *outPlaneSwizzle)

Get the swizzle operation of the given image format’s plane.

Parameters:

fmt – [in] Image format to be queried.
- Image format should have less packing channels and swizzle channels.
plane – [in] Plane to be queried.
- Valid values range from 0 (first) to 3 (fourth and last) plane.
outPlaneSwizzle – [out] The channel swizzle operation performed in the given plane.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatSetMemLayout (NVCVImageFormat *fmt, NVCVMemLayout memLayout)

Set the image format’s memory layout.

Parameters:

fmt – [inout] Image format have its memory layout replaced.
- Cannot be NULL.
memLayout – [in] The new memory layout.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetMemLayout (NVCVImageFormat fmt, NVCVMemLayout *outMemLayout)

Get the image format’s memory layout.

Parameters:

fmt – [in] Image format to be queried.
outMemLayout – [out] The image format’s memory layout.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatSetColorSpec (NVCVImageFormat *fmt, NVCVColorSpec colorSpec)

Set the image format’s color standard.

Parameters:

fmt – [inout] Image format have its color spec replaced.
- Cannot be NULL.
- Format’s color model must represent image coding systems, such as RGB, Y’CrCb, HSV, etc.
colorSpec – [in] The new color standard.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetColorSpec (NVCVImageFormat fmt, NVCVColorSpec *outColorSpec)

Get the image format’s color standard.

Parameters:

fmt – [in] Image format to be queried.
outColorSpec – [out] The image format’s color standard.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetColorModel (NVCVImageFormat fmt, NVCVColorModel *outColorModel)

Get the image format’s color model.

Parameters:

fmt – [in] Image format to be queried.
outColorModel – [out] The image format’s color model.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatSetChromaSubsampling (NVCVImageFormat *fmt, NVCVChromaSubsampling css)

Set the image format’s chroma subsampling type.

Parameters:

fmt – [inout] Image format have its chroma subsampling type replaced.
- It’s only applicable if format has YCbCr color model.
- Cannot be NULL.
css – [in] The new chroma subsampling type.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetChromaSubsampling (NVCVImageFormat fmt, NVCVChromaSubsampling *outCSS)

Get the image format’s chroma subsampling type.

Parameters:

fmt – [in] Image format to be queried.
outCSS – [out] The image format’s chroma subsampling type.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetPlaneNumChannels (NVCVImageFormat fmt, int32_t plane, int32_t *outPlaneNumChannels)

Get the number of channels in a plane of an image format.

Parameters:

fmt – [in] Image format to be queried.
plane – [in] Plane to be queried.
- Valid values range from 0 (first) to 3 (fourth and last) plane.
outPlaneNumChannels – [out] Number of channels in the given plane.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetNumPlanes (NVCVImageFormat fmt, int32_t *outNumPlanes)

Get the number of planes of an image format.

Parameters:

fmt – [in] Image format to be queried.
outNumPlanes – [out] Number of planes defined by the given image format.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetNumChannels (NVCVImageFormat fmt, int32_t *outNumChannels)

Get the total number of channels of an image format.

Parameters:

fmt – [in] Image format to be queried.
outNumChannels – [out] The sum of all channel counts in all planes.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetBitsPerChannel (NVCVImageFormat fmt, int32_t *bits)

Get the image format’s bit size for each channel.

Parameters:

fmt – [in] Image format to be queried.
bits – [out] Pointer to an int32_t array with 4 elements where output will be stored.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetPlaneDataType (NVCVImageFormat fmt, int32_t plane, NVCVDataType *outPixType)

Get the data type of image format’s plane.

Parameters:

fmt – [in] Image format to be queried.
plane – [in] Plane to be queried.
- Valid values range from 0 (first) to 3 (fourth and last) plane.
- Cannot be NULL.
outPixType – [out] The data type of the given plane.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetPlaneFormat (NVCVImageFormat fmt, int32_t plane, NVCVImageFormat *outFormat)

Get the plane format of an image format.

Parameters:

fmt – [in] Image format to be queried.
plane – [in] Plane to be queried.
- Valid values range from 0 (first) to 3 (fourth and last) plane.
outFormat – [out] The image format of the given plane.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetPlanePixelStrideBytes (NVCVImageFormat fmt, int32_t plane, int32_t *outStrideBytes)

Get the stride of the pixel in the given plane of an image format.

Parameters:

fmt – [in] Image format to be queried.
plane – [in] Plane to be queried.
- Valid values range from 0 (first) to 3 (fourth and last) plane.
outStrideBytes – [out] Stride (size) of the pixel in bytes.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvMakeImageFormatFromPlanes (NVCVImageFormat *outFormat, NVCVImageFormat plane0, NVCVImageFormat plane1, NVCVImageFormat plane2, NVCVImageFormat plane3)

Constructs an image format given the format of each plane.

Parameters:

outFormat – [out] The image format whose planes have the given formats.
plane0, plane1, plane2, plane3 – [in] Image format of each plane.
- When plane doesn’t exist, pass NVCV_IMAGE_FORMAT_NONE,
- All plane formats must have only 1 plane.
- First plane must have a valid packing.
- Total number of channels must be at most 4.
- Color spec, mem layout and data type of all planes must be the same.
- Only one kind of chroma subsampling is allowed.
- At least one channel is allowed.
- All planes after the first invalid one must be invalid.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC const char * nvcvImageFormatGetName (NVCVImageFormat fmt)

Returns a string representation of the image format.

Parameters:: fmt – [in] Image format whose name is to be returned.
Returns:: The string representation of the image format. Returned string is valid until next call of this function from the same calling thread. Returned pointer must not be freed.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetRawPattern (NVCVImageFormat fmt, NVCVRawPattern *outRawPattern)

Returns the raw color pattern of the image format.

Parameters:

fmt – [in] Image format to be queried.
- Its color model must be NVCV_COLOR_MODEL_RAW .
outRawPattern – [out] The raw pattern of given raw image format.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatSetRawPattern (NVCVImageFormat *fmt, NVCVRawPattern rawPattern)

Sets the raw color pattern of the image format.

Parameters:

fmt – [inout] Image format to be updated.
- Its color model must be NVCV_COLOR_MODEL_RAW.
- Cannot be NULL.
rawPattern – [in] The new raw pattern.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatHasSameDataLayout (NVCVImageFormat a, NVCVImageFormat b, int8_t *outBool)

Returns whether the image formats have the same data layout.

Data layout referts to how pixels are laid out in memory. It doesn’t take into account the format’s color information.

The following characteristics are taken into account:

memory layout (block linear, pitch linear, …)
data type (signed, unsigned, float, …)
Swizzle (except for 1/0 in 4th channel)
number of planes
packings (X8_Y8, X16, …)
chroma subsampling (4:4:4, 4:2:0, …)

Parameters:

a, b – [in] Image formats to be compared.
outBool – [out] != 0 if image formats compares equal with respect to how pixels are laid out in memory, 0 otherwise.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetAlphaType (NVCVImageFormat fmt, NVCVAlphaType *outAlphaChannelType)

Get the image format’s alpha Channel type.

Parameters:

fmt – [in] Image format to be queried.
outAlphaChannelType – [out] The image format’s alpha channel type.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatSetAlphaType (NVCVImageFormat *fmt, NVCVAlphaType alphaChannelType)

Set the image format’s alpha channel type.

Parameters:

fmt – [inout] Image format have its data type replaced.
- Cannot be NULL.
alphaChannelType – [in] The new alphaChannel type.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatGetExtraChannelInfo (NVCVImageFormat fmt, NVCVExtraChannelInfo *outExChannelInfo)

Get the image format’s extra channel information.

Parameters:

fmt – [in] Image format to be queried.
outExChannelInfo – [out] The image format’s extra channel information.
- Cannot be NULL.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.

NVCV_PUBLIC NVCVStatus nvcvImageFormatSetExtraChannelInfo (NVCVImageFormat *fmt, const NVCVExtraChannelInfo *exChannelInfo)

Set the image format’s extra channel information.

Parameters:

fmt – [inout] Image format have its data type replaced.
- Cannot be NULL.
exChannelInfo – [in] The new extra channel info.

Return values:

NVCV_ERROR_INVALID_ARGUMENT – Some argument is outside its valid range.
NVCV_SUCCESS – Operation executed successfully.