mvIMPACT Acquire SDK C++
VideoStream Class Reference

A class to create compressed video stream from images captured or loaded using the mvIMPACT Acquire API. More...

Public Member Functions

const TVideoCodecgetCodec (void) const
 Returns the codec used by this video stream. More...
 
std::string getCodecAsString (void) const
 Returns the codec used by this video stream as a string. More...
 
const std::string & getFileName (void) const
 Returns the file name of this video stream. More...
 
bool isPaused (void) const
 Checks is this video stream is currently paused. More...
 
int pause (void) const
 Pauses this video stream. More...
 
int resume (void) const
 Resumes this video stream. More...
 
int saveImage (const ImageBuffer *pBuffer, int64_type timestamp_us=0LL)
 Stores an image into the video stream. More...
 
int saveImage (Device *pDev, const Request *pRequest)
 Encodes and stores the image associated with the mvIMPACT::acquire::Request object into the stream. More...
 
 VideoStream (const std::string &fileName, const ImageBuffer *pBuffer, const TVideoCodec codec=vcH264, const unsigned int quality_pc=60, const unsigned int bitrate=6000)
 Creates a new video stream file. More...
 
 VideoStream (const std::string &fileName, const Request *pRequest, const TVideoCodec codec=vcH264, const unsigned int quality_pc=60, const unsigned int bitrate=6000)
 Creates a new video stream file. More...
 
 VideoStream (const std::string &fileName, const unsigned int imageWidth, const unsigned int imageHeight, const TVideoCodec codec=vcH264, const unsigned int quality_pc=60, const unsigned int bitrate=6000)
 Creates a new video stream file. More...
 
 ~VideoStream ()
 

Static Public Member Functions

static std::string getCodecAsString (const TVideoCodec codec)
 Returns the a string representation for a video codec. More...
 
static bool isAPIAvailable (void)
 Checks if the video stream API is available. More...
 

Detailed Description

A class to create compressed video stream from images captured or loaded using the mvIMPACT Acquire API.

This class heavily depends on the FFmpeg project (see FFmpeg). Without the libraries belonging to this project being present on the target system video streams cannot be created.

Because of what is stated in the above section mvIMPACT Acquire is NOT shipped with the FFmpeg binaries required to use this class!

On Windows the FFmpeg-share package matching the platform the application shall run with (32- or 64-bit) is needed. This can either be extracted into the installation folder of mvIMPACT Acquire e.g. into $(MVIMPACT_ACQUIRE_DIR)/Toolkits/ffmpeg-4.2.2-win64-shared or $(MVIMPACT_ACQUIRE_DIR)/Toolkits/ffmpeg-4.2.2-win32-shared (Works only for this versions) OR at the location pointed to by MVIMPACT_ACQUIRE_FFMPEG_DIR (see below) OR anywhere into the systems search path.

On Linux the package ffmpeg must be installed and if e.g. H.264 support is needed the libavcodec-extra package as well.

Attention
Please carefully read and understand the legal implications coming with the use of FFmpeg in a commercial product: http://ffmpeg.org/legal.html

mvIMPACT Acquire is capable of communicating with FFmpeg 4.x right now. This means that the following libraries will be recognized:

  • libavcodec-58, libavformat-58 and libavutil-56 (FFmpeg 4.0 was released on 20.04.2018)

In order to load the FFmpeg libraries from a custom location the environment variable MVIMPACT_ACQUIRE_FFMPEG_DIR can be defined before creating the first mvIMPACT::acquire::labs::VideoStream instance after loading the mvDeviceManager library into the current processes address space. Without this environment variable only the systems default search path will be used to locate it and (Windows only) the Toolkits folder of the installation directory. This is how the search algorithm will operate:

if isEnvironmentVariableDefined( MVIMPACT_ACQUIRE_FFMPEG_DIR )
if tryToLoadFFmpegVersion4Succeeded
return
if tryToLoadFFmpegVersion3Succeeded
return
if isWindowsSystem
if tryToLoadFFmpegVersionFromToolkits4Succeeded
return
if tryToLoadFFmpegVersion4Succeeded
return
if tryToLoadFFmpegVersion3Succeeded
return
ReportError
Note
Currently video streams can only be created for a limited number of pixel formats. Which codec supports which input formats is described at the corresponding mvIMPACT::acquire::TVideoCodec value. Make sure to use one of these formats either by setting up your device accordingly or by using the mvIMPACT::acquire::ImageDestination::pixelFormat property of the Image Format Conversion Filter.
Attention
  • You have to feed one of the supported pixel formats depending on the video codecs requirements into the stream! The video stream API will NOT perform internal conversion. If you need to convert (most likely you will be!) use the Image Format Conversion Filter to achieve that. It will get the job done!
  • When not providing timestamps together with the images that are fed into the encoder the resulting video stream can still be used, but the playback speed will differ from the acquisition speed then. When providing the timestamps coming with the requests the playback speed will resemble exactly the acquisition speed. Most codecs even support variable playback speeds so dynamic changes in the frame rate will be reflected during playback.
Since
2.39.0

Constructor & Destructor Documentation

◆ VideoStream() [1/3]

VideoStream ( const std::string &  fileName,
const ImageBuffer pBuffer,
const TVideoCodec  codec = vcH264,
const unsigned int  quality_pc = 60,
const unsigned int  bitrate = 6000 
)
inlineexplicit

Creates a new video stream file.

Note
Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.
Parameters
[in]fileNameThe name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT::acquire::TVideoCodec enumeration is documented
[in]pBufferAn image buffer containing the layout of the images that are about to get stored in the stream. This structure can be extracted from a real mvIMPACT::acquire::Request object captured previously but NOT by calling the mvIMPACT::acquire::FunctionInterface::getCurrentCaptureBufferLayout function after setting up the device completely.The latter one will not contain all the information needed for a successful stream creation. You could even create a stream from a list of files e.g. on a hard-disc using the mvIMPACT::acquire::ImageBufferDesc constructor accepting a file name. If you want to use the mvIMPACT::acquire::Request object obtained from a call to mvIMPACT::acquire::FunctionInterface::getCurrentCaptureBufferLayout use the constructor accepting a mvIMPACT::acquire::Request pointer!
[in]codecThe codec that shall be used while encoding the images into the stream.
[in]quality_pcThe quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT::acquire::vcH264, mvIMPACT::acquire::vcH265
[in]bitrateThe bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT::acquire::vcMPEG2.

◆ VideoStream() [2/3]

VideoStream ( const std::string &  fileName,
const unsigned int  imageWidth,
const unsigned int  imageHeight,
const TVideoCodec  codec = vcH264,
const unsigned int  quality_pc = 60,
const unsigned int  bitrate = 6000 
)
inlineexplicit

Creates a new video stream file.

Note
Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.
Parameters
[in]fileNameThe name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT::acquire::TVideoCodec enumeration is documented
[in]imageWidthThe input image width in pixels
[in]imageHeightThe input image height in pixels
[in]codecThe codec that shall be used while encoding the images into the stream.
[in]quality_pcThe quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT::acquire::vcH264, mvIMPACT::acquire::vcH265
[in]bitrateThe bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT::acquire::vcMPEG2.

◆ VideoStream() [3/3]

VideoStream ( const std::string &  fileName,
const Request pRequest,
const TVideoCodec  codec = vcH264,
const unsigned int  quality_pc = 60,
const unsigned int  bitrate = 6000 
)
inlineexplicit

Creates a new video stream file.

Note
Internally the FFmpeg project (see FFmpeg section) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this constructor will raise an exception.
Parameters
[in]fileNameThe name or full path of the file to create. The recommended file extensions for files can be found where the mvIMPACT::acquire::TVideoCodec enumeration is documented.
[in]pRequestA mvIMPACT::acquire::Request object carrying the image related information that are about to get stored in the stream. This can either be extracted from a real mvIMPACT::acquire::Request object captured previously or by calling the mvIMPACT::acquire::FunctionInterface::getCurrentCaptureBufferLayout function after setting up the device completely. To create a stream from a list of files e.g. on a hard-disc use the mvIMPACT::acquire::labs::VideoStream constructor accepting a mvIMPACT::acquire::ImageBufferDesc instead! Create instances of b mvIMPACT::acquire::ImageBufferDesc objects from files call the mvIMPACT::acquire::ImageBufferDesc constructor accepting a file name.
[in]codecThe codec that shall be used while encoding the images into the stream.
[in]quality_pcThe quality of the resulting video stream in percent. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT::acquire::vcH264, mvIMPACT::acquire::vcH265
[in]bitrateThe bitrate of the resulting video stream in kBit/s. The higher this value the larger the file will get. This value is only taken into account for the following codecs: mvIMPACT::acquire::vcMPEG2.

◆ ~VideoStream()

~VideoStream ( )
inline

Member Function Documentation

◆ getCodec()

const TVideoCodec& getCodec ( void  ) const
inline

Returns the codec used by this video stream.

This function returns the codec used by this video stream.

Since
2.39.0
Returns
The codec used by this video stream.

◆ getCodecAsString() [1/2]

static std::string getCodecAsString ( const TVideoCodec  codec)
inlinestatic

Returns the a string representation for a video codec.

This function returns a string representation for a video codec.

Since
2.39.0
Returns
A string representation for a video codec.

◆ getCodecAsString() [2/2]

std::string getCodecAsString ( void  ) const
inline

Returns the codec used by this video stream as a string.

This function returns the codec used by this video stream as a string.

Since
2.39.0
Returns
The codec used by this video stream as a string.

◆ getFileName()

const std::string& getFileName ( void  ) const
inline

Returns the file name of this video stream.

This function returns the file name of this video stream.

Since
2.39.0
Returns
The file name of this video stream.

◆ isAPIAvailable()

static bool isAPIAvailable ( void  )
inlinestatic

Checks if the video stream API is available.

This function checks if the video stream API is available.

Since
2.39.0
Returns
  • true if the video stream API is available thus video streams can be created
  • false otherwise.

◆ isPaused()

bool isPaused ( void  ) const
inline

Checks is this video stream is currently paused.

Note
Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT::acquire::labs::VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.
Since
2.41.0
See also
mvIMPACT::acquire::labs::VideoStream::pause,
mvIMPACT::acquire::labs::VideoStream::resume
Returns
  • true if this video stream is currently paused.
  • false otherwise.

◆ pause()

int pause ( void  ) const
inline

Pauses this video stream.

This function pauses this video stream. While paused no images can be written into the stream. Pausing internally simply starts a timer and all accumulated pause times will be subtracted from images that will be written into the stream after the pause has been ended effectively allowing to remove inactive sections from the video stream.

Note
Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT::acquire::labs::VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.
Since
2.41.0
See also
mvIMPACT::acquire::labs::VideoStream::resume,
mvIMPACT::acquire::labs::VideoStream::isPaused
Returns

◆ resume()

int resume ( void  ) const
inline

Resumes this video stream.

This function resumes this previously paused video stream. While paused no images can be written into the stream. Pausing internally simply starts a timer and all accumulated pause times will be subtracted from images that will be written into the stream after the pause has been ended effectively allowing to remove inactive sections from the video stream.

Note
Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT::acquire::labs::VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.
Since
2.41.0
See also
mvIMPACT::acquire::labs::VideoStream::pause,
mvIMPACT::acquire::labs::VideoStream::isPaused
Returns

◆ saveImage() [1/2]

int saveImage ( const ImageBuffer pBuffer,
int64_type  timestamp_us = 0LL 
)
inline

Stores an image into the video stream.

This function stores an image into the video stream.

Note
Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT::acquire::labs::VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.
Since
2.39.0
Returns
Parameters
[in]pBufferThe image to encode and store.
[in]timestamp_usA timestamp(in us) to associate this image with. This can be 0 if no timestamp is available.

◆ saveImage() [2/2]

int saveImage ( Device pDev,
const Request pRequest 
)
inline

Encodes and stores the image associated with the mvIMPACT::acquire::Request object into the stream.

This function stores the image associated with an mvIMPACT::acquire::Request object into the video stream.

Note
Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mvIMPACT::acquire::labs::VideoStream) is used for this operation. If the corresponding libraries cannot be located in one of the supported versions on the host system calling this function will fail.
Since
2.39.0
See also
mvIMPACT::acquire::labs::VideoStream::pause,
mvIMPACT::acquire::labs::VideoStream::isPaused,
mvIMPACT::acquire::labs::VideoStream::resume
Returns
Parameters
[in]pDevA pointer to a mvIMPACT::acquire::Device object obtained from a mvIMPACT::acquire::DeviceManager object.
[in]pRequestA pointer to the mvIMPACT::acquire::Request object carrying the image to encode and store.

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