...

A plug-in dialog must be compiled into a DLL. The DLL file must have the extension “.dll” and should export the functions described below, according to the features your plug-in will have. The exported functions must use the standard WIN32 calling convention, normally indicated with the __stdcall keyword. The exported function names can be undecorated (e.g. “OpenDialog”) or decorated with _ prefix and @ suffix with number of parameter bytes (e.g. “_OpenDialog@16”). The functions you may export are as follows.

Function	Details	Calling Thread
OpenDialog	__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.)	GUI
OpenQtDialog	*__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.	GUI
OpenHeadless	*__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.	GUI
CloseDialog	__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.	GUI
CloseHeadless	__declspec(dllexport) void CALLBACK CloseHeadless(void); Like CloseDialog(), but used with OpenHeadless().	GUI

ImageData

RawImageData

__declspec(dllexport) void CALLBACK

ImageData

RawImageData(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.

DisplayRawImageData

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

Like ImageData(), but called earlier in the color processing, before black subtraction and multiple exposure combining. The RawImageData

Like ImageData(), but called prior to color processing, before black subtraction and multiple exposure combining. The RawImageData() function is optional. If you do not need the notifications then you do not need to have this function.

Display

LinearImageData

__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.

Display

ImageData

__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

the notifications

image data then you do not need to have this function.

Display

LinearImageData

RgbImageData

__declspec(dllexport) void CALLBACK

LinearImageData

RgbImageData(unsigned char * pImage,
mi_image_types imageType,
int nWidth,
int nHeight,
int nStride);
Like

RawImageData

ImageData(), but called

right after multiple exposure combining. The LinearImageData

after conversion to RGB, prior to display, so the image is always an RGB format and colorpipe processing is finished. The RgbImageData() function is optional. If you do not need the notifications then you do not need to have this function.	Display
GrabFrame	__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.	Camera
SaveImage	__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.	Display?
RegisterChanged	__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.

__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. The LinearImageData() function is optional. If you do not need the notifications then you do not need to have this function.

DevWare Callback Functions

DevWare passes function pointers to your OpenDialog() function in the DEVW_Callbacks structure.

Function Name

Details

ReadRegister()

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).

WriteRegister()

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().

ReadRegisterAddr()

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.

WriteRegisterAddr()

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().

PeekRegister()

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().

PokeRegister()

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().

PeekRegisters()

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().

PokeRegisters()

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().

Anchor

	Begin/EndAccessRegs
	Begin/EndAccessRegs

BeginAccessRegs() EndAccessRegs()

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.

Anchor

	SyncChanges
	SyncChanges

SyncChanges()

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.

Anchor

	Stop
	Stop

Stop()

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.

Pause()

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.

MonitorRegister()

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.

GetState()

int Callbacks.GetState(const char *state);
Retrieves the DevWare software control variable value for numeric-valued variables. These are mostly software color pipeline variables; for example, software auto exposure, software color processing, etc. The parameter is a string containing the name of the state. To see the state names, save a new preset using the Presets dialog in DevWare, open the sensor .ini file and look for lines beginning with “STATE=”.
Example:

Code Block

language	cpp

int ae = Callbacks.GetState("Auto Exposure");

SetState()

void Callbacks.SetState(const char *state, int nVal);
Sets a state to a new value for numeric-valued state variables. See GetState(), above.
Example:

Code Block

language	cpp

Callbacks.SetState("Auto Exposure", 0); // turn off software AE

GetStateStr()

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

SetStateStr()

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

GetOption()

int Callbacks.GetOption(const char *option, int nDefault);
Retrieves the Option variable value for numeric-valued variables. There are variables that are used by DevWare to control various features of the application. See the DevWare COM document for more details. You can also create your own variables, just use any name. The Option values persist between invocations of DevWare.
The first parameter is a string containing the name of the variable. The second parameter is the default value to use if the variable hasn?t been defined yet.
Example:

Code Block

language	cpp

int mode = Callbacks.GetOption("Myplugin Mode", 1);

SetOption()

void Callbacks.SetOption(const char *option, int nVal);
Sets an Option variable to a new value for numeric-valued state variables. See GetOption(), above.
Example:

Code Block

language	cpp

Callbacks.SetOption("AnalysisDlg Show", 1); // make Analysis Graph visible

GetOptionStr()

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.

SetOptionStr()

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

LoadPreset()

void Callbacks.LoadPreset(const char *szFilename, const char *szPreset);
Load an ini file preset. The szFilename parameter may be NULL or the empty string, in which case the currently loaded default ini file is used.
Example:

Code Block

language	cpp

Callbacks.LoadPreset(NULL, "Demo Initialization");

RunPython()

int Callbacks.RunPython(const char *szStatements);
Pass a sequence of Python statements to the Python interpreter. There can be any number of statements separated by \n characters. This is the same as executing a Python preset.
Example:

Code Block

language	cpp

CString stmt;
stmt.Format("image_size(%d, %d)", width, height);
Callbacks.RunPython(stmt);

GetMouseSelection()

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

SetMouseSelection()

void Callbacks.SetMouseSelection(int nSelectType, int nStartX, int nStartY, int nEndX, int nEndY);
Sets the Mouse Selection.
Example:

Code Block

language	cpp

Callbacks.SetMouseSelection(1, 0, height / 2, 0, height / 2);

GetIniFileName()

const char * Callbacks.GetIniFileName(int nSeq);
Gets the names of the currently loaded ini files. Pass 0, 1, 2, etc. to this function to enumerate the filenames. Returns NULL when the parameter meets or exceeds the number of open ini files.
Example:

Code Block

language	cpp

CString sIniFile = Callbacks.GetIniFileName(0);

SendCommand()

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.

Plug-ins Directory

The DLL file must be in the plug-ins directory so DevWare can find it and load it. By default it is the Plugins directory where your Aptina Imaging software is installed. Example:
C:\Aptina Imaging\Plugins

...

Versions Compared

Old Version 4

New Version 5

Key

DevWare Callback Functions

Plug-ins Directory

Page Comparison

Versions Compared

Old Version 4

New Version 5

Key

DevWare Callback Functions

Plug-ins Directory