Back to Aurora Vision Library website

You are here: Start » Function Reference » GigE Vision » AvsFilter_GigEVision_GetStreamingStatistics

AvsFilter_GigEVision_GetStreamingStatistics


This is Filter Equivalent. This function may be present in generated code, but should not be used in hand-written code.

Header: Genicam.h
Namespace: avs
Module: Genicam

Retrieves basic statistics of video streaming out of a GigEVision device.

Syntax

void avs::AvsFilter_GigEVision_GetStreamingStatistics
(
	GigEVision_GetStreamingStatistics_State& ioState,
	const avl::GevAddress& inAddress,
	bool inReset,
	int& outReceivedFrames,
	int& outLostFrames,
	int& outDroppedFrames,
	int& outDamagedFrames,
	int& outCurrentQueueSize,
	int& outResendRequests,
	int& outLostPackets,
	int& outErroneousPackets,
	int& outReconnections,
	atl::String& outLastPacketError,
	atl::String& outLastFrameError
)

Parameters

Name Type Default Description
Input will be modified ioState GigEVision_GetStreamingStatistics_State& Object used to maintain state of the function.
Input value inAddress const GevAddress& GigE Vision Device identifying address (IP, MAC or Serial Number)
Input value inReset bool False True to reset internal device statistics after read.
Output value outReceivedFrames int& Number of received valid frames that were put into the input queue.
Output value outLostFrames int& Number of all frames that the device should have sent but were not retrieved by the application.
Output value outDroppedFrames int& Number of received valid frames that were lost because of input queue overflow.
Output value outDamagedFrames int& Number of frames that were partially received but were discarded because of data damage.
Output value outCurrentQueueSize int& Number of frames currently held in the input queue.
Output value outResendRequests int& Number of times the device was requested to resend some parts of lost frames.
Output value outLostPackets int& Number of video stream network packets that were expected but not retrieved.
Output value outErroneousPackets int& Number of video stream network packets that contained error in their content, or notify errors from the device.
Output value outReconnections int& Number of times the connection with the device was lost and automatically reestablished.
Output value outLastPacketError String& Last network packet related error logged by the stream receiver.
Output value outLastFrameError String& Last frame reconstruction related error logged by the stream receiver.

Description

This filter is intended for retrieving the video streaming statistics and diagnosing video streaming problems related to GigE Vision® compliant video transmitter. It is usually used beside other GigEVision filters, especially AvsFilter_GigEVision_GrabImage or AvsFilter_GigEVision_GrabImage_WithTimeout performing actual video streaming, and only for diagnostic purpose.

Device address (inAddress port) is a textual definition of either IP, MAC or serial number. Use Device Manager to select appropriate address of connected device.

This filter will interpret the value of inAddress port only during the first iteration, when the connection to the device is established. During the next iterations the filter will use previously established connection and subsequent changes in the device address will be ignored.

On every execution this filter will return the following statistics on its outputs:

  • outReceivedFrames - Number of all frames that were internally received from the device without any errors, and that were put into the image input queue. Those frames are intended for processing by the application through AvsFilter_GigEVision_GrabImage and equivalent filters. It is possible that not all of those frames were processed by the application.
  • outLostFrames - Number of all frames that should have been generated by the device (based on frames counter) but were not, for any reason, processed by the application through the AvsFilter_GigEVision_GrabImage or equivalent filter. This is an estimated value and on serious transport problems may be different than actual lost frames count. This counter includes dropped frames, damaged frames, and other frames that were fully lost (not received even partially).
  • outDroppedFrames - Number of frames that were internally received from the device without any errors, and that were put into the image input queue, but were not consumed by the application on time using the AvsFilter_GigEVision_GrabImage or equivalent filter and was discarded because of the input queue overflow. Large values of this statistic and its constant continuous growth means that the application is not keeping up with processing frames generated by the device and may indicate application performance issues or too large camera framerate. Occasional short growths of this statistic may indicate periodic performance problems in the application and (when loosing of frames is not acceptable) may indicate the need to increase capacity of the input queue.
  • outDamagedFrames - Number of all frames that were internally received from the device but were incomplete (some data were lost on transport layer) or were otherwise damaged (some data was corrupted or not recognized), and was discarded without putting them into the images input queue. Large values of this statistic may indicate network problems, network infrastructure performance problems, local system network stack performance problems, or use of unsupported or invalid format of stream payload by the device.
  • outCurrentQueueSize - Number of valid frames that at the time of this filter execution was stored in the frames input queue and waiting for retrieving through the AvsFilter_GigEVision_GrabImage or equivalent filter. This value can be changing rapidly due too the race condition between filter execution time and internal receiving of new frames from the device.
  • outResendRequests - Number of times transport layer detected missing network packets and requested the device to retransmit some parts of incomplete frames. This takes place only when the device is supporting packets retransmission. When retransmission is successful the frames are not damaged despite increment in this statistic. When retransmission is not successful the packets are lost and the outLostPackets and outDamagedFrames statistics will be incremented according to resulting damage. Large value of this statistic may indicate network communication issues, network infrastructure performance issues or local system network stack performance issues. Very small periodic increments of this statistic are usually acceptable.
  • outLostPackets - Estimated number of network packets that were expected but were not received or received with significant delay to other packets. Packets can be lost due to network communication issues, network infrastructure performance issues or local system network stack performance issues. When the device is supporting packets retransmission and the packets were successfully retransmitted this statistic is not incremented. As a result of lost network packets one or more frames can be damaged or left incomplete and the outDamagedFrames statistic will be incremented.
  • outErroneousPackets - Number of video stream network packets that were rejected because of the errors in their structure/content or unknown/unsupported content (e.g. packet too short, value out of range, unknown type, etc.), and video stream network packets sent by the device to notify about errors (e.g. inability to resent a lost packet, frame dropped). This statistic does not include CRC/transmission errors (those packets, after retransmission attempt, are eventually counted as lost packets). This statistic can increment periodically by small values after failed packet retransmission attempts (caused by communication problems). Large, constant and continuous incrementing of this statistic can indicate a standard incompatibility issue with the device or unsupported video streaming format currently selected in the device. The description of the issue with the last erroneous packet is available on the outLastPacketError output.
  • outReconnections - Number of times the network connection with the device was broken and successfully restored. Restoring network connection usually results in resetting of the device stream state, resetting of some other statistics and lost of unspecified amount of frames. In properly working system network connection should never be lost. Often reconnections may indicate very serious network communication issues, serious local system performance issues (like stalling of whole system) or technical problems with the device.

Setting the inReset input to True results in resetting of all statistics back to zero (filter outputs will be set to the last value of statistics before their reset).