CoaxlinkGrabber to EGrabber migration guide

This document shows how to migrate from the obsolete .NET CoaxlinkGrabber interface to the new .NET EGrabber interfaces.

IntelliSense

Visual Studio is of great help while migrating from CoaxlinkGrabber to EGrabber: you can explore the Euresys API with the IntelliSense auto-complete feature of the IDE.

Namespaces

• The namespace Euresys.Managed no longer exists
• The grabber and buffer classes are all in namespace Euresys
• The types related to GenICam are in namespace Euresys.gc (gc stands for GenICam.Client)
• The Euresys custom types related to GenICam are in namespace Euresys.ge (ge stands for GenICam.Client.Euresys)
• The image converter tools are in namespace Euresys.RGBConverter

EGrabber

CoaxlinkGrabber is superseded by a set of EGrabber classes:

• EGrabberCallbackOnDemand:
  • close to CoaxlinkGrabber
  • "on demand" variant of EGrabber
  • .NET wrapper of EGrabber<CallbackOnDemand>
  • buffers are popped "on demand" by the application using ScopedBuffer
• EGrabberCallbackSingleThread:
  • "single thread of callbacks" variant of EGrabber
  • .NET wrapper of EGrabber<CallbackSingleThread>
  • buffers and events are all given in a single dedicated thread via delegates (buffer and events are sorted by timestamp)
• EGrabberCallbackMultiThread:
  • "one thread of callbacks for each type of event" variant of EGrabber
  • .NET wrapper of EGrabber<CallbackMultiThread>
  • buffers and events of different types are given in dedicated threads via delegates
  • depending on the thread scheduling, events from different event queues might not be delivered in their chronological order
  • as no sorting is applied, this is the fastest delivery mechanism

A few methods from CoaxlinkGrabber have been renamed in EGrabber:

• method Width becomes getWidth
• method Height becomes getHeight
• methods GetInfoXyz become getInfo(..., out) (see next paragraph)

ScopedBuffer

• The class ScopedBuffer moved from Euresys.CoaxlinkGrabber to Euresys

• GetInfo methods: the type of the return value is no longer encoded in the method name, but is now inferred by the type of the output value. E.g.,

  UInt64 ts;
  ts = buffer.GetInfoUInt64(GenICam.Client.Managed.BUFFER_INFO_CMD.BUFFER_INFO_TIMESTAMP);

  becomes

  UInt64 ts;
  buffer.getInfo(Euresys.gc.BUFFER_INFO_CMD.BUFFER_INFO_TIMESTAMP, out ts);

Euresys.SizeT, Euresys.PtrDiffT

Some GenTL module information (e.g., BUFFER_INFO_SIZE_FILLED) correspond to size_t values. The size of such information depend on the target architecture. Unfortunately C# does not expose such types directly. For this purpose, Euresys exposes two value structures: SizeT and PtrDiffT. Those structures embed a private element whose size corresponds to size_t and ptrdiff_t respectively (i.e., 4 bytes for x86 and 8 bytes for x64). These structures provide implicit conversions, which allow the user to use them as integers without worrying about the actual size of the underlying data. For example:

Euresys.SizeT size;
buffer.getInfo(Euresys.gc.BUFFER_INFO_CMD.BUFFER_INFO_SIZE_FILLED, out size);
// the information is available in size

Euresys.GenTL.Infinite

Some EGrabber methods (e.g., those with a timeout parameter) accept an infinite value. That special value is available as a static member of the GenTL class:

grabber.pop(Euresys.GenTL.Infinite)

Euresys.Platform

The new class Euresys.Platform provides static information about the library:

• Euresys.Platform.is64bit: a boolean indicating whether the library has been compiled for the target x64 or for the target x86
• Euresys.Platform.ptrSize: basically sizeof(void *), i.e. 4 for x86 and 8 for x64.

Exceptions

The managed exceptions corresponding to the C++ EGrabber exceptions are now available in the namespace Euresys and their members are the same as their C++ counterparts.

New features

Euresys.GenApiQueryBuilder

The class GenApiQueryBuilder exposes helper functions to build special GenICam features that perform advanced queries on the GenICam features and/or enumeration entries. For example:

using Euresys;

// To get all the features of the remote device
String[] features =
    grabber.getStringListRemoteModule(GenApiQueryBuilder.Features());

// To get the available enumeration entries of the feature "ExposureMode"
String[] entries =
    grabber.getStringListRemoteModule(GenApiQueryBuilder.EnumEntries("ExposureMode"));

Euresys Events

• The EGrabber configuration to enable events slightly differs between the C++ version and the C# (.NET) version. This is because the C++ EGrabber interface heavily depends on C++ templates (to select at compile time the right EGrabber variant and combination of events). However the concept of C++ template is not transposable to .NET classes. Therefore the .NET EGrabber interface exposes EGrabber variants as actual classes and the API such as enableEvent<DATA> are replaced by a set of functions for each event DATA types. The following code snippets show C++ and C# code that perform the same job:

  // C++ code
  grabber.enableEvent<Euresys::NewBufferData>();
  grabber.enableEvent<Euresys::DataStreamData>();
  grabber.processEvent<OneOf<Euresys::NewBufferData, Euresys::DataStreamData> >(100);

  // C# code
  grabber.enableNewBufferDataEvent();
  grabber.enableDataStreamDataEvent();
  grabber.processEventFilter(100, Euresys::NewBufferData, Euresys::DataStreamData);

• Event delivery: The C++ code gets EGrabber callback events by deriving the EGrabber class and implementing the onXyzEvent methods. With the C# (.NET) classes, events are delivered via delegates of the EGrabber instances. Here are code snippets that show C++ and C# code to handle new buffer and data stream events (with CallbackMultiThread variant):

  // C++ code
  class MyGrabber: public Euresys::EGrabber<Euresys::CallbackMultiThread> {
      public:
          // ...
          void onNewBufferEvent(const Euresys::NewBufferData &data) {
              Euresys::ScopedBuffer buffer(*this, data);
              // code using the buffer (buffer is pushed back automatically)
          }
          void onDataStreamEvent(const Euresys::DataStreamData &data) {
              // code using the data stream event
          }
  };

  // C# code
  grabber.onNewBufferEvent =
      delegate(Euresys.EGrabberCallbackMultiThread g, Euresys.NewBufferData data) {
          using (Euresys.ScopedBuffer buffer = new Euresys.ScopedBuffer(g, data)) {
              // code using the buffer (buffer is pushed back automatically)
          }
      };
  grabber.onDataStreamEvent =
      delegate(Euresys.EGrabberCallbackMultiThread g, Euresys.DataStreamData data) {
          // code using the data stream event
      };

Sample programs

Please have a look at the samples in the cs and vb directories.