GenTL defines 5 types of objects, organized in a parent/child relationship:
| 1. | the system module |
| 2. | the interface module |
| 3. | the device module |
| 4. | the data stream module |
| 5. | the buffer module |
Each module:
| ● | corresponds to a particular element of the system; |
| ● | defines relevant pieces of information (info commands) that can be queried (using get info functions); |
| ● | allows exercising that module's functionality (using specific functions). |
Additionally, all modules except the buffer module behave as ports that allow read/write operations. These port functions are used by GenApi to load that module's description file, and to use its GenApi features.
System module
The system module (also referred to as TLSystem), represents the GenTL producer (e.g. the coaxlink.cti library). This module is at the top of the parent/child tree.
The system module provides basic information about the GenTL producer: things like the complete path to the CTI file and the vendor name (Euresys).
The real point of the system module is to list the interfaces (or frame grabbers) present in the system. The most important functions of the system module are TLGetNumInterfaces (to retrieve the number of frame grabbers in the system) and TLOpenInterface (to get access to one of the frame grabbers).
The GenTL standard calls frame grabbers interfaces. The system module has one child interface for each frame grabber: if there are 2 Coaxlink cards in the computer, the system module will have two child interfaces.
Each interface represents a frame grabber. Global frame grabber features such as digital I/O lines belong in the interface module. This means that the GenApi features controlling the I/O lines are attached to the interface.
Each interface also acts as parent to one or several devices. The most important functions of the interface module are IFGetNumDevices (to retrieve the number of cameras that can be connected to the interface) and IFOpenDevice (to get access to one of the devices).
The GenTL standard uses the terms device and remote device for two related but different concepts. A remote device is a real camera, physically connected to a frame grabber. This is different from the device module we describe here.
The device module is the module that contains the frame grabber settings relating to the camera. This includes things like triggers and strobes.
The device module also acts as parent to one or several data streams, and can be viewed as the sibling of the remote device. The most important functions of the device module are DevOpenDataStream (to get access to one of the data streams) and DevGetPort (to get access to the remote device).
The data stream module handles buffers. During acquisition runs, images are sent from the camera to the frame grabber, which transfers them to memory buffers allocated on the host computer. The data stream module is where image acquisition occurs. It is where most of the functionality resides.
Buffer handling is very flexible. Any number of buffers can be used. Buffers are either in the input queue, in the output queue, or temporarily unqueued. The application decides when empty buffers are queued (to the input FIFO), and when filled buffers are popped (from the output FIFO).
The buffer module simply represents a memory buffer given to a parent data stream. Useful metadata is associated to buffers. This includes the image width, height, pixel format, timestamp... These are retrieved through info commands (see BUFFER_INFO_CMD_LIST in the standard GenTL header file).
The buffer module is the only module that doesn't have read/write port functions; it doesn't have GenApi features.
GenTL API
GenTL makes it possible to detect, control and use all camera and frame grabber features, but its usage is tedious:
| ● | cti files must be dynamically loaded, and the functions they export must be accessed through pointers. |
| ● | Functions return an error code that must be checked by the application. |
| ● | Most functions read from/write to untyped buffers: the application must determine the required buffer size, allocate a temporary buffer, convert data to/from this buffer, and finally release the buffer memory. |
Instead of using the GenTL API directly, we recommend using either:
| ● | the EGenTL C++ class which deals with these complications so that the user doesn't have to; |
| ● | or the eGrabber library which provides a high-level, easy-to-use interface. |