C# / .NET

Prerequisites

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

To use it in a C# project, add a reference to the ids_peak_dotnet.dll to the project.

Before starting your application, make sure that the DLL-Loader can find all required libraries. This means that ids_peak_dotnet.dll, ids_peak_dotnet_interface.dll, ids_peak.dll and all GenICam libraries required by ids_peak.dll are located next to your application binary or that the directory where they are located is added to the DLL-Loader's search directories. To add their directory to the DLL-Loader's search directories, you could simply append their directory to the environment variable Path:

• PowerShell

  $env:Path="$env:Path;<Installation-Directory-Of-ids_peak.dll>"
  $env:Path="$env:Path;<Installation-Directory-Of-ids_peak_dotnet.dll>"
  # Then start your application

• CMD

  set Path=%Path%;<Installation-Directory-Of-ids_peak.dll>
  set Path=%Path%;<Installation-Directory-Of-ids_peak_dotnet.dll>
  REM Then start your application

Usage

The .NET API works much like the C++ API. The same principles, class and method names apply. For example, listing all available devices:

using peak; 
try
{
    Library.Initialize();
    var deviceManager = DeviceManager.Instance();
    deviceManager.Update();
    var deviceDescriptors = deviceManager.Devices();
    foreach (var deviceDescriptor in deviceDescriptors)
    {
        Console.WriteLine(deviceDescriptor.DisplayName());
    }
}
catch (System.ApplicationException e)
{
    Console.WriteLine("Exception: " + e.Message);
}

Warning

The DeviceManager is incompatible with using statements or declarations, since it is implemented as a singleton. Being part of a using statement or declaration would result in Dispose() being called on the DeviceManager at the end of the scope. Further use of the reference returned by DeviceManager.Instance would then result in a crash, since that instance has been disposed already.

Converting a Buffer to an Image

It is possible to convert the content of a Buffer into an image by directly employing Buffer::BasePtr alongside a custom conversion routine to ensure compatibility with any image processing library. However, the recommended method is to use the BufferToImage function. This function is included in the supplementary assembly ids_peak_ipl_extension_dotnet.dll. BufferToImage is specifically engineered to simplify the conversion process of raw memory data stored within a Buffer into an peak::ipl::Image that can be used for further processing.

In order to make use of this functionality, an assembly reference must be added to the project and the ids_peak_ipl_extension_dotnet_interface.dll needs to be available. See the Prerequisites section above for further instructions or use one of the provided samples that are shipped with the SDK as a starting template.

An example usage could look like as follows:

// Get buffer from device's data stream
buffer = dataStream.WaitForFinishedBuffer(1000);
 
// Create peak::ipl::Image (shallow copy)
var image = ids_peak_ipl_extension.BufferToImage(buffer);

Warning

The resulting image still uses the underlying memory of buffer. For this reason, you must ensure that you do not re-queue the buffer until you have finished processing image.

Comparison to the C++ API

There are a few differences between the C++ API and the .NET API. The most important ones are listed here:

Resource Management

The C++ API utilizes smart pointers for deterministic memory management, where the last smart pointer that holds a reference to the object destroys it when the smart pointer goes out of scope.

To close a module (e.g. the Device), you have to release all its shared_ptr instances (out-of-scope, call reset(), set to nullptr), then the module closes immediately.

• C++

  {
      auto device = deviceDescriptors[0].OpenDevice(DeviceAccessType.Control);
      // ...
  } // Device closes here

By default, C# uses garbage collection to manage memory and resources. As a result, an object without any active references is not immediately closed or deleted. Instead, it will be removed by the garbage collector at an unspecified point in the future.

However, many peak objects hold resources that are not managed by the garbage collector, known as unmanaged resources. When working with unmanaged resources, it is essential to release them as soon as they are no longer needed. This can be achieved using one of the following methods:

Call Dispose() explicitly:

• C#

  var device = deviceDescriptors[0].OpenDevice(DeviceAccessType.Control);
  // do something with device...
  device.Dispose(); // Device is closed here

Or let a using statement handle calling Dispose() at the end of the scope:

• C#

  using (var device = deviceDescriptors[0].OpenDevice(DeviceAccessType.Control))
  {
      // do something with device...
  } // Device is closed here

It is important to release unmanaged resources in the reverse order in which they were acquired:

• C#

  var device = deviceDescriptors[0].OpenDevice(DeviceAccessType.Control);
   
  using (var nodemap = device.RemoteDevice().NodeMaps()[0])
  {
      var frameRateNode = nodemap.FindNode<FloatNode>("AcquisitionFrameRate");
      frameRateNode.SetValue(5);
  } // Nodemap is closed here
   
  var dataStream = device.DataStreams()[0].OpenDataStream();
  var grabbing = dataStream.IsGrabbing();
  dataStream.Dispose(); // DataStream is closed here
   
  device.Dispose(); // Device is closed here

Change Notification

To be notified when certain events happen, the C++ API employs callbacks that you have to register and unregister. C# has the concept of events built-in and similarly to C++ you have to register a delegate as an event handler:

• C++ Callbacks

  device_manager.RegisterDeviceFoundCallback(
      [](const std::shared_ptr<peak::core::DeviceDescriptor>& newDev)
      { std::cout << "Device found: " << newDev->DisplayName() << '\n'; });

• C# Events + Delegates

  deviceManager.DeviceFoundEvent += (object o, DeviceDescriptor newDev)
      => Console.WriteLine("Device found: {0}", newDev.DisplayName());

Overloads vs. Default Parameters

While C# supports optional parameters as well, the current C# API provides an overload for each default parameter instead:

• C++ Method Default Parameters

  DataStream::StartAcquisition(
      AcquisitionStartMode mode=AcquisitionStartMode::Default,
      uint64_t numToAcquire=INFINITE_NUMBER);

• C# Method Overloads

  DataStream.StartAcquisition(peak.core.AcquisitionStartMode mode, ulong numToAcquire)
  DataStream.StartAcquisition(peak.core.AcquisitionStartMode mode) // with numToAcquire=INFINITE_NUMBER
  DataStream.StartAcquisition() // with mode=Default and numToAcquire=INFINITE_NUMBER

Generic Methods

C# also supports function templates (i.e. generic methods), which can be used as follows:

• C++ Function Templates

  nodeMapRemoteDevice->FindNode<peak::core::nodes::StringNode>("DeviceModelName")->Value()

• C# Generic Methods

  nodeMapRemoteDevice.FindNode<peak.core.nodes.StringNode>("DeviceModelName").Value());

However, some IDE's and/or .NET implementations might not support such generic methods (e.g. NI Labview). Therefore all template specifications have been made available separately:

• C#

  nodeMapRemoteDevice.FindNodeString("DeviceModelName").Value());