__declspec(dllexport) HWND CALLBACK
OpenDialog(DWORD dwApiVersion,
HWND hwndParent,
DEVW_Camera *pCamera,
DEVW_Callbacks *pCallbacks);

(Only on Windows, if your plug-in is creating a dialog, but not using the Qt GUI library.)

DevWare calls this function when it's starting up a camera or switching cameras. You should create your window but not show it. Return the Windows window handle for your window. DevWare will use the handle to show and hide your window. The title of your window will be used for the menu in DevWare. Do only basic initialization here. Do not access registers yet; you will have an opportunity to do that later.

Parameters:

• dwApiVersion: Compare this against the constant PLUGIN_DLG_API to make sure you and DevWare are using the same version of the API.
• hwndParent: The Windows window handle of the main DevWare window. Normally your window would be a WS_POPUP style window with DevWare as its parent (but this is not strictly necessary). Also you can use this handle to send messages to DevWare.
• pCamera: Information about the sensor and camera. See the header files for details. The pointer does not remain valid after OpenDialog() returns, you must copy the contents of the structure into your own variable.
• pCallbacks: Pointers to the callback functions in DevWare. See below. The pointer does not remain valid after OpenDialog() returns, you must copy the contents of the structure into your own variable. (The pointers to functions within the structure do remain valid.)

If something goes wrong return 0. If your plug-in should only work with certain devices you can examine the pCamera structure and return 0 if you plug-in is not designed for that device.

Otherwise DevWare will add your plug-in to the “Plug-Ins” menu, using the title bar text from your window for its menu item. The API supports only one window per DLL. (But that window could be a tabbed dialog with any number of tabs, or could have child windows. Also, DevWare can load up to 24 DLLs simultaneously.)

__declspec(dllexport) QWidget * CALLBACK
OpenQtDialog(DWORD dwApiVersion,
QWidget * widgetParent,
DEVW_Camera *pCamera,
DEVW_Callbacks *pCallbacks);

(If your plug-in is creating a dialog window using the Qt GUI library. Any OS.)

Same as OpenDialog(), but using Qt widgets instead of Windows window handles.

__declspec(dllexport) void * CALLBACK
OpenHeadless(DWORD dwApiVersion,
DEVW_Camera *pCamera,
DEVW_Callbacks *pCallbacks);

(If your plug-in will run with no UI. Any OS.)

Same as OpenDialog(), but return any non-NULL pointer to indicate that the plug-in should be active. A headless plug-in can implement any of the image data functions, and can call DevWare through the callbacks.

__declspec(dllexport) void CALLBACK
CloseDialog(void);

Called when DevWare is switching to another camera, or exiting. Destroy your window and free all allocated memory. If OpenDialog() returned 0, CloseDialog() will not be called.

__declspec(dllexport) void CALLBACK
CloseHeadless(void);

Like CloseDialog(), but used with OpenHeadless().

__declspec(dllexport) void CALLBACK
RawImageData(unsigned char * pImage,
mi_image_types imageType,
int nWidth,
int nHeight,
int nStride);

__declspec(dllexport) void CALLBACK
LinearImageData(unsigned char * pImage,
mi_image_types imageType,
int nWidth,
int nHeight,
int nStride);
Like RawImageData(), but called right after multiple exposure combining. (If the image is not multiple exposures, then this is the same data as RawImageData.) The LinearImageData() function is optional. If you do not need the notifications then you do not need to have this function.

__declspec(dllexport) void CALLBACK
ImageData(unsigned char * pImage,
mi_image_types imageType,
int nWidth,
int nHeight,
int nStride);

DevWare will pass all image data to your plug-in through this function. It will be called at least twice for every frame displayed by DevWare. Once with the data in sensor-dependent format, and again with the final RGB image that DevWare is going to display in its window. You do not need to export this function if your plug-in does not use the image data.

Parameters:

• pImage: Pointer to upper left pixel of image.
• imageType: See midlib.h. Tells you the image type, for example, MI_BAYER_S12, MI_YCBCR, MI_RGB32, etc.
• nWidth: Width in pixels.
• nHeight: Height in pixels.
• nStride: Distance in bytes between rows in the image. To get the y?th row use pImage + y * nStride. Never depend on the nWidth parameter for this. DevWare may put pad bytes between rows.

This function can be used for analysis, image processing, or data capture. You can write to the image buffer and DevWare will use the new data. For example, you can write to the MI_RGB32 buffer to create indicator graphics in the image. You could also filter image data, etc.

This function is called every frame regardless of whether your window is visible or not. If you want your processing to stop when your window is hidden then you must explicitly check for that case and return immediately from the function.

You must be careful of what you do in this function because it is called from a different thread than the UI thread. You must not directly access your window controls from this function. If the UI needs to be updated use inter-thread communication such as PostMessage() or Qt signals to send a message to your window, or use some other communication mechanism such as common variables and critical sections.

You should not call DevWare callback functions, except that it is permissible to read and write sensor registers.

DevWare converts all Bayer data to MI_BAYER_S12 for processing. MI_BAYER_S12 uses a 16-bit signed 2s-complement integer for each pixel. The value 0 represents the Black Level, and the value 4095 represents the maximum brightness. Values outside this range are possible as a result of noise or image processing. The final image is always MI_RGB32, which is 32-bits per pixel, B-G-R-x byte order.

The ImageData() function is optional. If you do not need image data then you do not need to have this function.

__declspec(dllexport) void CALLBACK
GrabFrame(unsigned char * pBuffer, int nDataLength);

DevWare will call this function every time it gets a new frame from the camera. This is called before the ImageData() functions. The parameters are a pointer to the data and the data length. The data is just as it came from the camera. You do not need to export this function if your plug-in does not need this notification.

If you need to poll registers or update registers frequently, this function is the best place to do it. Register access here will have the least interference with the frame rate.

Parameters:

• pBuffer: Pointer to the data from the camera.
• nDataLength: Number of bytes of data received.

This function can be used for analysis, image processing, or data capture. You can write to the image buffer and DevWare will use the new data.

This function is called on every received frame regardless of whether your window is visible or not. If you want your processing to stop when your window is hidden then you must explicitly check for that case and return immediately from the function.

You must be careful of what you do in this function because it is called from a different thread than the UI thread. You must not directly access your window controls from this function.

You should not call DevWare callback functions, except that it is permissible to read and write sensor registers.

__declspec(dllexport) void CALLBACK
SaveImage(const char * szPath);

DevWare will call this function when it saves a captured image. The plug-in may save additional data files if desired.

Parameters:

• szPath: A C style string that is the saved file path and name without an extension.

This function is called whenever the application saves a captured image, regardless of whether your window is visible or not.

This function is typically called from the main thread.

The SaveImage() function is optional. If you do not need the notifications then you do not need to have this function.

__declspec(dllexport) void CALLBACK
RegisterChanged(int nId, unsigned int nValue);

DevWare will call this function when a sensor register you are monitoring has been written. See MonitorRegister() below. Take any action needed. This function will be called even if your plug-in window is hidden.

This function is typically called from the UI thread.

The RegisterChanged() function is optional. If you do not need the notifications then you do not need to have this function.

int Callbacks.ReadRegister(const char *regname, const char *fieldname, int cached);

Read a sensor register or field of a sensor register. If you want to read the whole register, pass NULL for the field name. You can only access registers and fields defined in the sensor data file.

For performance, DevWare caches the last value written to a register. For most registers it is sufficient to only get the cached value. In that case pass 1 for cached. If a register can be changed by the hardware or if it can return a different value each time when read then pass 0 for cached to always read the hardware (cached = 0 for volatile registers).

void Callbacks.WriteRegister(const char *regname, const char *fieldname, unsigned int value);

Write a sensor register or field of a sensor register. If you want to write the whole register, pass NULL for the fieldname. You can only access registers and fields defined in the sensor data file.

Important: call Begin/EndAccessRegs(), SyncChanges() or Stop() if needed around WriteRegister().

int Callbacks.ReadRegisterAddr(unsigned int nAddr, unsigned int nBitmask, unsigned int nAddrSpace, mi_addr_type nAddrType, int cached);

Read a sensor register or field of a sensor register by register number and address space. If you want to read the whole register, pass 0 for nBitmask. You can only access registers defined in the sensor data file.

void Callbacks.WriteRegisterAddr(unsigned int nAddr, unsigned int nBitmask, unsigned int nAddrSpace, mi_addr_type nAddrType, unsigned int value);

Write a sensor register or field of a sensor register by register number and address space. If you want to write the whole register, pass 0 for nBitmask. You can only access registers defined in the sensor data file.

Important: call Begin/EndAccessRegs(), SyncChanges() or Stop() if needed around WriteRegisterAddr().

int Callbacks.PeekRegister(unsigned int nBaseAddr, unsigned int nAddr, int nAddrSize, int nDataSize);

Read a register by Serial I/O. Can be a sensor register or a register on another chip on the Serial bus. nAddrSize and nDataSize are the width in bits of the register address and register value parameters. Valid values of nAddrSize and nDataSize are 8 or 16.

Important: call Begin/EndAccessRegs(), SyncChanges() or Stop() if needed around PeekRegister().

void Callbacks.PokeRegister(unsigned int nBaseAddr, unsigned int nAddr, unsigned int value, int nAddrSize, int nDataSize);

Write a register by Serial I/O. Can be a sensor register or a register on another chip on the Serial bus. nAddrSize and nDataSize are the width in bits of the register address and register value parameters. Valid values of nAddrSize and nDataSize are 8 or 16. This is a “dangerous” register write. It goes straight to the hardware without any snooping or special handling by DevWare.

Important: call Begin/EndAccessRegs(), SyncChanges() or Stop() if needed around PokeRegister().

void Callbacks.PeekRegisters(unsigned int nBaseAddr, unsigned int nAddr, int count, void *pValues, int nAddrSize, int nDataSize);

Read a sequence of successive registers by Serial I/O in one function call. Can be sensor registers or registers on another chip on the Serial bus. nAddrSize and nDataSize are the width in bits of the register address and register value parameters. Valid values of nAddrSize and nDataSize are 8 or 16. The pValues parameter is interpreted as either an unsigned char * or unsigned short * depending on the value of nDataSize.

Important: call Begin/EndAccessRegs(), SyncChanges() or Stop() if needed around PeekRegisters().

void Callbacks.PokeRegisters(unsigned int nBaseAddr, unsigned int nAddr, int count, void *pValues, int nAddrSize, int nDataSize);

Write a sequence of successive registers by Serial I/O in one function call. Can be sensor registers or registers on another chip on the Serial bus. nAddrSize and nDataSize are the width in bits of the register address and register value parameters. Valid values of nAddrSize and nDataSize are 8 or 16. The pValues parameter is interpreted as either an unsigned char * or unsigned short * depending on the value of nDataSize. This is a “dangerous” register write. It goes straight to the hardware without any snooping or special handling by DevWare.

Important: call Begin/EndAccessRegs(), SyncChanges() or Stop() if needed around PokeRegisters().

void Callbacks.BeginAccessRegs();
void Callbacks.EndAccessRegs();

This function pauses the capture thread in DevWare if the device or device driver does not support simultaneous register access and image capture. Call BeginAccessRegs() before reading or writing registers and EndAccessRegs() afterward. When writing several registers, call this function once at the beginning and once again when done:
Callbacks.BeginAccessRegs();
Callbacks.WriteRegister(…);
…
Callbacks.WriteRegister(…);
Callbacks.EndAccessRegs();
This is important for performance and reliability on the Demo board. Use Stop() instead if the register writes will change the image size or pixel format.

void Callbacks.SyncChanges(int sync);
Same as Begin/EndAccessRegs(), but also sets the SYNC or GROUPED_PARAMETER_HOLD bit on the sensor. The SYNC bit guarantees that all the register changes take effect at the same time. Call SyncChanges(TRUE) before writing registers and SyncChanges(FALSE) afterward. When writing several registers, call this function once at the beginning and once again when done:
Callbacks.SyncChanges(TRUE);
Callbacks.WriteRegister(…);
…
Callbacks.WriteRegister(…);
Callbacks.SyncChanges(FALSE);
This is important for performance and reliability on the Demo board. Use Stop() instead if the register writes will change the image size or pixel format.

void Callbacks.Stop(int stop);

This function stops the image capture and image processing threads. Call Stop(TRUE) before writing registers that will change the image size or image pixel format. Call Stop(FALSE) afterward to restart image capturing:
Callbacks.Stop(TRUE);
Callbacks.WriteRegister(…);
…
Callbacks.WriteRegister(…);
Callbacks.Stop(FALSE);
This is important for performance and reliability.

void Callbacks.Pause(int pause);

This function pauses the capture thread in DevWare. The image processing thread continues to run with the last captured image.

void Callbacks.MonitorRegister(const char *regname, int id, HWND hwnd);

This provides a way for your plug-in to be notified if a register is written in another part of DevWare. If you have controls based on the register you can update your controls.

• regname: Name of the register in the sensor data file.
• id: An arbitrary integer value of your choosing. This value will be passed back to your window when this register changes so you can identify which register changed if you are monitoring more than one register.
• hwnd: This parameter is now ignored, but included for backward compatibility. Pass NULL.

When a register you are monitoring changes, DevWare will send call your RegisterChagned() function.
The RegisterChanged() function will be called even when your window is hidden.

char * Callbacks.GetStateStr(const char *state);
Retrieves the DevWare software control variable value for string-valued variables.

void Callbacks.SetStateStr(const char *state, const char *szVal);
Sets a state to a new value for string-valued state variables.

void Callbacks.GetOptionStr(const char *option, char *szValue, int nBufSize, const char *szDefault);
Retrieves the Option variable value for string-valued variables. You must allocate a buffer to receive the string, and pass in the size of the buffer.

void Callbacks.SetOptionStr(const char *option, const char *szValue);
Sets a new value for string-valued Option variables.

void Callbacks.GetMouseSelection(int* pnSelectType, int* pnStartX, int* pnStartY, int* pnEndX, int* pnEndY);
Get the current Mouse Selection. The select type values are:
0 – Off
1 – Row; nStartY is the row
2 – Column; nStartX is the column
3 – Rectangle
4 – Point; nStartX, nStartY is the point

unsigned int Callbacks.SendCommand(unsigned int nCommand, unsigned int pParamSize, unsigned char *pParamBuffer, unsigned int nResultSize, unsigned char *pResultBuffer, unsigned int *pBytesReturned);

Sends a host command to the camera. For network-connected or serial-connected cameras.