C# Wrapper

为了让您能够在用 C# 创建的程序中使用 Framegrabber API，系统为您提供了一个 C# Framegrabber API 包装器。该包装器将 Framegrabber API 的功能包装到了 C# API 中。

所有 C Framegrabber API 函数都作为静态函数封装在单个 C# 类 SiSoCsRt 中。其用法和函数声明在大多数情况下如 Framegrabber API 文档所述。详细区别见以下各节。

Wrapper 组件

C# 包装器随 Framegrabber SDK 一起安装。

C# 封装由两个文件组成：SiSoCsInterface.dll 和 SiSoCsRt.dll：

• SiSoCsRt.dll 是您在代码中用于访问 C# API 的类。
• SiSoCsInterface.dll 是与 Framegrabber API 进行通信的 DLL。

此外，还为您提供了一些用于使用 C# 包装器的代码示例。

准备您的项目

要开始使用此封装：

1. 在您的 C# 项目中添加对 SiSoCsInterface.dll 的引用。您可以在 Framegrabber SDK 安装路径中找到该文件：Basler\FramegrabberSDK5.x.x\lib
2. 复制 SiSoCsRt.dll 在运行程序之前，将其添加到您的 PATH 目录中。您可以在 Framegrabber SDK 安装路径中找到该文件： Basler\FramegrabberSDK5.x.x\bin

示例

为了最轻松地开始使用封装进行图像采集，您可以在 Framegrabber SDK 安装目录中找到一些 C# 示例：

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

Framegrabber API 映射

类型映射

C 数据类型映射到对应的 C# 数据类型，如下所示：

C 数据类型	C# 数据类型
int, int32_t	int
unsigned int, uint32_t	uint
int64_t	long
uint64_t, size_t	ulong
char *	string

指针要么映射到数组，要么映射到 ref/out 参数。

In/Out 函数参数定义为 ref，而 out 函数参数定义为 out。例如：

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

bufferSize 是一个 in/out 参数，而 version 是一个 out 参数。

C 枚举直接转换为 C# 枚举。

C structs 映射为 C# 类，结构体的字段仍然可以直接访问，或者通过构造函数或 setter/getter 进行访问。

空指针根据其用途映射到不同的类型。在许多情况下，它被映射为 byte。

函数映射

Framegrabber API 的每个函数在类中都有一个相应的公开静态函数 SiSoCsRt.

创建对以下内容的引用的 Framegrabber API 函数： struct 并返回错误代码，已被修改为直接返回引用（或 null （如果发生错误），并在 out 参数中写回错误代码。例如，函数 Fg_getAppletIterator 定义为：

Framegrabber API 定义：

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

返回值是结果错误代码，并且 iter 是所创建的引用。

C# 定义：

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

返回值是创建的引用，并且结果 errorCode 是错误代码。

回调函数

每个回调函数都必须具有与其对应的委托相同的签名。该 SiSoCallback 类包含所有可用函数委托的声明。

例如，以下代码用于注册 APC 处理程序：

FgApcControl apcCtrl = new FgApcControl(10000,

(uint)(Fg_Apc_Flag.FG_APC_DELIVER_ERRORS));

apcCtrl.setApcCallbackFunction(apcCallback, null);

函数 apcCallback 必须具有相同的签名 SiSoCallback.Fg_ApcFuncDelegate，一个示例实现为：

static int apcCallback(uint imgNr, fg_apc_data userData) {

global_imgNr = (int)(imgNr);

return 0;

}

声明 SiSoCallback.Fg_ApcFuncDelegate 外观如下：

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

C# 封装 API 列表

包装器的 API 与 Framegrabber API 基本相同。本节仅包含重命名或参数顺序不同的函数的定义。

此处提供的函数按库进行分组：

• fg
• clser
• siso_genicam
• SisoDisplay
• SisoIo.h

有关使用特定函数的详细信息以及此处未列出的函数的信息，请参阅 Framegrabber API documentation。

fg

新定义的函数

string Fg_getErrorDescription (int ErrorNumber)

此函数替代了以下两个函数：

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)

用于获取具有不同类型信息的采集卡参数的重载函数列表。它们替换了 Framegrabber API 函数 Fg_getParameterWithType，根据传递的类型如下：

FgParamTypes	C# 封装函数
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	未实现

int Fg_setParameterWith…(Fg_Struct Fg, int Parameter, … Value, uint DmaIndex)

用于通过不同类型的信息设置采集卡参数的重载函数列表。它们替代了 Framegrabber API 函数 Fg_setParameterWithType，根据传递的类型如下：

FgParamTypes	C# 封装函数
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	未实现

带有不同参数的函数

C# Framegrabber API 封装	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)

在 Fg_getImagePtr和 Fg_getImagePtrEx 函数中，返回类型从 Framegrabber API 中的 void 指针（直接表示图像字节）更改为了 SisoImage 实例。

若要再次从 SisoImage中，函数 SisoImage.toByteArray(uint imageSize) 中获取字节数组，可以调用

此外，它还可以直接与 DrawBuffer 函数。

clser

参数重新排序的函数

在以下函数中，错误代码被写入 out int errorCode 而不是从函数中返回。同时，创建的句柄会从函数中返回，而不是作为参数传递。如果发生错误， errorCode 将具有除 0 以外的值，并且返回值将为 null。

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

siso_genicam

参数重新排序的函数

在以下函数中，错误代码会被写入 out int errorCode 而不是从函数中返回。同时，创建的句柄会从函数中返回，而不是作为参数传递。如果发生错误， errorCode 将具有除 0 以外的值，并且返回值将为 null。

C# Framegrabber API 封装	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

带有不同参数的函数

C# Framegrabber API 封装	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)

在 DrawBuffer 函数， ulpBuf 参数类型从 void pointer（它直接表示 Framegrabber API 中的图像字节）转换为 SisoImage 实例。

SisoImage 是使用 Fg_getImagePtr 和 Fg_getImagePtrEx 功能。此外， SisoImage 创建的，可以使用以下构造函数从字节数组创建：

SisoImage(byte[] imagePtr, uint pixelCount)

如果某个 SisoImage 实例通过调用 fg_AddMem 在其上，则必须确保垃圾回收器既不会收集该字节数组，也不会在 Memory 中对其进行移动。这可以通过使用 gcHandle = GCHandle.Alloc(image, GCHandleType.Pinned)用作 DMA 缓冲区。可以使用以下代码释放句柄： gcHandle.Free() 在将 Memory 从 DMA 缓冲区移除（使用 fg_DelMem.

SisoIo.h

参数重新排序的函数

在以下函数中，错误代码会被写入 out int errorCode 而不是从函数中返回。同时，创建的句柄会从函数中返回，而不是作为参数传递。如果发生错误， errorCode 将具有除 0 以外的值，并且返回值将为 null。

C# Framegrabber API 封装	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)

具有不同返回数据类型和输出参数数据类型的函数

在以下函数中，返回类型已从表示图像句柄的 void 指针更改为更具体的句柄类型。

输出参数 unsigned char ** data其设置为指向原始图像数据的指针，已更改为 SisoImage，它是未托管 Memory 中图像数据的句柄。若要从 SisoImage 作为字节数组，这些函数 SisoImage.toByteArray(uint imageSize) 和 SisoImage.asByteArray() 中检索数据，已提供相应支持。

C# Framegrabber API 封装	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)