You are here: Start » Technical Issues » Working with GenICam GenTL Devices

Working with GenICam GenTL Devices


GenICam GenTL is a standard that defines a software interface encapsulating a transport technology and that allows applications to communicate with general vision devices without prior knowledge of its communication protocol. GenTL supporting application (a GenTL consumer) is able to load a third party dynamic link library (a GenTL provider) that is a kind of a "driver" for a vision device. GenICam standard allows to overcome differences with communication protocols and technologies, and allows to handle different devices in same common way. However application still needs to be aware of differences in device capabilities and be prepared to cooperate with specific device class or device model.

FabImage Library contains a built-in GenTL subsystem that helps and simplifies usage of a GenTL device in vision application. FIL GenTL subsystem helps in loading provider libraries, enumerating GenTL infrastructure, managing acquisition engine and frame buffers, converting image formats and implements GenAPI interface.

In order to be able to use a GenTL provider it needs to be properly registered (installed) in local system. Usually this task is performed by an installer supplied by a device vendor. Please note that a 32bit application requires a 32 bit provider library and a 64 bit application requires respectively a 64 bit provider library. A registered GenTL provider is characterized by a file with ".cti" extension. Path to cti library containing folder is stored in an environmental variable named "GENICAM_GENTL32_PATH" ("GENICAM_GENTL64_PATH" for 64 bit providers).

Basic Usage

Functions designed for GenTL support can be found in GenTL and GenApi categories. A basic application will first use a GenTL_OpenDevice function to open a device instance (to establish the connection) and to request a handle for further operations on the device. This handle can be than used with GenApi functions to access device specific configuration and manage them. When the device identifiers are not fully known, or can dynamically change at runtime a GenTL_FindDevices function can be first used to enumerate available GenTL devices.

To start streaming video out of configured device a GenTL_StartAcquisition function must be executed. After this sequentially upcoming images can be retrieved with GenTL_ReceiveImage or GenTL_TryReceiveImage functions. Images will be stored in an input FIFO queue. Not retrieved images (on queue overflow) will be dropped starting from the oldest one. To stop image acquisition a GenTL_StopAcquisition function should be called. Image acquisition can be stopped and than started again multiple times for same device with eventual configuration change in between (some parameters can be locked for time of image streaming).

To release the device instance its handle need to be closed with GenTL_CloseHandle function.

Advanced Usage

When more information need to be known about GenTL environment its structure can be explored using GenTL_EnumLibraries, GenTL_GetLibraryDescriptor, GenTL_EnumLibraryInterfaces, GenTL_GetInterfaceDescriptor functions.

When extended information or configuration, specific for GenTL provider or transport technology need to be accessed, following functions can be considered: GenTL_OpenLibrarySystemModuleSettings, GenTL_OpenInterfaceModuleSettings, GenTL_OpenDeviceModuleSettings, GenTL_OpenDeviceStreamModuleSettings.

Additional Requirements

When using GenTL subsystem of FabImage Library a "Genicam_Kit.dll" file is required to be in range of application. This file (selected for 32/64 bit) can be found in FabImage Library SDK "bin" directory.

Previous: Known Issues Next: Processing Images in Worker Thread