The VideoEncoder class supports encoding a series of images to a video format, and then writing the video to disk. More...

#include <VideoEncoder.hh>

Public Member Functions
	VideoEncoder ()
	Constructor. More...

virtual	~VideoEncoder ()
	Destructor. More...

bool	AddFrame (const unsigned char *_frame, const unsigned int _width, const unsigned int _height)
	Add a single frame to be encoded. More...

bool	AddFrame (const unsigned char *_frame, const unsigned int _width, const unsigned int _height, const std::chrono::steady_clock::time_point &_timestamp)
	Add a single timestamped frame to be encoded. More...

unsigned int	BitRate () const
	Get the bit rate. More...

std::string	Format () const
	Get the encoding format. More...

bool	IsEncoding () const
	True if the enoder has been started, false otherwise. More...

void	Reset ()
	Reset to default video properties and clean up allocated memory. This will also delete any temporary files. More...

bool	SaveToFile (const std::string &_filename)
	Write the video to disk param[in] _filename File in which to save the encoded data. More...

bool	Start (const std::string &_format="mp4", const std::string &_filename="", const unsigned int _width=1280, const unsigned int _height=720, const unsigned int _fps=25, const unsigned int _bitRate=0)
	Start the encoder. This should be called once. Add new frames to the video using the AddFrame function. Use SaveToFile when the video is complete. More...

bool	Start (const std::string &_format, const std::string &_filename, const unsigned int _width, const unsigned int _height, const unsigned int _fps, const unsigned int _bitRate, const bool _allowHwAccel)
	Start the encoder. This should be called once. Add new frames to the video using the AddFrame function. Use SaveToFile when the video is complete. More...

bool	Start (const std::string &_format, const std::string &_filename, unsigned int _width, unsigned int _height, unsigned int _fps, unsigned int _bitRate, const FlagSet< HWEncoderType > &_allowedHwAccel, const std::string &_hwAccelDevice="", std::optional< bool > _useHwSurface={})
	Start the encoder. This should be called once. Add new frames to the video using the AddFrame function. Use SaveToFile when the video is complete. More...

bool	Stop ()
	Stop the encoder. The SaveToFile function also calls this function. More...

Detailed Description

The VideoEncoder class supports encoding a series of images to a video format, and then writing the video to disk.

Constructor & Destructor Documentation

◆ VideoEncoder()

VideoEncoder ( )

Constructor.

◆ ~VideoEncoder()

virtual ~VideoEncoder ( )

virtual

Destructor.

Member Function Documentation

◆ AddFrame() [1/2]

bool AddFrame	(	const unsigned char *	_frame,
		const unsigned int	_width,
		const unsigned int	_height
	)

Add a single frame to be encoded.

Parameters

[in]	_frame	Image buffer to be encoded
[in]	_width	Input frame width
[in]	_height	Input frame height

Returns: True on success

◆ AddFrame() [2/2]

bool AddFrame	(	const unsigned char *	_frame,
		const unsigned int	_width,
		const unsigned int	_height,
		const std::chrono::steady_clock::time_point &	_timestamp
	)

Add a single timestamped frame to be encoded.

Parameters

[in]	_frame	Image buffer to be encoded
[in]	_width	Input frame width
[in]	_height	Input frame height
[in]	_timestamp	Timestamp of the image frame

Returns: True on success.

◆ BitRate()

unsigned int BitRate ( ) const

Get the bit rate.

Returns: Bit rate

◆ Format()

std::string Format ( ) const

Get the encoding format.

Returns: Encoding format

◆ IsEncoding()

bool IsEncoding ( ) const

True if the enoder has been started, false otherwise.

Returns: True if Start has been called.

◆ Reset()

void Reset ( )

Reset to default video properties and clean up allocated memory. This will also delete any temporary files.

◆ SaveToFile()

bool SaveToFile ( const std::string & _filename )

Write the video to disk param[in] _filename File in which to save the encoded data.

Returns: True on success.

◆ Start() [1/3]

bool Start	(	const std::string &	_format = `"mp4"`,
		const std::string &	_filename = `""`,
		const unsigned int	_width = `1280`,
		const unsigned int	_height = `720`,
		const unsigned int	_fps = `25`,
		const unsigned int	_bitRate = `0`
	)

Start the encoder. This should be called once. Add new frames to the video using the AddFrame function. Use SaveToFile when the video is complete.

Parameters

[in]	_width	Width in pixels of the output video.
[in]	_height	Height in pixels of the output video.
[in]	_format	String that represents the video type. Supported types include: "avi", "ogv", mp4", "v4l2". If using "v4l2", you must also specify a _filename.
[in]	_bitRate	Bit rate to encode the video. A value of zero will cause this function to automatically compute a bitrate.
[in]	_filename	Name of the file that stores the video while it is being created. This is a temporary file when recording to disk, or a video4linux loopback device like /dev/video0 when the _format is "v4l2". If blank, a default temporary file is used. However, the "v4l2" _format must be accompanied with a video loopback device filename.

Returns: True on success. Do NOT ignore the return value. If Start() failed, encoding will not work. If Start() function failed, you can try running the overload with _allowHwAccel=false to see if the failure isn't a result of faulty HW encoding (e.g. when NVENC sessions are exhausted).

Note

This will automatically select a HW-accelerated encoder based on the values of environment variables IGN_VIDEO_ALLOWED_ENCODERS, IGN_VIDEO_ENCODER_DEVICE and IGN_VIDEO_ENCODER_USE_HW_SURFACE. To completely avoid trying to set up HW accelerated encoding, set IGN_VIDEO_ALLOWED_ENCODERS to value NONE or leave it empty or unset. The meaning of these variables is the following:

IGN_VIDEO_ALLOWED_ENCODERS is a colon-separated list of values of HWEncoderType enum, or ALL to allow all encoders. Default is NONE.
IGN_VIDEO_ENCODER_DEVICE optionally specifies the HW device to use for encoding (used only when a matching encoder is found first). By default, an empty string is used, which means to use whatever device is found to work first.
IGN_VIDEO_USE_HW_SURFACE specifies whether the encoder should use an explicit GPU buffer for video frames. Some codecs do this implicitly, and then this setting has no meaning (setting it to 1 can actually decrease performance). For codecs that need to set this explicitly, this variable is checked for three values: 1, 0 and empty. Empty value means that the implementation should guess whether explicit GPU buffers are worth it or not.

◆ Start() [2/3]

bool Start	(	const std::string &	_format,
		const std::string &	_filename,
		const unsigned int	_width,
		const unsigned int	_height,
		const unsigned int	_fps,
		const unsigned int	_bitRate,
		const bool	_allowHwAccel
	)

Start the encoder. This should be called once. Add new frames to the video using the AddFrame function. Use SaveToFile when the video is complete.

Parameters

[in]	_width	Width in pixels of the output video.
[in]	_height	Height in pixels of the output video.
[in]	_format	String that represents the video type. Supported types include: "avi", "ogv", mp4", "v4l2". If using "v4l2", you must also specify a _filename.
[in]	_bitRate	Bit rate to encode the video. A value of zero will cause this function to automatically compute a bitrate.
[in]	_filename	Name of the file that stores the video while it is being created. This is a temporary file when recording to disk, or a video4linux loopback device like /dev/video0 when the _format is "v4l2". If blank, a default temporary file is used. However, the "v4l2" _format must be accompanied with a video loopback device filename.
[in]	_allowHwAccel	If true, HW acceleration settings are read from environment variables (see the other Start() overload for the loading mechanism description). If set to false, only SW encoding will be done.

Returns: True on success. Do NOT ignore the return value. If Start() failed, encoding will not work. If Start() function failed and you ran it with allowed HW acceleration, you can try running it once more without it (this can help in case the HW encoder can be found and detected, but it fails to start, e.g. when NVENC sessions are exhausted).

◆ Start() [3/3]

bool Start	(	const std::string &	_format,
		const std::string &	_filename,
		unsigned int	_width,
		unsigned int	_height,
		unsigned int	_fps,
		unsigned int	_bitRate,
		const FlagSet< HWEncoderType > &	_allowedHwAccel,
		const std::string &	_hwAccelDevice = `""`,
		std::optional< bool >	_useHwSurface = `{}`
	)

Start the encoder. This should be called once. Add new frames to the video using the AddFrame function. Use SaveToFile when the video is complete.

Parameters

[in]	_width	Width in pixels of the output video.
[in]	_height	Height in pixels of the output video.
[in]	_format	String that represents the video type. Supported types include: "avi", "ogv", mp4", "v4l2". If using "v4l2", you must also specify a _filename.
[in]	_bitRate	Bit rate to encode the video. A value of zero will cause this function to automatically compute a bitrate.
[in]	_filename	Name of the file that stores the video while it is being created. This is a temporary file when recording to disk, or a video4linux loopback device like /dev/video0 when the _format is "v4l2". If blank, a default temporary file is used. However, the "v4l2" _format must be accompanied with a video loopback device filename.
[in]	_allowedHwAccel	Allowed HW acceleration frameworks to probe (as a bitmask of values of HWAccelerationDevice enum). Set to HWAccelerationDevice::NONE to force software encoding only.
[in]	_hwAccelDevice	If nonempty, specifies the HW device to use for encoding. If empty, the framework search method will look for some default devices.

Returns: True on success. Do NOT ignore the return value. If Start() failed, encoding will not work. If Start() function failed and you ran it with some HW acceleration, you can try running it once more with a different acceleration config (this can help in case the HW encoder can be found and detected, but it fails to start, e.g. when NVENC sessions are exhausted).

◆ Stop()

bool Stop ( )

Stop the encoder. The SaveToFile function also calls this function.

Returns: True on success.

The documentation for this class was generated from the following file:

VideoEncoder.hh

Ignition Common

API Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ VideoEncoder()

◆ ~VideoEncoder()

Member Function Documentation

◆ AddFrame() [1/2]

◆ AddFrame() [2/2]

◆ BitRate()

◆ Format()

◆ IsEncoding()

◆ Reset()

◆ SaveToFile()

◆ Start() [1/3]

◆ Start() [2/3]

◆ Start() [3/3]

◆ Stop()