Back to Adaptive Vision Library website

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

GigEVision_ReceiveImage


Header:Genicam.h
Namespace:avl

Receives next frame from video stream.

Syntax

C++
C#
 
void avl::GigEVision_ReceiveImage
(
	GigEHandle inDeviceHandle,
	avl::Image& outImage,
	atl::Optional<atl::uint64&> outFrameId = atl::NIL,
	atl::Optional<atl::uint64&> outTimestamp = atl::NIL
)

Parameters

Name Type Default Description
inDeviceHandle GigEHandle Handle of an opened device that is streaming video.
outImage Image& Image buffer that will receive a new frame.
outFrameId Optional<uint64&> NIL Frame block Id set by device
outTimestamp Optional<uint64&> NIL Frame capture timestamp set by device (when supported)

Optional Outputs

The computation of following outputs can be switched off by passing value atl::NIL to these parameters: outFrameId, outTimestamp.

Read more about Optional Outputs.

Description

This function will return the next available frame from incoming buffer. When input buffer is empty the function will block execution and wait for the next frame to be completed.

The function returns only complete and valid frames, when a frame is corrupted and it cannot be fixed, it is automatically discarded by the library.

A frame is converted from the device stream pixel format to the best suitable format of avl::Image. Automatic conversion includes:

  • Conversion from Bayer color mosaic to RGB.
  • Conversion of YUV to RGB.
  • Ordering of RGB/aRGB channels.
  • Unpacking 10, 12 or 14 bpp into 16 bpp images.

Returned image can contain 1, 3 or 4 channels with sint8, uint8 or uint16 pixel type.

outFrameId parameter is optional (can be set to Nil, when not used or given a reference to an output variable). This parameter returns a number identifying current frame in video sequence. This number is generated by device and incremented by one at the beginning of transmission of every frame block. The valid range of this id, for GigEVision compliant devices, is 1...65535 (starting at 1 and incrementing sequentially up to 65535, then wrapping back to 1). This value can be used to control correctness of received image sequence and detection of lost frames. Please note that this method can be used only to detect frames that was transmitted by device but lost before application could process them. This method cannot be used when lost image was not transmitted by device (e.g. when device missed trigger signal).

outTimestamp parameter is optional (can be set to Nil, when not used or given a reference to an output variable). This parameter returns a timestamp of current frame that was marked by the device at point of grabbing the image. Support of this parameter by the device is optional and for some devices this output can be not effective. Frequency of the timer used for this timestamp is device dependent. Refer to device documentation for details about timestamp timer. Usually a frequency of this timer can be retrieved using a GevTimestampTickFrequency parameter available in device parameters tree. Value of this output will wrap around in range from 0 to 231-1.

Exceptions

This function will throw an exception in the following situations:

  • Device handle is invalid.
  • Device is not streaming video.
  • Timeout occurred when waiting for next complete frame.
  • Device sends image in pixel format that cannot be converted.
  • Device streams in a mode that does not transport images or the library is unable to read the image from stream.
  • Device connection is lost and cannot be restored.

See Also