Mainpage

Introduction

The IDS peak genericAPI library provides a unified interface for GenTL and GenApi, while also adding additional convenience features. These enhancements are designed to improve usability and simplify common tasks, making interaction with GenApi more efficient and user-friendly.

GenAPI & GenTL Wrapper

The classes in the core namespace are mostly a tight wrapper around the GenAPI and GenTL. It provides some convenience by automatic resource cleanup (RAII), but mostly it reflects the hierarchical structure of the GenTL:

• Each ProducerLibrary represents one *.cti and contains exactly one System (not part of GenTL).
• Each System contains 0 or more Interfaces.
• Each Interface represents one physical interface in the system (i.e. one network interface card) and contains 0 or more Devices.
• Each Device represents the GenTL Producers’ proxy for one physical RemoteDevice (i.e. a camera) and contains 0 or more DataStreams.
• Each DataStream represents a single (image) data stream. 0 or more Buffers can be assigned to each DataStream.
• Each Buffer represents a single, separate memory buffer from the DataStream.

Each module can list the Descriptors of its child modules, which can open the corresponding child module.

Each module needs its parent module to function properly. Therefore, you need to keep the parent modules around until you are done with the child module. When using the DeviceManager, it keeps the ProducerLibrary, System, and Interface modules open until program termination (or until calling DeviceManager::Reset()).

Convenience Layer

The main peak namespace contains global library functions as well as convenience functionality, which don't exist in GenAPI/GenTL. The convenience functionality simplifies the standard usage of the API, without sacrificing access to the more complex API in the core namespace.

Usage

Initialize / Close Library

Before doing anything else, call Library::Initialize(). This will initialize any needed resources. Calling any other function before calling Library::Initialize() will result in a NotInitializedException.

After you are done using the library, call Library::Close() before unloading the library. This will clean up any internal resources and stop any running threads.

Note

Calling Library::Close() is of particular importance on MS Windows platforms, when using "Run-Time Dynamic Linking", especially when unloading the DLL with FreeLibrary(). Otherwise it is very likely to run into the "Loader-Lock Deadlock Problem" during DLL unloading.

peak::Library::Initialize();
// do something here ...
peak::Library::Close();

Hierarchical access

A common way to start programming with the IDS peak genericAPI is to enumerate the GenTL producer libraries found in the current environment. This is achieved by calling EnvironmentInspector::CollectCTIPaths(). Once you have chosen a producer library, you pass its path to the static method ProducerLibrary::Open(). From there, you can follow the hierarchical structure of the modules: ProducerLibrary -> System -> Interface -> Device -> DataStream. Each Module can list and open its child-modules.

DeviceManager

If you don't need tight control over when modules are opened and closed, you can also use the DeviceManager. It provides much more convenience by enabling you to enumerate all modules of the available producer libraries with a single function call (DeviceManager::Update()):

• C++

  auto& deviceManager = peak::DeviceManager::Instance();
  deviceManager.Update();
  auto deviceDescriptors = deviceManager.Devices();

• C#

  var deviceManager = peak.DeviceManager.Instance();
  deviceManager.Update();
  deviceDescriptors = deviceManager.Devices();

• Python

  device_manager = peak.DeviceManager.Instance()
  device_manager.Update()
  device_descriptors = device_manager.Devices()

To enumerate the Devices, the underlying modules (i.e. ProducerLibraries, Systems, and Interfaces) need to be opened. Since the DeviceManager is a singleton, these modules stay open until program termination or until DeviceManager::Reset() is called.

GenTL Compatibility

*.ctis using GenTL v1.1 or higher are supported. When accessing features the *.cti doesn't support, there will be a "not implemented" error. E.g. chunks exist since GenTL v1.3, so trying to access chunks with a GenTL v1.2 *.cti will result in a exception. GenTL v1.0 *.ctis are not supported.

Core-Principles

C-API with C++ Wrapper

The IDS peak genericAPI exists as a plain C-API, so it can be integrated in any programming environment. As a wrapper around the the C-API, there is also a more convenient C++ API. These C++ wrapper classes are implemented as header-only, so there are no compiler incompatibilities.

Descriptors

This API uses the concept of descriptors acting as delegates for all openable modules. A descriptor holds information about its module and can open its module.

Automatic resource release (RAII)

This API uses smart pointers to automatically release unused resources. This makes the interaction with the API very intuitive. As an example the descriptors' open functions return a smart pointer holding the opened module. If the user releases the last smart pointer referencing the opened module, the module automatically gets closed and destroyed.

• C++

  {
      auto device = deviceDescriptors.at(0)->OpenDevice(peak::core::DeviceAccessType::Control);
      // ...
  } // Device closes here

• C#

  using (var device = deviceManager.Devices()[0].OpenDevice(peak.core.DeviceAccessType.Control))
  {
      // ...
  } // Device closes here

• Python

  device = device_manager.Devices()[0].OpenDevice(ids_peak.DeviceAccessType_Control)
  # ...
  # Device closes when variable is destroyed

The same applies to the event controller returned by EventSupportingModule::EnableEvents(). After releasing the last smart pointer referencing the event controller, the corresponding event type is disabled automatically and the event controller itself is destroyed.

Static or Dynamic Loading

By default, this library is linked into the user program, therefore is loaded statically at program start. Instead, it can also be loaded dynamically, when the first library function is called. To use this feature, enable the CMake option PEAK_DYNAMIC_LOADING or set the #define PEAK_DYNAMIC_LOADING before including any of the libraries files.

Bindings

For all supported operating systems and architectures there exists an equivalent Python Binding.

For Windows, there is also a .NET version of the library.