C# 包裝函式#

為了讓您能在使用 C# 建立的程式中使用 Framegrabber API，系統為您提供了 C# Framegrabber API Wrapper。此 Wrapper 將 Framegrabber API 的功能封裝到 C# API 中。

所有 C Framegrabber API 函式都包裝為單一 C# 類別 SiSoCsRt 中的靜態函式。其用法與函式宣告在大多數情況下均如 Framegrabber API 文件中所述。詳細差異請見以下章節。

Wrapper 元件#

C# Wrapper 與 Framegrabber SDK 一同安裝。

C# wrapper 由 2 個檔案組成：SiSoCsInterface.dll 和 SiSoCsRt.dll：

SiSoCsRt.dll 是您用來在程式碼中存取 C# API 的類別。
SiSoCsInterface.dll 是與 Framegrabber API 進行通訊的 DLL。

此外，系統還為您提供了一些用於使用 C# Wrapper 的程式碼範例。

準備您的專案#

若要開始使用此封裝：

在您的 C# 專案中新增對 SiSoCsInterface.dll 的參考。您可以在 Framegrabber SDK 安裝資料夾中找到此檔案：Basler\FramegrabberSDK5.x.x\lib
複製 SiSoCsRt.dll 在執行程式之前，請先將其加入您的 PATH 目錄。您可以在 Framegrabber SDK 安裝資料夾中找到此檔案： Basler\FramegrabberSDK5.x.x\bin

範例#

為了最輕鬆地開始使用 Wrapper 進行影像擷取，您可以在 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 *	字串

指標會對應至陣列或 ref/out 引數。

In/Out 函式引數定義為 ref，而 out 函式引數定義為 out。例如：

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

bufferSize 是輸入/輸出引數，而 version 是輸出引數。

C 列舉會直接轉換為 C# 列舉。

C structs 對應至 C# 類別，struct 的欄位仍然可以直接存取，或透過建構子或設定子/取得子（setters/getters）存取。

空指標（Void pointers）會根據其用途對應至不同的類型。在許多情況下，它會對應至 byte。

函式對應#

Framegrabber API 的每個函式在類別中都有一個對應的 public static 函式 SiSoCsRt.

建立參考的 Framegrabber API 函式 struct 並傳回錯誤代碼，已進行修改，以便直接傳回參考（或 null 如果發生錯誤），並將錯誤代碼寫入輸出引數中。例如，函式 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 是錯誤代碼。

回呼函式#

每個回呼函式都必須具備其對應委派（delegate）的簽章。 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# Wrapper API 清單#

Wrapper 的 API 基本上與 Framegrabber API 相同。本節僅包含已重新命名或具有不同引數順序之函式的定義。

此處提供的函式依 library 分組：

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取得 bytearray， 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)來實現。在從 DMA 緩衝區移除記憶體後，可以使用 gcHandle.Free() 釋放控制代碼 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)`

帶有無不同傳回資料類型和 Out 引數資料類型的函式#

在以下函數中，返回類型從代表影像控制代碼的 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)`