Gazebo Common

API Reference

5.6.0
VideoEncoder Class Reference

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, 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 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 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()

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]_frameImage buffer to be encoded
[in]_widthInput frame width
[in]_heightInput 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]_frameImage buffer to be encoded
[in]_widthInput frame width
[in]_heightInput frame height
[in]_timestampTimestamp 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,
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]_widthWidth in pixels of the output video.
[in]_heightHeight in pixels of the output video.
[in]_formatString that represents the video type. Supported types include: "avi", "ogv", mp4", "v4l2". If using "v4l2", you must also specify a _filename.
[in]_bitRateBit rate to encode the video. A value of zero will cause this function to automatically compute a bitrate.
[in]_filenameName 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]_allowHwAccelIf 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() [2/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]_widthWidth in pixels of the output video.
[in]_heightHeight in pixels of the output video.
[in]_formatString that represents the video type. Supported types include: "avi", "ogv", mp4", "v4l2". If using "v4l2", you must also specify a _filename.
[in]_bitRateBit rate to encode the video. A value of zero will cause this function to automatically compute a bitrate.
[in]_filenameName 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]_allowedHwAccelAllowed HW acceleration frameworks to probe (as a bitmask of values of HWAccelerationDevice enum). Set to HWAccelerationDevice::NONE to force software encoding only.
[in]_hwAccelDeviceIf 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).

◆ Start() [3/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]_widthWidth in pixels of the output video.
[in]_heightHeight in pixels of the output video.
[in]_formatString that represents the video type. Supported types include: "avi", "ogv", mp4", "v4l2". If using "v4l2", you must also specify a _filename.
[in]_bitRateBit rate to encode the video. A value of zero will cause this function to automatically compute a bitrate.
[in]_filenameName 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 GZ_VIDEO_ALLOWED_ENCODERS, GZ_VIDEO_ENCODER_DEVICE and GZ_VIDEO_ENCODER_USE_HW_SURFACE. To completely avoid trying to set up HW accelerated encoding, set GZ_VIDEO_ALLOWED_ENCODERS to value NONE or leave it empty or unset. The meaning of these variables is the following:
  • GZ_VIDEO_ALLOWED_ENCODERS is a colon-separated list of values of HWEncoderType enum, or ALL to allow all encoders. Default is NONE.
  • GZ_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.
  • GZ_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.

◆ 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: