Skip to main content

Using Zebra GenTL Consumer (library)

To use your Zebra GenTL Consumer (library) with Aurora Imaging Library, you must first install at least one third-party GenTL Producer (library). The Aurora Imaging Library GenTL Consumer communicates with the third-party GenTL Producer that allows you to configure or grab from your compliant devices (camera).

[Image: bsn_gentl_configurationfiles.png]

Aurora Imaging Capture Works' Feature Browser can access all of the GenICam GenTL-compliant device description files (XML), providing an interface to view and change the system information, digitizer, device (camera), and buffer.

GenICam-compliant device description files​

The Zebra GenTL Producer (library) uses five distinct sets of GenICam-compliant device description files (XML).

  • Per Aurora Imaging Library system:
    • GenTL system configuration information. The system refers to the allocated GenTL Producer. There is one GenTL system configuration information file per GenTL Producer.
    • GenTL interface configuration information. The interface, in this case, is the type of physical connection (port) between the Host and the device (such as Camera Link, Ethernet, or USB3 connections). Note that this could include auxiliary I/O signals such as trigger input, user input or user output, depending on the signal.
  • Per Aurora Imaging Library digitizer:
    • GenTL device configuration information. The GenTL device is a proxy to the remote device controlling the GenTL Producer's view of the device. Typically, there is one GenTL device configuration information file for each digitizer allocated on your Aurora Imaging Library system.
    • GenTL remote device configuration information. The GenTL remote device is your actual device (camera). Typically, there is one remote device configuration information file for each camera allocated to a specific Aurora Imaging Library digitizer. With Aurora Imaging Library, this is a one-to-one relationship.
    • GenTL stream configuration information. The GenTL stream is the data stream generated by your device (camera) is handled by the GenTL Producer. Typically, there is one GenTL stream configuration information file per data stream between your device and your digitizer.
  • Per Aurora Imaging Library buffer:
    • GenTL buffer configuration information (optional). The GenTL buffer is how the GenTL Consumer handles buffers. Typically, there is one GenTL buffer configuration information file per acquisition target (that is, per Aurora Imaging Library buffer used by your Aurora Imaging Library system).

Allocating Aurora Imaging Library GenTL systems​

You can then allocate an Aurora Imaging Library GenTL system using MsysAllocwith M_SYSTEM_GENTL. Set SystemNum to M_DEVn + M_GENTL_PRODUCER(n), where M_DEVn corresponds to the rank of the adapter board and M_GENTL_PRODUCER(n) specifies the index of the GenTL Producer to allocate. When you install more than one GenTL Producer on your computer, the GenTL Producers are indexed and sorted by Aurora Imaging Library. You can establish the number of GenTL Producers, using MappInquire with M_GENTL_PRODUCER_COUNT or using the General Default Values page of the Aurora Imaging Configurator utility. Allocating a GenTL system opens general communication with all connected third-party devices that can communicate with the GenTL Producer. You can then allocate a digitizer for each device (camera) using MdigAlloc.

You can allocate more than one Aurora Imaging Library GenTL system (MsysAllocwith M_SYSTEM_GENTL) in a process (executable); and each must have a unique SystemNum. Note that for GigE Vision, USB3 Vision, and custom transport layer type Producers, you must only use M_DEV0 to allocate the GenTL system. Allocating one Producer will discover all devices of this type regardless of their adapter board. For all other transport layer type Producers, M_DEVn targets the nth frame grabber of that type. For example, you can allocate two systems that use the same GenTL Producer but target different frame grabbers that have the same type as the Producer. GenICam GenTL Producers of mixed-type can be used multiple times; the mixed-type supports multiple interface technologies, and can be used once per interface type. For example, a mixed-type library can support both a proprietary Ethernet (non-GigE Vision) camera and a proprietary USB (non-USB3 Vision) camera; therefore, a GenICam GenTL mixed-type Producer can be allocated twice. Otherwise, a GenTL Producer can only be used once per Aurora Imaging Library application.

Mixed-type GenTL Producers​

When allocating an Aurora Imaging Library GenTL system for a mixed-type GenTL Producer, you can also set the InitFlag parameter to the type of interface technology that you want to use. For example, if you have a mixed-type GenTL Producer that supports both GigE Vision and USB3 Vision, but you only want GigE Vision interfaces, set the InitFlag to M_GEV. If you do not specify an interface type, all interface types supported by the Producer are used.

Controlling and Inquiring GenTL features​

In most cases, you should control and inquire GenTL features using the conventional Aurora Imaging Library functions (for example, MsysControl/MsysInquire, MdigControl/MdigInquire, and MbufControl/MbufInquire). However, some GenTL-compliant device have features that can only be accessed using MsysControlFeature/MsysInquireFeature, MdigControlFeature/MdigInquireFeature, and MbufControlFeature/MbufInquireFeature. For more information about accessing the features of your GenTL-compliant device, refer to Using Aurora Imaging Library with GenICam.

Aurora Imaging Library buffer handling with the Zebra GenTL Consumer (library)​

The GenICam GenTL standard specifies that a buffer must be announced before it can be used to receive a grabbed image. To overcome this requirement, the Zebra GenTL Consumer automatically announces ten internal buffers when any digitizer is allocated (using MdigAlloc). Note that allocated grab buffers will also be automatically announced to the Producer when MdigGrab, MdigGrabContinuous, or MdigProcess is called. This allows you to use MdigGrab, MdigGrabContinuous, or MdigProcess to capture frames. These functions use internal buffers to buffer the incoming data before it is copied to the specified Aurora Imaging Library buffer, or if a grab cannot be made directly to the allocated buffer. For example, if you allocate a 3-band color grab buffer and the device (camera) outputs a monochrome image, the image will be grabbed into an internal buffer and copied into the allocated 3-band color buffer. Note that you are still require to allocate and specify an Aurora Imaging Library buffer. Note that when usingMdigProcess, each buffer queued is automatically announced by Aurora Imaging Library.

Note that when using MdigGrab, there is a delay announcing the buffer because pending grabs must finish before announcing a new buffer. You can manually announce buffers using MdigControl with M_GENTL_ANNOUNCE_BUFFER. When using MdigGrabContinuous or MdigProcess, there is no delay present; this is because grabs are not immediately executed when these functions are called. When you are finished with the buffer, revoke it using MdigControl withM_GENTL_REVOKE_BUFFER before freeing it. Note that if you use M_GENTL_ANNOUNCE_BUFFER, Aurora Imaging Library will not use its internal buffers.

General GenTL Producer configuration and installation requirements​

The GenTL Producer communicates with and is used by the Zebra GenTL Consumer (library) to configure or grab from your GenICam-compliant devices (camera). You can configure a GenTL Producer in the Aurora Imaging Configurator utility by expanding the General item in the tree structure and navigating to theDefault Values subitem where you can select the GenTL Producer number that corresponds to the correct GenTL Producer library. Alternatively, you can specify the GenTL Producer to allocate the Aurora Imaging Library GenTL system by setting SystemNum to M_DEVn + M_GENTL_PRODUCER(n), where M_DEVn corresponds to the rank of the board and M_GENTL_PRODUCER(n) specifies the index of the GenTL Producer to allocate. You can determine the number of GenTL libraries installed on your computer, using MappInquire with M_GENTL_PRODUCER_COUNT. If the expected GenTL Producer library is not visible in the Aurora Imaging Configurator utility, the cause is typically that the device's GenTL Producer file (CTI file extension) or the GENICAM_GENTL64_PATH environment variable does not include the path to the correct CTI file. Make sure that the GenTL Producer is installed either by the software provided with the device, or install a compatible generic GenTL Producer. In addition, verify that the GENICAM_GENTL64_PATH environment variable has the appropriate CTI file path. Each directory that you list in the environment variable must contain a CTI file (GenTL Producer).

Note: Note that GenTL Producer information is highly dependent on the vendor of the GenICam-compliant device. For specific information related to your device, refer to the device's documentation.

GenIcam SFNC​

For more information on the GenICam GenTL standard features available, refer to GenICam's standard feature naming convention (SFNC), found online at: emva.org/standards-technology/genicam/. Additional GenICam GenTL SFNC-extension features might be available; check your camera's manual and Aurora Imaging Capture Works' Feature Browser for details. Note that the standard features specified in the GenICam SFNC work with the Aurora Imaging Library Digitizer module.

Copyright © 2026 Zebra Technologies.