C# 包裝函式#

為了讓您能在使用 C# 建立的程式中使用 Framegrabber API，我們提供了 C# Framegrabber API wrapper。此 wrapper 將 Framegrabber API 的功能包裝成 C# API。

所有 C Framegrabber API 函式都包裝為單一 C# 類別 SiSoCsRt 中的靜態函式。其用法與函式宣告在大部分情況下與 Framegrabber API 文件中的描述相同。詳細差異請參閱以下章節。

包裝函式庫元件#

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 *	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# 類別，struct 的欄位可以直接存取，或是透過建構函式或 setter/getter 存取。

void 指標會根據其用法對應至不同的類型。在許多情況下，會對應至 byte。

函式對應#

Framegrabber API 的每個函數在類別中都有對應的 public static 函數 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# Wrapper 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)#

這是多載函數的列表，用於透過不同類型的資訊來設定擷取卡（frame grabber）參數。它們取代了 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)`