Overview

The DevWare COM interface lets your application connect to a running DevWare and get live images, access sensor registers, and do other "remote control" of DevWare.

Any programming language or tool that supports COM objects can use the interface, including Visual Basic, C++, C#, Matlab, various scripting tools, etc.

Quick Start

Here is Visual Basic code to connect to a running DevWare and get a live image. First you must add a Reference to DevWare to your project. Select Add Reference under the Project menu. Select the COM tab, and select DevWare 1.0 Type Library. Then you can create a DevWareLib.ImageSource object and use it:

' The variable "devware" encapsulates the connection to DevWare
Dim devware As DevWareLib.ImageSource
Dim image As Object
Dim width, height, depth As Integer

' Connect to DevWare. Only needs to be done once.
devware = New DevWareLib.ImageSource

' Get a processed RGB image
image = devware.GetRgbImage(width, height, depth)
' "image" will be a 2-dimensional array of Integer.

' Each element of the array is the color of the corresponding pixel.
Dim x, y, pixelcolor As Integer
x = …
y = …
pixelcolor = image(x, y)

That's all it takes!
You may need to call devware.Quit() when you are finished.
(If DevWare 1.0 Type Library does not appear in the list, open a Command Prompt window and type devware /register)

DevWare COM API

The functions and properties defined on the DevWare COM Interface are described below.

The data types of function parameters and return values have different names in different languages. This document uses the following conventions.

Byte	Unsigned 8-bit integer
Short	16-bit integer
Word	Unsigned 16-bit integer (Char in VB)
Int	32-bit integer
UInt	Unsigned 32-bit integer
String	Character string
Variant	An object that could become different types. Usually it will be an array of some sort.
Void	To indicate a function that does not return a value.

An asterisk after the parameter data type means the parameter is passed by reference, and the function will fill in the value. Otherwise the parameter value is provided by you.

Image Capture Functions

You can get the raw data directly from the sensor, or get the final processed RGB image that DevWare displays on the screen. The raw data can be in a variety of possible image data types including Bayer pattern at 8, 10 or 12 bits per pixel, Y-Cb-Cr, JPEG, and different RGB formats.

GetRgbImage()

Definition:
Variant GetRgbImage(Int* Width, Int* Height, Int* Depth)

Summary:
Get a processed RGB image from DevWare's live display. The return value will be a 2-dimensional array of Int values. Each array element is the RGB color, with blue in the low byte, green in bits 15:8, and red in bits 23:16. This is the same format as a Windows COLORREF type.

The function will time out after 15 seconds if no new image is available. To change the timeout use SetOption("COM GetImage Timeout", …). If DevWare is not streaming it will return a 0x0 image.

Parameters:

Width	The function will set to the image width.
Height	The function will set to the image height.
Depth	The function will set to 8.

Returns:

Array of RGB image data

2-D array of RGB colors

GetRawImage()

Definition:
Variant GetRawImage(Int* Width, Int* Height, Int* Type, Int* Black, Int* White, Int* Pattern)

Summary:
Get a raw image from DevWare's live display. This is the data as it came out of the sensor. The data type of the image depends on the sensor and the current mode of the sensor.
The function will time out after 15 seconds if no new image is available. To change the timeout use SetOption("COM GetImage Timeout", …). If DevWare is not streaming it will return a 0x0 image.

Parameters:

Width	The function will set to the image width.
Height	The function will set to the image height.
Type	The function will set to the image data type. See text below
Black	The function will set to the black level. See text below.
White	The function will set to the white level. See text below.
Pattern	The function will set to the Bayer pattern offset. See text below.

Returns:

Array of image data

Depends on Type parameter

The details of the returned array, and the meanings of the Black, White and Pattern parameters depend on the Type.

Usually the image is a 2-dimensonal array, but 24-bit RGB and 48-bit RGB are 3-D arrays with the third dimension being the color component. Compressed formats are 1-dimensional.

Black is the pixel value corresponding to black. For non-Bayer images it's usually 0. White is the white value, usually the maximum value that can be represented with the available bits. For Y-Cb-Cr data Black and White are the luma range, typically either 0-255 or 16-240 or 16-235. For compressed formats the Black and White values returned by this function are meaningless; refer to the specification of the compression format.

Type	Pixel	Image data	Black	White
1, 3	Bayer, 8 bits	2-D array of Byte	Typically 10	255
2, 4	Bayer, 10 bits	2-D array of Short	Typically 42	1023
5	Y-Cb-Cr	2-D array of Short; C in low byte, Y in high byte, Cb first	Typically either 0 or 16	Typically either 255, 240 or 235
6	RGB 5-6-5	2-D array of Short	0	31
7	RGB 5-5-5	2-D array of Short	0	31
8	RGB 4-4-4-x	2-D array of Short	0	15
9	RGB x-4-4-4	2-D array of Short	0	15
10	RGB, 24 bits	3-D array of Byte	0	255
11	RGB, 32 bits	2-D array of Int	0	255
12	Bayer, 12 bits	2-D array of Short	Typically 168	4095
14	RGB, 48 bits	3-D array of Word	0	65535
15	JPEG	1-D array of Byte	0 (irrelevant)	255 (irrelevant)
16	Bayer, 8 bits, stereo	2-D array of Byte; pixels alternate between left and right images	Typically 10	255
17	PNG	1-D array of Byte	0 (irrelevant)	255 (irrelevant)
19	YUV 4:2:0	1-D array of Byte	Typically either 0 or 16	Typically either 255, 240 or 235
20	Bayer 14	2-D array of Short	Typically 672	16383
21	Bayer 12 HiDy	2-D array of Short	0	4095
22	Bayer 14 HiDy	2-D array of Short	0	16383
24	RGB 3-3-2	2-D array of Byte	0	7
25	M420	1-D array of Byte	Typically either 0 or 16	Typically either 255, 240 or 235

The Pattern parameter defines the Bayer pattern for Bayer images, and is 0 for all other image types. The meaning of the Pattern value is as follows:

0:

G R
B G

1:

R G
G B

2:

B G
G R

3:

G B
R G

Register Access Functions

These functions access the registers on the sensor.

ReadRegister()

Definition:
Int ReadRegister(String Register, String Bitfield, Int Cached)

Summary:
Read a named register or bitfield using the name defined in the sensor data file.
Parameters:

Register	Register name from sensor data file.
Bitfield	Bitfield name from sensor data file, or use "" or "*" (asterisk) to read the whole register.
Cached	If 0 then read from the sensor, if 1 then return the last known value.

Returns:

Register or bitfield value

WriteRegister()

Definition:
Void WriteRegister(String Register, String Bitfield, Int Value)

Summary:
Write a named register or bitfield using the name defined in the sensor data file.

Parameters:

Register	Register name from sensor data file.
Bitfield	Bitfield name from sensor data file, or use "" or "*" (asterisk) to write the whole register.
Value	New value for register or bitfield

Returns:

None

ReadRegisterAddr()

Definition:
Int ReadRegisterAddr(Int AddrType, Int AddrSpace, Int Addr, Int Bitmask, Int Cached)

Summary:
Read a register given its address. This function can read sensor registers or bitfields that are not defined in the sensor data file.

Parameters:

AddrType	Register address type: 0: Normal SHiP register 1: Firmware variable on SOC sensors with embedded firmware 2: SFR or SRAM absolute address on SOC sensor 3: Sensor register on stereo headboard
AddrSpace	Address space or page of the register, if applicable.
Addr	Register address
Bitmask	Bitmask of a bitfield if you want to read only a subset of the register. If 0 then returns the whole register.
Cached	If 0 then read from the sensor, if 1 then return the last known value.

Returns:

Value

If a bitmask was specified the return value is the value within the bitfield.

WriteRegisterAddr()

Definition:
Void WriteRegisterAddr(Int AddrType, Int AddrSpace, Int Addr, Int Bitmask, Int Value)

Summary:
Write a register given its address. This function can write sensor registers or bitfields that are not defined in the sensor data file.

Parameters:

AddrType	Register address type: 0: Normal SHiP register 1: Firmware variable on SOC sensors with embedded firmware 2: SFR or SRAM absolute address on SOC sensor 3: Sensor register on stereo headboard
AddrSpace	Address space or page of the register, if applicable.
Addr	Register address
Bitmask	Bitmask of a bitfield if you want to write only a subset of the register. If 0 then write the whole register.
Value	Value to write. If a bitfield bitmask was specified, this is the value within the bitfield.

Returns:

None

PeekRegisters()

Definition:
Variant PeekRegisters(Int BaseAddr, Int Addr, Int Count, Int AddrSize, Int DataSize)

Summary:
This function reads registers from any SHiP or I2C device. It can read up to 64 sequential registers in one operation.

Parameters:

BaseAddr	Device base address
Addr	Register address
Count	Number of registers to read
AddrSize	Width of address in bits. May be 8 or 16 (typically 8)
DataSize	Width of register data in bits. May be 8 or 16 (typically 16)

Returns:

Register values

Array of Int

PokeRegisters()

Definition:
Void PokeRegisters(Int BaseAddr, Int Addr, Int Count, Int AddrSize, Int DataSize, Variant Values)

Summary:
This function writes registers on any SHiP or I2C device. It can write up to 64 sequential registers in one operation.

Parameters:

BaseAddr	Device base address
Addr	Register address
Count	Number of registers to write
AddrSize	Width of address in bits. May be 8 or 16 (typically 8)
DataSize	Width of register data in bits. May be 8 or 16 (typically 16)
Values	New register values in an array of Int

Returns:

None

BeginAccessRegs()

Definition:
Void BeginAccessRegs(Void)

Summary:
Some device drivers do not support register access simultaneously with image capture. If that is the case with the current device then this function will pause the image acquisition thread in DevWare. DevWare will pause automatically on a register access if it is not already paused, but for better performance when reading or writing many registers at once you should call BeginAccessRegs() first, and then EndAccessRegs() at the end to un-pause. BeginAccessRegs() / EndAccessRegs() calls can be nested. You must call EndAccessRegs() for each call to BeginAccessRegs() or else DevWare image capture will not resume.
The use of Pause(1) / Pause(0) for this purpose is deprecated.

Parameters:

None

Returns:

None

EndAccessRegs()

Definition:
Void EndAccessRegs(Void)

Summary:
Resume image capturing if it was paused in a previous call to BeginAccessRegs().

Parameters:

None

Returns:

None

Pause()

Definition:
Void Pause(Int PauseState)

Summary:
Pause image acquisition in DevWare. If DevWare was streaming images it will stop getting new images and display the last image it did get. Pause(1) pauses, and Pause(0) un-pauses. Pause(1) / Pause(0) calls can be nested, DevWare will not un-pause until the last pause is undone.
The use of this function to bracket register accesses is deprecated. Use BeginAccessRegs() / EndAccessRegs() instead.

Parameters:

PauseState

1 to pause, 0 to un-pause

Returns:

None

Stop()

Definition:
Void Stop(Int StopState)

Summary:
Like Pause(), see above, but puts DevWare in the Stop state, which completely shuts down all worker threads.

Parameters:

StopState

1 to stop, 0 to un-stop

Returns:

None

STATE Variable Functions

These functions give you access to the STATE variables in DevWare, which control the image color processing and display. These are the same settings that are programmed with the STATE= command in DevWare ini files. See the STATE Variables for a complete list of the STATE variables and what they do.
Some STATE variables are Int type and some are String type.

GetState()

Definition:
Int GetState(String StateName)

Summary:
Get the current value of an integer-valued variable.

Parameters:

StateName

Name of the state, example "Display Zoom"

Returns:

Value

SetState()

Definition:
Void SetState(String StateName, Int Value)

Summary:
Set an integer-valued variable to a new value.

Parameters:

StateName	Name of the state, example "Display Zoom"
Value	New value

Returns:

None

GetStateStr()

Definition:
String GetStateStr(String StateName)
Summary:
Get the current value of a string-valued variable.
Parameters:

StateName

Name of the state, example "WB Custom"

Returns:

Value

SetStateStr()

Definition:
Void SetStateStr(String StateName, String Value)

Summary:
Set a string-valued variable to a new value.

Parameters:

StateName	Name of the state, example "WB Custom"
Value	New value

Returns:

None

Option Functions

These functions access the settings in the DevWare.ini file. Option settings are other DevWare settings not included in the STATE variables. Most would not be of interest to a program using the COM interface.

You can also store your own settings with these functions. Just supply a name of your own. The setting will end up in the DevWare.ini file.
Option settings can be integer-valued or string-valued.

GetOption()

Definition:
Int GetOption(String Option)

Summary:
Get an integer-valued setting from the DevWare.ini file. Some settings are read-only.
This table shows the read-only settings. See SetOption() for the writeable settings.

Option	Description
"Grab Frame Count"	Number of frames grabbed so far.
"Bad Frame Count"	Number of bad frames so far (got an error on the grab).
"Display Frame Count"	Number of frames displayed so far.
"Sensor Frame Rate"	Current native frame rate of the sensor, calculated from the current register values and the clock speed shown on the Info panel and Options dialog. Requesting this value causes the frame rate to be calculated immediately, and so it will result in reading sensor registers, and it does not matter if Allow Update Sensor FPS is checked on the Options dialog.
"Grab Frame Rate"	Measured rate at which images are arriving from the camera, in frames per second * 1000. Corresponds to Sensor FPS on the Info panel.
"Display Frame Rate"	Measured rate at which DevWare is displaying images on the screen, in frames per second * 1000. Corresponds to Display FPS on the Info panel.
"Device Count"	Number of devices connected to the computer.
"Subdevice Count"	Number of sensors connected to the currently selected device.

Parameters:

Option

Name of the setting

Returns:

Value

SetOption()

Definition:
Void SetOption(String Option, Int Value)
Summary:
Change an integer-valued setting to a new value. Some interesting option values:

Option	Description
"InfoDlg Show"	Info panel on/off (1 = on, 0 = off)
"SensorCtrl Show"	Sensor Control dialog on/off (1 = on, 0 = off)
"PresetsDlg Show"	Presets dialog on/off (1 = on, 0 = off)
"RegisterDlg Show"	Register panel on/off (1 = on, 0 = off)
"RegisterLog Show"	Log dialog on/off (1 = on, 0 = off)
"AnalysisDlg Show"	Analysis Graph dialog on/off (1 = on, 0 = off)
"AnalysisDlg Type"	Set Analysis Graph type. 0 = Intensity; 1 = Histogram; 2 = Cumulative Intensity; 3 = Cumulative Histogram; 4 = Noise; 5 = Vectorscope.
"WatchDlg Show"	Watch dialog on/off (1 = on, 0 = off)
"RegDataDlg Show"	Register Data dialog on/off (1 = on, 0 = off)
"PythonDlg Show"	Python Console dialog on/off (1 = on, 0 = off)
"Toolbar Labels"	Toolbar labels on/off (1 = on, 0 = off)
"User Toolbar Show"	Show or hide the User toolbar. (1 = on, 0 = off, -1 = auto)
"User Toolbar 2 Show"	Show or hide the 2nd User toolbar. (1 = on, 0 = off, -1 = auto)
"Plugin Toolbar Show"	Show or hide the Plugin toolbar. (1 = on, 0 = off, -1 = auto)
"Capture FileName Increment"	Auto-increment still image capture filename. 1 = on, 0 = off. If on, then still image will be saved automatically.
"VidCap FileName Increment"	Auto-increment video capture filename. 1 = on, 0 = off.
"VidCap Format"	Video recording file format. (0 = AVI, 1 = RAW)
"RAM Capture"	Whether to capture video to RAM.
"RAM Capture MB"	How much RAM to allocate to video capture.
"RAM Capture Autostop"	Whether to stop video capture automatically when RAM is full.
"Format Address"	Address number format on Register panel. 0 = hex, 1 = decimal.
"Format Value"	Value number format on Register panel. 0 = hex, 1 = decimal.
"Log Format Address"	Address number format on Log dialog. 0 = hex, 1 = decimal, 2 = symbol.
"Log Format Value"	Value number format on Log dialog. 0 = hex, 1 = decimal.
"RegisterLog Enable"	Enable logging in the Log dialog. (1 = on, 0 = off)
"RegisterLog Sequential"	In the register Log window, show all register writes in chronological order, or sort by address. (1 = chronological, 0 = by address)
"RegisterLog REG="	Split variable writes into equivalent register writes. (1 = yes, 0 = no)
"RegisterLog Clear"	Clear the contents of the register Log window. (The value is ignored.)
"COM GetImage Timeout"	In milliseconds.
"Sensor Base"	The SHiP base address of the sensor.
"XMCLK"	The XMCLK clock frequency on the camera base board, in Hz.
"Device"	Select the device if there are multiple devices attached to the system.
"Subdevice"	Select the primary or secondary sensor on devices that support multiple sensors.
"Camera Sounds"	Enable or disable the Snapshot sound. (1 = on, 0 = off)
"Reg Control"	Enable or disable DevWare Register" spying"; DevWare monitors register writes for configuration changes. (1 = on, 0 = off)
"Show Reserved"	Enable to disable of "Reserved" registers in the Register Dialog (1 = on, 0 = off). Is remembered between app execution.
"PythonDlg Clear"	Clear the Python dialog.

Parameters:

Option	Name of the setting
Value	New value

Returns:

None

GetOptionStr()

Definition:
String GetOptionStr(String Option)

Summary:
Get a string-valued setting from the DevWare.ini file.
These read-only options return sensor information:

Option	Description
"Sensor Name"	Example: "A-5100".
"Sensor Part Number"	Example: "MT9P001".
"Sensor Version Name"	Example: "REV2".
"FuseID"	A string of 16 hex digits that uniquely identifies the sensor.
“Application Version”	Example: “4.5.13.36518”
“Application Build”	Example: “4.5.13”

Parameters:

Option

Name of the setting

Returns:

Value

SetOptionStr()

Definition:
Void SetOptionStr(String Option, String Value)

Summary:
Change a string-valued setting to a new value. Some useful string-valued options:

Option	Description
"Capture File"	Filename for still image capture.
"VidCap File"	Filename for video recording.
"Plugin Show"	Show the plugin with the given display name.
"RegisterLog File"	Sets the filename for saving the register log.
"RegisterLog Preset"	Setting this option causes the current contents of the register Log window to be written to an ini file named by "RegisterLog File", to a preset name given by the Value parameter.

Parameters:

Option	Name of the setting
Value	New value

Returns:

None

DevWare Control Functions

Other functions and properties for controlling DevWare are described below.

SensorFile

Definition:
String SensorFile

Summary:
This is the current sensor data file. You can change the value of this property; doing so will cause DevWare to load the new sensor data file. The sensor data file can be a sensor data file or it can be an image file or video file.
Setting this property is equivalent to the File->Open Sensor Data File or File->Open Image File menu on DevWare.

PresetsFile

Definition:
String PresetsFile

Summary:
This is the current Presets file (sensor INI file). You can change the value of this property; doing so will cause DevWare to load the new Presets file. To load a Preset use the LoadPreset() function.
Setting this property is equivalent to the File->Open Presets menu on DevWare.

LoadPreset()

Definition:
Void LoadPreset(String Preset)

Summary:
Load a preset from the current sensor INI file.
These are some standard presets that most Ini files that ship with DevWare contain.

Preset	Effect
"Demo Initialization"	Some recommended initial register settings. Usually equivalent to the Recommended button the toolbar.
"Reset"	Equivalent to the Reset button on the toolbar.
"Viewfinder ON"	Equivalent to clicking the Preview toolbar button on.
"Viewfinder OFF"	Equivalent to clicking the Preview toolbar button off.
"Color Processing ON"	Normally on non-SOC sensors only, equivalent to clicking the Full Auto toolbar button on.
"Color Processing OFF"	Normally on non-SOC sensors only, equivalent to clicking the Full Auto toolbar button off.

Parameters:

Preset

Name of the preset

Returns:

None

LoadPreset2()

Definition:
Int LoadPreset2(String PresetsFile, String Preset, Int SuppressDlgs)

Summary:
Load a preset from the sensor INI file if supplied, else the current sensor INI file. See "LoadPreset()" for a list of some standard presets that most Ini files that ship with DevWare contain.

The SuppressDlgs parameter determines how to handle errors in the preset. To prompt the user with a dialog pass 0. To ignore errors pass 1 (this is equivalent to automatically clicking OK to every error dialog). The function will always return 1 (success) when errors are ignored. To stop execution when an error is encountered pass 2 (this is equivalent to automatically clicking Cancel to the error dialog). In this case the function will return 2 if an error was encountered, or 1 if there were no errors.

Parameters:

PresetsFile	Name of the sensor INI file (optional)
Preset	Name of the preset
SuppressDlgs	Error handling choice; prompt user, ignore, stop

Returns:

1	Success
2	Preset failed – either non-existent or error in preset itself

RunPython()

Definition:
Int RunPython(String Statements)

Summary:
Pass the Python statements to the Python interpreter. The string can contain any number of statements separated by newline characters. This is equivalent to running a Python ini file preset with same contents.

Parameters:

Statements

String containing Python statements

Returns:

0	Success
-1	An exception was raised in the Python code
-2	Can't run Python

GetMouseSelection()

Definition:
Void GetMouseSelection(Int* SelectType, Int* StartX, Int* StartY, Int* EndX, Int* EndY)

Summary:
Get the state of the Mouse Selection box on the left-hand Info panel in DevWare, and the row and column coordinates of the selection.

Parameters:

SelectType	The function will set to the current selection type. See the table below.
StartX	The function will set to the beginning X coordinate
StartY	The function will set to the beginning Y coordinate
EndX	The function will set to the end X coordinate
EndY	The function will set to the end Y coordinate

Returns:

None	(All values are returned through the parameters.)

The meanings of the parameter values are as follows:

Type	Selecting	StartX	StartY	EndX	EndY
0	None	–	–	–	–
1	Row	–	Selected row	–	–
2	Column	Selected column	–	–	–
3	Rectangle	Start corner X coord.	Start corner Y coord.	End corner X coord.	End corner Y coord.
4	Point	Point X coord.	Point Y coord.	–	–

For the Rectangle selection, note that the start corner is not necessarily the upper left corner. It depends on how the user selected the rectangle. The start corner is where the user began the mouse drag and the end corner is where he ended the mouse drag. To find the upper left corner you must find the minimum of StartX and EndX and the minimum of StartY and EndY. Similarly, you must find the maximums to get the lower right corner.

Also note for the Rectangle selection that the selected area includes the start and end corners. The width of the rectangle is Abs(EndX – StartX) + 1 and the height is Abs(EndY – StartY) + 1. This is different from the Windows RECT structure where the right and bottom sides are one pixel past the edge of the rectangle.

SetMouseSelection()

Definition:
Void SetMouseSelection(Int SelectType, Int StartX, Int StartY, Int EndX, Int EndY)

Summary:
Change the mouse selection type and coordinates. See GetMouseSelection() for the meanings of the parameters.

Parameters:

SelectType	New selection type
StartX	New beginning X coordinate
StartY	New beginning Y coordinate
EndX	New end X coordinate
EndY	New end Y coordinate

Returns:

None

Image()

Definition:
Void Image(Int Width, Int Height, Int Type)

Summary:
Sets DevWare's current image size and type. This is equivalent to the Sensor Output controls on the Options dialog or the IMAGE= command in a .ini file. Note that this does not change anything on the sensor. It may change how the DEMO2 captures the sensor data.

Parameters:

Width	The new image width.
Height	The new image height.
Type	The new pixel data type. See table below

Returns:

None

You can pass 0 for any parameter and that means to keep it the same. For example, Image(0, 0, 1) changes only the pixel data format, not the image dimensions.

Type	Pixel Data Format
1	Bayer, 8 bits; one clock per pixel
2	Bayer, 10 bits; one clock per pixel
3	Bayer, 12 bits; two clocks per pixel (8+4 format)
4	Bayer, 10 bits; two clocks per pixel (8+2 format)
5	Y-Cb-Cr
6	RGB 5-6-5
7	RGB 5-5-5
8	RGB 4-4-4-x
9	RGB x-4-4-4
10	RGB, 24 bits
11	RGB, 32 bits
12	Bayer, 12 bits; one clock per pixel
14	RGB, 48 bits
15	JPEG
16	Bayer, 8 bits, stereo
17	PNG
19	YUV 4:2:0
20	Bayer 14
21	Bayer 12 HiDy
22	Bayer 14 HiDy
23	Bayer, 20 bits (10+10 format)
24	RGB 3-3-2
25	M420
26	Bayer 10 iHDR
27	JPEG with SpeedTags

GetGraphData()

Definition:
Variant GetGraphData(Int* Columns, Int* Rows)

Summary:
Gets the data currently being shown on the Analysis Graph window. For the data to be meaningful, the Analysis Graph window should be active and set to an appropriate graph type. To activate the Analysis Graph call SetOption("AnalysisDlg Show", 1). To select the graph type call SetOption("AnalysisDlg Type", …), see above.

The return value will be an array. The dimensions will depend on the graph. If the graph type is Intensity, Cumulative Intensity, Histogram, or Cumulative Histogram the return value will be a 2-D array. The number of columns will be the number of color channels, and the number of rows will be the number of pixels or number of pixel values. If the graph type is Noise, the return value is a 1-D array of the SNR values. The number of columns will be the number of SNR values on the graph, and the number of rows will be 1.

The data type of the returned array is always double-precision floating-point.

Parameters:

Columns	The function will set to the number of columns of data.
Rows	The function will set to the number of rows of data.

Returns:

Array of data

1-D or 2-D array of floating-point values.

Command()

Definition:
Void Command(Int Command, Int Param)

Summary:
Post a WM_COMMAND message the DevWare main window. This simulates selecting menus or clicking on toolbar buttons. Some interesting command codes are listed below.

Command	Effect
155	Toggle Options dialog on/off (click Options button on toolbar)
156	Toggle Analysis Graph dialog on/off (click Analysis button on toolbar)
157	Toggle Peek & Poke dialog on/off (click PeekPoke button on toolbar)
170	Toggle Magnify dialog on/off (click Magnify button on toolbar)
158	Play (click Play button on toolbar)
159	Pause (click Pause button on toolbar)
160	Stop (click Stop button on toolbar)
162	Load default settings (click Recommended button on toolbar)
164	Toggle the Preview button (available mainly for SOCs and ISPs)
165	Initiate an image capture according to the current Still Mode state.
166	Toggle Record mode (click Record button on toolbar)
169	Toggle Fullscreen mode (click Fullscreen button on toolbar)
186	Toggle the LOCK (half-press) button (available mainly for SOCs and ISPs)
187	Snapshot (capture a full resolution image)
188	Zero Shutter Lag Snapshot (1st selection starts batch-capture mode. Issue a Snapshot command to save the given number of full resolution image.Issue a Preview Button command to cancel this mode)
189	Grab the currently displayed image. Assuming you have Still Hold set to 0, after devware.command(189), do a loop and every few milliseconds do apbase.getstate('capture state'). When this returns zero then the capturing process has finished.
33307	Run device probe (select File->Probe for Devices menu)
57634	Copy image to clipboard (select File->Copy to Clipboard menu)
57665	Exit DevWare (select File->Exit menu)

Parameters:

Command	Command code. See table.
Param	Command parameter. Set to 0.

Returns:

None

Quit()

Definition:
Void Quit(Void)

Summary:
Shut down DevWare. If DevWare was started via COM invocation and you want DevWare to unload completely from memory then call this function.

Parameters:

None

Returns:

None

Controlling Still Image Capture

The still image capture and save-to-file mechanism of DevWare is controlled through the SetState(), GetState() SetOption() and SetOptionStr() functions. This section describes in more detail how to automate capturing and saving images with DevWare.

Set Up Mode and Parameters

Use SetState() to set the following still image capture modes and parameters prior to taking a still image.

State Name	Value and Its Meaning
"Still Mode"	0 = Capture currently displayed image; 1 = switch to full resolution or use still capture sequence on SOC, 4 = zero shutter lag.
"Flash Lamp"	0 = no flash; 1 = Xenon flash; 2 = LED flash.
"Still Global Reset"	1 = Use global reset feature on sensor, for supported sensors. 0 = rolling shutter.
"Num Capture Frames"	How many images to capture. If averaging then all images will be combined into one final image.
"Still Capture Average"	1 = Average images together. 0 = keep images separate.
"Delay before snap"	Delay in milliseconds before and between image captures.
"Still Capture Timeout"	Timeout in seconds. If no good image arrives from the sensor before the timeout then the capture fails.

Set Up File Name and File Formats

Use SetState(), SetOption(), or SetOptionStr() to set the following image file choices. If you set option "Capture FileName Increment" to 1, then the image will be saved automatically when it's captured and so these settings must be done before triggering the capture. Otherwise they can be done after the image is captured, but before it is saved. These settings are equivalent to the selections on the Sensor Control -> Save Options dialog.

SetOption("Capture FileName Increment", …)
1 = Automatically save image to file(s) immediately after image is captured. 0 = Wait for Save command after capturing image. This is equivalent to the "Auto File Name Increment and Save" checkmark on the Sensor Control -> Save Options dialog.
SetOptionStr("Capture File", …)
Set the image filename.

Use SetState() to select the image file formats you want:

State Name	Value and Its Meaning
"Save RAW "	Save raw data from sensor in a binary file.
"Save RAW TIFF"	Save raw data in TIFF file. Normally for Bayer only.
"Save ITX"	Save raw data in a text file with decimal values separated by commas and a header.
"Save RAW PNG"	Save raw data in a PNG file. Normally for Bayer only.
"Save HEX"	Save raw data in a text file, decimal values separated by commas with a footer at the end.
"Save RAW JPEG"	Save raw data from sensor as a JPEG file. Only if the raw data is already JPEG.
"Save 24bpp BMP"	Save the color-processed RGB image in Windows BMP format.
"Save 48bpp COLOR TIFF"	Save the color-processed RGB image in TIFF format. May be 24bpp RGB depending on the bit depth of the raw image.
"Save PNG"	Save the color-processed RGB image in PNG format.
"Save JPEG"	Save the color-processed RGB image in JPEG format.
"JPEG Quality (1-100)"	When saving RGB image as JPEG, this is the JPEG quality setting.
"Save TXT"	Save a register dump to a text file.
"Save Selection Rectangle"	Save only the Mouse Selection rectangle, not the whole image.

Trigger, Save and Dismiss Image Capture

Use SetState("Capture State", …) and GetState("Capture State") to control the still capture operation.

Initiate Capture:
SetState("Capture State", 1)
The function only initiates the capture sequence, it does not wait for the capture to finish. In your program you must wait for the capture to finish; use GetState("Capture State") to find out when the image is ready.

If Still Mode is Zero Shutter Lag then this puts the device and DevWare into the Zero Shutter Lag preview mode. To "close the shutter" and display the captured images do SetState("Capture State", 11).

Query if Capture is ready:
if (GetState("Capture State") = 9) then ...

When Capture State becomes 9 then the image is ready. If Capture State becomes 10 instead, then an error occurred. Wait until Capture State becomes 9 before attempting to save the image.

Save Capture:
SetState("Capture State", 7)
This is equivalent to clicking the Save button the Sensor Control -> Save Options dialog. The image will be saved in the selected format or formats. Capture State will return to 9 when the image is done saving.

Next Picture:
SetState("Capture State", 5)
If you have more than one image, this advances the display to the next image. Capture State will return to 9 when then next image is ready.

Previous Picture:
SetState("Capture State", 6)
If you have more than one image, this go back to the previous image. Capture State will return to 9 when the image is ready.

Dismiss Capture:
SetState("Capture State", 8)
This is equivalent to clicking the Done button on the Sensor Control -> Save Options dialog, or to clicking the Capture toolbar button again to dismiss the captured image and return to live images. Capture State will return to 0 when the live image display is restored.

Data Upload Functions

Other functions that upload data to the camera are described below.

UploadFirmware

Definition:
Int UploadFirmware(String File, Int Burstmode = true)

Summary:
For sensors with a built-in microcontroller, this function uploads firmware patches to the sensor. On certain emulation systems, it can upload the entire firmware. The file must be Motorola S-Record format (normally .s19 extension). After the firmware is uploaded, additional steps will be required to activate the new code; those steps will depend on the specifics of the device and the code that was uploaded.

Parameters:

File	Name of file containing firmware code
Burstmode	Faster upload. This parameter is optional and defaults to 1. Set to 1 (true) unless you specifically know the burst mode is not working on the device.

Returns:

The number of bytes of code uploaded, or 0 on error.

UploadImageFile

Definition:
UInt UploadImageFile(String File, UInt Offset, UInt Length)

Summary:
This function only applies to certain emulation systems that can accept uploaded test images. It uploads binary data from the file to the device using USB bulk transfer protocol. The function does not interpret the data in the file, it only sends it verbatim.

Parameters:

File	The name of the file containing the data
Offset	The offset from the beginning of the file to begin loading data from
Length	The number of bytes to upload

Returns:

Number of bytes uploaded or error code:
-1	The file could not be opened
-3	The file is shorter than Offset
-4	Out of memory
-5	Couldn't read the requested number of bytes from the file
-6	The device does not support image upload
-7	I/O error from the device

Example Code

To use the COM interface you must create an object based on "DevWare 1.0 Type Library". How to do that depends on your development tool.

Visual Basic Example Code

Select Add Reference under the Project menu.
Select the COM tab, and select DevWare 1.0 Type Library.
Create a variable with type DevWareLib.ImageSource.

Dim devware As DevWareLib.ImageSource
devware = New DevWareLib.ImageSource

GetRgbImage()

Dim image As Object
Dim width, height, depth As Integer

image = devware.GetRgbImage(width, height, depth)

Index into the image with the x coordinate first: image(x, y). Each element is an Integer encoding the color of the pixel. You can extract the red, green and blue components by shifting and masking or by converting to a Color object. (Definitions of x and y not shown.)

Dim red, green, blue As Integer
Dim pix As Integer
pix = image(x, y)
red = pix >> 16 And 255
green = pix >> 8 And 255
blue = pix And 255

Alternately, using a Color object:

Dim pix As Color
pix = Color.FromArgb(image(x, y))

The red, green and blue components are pix.R, pix.G and pix.B.

GetRawImage()

Dim image As Object
Dim width, height, type, black, white, pattern As Integer

image = devware.GetRawImage(width, height, type, black, white, pattern)

ReadRegister(), WriteRegister()

Dim value As Integer

Read a whole register:
value = devware.ReadRegister("RED_GAIN_REG", "", 1)

Read a bitfield:
value = devware.ReadRegister("RED_GAIN_REG", "RED_GAIN_VALUE", 1)

Write a bitfield:
devware.WriteRegister("RED_GAIN_REG", "RED_GAIN_VALUE", 16)

ReadRegisterAddr(), WriteRegisterAddr()

Dim value As Integer

Read a whole register: Normal register, page 0, address 0x2D, cached
value = devware.ReadRegisterAddr(0, 0, &H2D, 0, 1)

Read a bitfield: bitfield mask 0x003F
value = devware.ReadRegisterAddr(0, 0, &H2D, &H003F, 1)

Write a whole register: Normal register, page 0, address 0x2D, value 80
devware.WriteRegisterAddr(0, 0, &H2D, 0, 80)

Write a bitfield: bitfield mask 0x003F, value 16
devware.WriteRegisterAddr(0, 0, &H2D, &H003F, 16)

PeekRegisters(), PokeRegisters()

Read device at base address 100, register 16. Register addresses are 8 bits and registers are 16 bits:
Dim value(0) As Integer
value = devware.PeekRegisters(100, 16, 1, 8, 16)

Read four successive registers starting from register 17:
Dim values(3) As Integer
values = devware.PeekRegisters(100, 17, 4, 8, 16)

Write device at base address 100, four successive registers starting from register 56:
Dim values(3) As Integer
values(0) = ..
values(1) = ..
values(2) = ..
values(3) = ..
devware.PokeRegisters(100, 56, 4, 8, 16, values)

GetState(), SetState(), GetStateStr(), SetStateStr()

Dim zoom as Integer
Dim wbcustom as String

zoom = devware.GetState("Display Zoom")
devware.SetState("Display Zoom", 16) ' zoom 2X

wbcustom = devware.GetStateStr("WB Custom")
devware.SetStateStr("WB Custom", "1.45 -0.35 -0.10 -0.35 1.6 -0.25 -0.45 -0.55 2.0")

GetOption(), SetOption(), GetOptionStr(), SetOptionStr()

Dim timeout As Integer
Dim filename As String

timeout = devware.GetOption("COM GetImage Timeout")
devware.SetOption("COM GetImage Timeout", 30000) ' 30 seconds

filename = devware.GetOptionStr("Analysis Data File")
devware.SetOptionStr("Analysis Data File", "C:\5megapix\graphdata.txt")

SensorFile

Get the current sensor file name.
Dim sensor_filename As String
sensor_filename = devware.SensorFile

Force DevWare to use a particular sensor data file:
devware.SensorFile = "sensor_data\MT9V022-REV2.xsdat"

Load a test image into DevWare
devware.SensorFile = "C:\test_images\chart_2800K.tif"

PresetsFile, LoadPreset()

Get the current presets file (sensor ini file).
Dim presets_filename As String
presets_filename = devware.PresetsFile

Switch to another presets file and load a preset.
devware.PresetsFile = "C:\5megapixel\Module_A.ini"
devware.LoadPreset("New Lens Correction")

GetMouseSelection(), SetMouseSelection()

Get the current mouse selection and create a text string describing the selection.
Dim type, startx, starty, endx, endy As Integer
Dim selstr As String
devware.GetMouseSelection(type, startx, starty, endx, endy)

Select Case type
Case 0

selstr = "None"

Case 1

selstr = "Row " + Format(starty)

Case 2

selstr = "Col " + Format(startx)

Case 3

selstr = "Rect " + Format(startx) + "," + Format(starty) + " - "
+ Format(endx) + "," + Format(endy)

Case 4

selstr = "Point " + Format(startx) + "," + Format(starty)

End Select

Set the mouse selection to a particular rectangle.
devware.SetMouseSelection(3, 100, 120, 199, 189)

Command()

Fullscreen mode:
devware.Command(169, 0)