Euresys Coaxlink Manual
PROGRAMMER'S GUIDE
Coaxlink
Coaxlink Driver Version 7.1
© EURESYS s.a. 2017 - Document version 7.1.637 built on 2017-04-14
EURESYS s.a. shall retain all property rights, title and interest of the documentation of the hardware and the soware,
and of the trademarks of EURESYS s.a. All the names of companies and products mentioned in the documentation may
be the trademarks of their respective owners. The licensing, use, leasing, loaning, translation, reproduction, copying or
modification of the hardware or the soware, brands or documentation of EURESYS s.a. contained in this book, is not
allowed without prior notice. EURESYS s.a. may modify the product specification or change the information given in this
documentation at any time, at its discretion, and without prior notice. EURESYS s.a. shall not be liable for any loss of or
damage to revenues, profits, goodwill, data, information systems or other special, incidental, indirect, consequential or
punitive damages of any kind arising in connection with the use of the hardware or the soware of EURESYS s.a. or resulting
of omissions or errors in this documentation.
ContentsCoaxlink Programmer's Guide
Contents
Introduction............................................................................................................................................................................ 5
GenApi.........................................................................................................................................................................................6
Register description.....................................................................................................................................................................6
GenApi implementation.............................................................................................................................................................. 6
Features........................................................................................................................................................................................6
GenTL...........................................................................................................................................................................................7
System module............................................................................................................................................................................ 7
Interface module......................................................................................................................................................................... 8
Device module............................................................................................................................................................................. 8
Data stream module....................................................................................................................................................................8
Buffer module.............................................................................................................................................................................. 8
GenTL API..................................................................................................................................................................................... 8
Euresys::EGenTL................................................................................................................................................................ 10
A first example........................................................................................................................................................................... 10
Relevant files..............................................................................................................................................................................11
Euresys::EGrabber.......................................................................................................................................................... 12
A first example........................................................................................................................................................................... 12
Acquiring images....................................................................................................................................................................... 13
Configuring the grabber............................................................................................................................................................15
Events......................................................................................................................................................................................... 16
Background............................................................................................................................................................................ 16
Counters................................................................................................................................................................................. 17
Notifications...........................................................................................................................................................................17
Callback functions................................................................................................................................................................. 18
Event identification............................................................................................................................................................... 19
Examples................................................................................................................................................................................ 20
EGrabber flavors....................................................................................................................................................................... 20
Events and callbacks examples................................................................................................................................................21
On demand callbacks............................................................................................................................................................21
Single thread and multi thread callbacks........................................................................................................................... 22
New buffer callbacks.............................................................................................................................................................23
Relevant files..............................................................................................................................................................................24
iii
Coaxlink Programmer's GuideContents
Euresys GenApi scripts................................................................................................................................................. 25
doc/basics.js............................................................................................................................................................................. 25
doc/builtins.js........................................................................................................................................................................... 30
doc/grabbers.js.......................................................................................................................................................................... 31
doc/module1.js.......................................................................................................................................................................... 33
EGrabber for MultiCam users...................................................................................................................................34
.NET assembly.................................................................................................................................................................... 40
A first example........................................................................................................................................................................... 40
Differences between C++ and .NET EGrabber......................................................................................................................... 41
Single thread callbacks............................................................................................................................................................. 42
Definitions............................................................................................................................................................................. 44
iv
IntroductionCoaxlink Programmer's Guide
Introduction
The Application Programming Interface (API) for Coaxlink cards is based on GenICam.
The goal of GenICam is to provide a standardized, uniform programming interface for using cameras and frame
grabbers based on different physical interfaces (CoaXPress, GigE Vision, etc.) or from different vendors.
GenICam is a set of EMVA standards (GenApi and GenTL), as well as related conventions for naming things (the
SFNC for standard features, the PFNC for pixel formats).
• GenApi is about description. At the core of GenApi is the concept of register description. Register descriptions are
provided in the form of XML files. They map low-level hardware registers to high-level features.
GenApi allows applications to detect, configure and use the features of cameras and frame grabbers in a uniform
and consistent way.
• GenTL is about data transport. The TL suffix stands for Transport Layer.
The GenTL standard defines a set of C functions and data types for enumerating, configuring, and grabbing images
from cameras and frame grabbers. This API is defined by a C header file.
Frame grabber vendors provide libraries that implement this API (i.e., libraries that export the functions declared in
the standard header file). These libraries are referred to as GenTL producers, or Common Transport Interfaces
(CTI) and use the cti file extension. The GenTL producer for Coaxlink cards is coaxlink.cti.
This document is meant to be read from beginning to end. Each chapter and section builds upon the preceding ones.
If you skip parts of the text, some of the explanations and examples may seem cryptic. If that happens, you should go
back and read the parts that you've skipped over.
5
Coaxlink Programmer's GuideGenApi
GenApi
GenApi addresses the problem of configuring cameras. The way this is achieved is generic, and applies to different
kinds of devices, including frame grabbers. In this chapter, everything we say about cameras also applies to frame
grabbers.
GenApi requires two things to work: a register description, and a GenApi implementation.
Register description
A register description is an XML file that can be thought of as a computer-readable datasheet of the camera. It defines
camera settings (such as PixelFormat and TriggerSource), and instructions on how to configure them (e.g., to
set ExposureMode to Timed, write value 0x12 to register 0xE0140). It can also contain camera documentation.
GenApi implementation
A GenApi implementation is a soware module that can read and interpret register description files.
The EMVA provides a reference implementation, but it is fairly difficult to use, and logging is very poor. Instead, we
recommend using the Euresys implementation bundled with the Coaxlink soware package. This implementation also
allows writing powerful configuration scripts.
Features
What the user gets from GenApi is a bunch of named features, organized in categories.
Set/get features
Set/get features are simple settings (called parameters in MultiCam), and can be of different types:
• integer (e.g., Width)
• float (e.g., AcquisitionFrameRate)
• enumeration (e.g., PixelFormat)
• boolean (e.g., LUTEnable)
• string (e.g., DeviceVendorName)
The value of features can be retrieved/modified using get/set functions. Some features are read-only and some are
write-only, but most allow read/write access.
Commands
There is also another kind of features: commands (e.g., AcquisitionStart). Commands are special: they don't
have any associated value; they have side effects. Command features are meant to be executed. When a command is
executed, some action happens in the camera (e.g., a soware trigger is generated). Obviously, get/set functions don't
make sense for commands and can't be used.
6
GenTLCoaxlink Programmer's Guide
GenTL
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 coaxlink.c
Interface Module PC1633 – Coaxlink Quad G3 (2-camera) – KQG00014
Device Module Device0
Buffer Module Buffers
Stream Module Stream0
PC1630 – Coaxlink Mono (1-camera) – KMO97322
Remote
Device X Device1
Buffers
Stream0
Remote
Device Y Device0
Buffers
Stream0
Remote
Device Z
Figure 1: GenTL Module Hierarchy
System module
The system module (also referred to as TLSystem), represents the GenTL producer (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
coaxlink.cti and the vendor name (Euresys).
7
Coaxlink Programmer's GuideGenTL
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).
Interface module
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).
Device module
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 data stream, 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 the data stream) and
DevGetPort (to get access to the remote device).
Data stream module
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).
Buffer module
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:
8
GenTLCoaxlink Programmer's Guide
•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 Euresys::EGenTL library which deals with these complications so that the user doesn't have to;
• or the Euresys::EGrabber library which provides a high-level, easy-to-use interface.
9
Coaxlink Programmer's GuideEuresys::EGenTL
Euresys::EGenTL
Euresys::EGenTL is a library of C++ classes that provide the same functionality as standard GenICam GenTL, but
with a more user-friendly interface. For example, it uses std::string instead of raw char pointers, and error codes
are transformed into exceptions. Euresys::EGenTL also takes care of locating the GenTL producer and loading the
functions it exports.
This library is implemented entirely in C++ header files. As a result, you can simply include the relevant header file:
#include <EGenTL.h>
Instead of the raw, low-level C functions that GenTL defines, we get a Euresys::EGenTL object that represents the
GenTL producer:
• Each GenTL function is available as a member method of Euresys::EGenTL. GenTL function names start with
an upper-case prefix. In Euresys::EGenTL, method names start with the same prefix, but written in lower-case.
For example, the GCReadPort function is exposed as the gcReadPort method, and the TLOpenInterface
function as the tlOpenInterface method.
• All GenTL functions return a GC_ERROR code indicating success or failure. When a function returns a code other
than GC_ERR_SUCCESS, an exception is thrown. This removes the burden of manually checking error codes aer
each function call.
• Since GenTL functions return a GC_ERROR, output values are returned through pointers passed as arguments.
Euresys::EGenTL methods offer a more natural interface; they return the output value directly:
GC_API TLGetNumInterfaces(TL_HANDLE hTL, uint32_t *piNumIfaces);
uint32_t tlGetNumInterfaces(TL_HANDLE tlh);
(Note that GC_API is defined as GC_IMPORT_EXPORT GC_ERROR GC_CALLTYPE. It is simply a GC_ERROR
decorated with calling convention and DLL import/export attributes.)
• For GenTL functions that deal with text, the corresponding Euresys::EGenTL methods convert from char *
to std::string and vice-versa:
GC_API TLGetInterfaceID(TL_HANDLE hTL, uint32_t iIndex,
char *sID, size_t *piSize);
std::string tlGetInterfaceID(TL_HANDLE tlh, uint32_t index);
• Some GenTL functions retrieve information about the camera or frame grabber. These functions fill a void *
buffer with a value, and indicate in an INFO_DATATYPE the actual type of the value. Euresys::EGenTL uses C
++ templates to make these functions easy to use:
GC_API GCGetInfo(TL_INFO_CMD iInfoCmd, INFO_DATATYPE *piType,
void *pBuffer, size_t *piSize);
template<typename T> T gcGetInfo(TL_INFO_CMD cmd);
A first example
This program uses Euresys::EGenTL to iterate over the Coaxlink cards present in the system, and display their id:
#include <iostream>
#include <EGrabber.h> // 1
10
Tabla de contenidos
Manuales populares de Sistema de E/S de otras marcas
WAGO
WAGO 750-344 Manual de usuario
Teknim
Teknim TWM-1887 Manual de instrucciones
Intelligent Appliance
Intelligent Appliance IA-2662-E Manual de usuario
BERGHOF
BERGHOF ECC DIO 16/16 Manual de instrucciones
Advantech
Advantech PCM-27J3AU Manual de instalación y operación
Festo
Festo CP-E08-M12-CL Manual de usuario
