Video Encoding/Decoding#

Detailed Description#

Classes#

Name	Description
`struct` `cv::cudacodec::EncodeQp`	View details
`class` `cv::cudacodec::EncoderCallback`	Interface for encoder callbacks. View details
`struct` `cv::cudacodec::EncoderParams`	Different parameters for CUDA video encoder. View details
`struct` `cv::cudacodec::FormatInfo`	Struct providing information about video file format. : View details
`class` `cv::cudacodec::NVSurfaceToColorConverter`	Class for converting the raw YUV Surface output from VideoReader if output color format is set to ColorFormat::NV_YUV_SURFACE_FORMAT (VideoReader::set(ColorFormat::NV_YUV_SURFACE_FORMAT)) to the requested ColorFormat. View details
`class` `cv::cudacodec::RawVideoSource`	Interface for video demultiplexing. : View details
`class` `cv::cudacodec::VideoReader`	Video reader interface, see createVideoReader(). View details
`struct` `cv::cudacodec::VideoReaderInitParams`	VideoReader initialization parameters. View details
`class` `cv::cudacodec::VideoWriter`	Video writer interface, see createVideoWriter(). View details

Enumerations#

enum cv::cudacodec::BitDepth {
    cv::cudacodec::EIGHT = 0,
    cv::cudacodec::SIXTEEN = 1,
    cv::cudacodec::UNCHANGED = 2
}

Bit depth of the frame returned by VideoReader::nextFrame() and VideoReader::retrieve() View details

enum cv::cudacodec::ChromaFormat {
    cv::cudacodec::Monochrome = 0,
    cv::cudacodec::YUV420,
    cv::cudacodec::YUV422,
    cv::cudacodec::YUV444,
    cv::cudacodec::NumFormats
}

Chroma formats supported by cudacodec::VideoReader. View details

enum cv::cudacodec::Codec {
    cv::cudacodec::MPEG1 = 0,
    cv::cudacodec::MPEG2,
    cv::cudacodec::MPEG4,
    cv::cudacodec::VC1,
    cv::cudacodec::H264,
    cv::cudacodec::JPEG,
    cv::cudacodec::H264_SVC,
    cv::cudacodec::H264_MVC,
    cv::cudacodec::HEVC,
    cv::cudacodec::VP8,
    cv::cudacodec::VP9,
    cv::cudacodec::AV1,
    cv::cudacodec::NumCodecs,
    cv::cudacodec::Uncompressed_YUV420 = (('I' << 24) | ('Y' << 16) | ('U' << 8) | ('V')),
    cv::cudacodec::Uncompressed_YV12 = (('Y' << 24) | ('V' << 16) | ('1' << 8) | ('2')),
    cv::cudacodec::Uncompressed_NV12 = (('N' << 24) | ('V' << 16) | ('1' << 8) | ('2')),
    cv::cudacodec::Uncompressed_YUYV = (('Y' << 24) | ('U' << 16) | ('Y' << 8) | ('V')),
    cv::cudacodec::Uncompressed_UYVY = (('U' << 24) | ('Y' << 16) | ('V' << 8) | ('Y'))
}

Video codecs supported by cudacodec::VideoReader and cudacodec::VideoWriter. View details

enum cv::cudacodec::ColorFormat {
    cv::cudacodec::UNDEFINED = 0,
    cv::cudacodec::BGRA = 1,
    cv::cudacodec::BGR = 2,
    cv::cudacodec::GRAY = 3,
    cv::cudacodec::RGB = 5,
    cv::cudacodec::RGBA = 6,
    cv::cudacodec::NV_YUV_SURFACE_FORMAT = 7,
    cv::cudacodec::NV_NV12 = 4,
    cv::cudacodec::NV_YV12 = 8,
    cv::cudacodec::NV_IYUV = 9,
    cv::cudacodec::NV_YUV444 = 10,
    cv::cudacodec::NV_AYUV = 11,
    cv::cudacodec::NV_YUV420_10BIT = 12,
    cv::cudacodec::NV_YUV444_10BIT = 13
}

ColorFormat for the frame returned by VideoReader::nextFrame() and VideoReader::retrieve() or used to initialize a VideoWriter. View details

enum struct cv::cudacodec::ColorSpaceStandard {
    cv::cudacodec::ColorSpaceStandard::BT709 = 1,
    cv::cudacodec::ColorSpaceStandard::Unspecified = 2,
    cv::cudacodec::ColorSpaceStandard::Reserved = 3,
    cv::cudacodec::ColorSpaceStandard::FCC = 4,
    cv::cudacodec::ColorSpaceStandard::BT470 = 5,
    cv::cudacodec::ColorSpaceStandard::BT601 = 6,
    cv::cudacodec::ColorSpaceStandard::SMPTE240M = 7,
    cv::cudacodec::ColorSpaceStandard::YCgCo = 8,
    cv::cudacodec::ColorSpaceStandard::BT2020 = 9,
    cv::cudacodec::ColorSpaceStandard::BT2020C = 10
}

Video Signal Description Color Primaries of the VideoReader source (section E.2.1 VUI parameters semantics of H265 spec file) View details

enum cv::cudacodec::DeinterlaceMode {
    cv::cudacodec::Weave = 0,
    cv::cudacodec::Bob = 1,
    cv::cudacodec::Adaptive = 2
}

Deinterlacing mode used by decoder. View details

enum cv::cudacodec::EncodeMultiPass {
    cv::cudacodec::ENC_MULTI_PASS_DISABLED = 0x0,
    cv::cudacodec::ENC_TWO_PASS_QUARTER_RESOLUTION = 0x1,
    cv::cudacodec::ENC_TWO_PASS_FULL_RESOLUTION = 0x2
}

Multi Pass Encoding. View details

enum cv::cudacodec::EncodeParamsRcMode {
    cv::cudacodec::ENC_PARAMS_RC_CONSTQP = 0x0,
    cv::cudacodec::ENC_PARAMS_RC_VBR = 0x1,
    cv::cudacodec::ENC_PARAMS_RC_CBR = 0x2
}

Rate Control Modes. View details

enum cv::cudacodec::EncodePreset {
    cv::cudacodec::ENC_PRESET_P1 = 1,
    cv::cudacodec::ENC_PRESET_P2 = 2,
    cv::cudacodec::ENC_PRESET_P3 = 3,
    cv::cudacodec::ENC_PRESET_P4 = 4,
    cv::cudacodec::ENC_PRESET_P5 = 5,
    cv::cudacodec::ENC_PRESET_P6 = 6,
    cv::cudacodec::ENC_PRESET_P7 = 7
}

Nvidia Encoding Presets. Performance degrades and quality improves as we move from P1 to P7. View details

enum cv::cudacodec::EncodeProfile {
    cv::cudacodec::ENC_CODEC_PROFILE_AUTOSELECT = 0,
    cv::cudacodec::ENC_H264_PROFILE_BASELINE = 1,
    cv::cudacodec::ENC_H264_PROFILE_MAIN = 2,
    cv::cudacodec::ENC_H264_PROFILE_HIGH = 3,
    cv::cudacodec::ENC_H264_PROFILE_HIGH_444 = 4,
    cv::cudacodec::ENC_H264_PROFILE_STEREO = 5,
    cv::cudacodec::ENC_H264_PROFILE_PROGRESSIVE_HIGH = 6,
    cv::cudacodec::ENC_H264_PROFILE_CONSTRAINED_HIGH = 7,
    cv::cudacodec::ENC_HEVC_PROFILE_MAIN = 8,
    cv::cudacodec::ENC_HEVC_PROFILE_MAIN10 = 9,
    cv::cudacodec::ENC_HEVC_PROFILE_FREXT = 10
}

Supported Encoder Profiles. View details

enum cv::cudacodec::EncodeTuningInfo {
    cv::cudacodec::ENC_TUNING_INFO_UNDEFINED = 0,
    cv::cudacodec::ENC_TUNING_INFO_HIGH_QUALITY = 1,
    cv::cudacodec::ENC_TUNING_INFO_LOW_LATENCY = 2,
    cv::cudacodec::ENC_TUNING_INFO_ULTRA_LOW_LATENCY = 3,
    cv::cudacodec::ENC_TUNING_INFO_LOSSLESS = 4,
    cv::cudacodec::ENC_TUNING_INFO_COUNT
}

Tuning information. View details

enum cv::cudacodec::SurfaceFormat {
    cv::cudacodec::SF_NV12 = 0,
    cv::cudacodec::SF_P016 = 1,
    cv::cudacodec::SF_YUV444 = 2,
    cv::cudacodec::SF_YUV444_16Bit = 3
}

Video surface formats output by the decoder. View details

enum struct cv::cudacodec::VideoReaderProps {
    cv::cudacodec::VideoReaderProps::PROP_DECODED_FRAME_IDX = 0,
    cv::cudacodec::VideoReaderProps::PROP_EXTRA_DATA_INDEX = 1,
    cv::cudacodec::VideoReaderProps::PROP_RAW_PACKAGES_BASE_INDEX = 2,
    cv::cudacodec::VideoReaderProps::PROP_NUMBER_OF_RAW_PACKAGES_SINCE_LAST_GRAB = 3,
    cv::cudacodec::VideoReaderProps::PROP_RAW_MODE = 4,
    cv::cudacodec::VideoReaderProps::PROP_LRF_HAS_KEY_FRAME = 5,
    cv::cudacodec::VideoReaderProps::PROP_COLOR_FORMAT = 6,
    cv::cudacodec::VideoReaderProps::PROP_UDP_SOURCE = 7,
    cv::cudacodec::VideoReaderProps::PROP_ALLOW_FRAME_DROP = 8,
    cv::cudacodec::VideoReaderProps::PROP_BIT_DEPTH = 9,
    cv::cudacodec::VideoReaderProps::PROP_PLANAR = 10
}

cv::cudacodec::VideoReader generic properties identifier. View details

Enumeration Type Documentation#

BitDepth#

enum cv::cudacodec::BitDepth

#include <opencv2/cudacodec.hpp>

Bit depth of the frame returned by VideoReader::nextFrame() and VideoReader::retrieve()

Enumerator:

`EIGHT`	8 bit depth.
`SIXTEEN`	16 bit depth.
`UNCHANGED`	Use source bit depth.

ChromaFormat#

enum cv::cudacodec::ChromaFormat

#include <opencv2/cudacodec.hpp>

Chroma formats supported by cudacodec::VideoReader.

Enumerator:

Monochrome

YUV420

YUV422

YUV444

NumFormats

Codec#

enum cv::cudacodec::Codec

#include <opencv2/cudacodec.hpp>

Video codecs supported by cudacodec::VideoReader and cudacodec::VideoWriter.

Note

Support will depend on your hardware, refer to the Nvidia Video Codec SDK Video Encode and Decode GPU Support Matrix for details.

Enumerator:

`MPEG1`
`MPEG2`
`MPEG4`
`VC1`
`H264`
`JPEG`
`H264_SVC`
`H264_MVC`
`HEVC`
`VP8`
`VP9`
`AV1`
`NumCodecs`
`Uncompressed_YUV420`	Y,U,V (4:2:0)
`Uncompressed_YV12`	Y,V,U (4:2:0)
`Uncompressed_NV12`	Y,UV (4:2:0)
`Uncompressed_YUYV`	YUYV/YUY2 (4:2:2)
`Uncompressed_UYVY`	UYVY (4:2:2)

ColorFormat#

enum cv::cudacodec::ColorFormat

#include <opencv2/cudacodec.hpp>

ColorFormat for the frame returned by VideoReader::nextFrame() and VideoReader::retrieve() or used to initialize a VideoWriter.

Enumerator:

`UNDEFINED`
`BGRA`	OpenCV color format. VideoReader and VideoWriter.
`BGR`	OpenCV color format. VideoReader and VideoWriter.
`GRAY`	OpenCV color format. VideoReader and VideoWriter.
`RGB`	OpenCV color format. VideoReader and VideoWriter.
`RGBA`	OpenCV color format. VideoReader and VideoWriter.
`NV_YUV_SURFACE_FORMAT`	Nvidia YUV Surface Format output by the Nvidia decoder, see SurfaceFormat. VideoReader only.
`NV_NV12`	Nvidia Buffer Format - Semi-Planar YUV [Y plane followed by interleaved UV plane]. VideoWriter only. Deprecated Deprecated for use with VideoReader, use NV_YUV_SURFACE_FORMAT instead.
`NV_YV12`	Nvidia Buffer Format - Planar YUV [Y plane followed by V and U planes]. VideoWriter only.
`NV_IYUV`	Nvidia Buffer Format - Planar YUV [Y plane followed by U and V planes]. VideoWriter only.
`NV_YUV444`	Nvidia Buffer Format - Planar YUV [Y plane followed by U and V planes]. VideoWriter only.
`NV_AYUV`	Nvidia Buffer Format - 8 bit Packed A8Y8U8V8. This is a word-ordered format where a pixel is represented by a 32-bit word with V in the lowest 8 bits, U in the next 8 bits, Y in the 8 bits after that and A in the highest 8 bits. VideoWriter only.
`NV_YUV420_10BIT`	Nvidia Buffer Format - 10 bit Semi-Planar YUV [Y plane followed by interleaved UV plane]. Each pixel of size 2 bytes. Most Significant 10 bits contain pixel data. VideoWriter only.
`NV_YUV444_10BIT`	Nvidia Buffer Format - 10 bit Planar YUV444 [Y plane followed by U and V planes]. Each pixel of size 2 bytes. Most Significant 10 bits contain pixel data. VideoWriter only.

ColorSpaceStandard#

enum class cv::cudacodec::ColorSpaceStandard

#include <opencv2/cudacodec.hpp>

Video Signal Description Color Primaries of the VideoReader source (section E.2.1 VUI parameters semantics of H265 spec file)

Enumerator:

`BT709`	ITU-R [151] standard for high-definition television.
`Unspecified`	Unspecified color space standard.
`Reserved`	Reserved for future use.
`FCC`	FCC color space standard.
`BT470`	ITU - R BT.470, used for older analog television systems.
`BT601`	ITU - R BT.601, used for standard definition television.
`SMPTE240M`	SMPTE 240M, used for early HDTV systems.
`YCgCo`	YCgCo color space, used in some video compression algorithms.
`BT2020`	ITU - R BT.2020, used for ultra-high-definition television.
`BT2020C`	ITU - R BT.2020 Constant Luminance, used for ultra-high-definition television.

DeinterlaceMode#

enum cv::cudacodec::DeinterlaceMode

#include <opencv2/cudacodec.hpp>

Deinterlacing mode used by decoder.

Enumerator:

`Weave`	Weave both fields(no deinterlacing).For progressive content and for content that doesn’t need deinterlacing.
`Bob`	Drop one field.
`Adaptive`	Adaptive deinterlacing needs more video memory than other deinterlacing modes.

EncodeMultiPass#

enum cv::cudacodec::EncodeMultiPass

#include <opencv2/cudacodec.hpp>

Multi Pass Encoding.

Enumerator:

`ENC_MULTI_PASS_DISABLED`	Single Pass.
`ENC_TWO_PASS_QUARTER_RESOLUTION`	Two Pass encoding is enabled where first Pass is quarter resolution.
`ENC_TWO_PASS_FULL_RESOLUTION`	Two Pass encoding is enabled where first Pass is full resolution.

EncodeParamsRcMode#

enum cv::cudacodec::EncodeParamsRcMode

#include <opencv2/cudacodec.hpp>

Rate Control Modes.

Enumerator:

`ENC_PARAMS_RC_CONSTQP`	Constant QP mode.
`ENC_PARAMS_RC_VBR`	Variable bitrate mode.
`ENC_PARAMS_RC_CBR`	Constant bitrate mode.

EncodePreset#

enum cv::cudacodec::EncodePreset

#include <opencv2/cudacodec.hpp>

Nvidia Encoding Presets. Performance degrades and quality improves as we move from P1 to P7.

Enumerator:

ENC_PRESET_P1

ENC_PRESET_P2

ENC_PRESET_P3

ENC_PRESET_P4

ENC_PRESET_P5

ENC_PRESET_P6

ENC_PRESET_P7

EncodeProfile#

enum cv::cudacodec::EncodeProfile

#include <opencv2/cudacodec.hpp>

Supported Encoder Profiles.

Enumerator:

ENC_CODEC_PROFILE_AUTOSELECT

ENC_H264_PROFILE_BASELINE

ENC_H264_PROFILE_MAIN

ENC_H264_PROFILE_HIGH

ENC_H264_PROFILE_HIGH_444

ENC_H264_PROFILE_STEREO

ENC_H264_PROFILE_PROGRESSIVE_HIGH

ENC_H264_PROFILE_CONSTRAINED_HIGH

ENC_HEVC_PROFILE_MAIN

ENC_HEVC_PROFILE_MAIN10

ENC_HEVC_PROFILE_FREXT

EncodeTuningInfo#

enum cv::cudacodec::EncodeTuningInfo

#include <opencv2/cudacodec.hpp>

Tuning information.

Enumerator:

`ENC_TUNING_INFO_UNDEFINED`	Undefined tuningInfo. Invalid value for encoding.
`ENC_TUNING_INFO_HIGH_QUALITY`	Tune presets for latency tolerant encoding.
`ENC_TUNING_INFO_LOW_LATENCY`	Tune presets for low latency streaming.
`ENC_TUNING_INFO_ULTRA_LOW_LATENCY`	Tune presets for ultra low latency streaming.
`ENC_TUNING_INFO_LOSSLESS`	Tune presets for lossless encoding.
`ENC_TUNING_INFO_COUNT`

SurfaceFormat#

enum cv::cudacodec::SurfaceFormat

#include <opencv2/cudacodec.hpp>

Video surface formats output by the decoder.

Enumerator:

`SF_NV12`	Semi-Planar YUV [Y plane followed by interleaved UV plane].
`SF_P016`	16 bit Semi-Planar YUV [Y plane followed by interleaved UV plane]. Can be used for 10 bit(6LSB bits 0), 12 bit (4LSB bits 0)
`SF_YUV444`	Planar YUV [Y plane followed by U and V planes].
`SF_YUV444_16Bit`	16 bit Planar YUV [Y plane followed by U and V planes]. Can be used for 10 bit(6LSB bits 0), 12 bit (4LSB bits 0)

VideoReaderProps#

enum class cv::cudacodec::VideoReaderProps

#include <opencv2/cudacodec.hpp>

cv::cudacodec::VideoReader generic properties identifier.

Enumerator:

`PROP_DECODED_FRAME_IDX`	Index for retrieving the decoded frame using retrieve().
`PROP_EXTRA_DATA_INDEX`	Index for retrieving the extra data associated with a video source using retrieve().
`PROP_RAW_PACKAGES_BASE_INDEX`	Base index for retrieving raw encoded data using retrieve().
`PROP_NUMBER_OF_RAW_PACKAGES_SINCE_LAST_GRAB`	Number of raw packages recieved since the last call to grab().
`PROP_RAW_MODE`	Status of raw mode.
`PROP_LRF_HAS_KEY_FRAME`	FFmpeg source only - Indicates whether the Last Raw Frame (LRF), output from VideoReader::retrieve() when VideoReader is initialized in raw mode, contains encoded data for a key frame.
`PROP_COLOR_FORMAT`	ColorFormat of the decoded frame. This can be changed before every call to nextFrame() and retrieve().
`PROP_UDP_SOURCE`	Status of VideoReaderInitParams::udpSource initialization.
`PROP_ALLOW_FRAME_DROP`	Status of VideoReaderInitParams::allowFrameDrop initialization.
`PROP_BIT_DEPTH`	Bit depth of the decoded frame. This can be changed before every call to nextFrame() and retrieve().
`PROP_PLANAR`	Planar when true, packed when false. This can be changed before every call to nextFrame() and retrieve().

Function Documentation#

createNVSurfaceToColorConverter()#

Ptr< NVSurfaceToColorConverter > cv::cudacodec::createNVSurfaceToColorConverter(
const ColorSpaceStandard colorSpace,
const bool videoFullRangeFlag = false )

#include <opencv2/cudacodec.hpp>

Creates a NVSurfaceToColorConverter.

Parameters

colorSpace — The requested ColorSpaceStandard for the converter.
videoFullRangeFlag — Indicates if the black level, luma and chroma of the source are represented using the full or limited range (AKA TV or “analogue” range) of values as defined in Annex E of the ITU-T Specification.

createVideoReader()#

Ptr< VideoReader > cv::cudacodec::createVideoReader(
const Ptr< RawVideoSource > & source,
const VideoReaderInitParams params = VideoReaderInitParams() )

#include <opencv2/cudacodec.hpp>

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

source — RAW video source implemented by user.
params — Initializaton parameters. See cv::cudacodec::VideoReaderInitParams.

createVideoReader()#

Ptr< VideoReader > cv::cudacodec::createVideoReader(
const String & filename,
const std::vector< int > & sourceParams = {},
const VideoReaderInitParams params = VideoReaderInitParams() )

#include <opencv2/cudacodec.hpp>

Creates video reader.

FFMPEG is used to read videos. User can implement own demultiplexing with cudacodec::RawVideoSource

Parameters

filename — Name of the input video file.
sourceParams — Pass through parameters for VideoCapure. VideoCapture with the FFMpeg back end (CAP_FFMPEG) is used to parse the video input. The sourceParams parameter allows to specify extra parameters encoded as pairs (paramId_1, paramValue_1, paramId_2, paramValue_2, ...). See cv::VideoCaptureProperties e.g. when streaming from an RTSP source CAP_PROP_OPEN_TIMEOUT_MSEC may need to be set.
params — Initializaton parameters. See cv::cudacodec::VideoReaderInitParams.

createVideoWriter()#

Ptr< cudacodec::VideoWriter > cv::cudacodec::createVideoWriter(
const String & fileName,
const Size frameSize,
const Codec codec,
const double fps,
const ColorFormat colorFormat,
const EncoderParams & params,
Ptr< EncoderCallback > encoderCallback = 0,
const cuda::Stream & stream = cuda::Stream::Null() )

#include <opencv2/cudacodec.hpp>

Creates video writer.

Parameters

fileName — Name of the output video file.
frameSize — Size of the input video frames.
codec — Supports Codec::H264 and Codec::HEVC.
fps — Framerate of the created video stream.
colorFormat — OpenCv color format of the frames to be encoded.
params — Additional encoding parameters.
encoderCallback — Callbacks for video encoder. See cudacodec::EncoderCallback. Required for working with the encoded video stream.
stream — Stream for frame pre-processing.

createVideoWriter()#

Ptr< cudacodec::VideoWriter > cv::cudacodec::createVideoWriter(
const String & fileName,
const Size frameSize,
const Codec codec = Codec::H264,
const double fps = 25.0,
const ColorFormat colorFormat = ColorFormat::BGR,
Ptr< EncoderCallback > encoderCallback = 0,
const cuda::Stream & stream = cuda::Stream::Null() )

#include <opencv2/cudacodec.hpp>

Creates video writer.

Parameters

fileName — Name of the output video file.
frameSize — Size of the input video frames.
codec — Supports Codec::H264 and Codec::HEVC.
fps — Framerate of the created video stream.
colorFormat — OpenCv color format of the frames to be encoded.
encoderCallback — Callbacks for video encoder. See cudacodec::EncoderCallback. Required for working with the encoded video stream.
stream — Stream for frame pre-processing.

MapHist()#

void cv::cudacodec::MapHist(
const cuda::GpuMat & hist,
Mat & histFull )

#include <opencv2/cudacodec.hpp>

Utility function demonstrating how to map the luma histogram when FormatInfo::videoFullRangeFlag == false.

Note

This function demonstrates how to map the luma histogram back so that it is equivalent to the result obtained from cuda::calcHist() if the returned frame was ColorFormat::GRAY.

Parameters

hist — Luma histogram hist returned from VideoReader::nextFrame(GpuMat& frame, GpuMat& hist, Stream& stream).
histFull — Host histogram equivelent to downloading hist after calling cuda::calcHist(InputArray frame, OutputArray hist, Stream& stream).

operator==()#

bool cv::cudacodec::operator==(
const EncoderParams & lhs,
const EncoderParams & rhs )

#include <opencv2/cudacodec.hpp>