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

Public Member Functions
int	pause ()
	Pauses this video stream.

int	resume ()
	Resumes this video stream.

int	saveImage (Device pDev, Request pRequest)
	Encodes and stores the image associated with the mv.impact.acquire.Request object into the stream.

	VideoStream (String fileName, Request pRequest)
	Creates a new video stream file.

	VideoStream (String fileName, Request pRequest, TVideoCodec codec)
	Creates a new video stream file.

	VideoStream (String fileName, Request pRequest, TVideoCodec codec, uint quality_pc)
	Creates a new video stream file.

	VideoStream (String fileName, Request pRequest, TVideoCodec codec, uint quality_pc, uint bitrate)
	Creates a new video stream file.

	VideoStream (String fileName, uint imageWidth, uint imageHeight)
	Creates a new video stream file.

	VideoStream (String fileName, uint imageWidth, uint imageHeight, TVideoCodec codec, uint quality_pc, uint bitrate)
	Creates a new video stream file.

Static Public Member Functions
static String	getCodecAsString (TVideoCodec codec)
	Returns the a string representation for a video codec.

Properties
static Boolean	APIAvailable `[get]`
	Checks if the video stream API is available.

TVideoCodec	codec `[get]`
	Returns the codec used by this video stream.

String	CodecAsString `[get]`
	Returns the codec used by this video stream as a string.

String	fileName `[get]`
	Returns the file name of this video stream.

Boolean	paused `[get]`
	Checks is this video stream is currently paused.

Detailed Description

A class to create compressed video stream from images captured or loaded using the Impact 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 Impact 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 Impact 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

Impact 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 mv.impact.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 mv.impact.acquire.TVideoCodec value. Make sure to use one of these formats either by setting up your device accordingly or by using the mv.impact.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/6]

VideoStream	(	String	fileName,
		uint	imageWidth,
		uint	imageHeight,
		TVideoCodec	codec,
		uint	quality_pc,
		uint	bitrate )

inline

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]	fileName	The name or full path of the file to create. The recommended file extensions for files can be found where the mv.impact.acquire.TVideoCodec enumeration is documented
[in]	imageWidth	The input image width in pixels
[in]	imageHeight	The input image height in pixels
[in]	codec	The codec that shall be used while encoding the images into the stream.
[in]	quality_pc	The quality of the resulting video stream in percent (0-100). The higher this value the larger the file will get. This value is only taken into account for the following codecs: mv.impact.acquire.TVideoCodec.vcH264, mv.impact.acquire.TVideoCodec.vcH265.
[in]	bitrate	The 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: mv.impact.acquire.TVideoCodec.vcMPEG2.

◆ VideoStream() [2/6]

VideoStream	(	String	fileName,
		uint	imageWidth,
		uint	imageHeight )

inline

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]	fileName	The name or full path of the file to create. The recommended file extensions for files can be found where the mv.impact.acquire.TVideoCodec enumeration is documented
[in]	imageWidth	The input image width in pixels
[in]	imageHeight	The input image height in pixels

◆ VideoStream() [3/6]

VideoStream	(	String	fileName,
		Request	pRequest,
		TVideoCodec	codec,
		uint	quality_pc,
		uint	bitrate )

inline

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]	fileName	The name or full path of the file to create. The recommended file extensions for files can be found where the mv.impact.acquire.TVideoCodec enumeration is documented
[in]	pRequest	A mv.impact.acquire.Request object carrying the image related information that are about to get stored in the stream.
[in]	codec	The codec that shall be used while encoding the images into the stream.
[in]	quality_pc	The quality of the resulting video stream in percent (0-100). The higher this value the larger the file will get. This value is only taken into account for the following codecs: mv.impact.acquire.TVideoCodec.vcH264, mv.impact.acquire.TVideoCodec.vcH265.
[in]	bitrate	The 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: mv.impact.acquire.TVideoCodec.vcMPEG2.

◆ VideoStream() [4/6]

VideoStream	(	String	fileName,
		Request	pRequest,
		TVideoCodec	codec,
		uint	quality_pc )

inline

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]	fileName	The name or full path of the file to create. The recommended file extensions for files can be found where the mv.impact.acquire.TVideoCodec enumeration is documented
[in]	pRequest	A mv.impact.acquire.Request object carrying the image related information that are about to get stored in the stream
[in]	codec	The codec that shall be used while encoding the images into the stream.
[in]	quality_pc	The quality of the resulting video stream in percent (0-100). The higher this value the larger the file will get. This value is only taken into account for the following codecs: mv.impact.acquire.TVideoCodec.vcH264, mv.impact.acquire.TVideoCodec.vcH265

◆ VideoStream() [5/6]

VideoStream	(	String	fileName,
		Request	pRequest,
		TVideoCodec	codec )

inline

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]	fileName	The name or full path of the file to create. The recommended file extensions for files can be found where the mv.impact.acquire.TVideoCodec enumeration is documented
[in]	pRequest	A mv.impact.acquire.Request object carrying the image related information that are about to get stored in the stream
[in]	codec	The codec that shall be used while encoding the images into the stream.

◆ VideoStream() [6/6]

VideoStream	(	String	fileName,
		Request	pRequest )

inline

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]	fileName	The name or full path of the file to create. The recommended file extensions for files can be found where the mv.impact.acquire.TVideoCodec enumeration is documented
[in]	pRequest	A mv.impact.acquire.Request object carrying the image related information that are about to get stored in the stream

Member Function Documentation

◆ getCodecAsString()

static String getCodecAsString ( 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.

◆ pause()

int pause ( )

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: mv.impact.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: mv.impact.acquire.labs.VideoStream.resume,
mv.impact.acquire.labs.VideoStream.paused

Returns

mv.impact.acquire.TDMR_ERROR.DMR_NO_ERROR if successful.
mv.impact.acquire.TDMR_ERROR.DMR_BUSY if this stream has been paused already.
A negative error code of type mv.impact.acquire.TDMR_ERROR otherwise.

◆ resume()

int resume ( )

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: mv.impact.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: mv.impact.acquire.labs.VideoStream.pause,
mv.impact.acquire.labs.VideoStream.paused

Returns

mv.impact.acquire.TDMR_ERROR.DMR_NO_ERROR if successful.
mv.impact.acquire.TDMR_ERROR.DMR_EXECUTION_PROHIBITED if this stream has been paused already.
A negative error code of type mv.impact.acquire.TDMR_ERROR otherwise.

◆ saveImage()

int saveImage	(	Device	pDev,
		Request	pRequest )

inline

Encodes and stores the image associated with the mv.impact.acquire.Request object into the stream.

This function stores the image associated with an mv.impact.acquire.Request object into the video stream.

Note: Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mv.impact.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: mv.impact.acquire.labs.VideoStream.resume,
mv.impact.acquire.labs.VideoStream.pause,
mv.impact.acquire.labs.VideoStream.paused

Returns

mv.impact.acquire.TDMR_ERROR.DMR_NO_ERROR if successful.
mv.impact.acquire.TDMR_ERROR.DMR_LIBRARY_NOT_FOUND if no compatible version of the FFmpeg libraries could be located on the host system.
mv.impact.acquire.TDMR_ERROR.DEV_UNSUPPORTED_PARAMETER if a pixel format has been passed to the function that is not supported by the internal algorithms.
mv.impact.acquire.TDMR_ERROR.DEV_INPUT_PARAM_INVALID e.g. if a pixel format has been passed to the function that is not supported by the FFmpeg libraries.
A negative error code of type mv.impact.acquire.TDMR_ERROR otherwise.

Parameters

[in]	pDev	A pointer to a mv.impact.acquire.Device object obtained from a mv.impact.acquire.DeviceManager object.
[in]	pRequest	A pointer to the mv.impact.acquire.Request object carrying the image to encode and store.

Property Documentation

◆ APIAvailable

Boolean APIAvailable

staticget

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.

◆ codec

TVideoCodec codec

get

Returns the codec used by this video stream.

This function returns the codec used by this video stream.

Since: 2.39.0

Returns: The mv.impact.acquire.TVideoCodec used by this video stream.

◆ CodecAsString

String CodecAsString

get

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.

◆ fileName

String fileName

get

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.

◆ paused

Boolean paused

get

Checks is this video stream is currently paused.

Note: Internally the FFmpeg project (see FFmpeg section as well as the remarks made here: mv.impact.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: mv.impact.acquire.labs.VideoStream.pause,
mv.impact.acquire.labs.VideoStream.resume

Returns

true if this video stream is currently paused.
false otherwise.

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Constructor & Destructor Documentation

◆ VideoStream() [1/6]

◆ VideoStream() [2/6]

◆ VideoStream() [3/6]

◆ VideoStream() [4/6]

◆ VideoStream() [5/6]

◆ VideoStream() [6/6]

Member Function Documentation

◆ getCodecAsString()

◆ pause()

◆ resume()

◆ saveImage()

Property Documentation

◆ APIAvailable

◆ codec

◆ CodecAsString

◆ fileName

◆ paused