You are here: Start » Function Reference » GenTL » GenTL_ReceiveImage
GenTL_ReceiveImage
Receives next frame from video stream.
Syntax
void avl::GenTL_ReceiveImage ( GenTLHandle inDeviceHandle, avl::Image& outImage, atl::Optional<int&> outFrameId = atl::NIL, atl::Optional<atl::uint64&> outTimestamp = atl::NIL )
Parameters
| Name | Type | Default | Description | |
|---|---|---|---|---|
 |
inDeviceHandle | GenTLHandle | Handle of an opened device that is streaming video. | |
 |
outImage | Image& | Image buffer that will receive a new frame. | |
|
outFrameId | Optional<int&> | NIL | Frame block Id set by device (when supported) |
|
outTimestamp | Optional<uint64&> | NIL | Frame capture timestamp set by device (when supported) |
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 sequentially incremented number identifying current frame in video sequence. Support of this parameter is optional and for some devices this parameter can be not effective. The value of this output is supplied by the GenTL provider library. Its support, range and wrap around depends on GenTL provider library and transport technology of the device. Refer to device vendor documentation for more information about Buffer FrameId. 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 lost on application side. Detection of frames lost in device and transport layer depends on GenTL provider library implementation and device transport technology.
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. Support of this parameter is optional and for some devices this output can be not effective. Frequency of the timer used for this timestamp is device and GenTL provider library dependent. Refer to device documentation for details about timestamp timer. 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 video stream is not initialized.
- 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.
