Skip to content

C# Wrapper#

To allow you to use the Framegrabber API in programs you create with C#, you are provided with a C# Framgrabber API wrapper. This wrapper wraps the functionality of the Framegrabber API into a C# API.

All C Framegrabber API functions are wrapped as static functions in one C# class SiSoCsRt. The usage and function declaration is in most parts defined as described in the Framegrabber API documentation. The differences are detailed in the following sections.

Components of the Wrapper#

The C# wrapper is installed together with the Framegrabber SDK.

The C# wrapper consists of 2 files, SiSoCsInterface.dll and SiSoCsRt.dll:

  • SiSoCsRt.dll is the class you use to access the C# API within your code.
  • SiSoCsInterface.dll is the dll that communicates with the Framegrabber API.

In addition, you are provided with some code examples for using the C# wrapper.

Preparing Your Project#

To get started using the wrapper:

  1. Add a reference to the SiSoCsInterface.dll in your C# project. You find the file in your Framegrabber SDK installation: Basler\FramegrabberSDK5.x.x\lib
  2. Copy SiSoCsRt.dll to your PATH directory before running your program. You find the file in your Framegrabber SDK installation: Basler\FramegrabberSDK5.x.x\bin

Examples#

To get started with the image acquisition using the wrapper most easily, you find some C# examples in your Framegrabber SDK installation:

Basler\FramegrabberSDK5.x.x\SDKWrapper\CSharpWrapper\Examples

Framegrabber API Mapping#

Type Mapping#

C data types are mapped to the corresponding C# data types as follows:

C Data Types C# Data Types
int, int32_t int
unsigned int, uint32_t uint
int64_t long
uint64_t, size_t ulong
char * string

Pointers are either mapped into arrays or ref/out arguments.

In/Out function arguments are defined as ref, while the out function arguments are defined as out. For example:

int clGetManufacturerInfo(string manufacturerName, ref uint bufferSize, out uint version)

bufferSize is an in/out argument, while version is an out argument.

C enums are directly translated into C# enums.

C structs are mapped to C# classes, structs’ fields are either still directly accessible, or via constructors or setters/getters.

Void pointers are mapped to different types according to their usage. In many cases, it is mapped to byte.

Function Mapping#

Each function of the Framegrabber API has a corresponding public static function in the class SiSoCsRt.

Framegrabber API functions that create a reference to a struct and return an error code, are modified such that they return the reference directly (or null if an error occurred), and write back the error code in an out argument. For example, the function Fg_getAppletIterator is defined as:

Framegrabber API Definition:

int Fg_getAppletIterator(int boardIndex, const enum FgAppletIteratorSource src, Fg_AppletIteratorType * iter, int flags);

The return value is the result error code, and iter is the created reference.

C# Definition:

Fg_AppletIteratorType Fg_getAppletIterator(int boardIndex, const enum FgAppletIteratorSource src, int flags, int *errorCode)

The return value is the created reference, and the result errorCode is the error code.

Callback Functions#

Each callback function must have the signature of its corresponding delegate. The SiSoCallback class includes all declarations of the available function delegates.

For example, the following code is used to register an APC handler:

FgApcControl apcCtrl = new FgApcControl(10000,

(uint)(Fg_Apc_Flag.FG_APC_DELIVER_ERRORS));

apcCtrl.setApcCallbackFunction(apcCallback, null);

The function apcCallback must have the same signature as SiSoCallback.Fg_ApcFuncDelegate, an example implementation is:

static int apcCallback(uint imgNr, fg_apc_data userData) {

global_imgNr = (int)(imgNr);

return 0;

}

The declaration of SiSoCallback.Fg_ApcFuncDelegate looks as follows:

public delegate int Fg_ApcFuncDelegate(uint imgNr, fg_apc_data userData);

C# Wrapper API List#

The API of the wrapper is basically the same as that of the Framegrabber API. This section contains only the definitions of those functions that are renamed, or have a different order of arguments.

The functions provided here are grouped by library:

For detailed information about using a specific function, as well as for information regarding functions not listed here, refer to the Framegrabber API documentation.

fg#

Newly Defined Functions#

string Fg_getErrorDescription (int ErrorNumber)#

This function replaces both of the following functions:

const char *const Fg_getErrorDescription (Fg_Struct*Fg, int ErrorNumber)

const char *const getErrorDescription (int ErrorNumber)
int Fg_getParameterWith… (Fg_Struct Fg, int Parameter, out … Value, uint DmaIndex)#

List of overloaded functions that are used to get frame grabber parameters with information of different types. They replace the Framegrabber API function Fg_getParameterWithType, according to the passed type as follows:

FgParamTypes C# Wrapper Function
FG_PARAM_TYPE_INT32_T Fg_getParameterWithInt
FG_PARAM_TYPE_UINT32_T Fg_getParameterWithUInt
FG_PARAM_TYPE_INT64_T Fg_getParameterWithLong
FG_PARAM_TYPE_UINT64_T Fg_getParameterWithULong
FG_PARAM_TYPE_DOUBLE Fg_getParameterWithDouble
FG_PARAM_TYPE_CHAR_PTR Fg_getParameterWithString
FG_PARAM_TYPE_SIZE_T Fg_getParameterWithUInt /
Fg_getParameterWithULong
FG_PARAM_TYPE_STRUCT_FIELDPARAMACCESS Fg_getParameterWithIntArray /
Fg_getParameterWithUIntArray /
Fg_getParameterWithLongArray /
Fg_getParameterWithULongArray
FG_PARAM_TYPE_STRUCT_FIELDPARAMINT Fg_getParameterWithFieldParameterInt
FG_PARAM_TYPE_STRUCT_FIELDPARAMDOUBLE Fg_getParameterWithFieldParameterDouble
FG_PARAM_TYPE_COMPLEX_DATATYPE Not implemented
int Fg_setParameterWith…(Fg_Struct Fg, int Parameter, … Value, uint DmaIndex)#

List of overloaded functions that are used to set frame grabber parameters with information of different types. They replace the Framegrabber API function Fg_setParameterWithType, according to the passed type as following:

FgParamTypes C# Wrapper Function
FG_PARAM_TYPE_INT32_T Fg_setParameterWithInt
FG_PARAM_TYPE_UINT32_T Fg_setParameterWithUInt
FG_PARAM_TYPE_INT64_T Fg_setParameterWithLong
FG_PARAM_TYPE_UINT64_T Fg_setParameterWithULong
FG_PARAM_TYPE_DOUBLE Fg_setParameterWithDouble /
Fg_setParameterWithFloat
FG_PARAM_TYPE_CHAR_PTR Fg_setParameterWithString
FG_PARAM_TYPE_SIZE_T Fg_setParameterWithUInt /
Fg_setParameterWithULong
FG_PARAM_TYPE_STRUCT_FIELDPARAMACCESS Fg_setParameterWithIntArray /
Fg_setParameterWithUIntArray /
Fg_setParameterWithLongArray /
Fg_setParameterWithULongArray
FG_PARAM_TYPE_STRUCT_FIELDPARAMINT Fg_setParameterWithFieldParameterInt
FG_PARAM_TYPE_STRUCT_FIELDPARAMDOUBLE Fg_setParameterWithFieldParameterDouble
FG_PARAM_TYPE_COMPLEX_DATATYPE Not implemented

Functions with Different Arguments#

C# Framegrabber API Wrapper Framegrabber API
SisoImage Fg_getImagePtr(Fg_Struct Fg, int PicNr, uint DmaIndex) void *Fg_getImagePtr(Fg_Struct *\Fg, const frameindex_t PicNr, const unsigned int DmaIndex)
SisoImage Fg_getImagePtrEx(Fg_Struct Fg, int PicNr, uint DmaIndex, dma_mem pMem) void *Fg_getImagePtrEx(Fg_Struct *Fg, const frameindex_t PicNr, const unsigned int DmaIndex, dma_mem *pMem)

In Fg_getImagePtrand Fg_getImagePtrEx function, the return type is changed from void pointer, which directly represents the image bytes, in the Framegrabber API into SisoImage instance.

To get again the byte array from SisoImage, the function SisoImage.toByteArray(uint imageSize) can be called.

Additionally, it can be used directly with DrawBuffer function.

clser#

Functions with Reordered Arguments#

In the following function, the error code is written into out int errorCode instead of being returned from the function. While the created handle is returned from the function instead of being passed as an argument. If an error occurred, errorCode will have a value other than 0, and the return value will be null.

C# Framegrabber API Wrapper Framegrabber API
CLSerialRef
clSerialInit(uint serialIndex, out int errorCode)		 int clSerialInit(unsigned int serialIndex, void *serialRefPtr)

siso_genicam#

Functions with Reordered Arguments#

In the following functions, the error code is written into out int errorCode instead of being returned from the function. While the created handle is returned from the function instead of being passed as an argument. If an error occurred, errorCode will have a value other than 0, and the return value will be null.

C# Framegrabber API Wrapper Framegrabber API
SgcBoardHandle
Sgc_initBoard(Fg_Struct fg, int initFlag, out int errorCode)		 int Sgc_initBoard(Fg_Struct* fg, int initFlag, SgcBoardHandle* boardHandle)
SgcBoardHandle
Sgc_initBoardEx(Fg_Struct fg, uint initFlag, uint portMask, uint slaveMode, out int errorCode)		 int Sgc_initBoardEx(Fg_Struct* fg, unsigned int initFlag, SgcBoardHandle* boardHandle, unsigned int portMask, unsigned int slaveMode)
SgcCameraHandle
Sgc_getCamera(SgcBoardHandle boardHandle, uint port, out int errorCode)		 int Sgc_getCamera(SgcBoardHandle* boardHandle, const unsigned int port, SgcCameraHandle* cameraHandle)
SgcCameraHandle
Sgc_getCameraByIndex(SgcBoardHandle boardHandle, uint index, out int errorCode)		 int Sgc_getCameraByIndex(SgcBoardHandle* boardHandle, const unsigned int index, SgcCameraHandle* cameraHandle)
SgcConnectionProfile
Sgc_LoadConnectionProfile(Fg_Struct fg, string boardConfigurationFilePath, out int errorCode)		 int Sgc_LoadConnectionProfile(Fg_Struct* fg, const char* boardConfigurationFilePath, SgcConnectionProfile* connectionProfilePtr)
string
Sgc_getStringValue(SgcCameraHandle cameraHandle, string name, out int errorCode)		 int Sgc_getStringValue(SgcCameraHandle* cameraHandle, const char* name, const char* valuePtr)
string
Sgc_getEnumerationValueAsString(SgcCamer aHandle cameraHandle, string name, out int errorCode)		 int Sgc_getEnumerationValueAsString(SgcCa meraHandle* cameraHandle, const char* name, const char* valuePtr)

SisoDisplay#

Functions with Different Arguments#

C# Framegrabber API Wrapper Framegrabber API
void DrawBuffer(int nId, SisoImage ulpBuf, int nNr, string cpStr) void DrawBuffer(int nId, const void *ulpBuf, const int nNr, const char *cpStr)

In DrawBuffer function, the ulpBuf argument type is changed from void pointer, which directly represents the image bytes, in the Framegrabber API into SisoImage instance.

SisoImage is created using Fg_getImagePtr and Fg_getImagePtrEx functions. Additionally, SisoImage can be created from byte array using the following constructor:

SisoImage(byte[] imagePtr, uint pixelCount)

If such a SisoImage instance is used as a DMA buffer by calling fg_AddMem on it, it must be ensured that the byte array is neither collected nor moved around in memory by the garbage collector. This can be achieved using gcHandle = GCHandle.Alloc(image, GCHandleType.Pinned). The handle can be released with gcHandle.Free() after the memory was removed from the DMA buffer with fg_DelMem.

SisoIo.h#

Functions with Reordered Arguments#

In the following functions, the error code is written into out int errorCode instead of being returned from the function. While the created handle is returned from the function instead of being passed as an argument. If an error occurred, errorCode will have a value other than 0, and the return value will be null.

C# Framegrabber API Wrapper Framegrabber API
AviRef IoCreateAVIGray(string filename, int width, int height, double fps, out int errorCode) int IoCreateAVIGray(void *AviRef, const char *filename, int width, int height, double fps)
AviRef IoCreateAVIGrayW(string filename, int width, int height, double fps, out int errorCode) int IoCreateAVIGrayW(void *AviRef, const LPCWSTR filename, int width, int height, double fps)
AviRef IoCreateAVIColor(string filename, int width, int height, double fps, out int errorCode) int IoCreateAVIGrayColor(void *AviRef, const char *filename, int width, int height, double fps)
AviRef IoCreateAVIColorW(string filename, int width, int height, double fps, out int errorCode) int IoCreateAVIGrayColorW(void *AviRef, const LPCWSTR filename, int width, int height, double fps)
AviRef IoOpenAVI(string fileName, out int width, out int height, out int bitDepth, out int errorCode) int IoOpenAVI(void *AviRef, const char *fileName, int *width, int *height, int *bitDepth)
SeqRef IoCreateSeq(string pFilename, int width, int height, int bitdepth, int format, out int errorCode) int IoCreateSeq(void *SeqRef, const char *pFilename, int width, int height, int bitdepth, int format)
SeqRef IoOpenSeq(string pFilename, out int width, out int height, out int bitdepth, int mode, out int errorCode) int IoOpenSeq(void *SeqRef, const char *pFilename, int* width, int* height, int* bitdepth, int mode)
SisoIoImageEngine IoImageOpen(string filename, out int errorCode) int IoImageOpen(const char *filename, SisoIoImageEngine *handle)
SisoIoImageEngine IoImageOpenEx(string filename, int RGBSequence, out int errorCode) int IoImageOpenEx(const char *filename, SisoIoImageEngine *handle, int RGBSequence)

Functions With Different Return Data Types and Out Argument Data Types#

In the following functions, the return type is changed from void pointer, which represents an image handle, to a more specific handle type.

The output arguments unsigned char ** data, which are set to a pointer to the raw image data, are changed to SisoImage, which is a handle for image data in unmanaged memory. To retrieve the data from SisoImage as a byte array, the functions SisoImage.toByteArray(uint imageSize) and SisoImage.asByteArray() are provided.

C# Framegrabber API Wrapper Framegrabber API
TIFFHandle IoReadTiff(string filename, out SisoImage data, out int width, out int height, out int bitPerSample, out int samplePerPixel) void *IoReadTiff(const char *filename, unsigned char*data, int *width, int *height, int *bitPerSample, int *samplePerPixel)
TIFFHandle IoReadTiffW(string filename, out SisoImage data, out int width, out int height, out int bitPerSample, out int samplePerPixel) void *IoReadTiffW(const LPCWSTR filename, unsigned char*data, int *width, int *height, int *bitPerSample, int *samplePerPixel)
TIFFHandle IoReadTiffEx(string filename, out SisoImage data, out int width, out int height, out int bitPerSample, out int samplePerPixel, int RGBSequence) void *IoReadTiffEx(const char *filename, unsigned char*data, int *width, int *height, int *bitPerSample, int *samplePerPixel, int RGBSequence)
TIFFHandle IoReadTiffExW(string filename, out SisoImage data, out int width, out int height, out int bitPerSample, out int samplePerPixel, int RGBSequence) void *IoReadTiffExW(const LPCWSTR filename, unsigned char*data, int *width, int *height, int *bitPerSample, int *samplePerPixel, int RGBSequence)
BMPHandle IoReadBmp(string filename, out SisoImage data, out int width, out int height, out int bits) void *IoReadBmp(const char *filename,unsigned char *data,int *width,int *height,int *bits)