C# Wrapper#

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

所有 C Framegrabber API 函数均被封装为单个 C# 类 SiSoCsRt 中的静态函数。其用法和函数声明在大多数情况下与 Framegrabber API 文档中的描述一致。详细差异请参见后续章节。

包装器的组成部分#

C# 封装器与 Framegrabber SDK 一同安装。

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

SiSoCsRt.dll是您在代码中访问 C# API 时使用的类。
SiSoCsInterface.dll是与 SiSoCsInterface.dll 通信的 dll 文件。 Framegrabber API 。

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

准备您的项目#

若要开始使用该封装器：

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

示例#

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

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

Framegrabber API 地图#

类型映射#

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

C 数据类型	C# 数据类型
int，int32_t	整数
unsigned int，uint32_t	无符号整数
int64_t	长的
uint64_t，size_t	乌龙
字符 *	细绳

指针将被映射为数组或 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# 类，struct 的字段可以直接访问，也可以通过构造函数或 setter/getter 进行访问。

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

功能映射#

Framegrabber API 的每个函数在类 SiSoCsRt.

中都有一个对应的公共静态（public static）函数， struct 用于创建对 null 的引用并返回错误代码。这些函数经过修改，会直接返回引用（如果发生错误，则返回 Fg_getAppletIterator ），并将错误代码写入 out 参数中。例如，函数

定义为：

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 列表#

该包装器（wrapper）的 API 基本上与 Framegrabber API 相同。本节仅包含已重命名或具有不同参数顺序的函数的定义。

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

fg
clser
siso_genicam
SisoDisplay
SisoIo.h

有关使用特定功能的详细信息，以及有关此处未列出的功能的信息，请参阅Framegrabber API文档。

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 而被用作 DMA 缓冲区，则必须确保该字节数组不会被垃圾回收器收集或在内存中移动。这可以通过使用 gcHandle = GCHandle.Alloc(image, GCHandleType.Pinned)来实现。在通过 gcHandle.Free() 将内存从 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（它是托管内存中图像数据的句柄）。为了以字节数组形式从 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 chardata, 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 chardata, 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 chardata, 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 chardata, 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)`