DEVA DEVA028 User Manual

V1.1

DEVA028 USB 3 Mega Pixel Colour Camera

User’s Manual

V1.1

52 Woodside Business Park

Birkenhead

Wirral CH41 1EL

United Kingdom

Tel [phone]

Fax [phone]

Email: [e-mail]

Web: www.deva.co.uk

All information of a technical nature and particulars of the product and its use are given by
Deva Electronic Controls Ltd. in good faith. However, it is acknowledged that there may be
errors and omissions in this manual. We shall not be liable for loss or damage whatsoever
arising from the use of any information or particulars in, or any omissions from, this document.

DEVA028 USB User’s Manual Overview

i

1 Overview........................................................................1

1.1 Product Features.....................................................................1

1.2 Typical applications................................................................2

1.3 Support software.....................................................................2

1.3.1 Windows XP32/Vista32.............................................................................2

1.3.2 Utilities........................................................................................................2

1.4 Accessories.............................................................................3

2 Installation and configuration......................................4

2.1 Software support CDROM......................................................4

2.2 System requirements..............................................................4

2.2.1 Camera connection...................................................................................4

2.3 Device driver installation........................................................4

3 Software Development Kit............................................5

3.1 Common definitions................................................................5

3.1.1 Data types...................................................................................................5

3.2 Programming definitions........................................................6

3.2.1 CAM_CLIENT_TYPES...............................................................................7

3.2.2 CAM_OPERATION_MODES.....................................................................7

3.2.3 CAM_CAPTURE_TYPES...........................................................................7

3.2.4 CAM_FORMAT_TYPES.............................................................................8

3.2.5 CAM_SYNC_TYPES..................................................................................8

3.2.6 CAPTURE_CONTROL_TYPES.................................................................9

3.2.7 CAPTURE_COORDINATE_TYPES...........................................................9

3.2.8 CAPTURE_CALLBACK_TYPES...............................................................9

3.2.9 CAPTURE_AUTO_ADJUST_MODES.....................................................10

3.2.10 CAPTURE_IMAGE_ADUSTMENT_TYPES.............................................10

3.2.11 CAPTURE_AUTO_EXPOSURE_MODES...............................................11

3.2.12 CAPTURE_OVERLAY_TYPES................................................................12

3.2.13 CAPTURE_CURSOR_TYPES.................................................................12

Overview DEVA028 USB User’s Manual

ii

3.3 Data structures......................................................................13

3.3.1 CAM_IDENTIFICATION...........................................................................13

3.3.2 CAPTURE_COLOUR_ADJUSTMENT....................................................13

3.3.3 CAPTURE_IMAGE_ADJUSTMENT........................................................14

3.3.4 CAM_WINDOW........................................................................................14

3.3.5 DEST_WINDOW.......................................................................................15

3.3.6 CAPTURE_REQUIREMENT_PARAMS..................................................16

3.3.7 CAPTURE_AUTO_EXPOSURE_PARAMS.............................................17

3.3.8 CAPTURE_AUTO_ADJUST_PARAMS..................................................18

3.3.9 CAPTURE_HISTOGRAM.........................................................................18

3.3.10 CAPTURE_FRAME_INFO.......................................................................19

3.3.11 CAPTURE_SYNC_PARAMETERS.........................................................20

3.3.12 CAPTURE_RENDER_CONFIG...............................................................20

3.3.13 CAMERA_SETTINGS..............................................................................20

3.4 Initialisation and camera setup functions...........................21

3.4.1 open_cam................................................................................................21

3.4.2 close_cam................................................................................................21

3.4.3 reset_cam................................................................................................21

3.4.4 num_cameras..........................................................................................22

3.4.5 enumerate_cameras...............................................................................22

3.4.6 get_camera_id.........................................................................................23

3.4.7 get_camera_description.........................................................................23

3.4.8 set_camera_description.........................................................................24

3.4.9 get_camera_settings..............................................................................24

3.4.10 set_camera_settings...............................................................................25

3.5 Capture stream allocation and control functions...............25

3.5.1 alloc_capture...........................................................................................25

3.5.2 free_capture.............................................................................................26

3.5.3 reset_capture...........................................................................................26

3.5.4 chain_capture..........................................................................................27

3.5.5 capture_control.......................................................................................27

3.5.6 hook_capture_callback...........................................................................28

3.6 Capture stream setup and image data functions................29

DEVA028 USB User’s Manual Overview

iii

3.6.1 setup_capture..........................................................................................29

3.6.2 capture_occurred....................................................................................30

3.6.3 copy_capture_buffer...............................................................................31

3.6.4 flush_capture_buffer...............................................................................31

3.6.5 get_capture_params...............................................................................32

3.6.6 get_frame_info.........................................................................................32

3.7 Capture rendering functions................................................33

3.7.1 setup_timer_capture...............................................................................33

3.7.2 set_capture_render_config....................................................................34

3.7.3 get_capture_render_config....................................................................35

3.7.4 start_capture_render...............................................................................35

3.7.5 stop_capture_render...............................................................................36

3.7.6 capture_overlay.......................................................................................37

3.7.7 capture_cursor........................................................................................38

3.8 Automatic adjustment functions..........................................39

3.8.1 setup_auto_adjust...................................................................................39

3.8.2 get_auto_adjust_params........................................................................39

3.9 Hardware functions...............................................................40

3.9.1 setup_sync...............................................................................................40

1 Overview

The DEVA028 colour camera module is designed to enable a wide range of image
capture applications to be realised. Based on a 3M pixel CMOS sensor with bayer
mosaic for colour reproduction the Deva 028 makes use of high speed USB 2.0 to
transfer image data to a PC host system.

Multiple still and live capture streams are supported and may be configured in size,
position and resolution to match the application requirements.

The module can be mounted to the customers lens assembly or within the optional
enclosure that is available with a C-Mount.

The camera may be integrated with Deva’s motion control products to provide
advanced auto-focus and measurement features.

1.1 Product Features

• High speed USB 2.0 interface

• 2048 x 1536 3M pixel colour image

• Cropping, panning, skipping and binning modes

• 6 frames per second at max resolution

• Flexible capture modes

• Touch trigger probe input

• Camera sync bus

• Comprehensive auto exposure modes

• Colour compensation

• Compact enclosure with C-Mount

• Extensive software support

• Support and demonstration software

• Seamless integration with Deva motion control products

• Advanced Auto-focus and position measurement

1.2 Typical applications

The DEVA028 colour camera module is suitable for a wide range of applications
including:

• Non- contact measuring machines

• Automatic inspection machines

• Machine vision applications

• Process / Quality Control

• Microscopes / Telescopes

• Security and Remote Sensing

1.3 Support software

A variety of software drivers, libraries and utilities are provided with the DEVA028
colour camera module. These drivers both enable the camera to operate with existing
software developed by 3rd parties and facilitate software development for integration
with new applications.

Software support is an ongoing activity, if support for a particular application or
operating system is not currently provided, please call the Deva office to determine its
availability.

1.3.1 Windows XP32/Vista32

Windows Driver Model (WDM) drivers support the DEVA028 colour camera module
whilst the Deva capture library functions are exported by a Win32 dynamic link library
(DLL). Both of these items are installed automatically from the Deva software support
CDROM when the camera is first installed.

For software developers, the Deva capture library functions are described later in this
manual. Example programs written using common modern visual programming tools
are provided on the Deva software support CDROM to illustrate the use of the Deva
capture library functions.

For operation with 3rd party software applications, please refer to the documentation
supplied by the software provider.

1.3.2 Utilities

Demonstration image capture utility software is provided which may be used to
quickly verify that the DEVA028 colour camera module is installed correctly and

operational without requiring the use of 3rd party applications or software
development.

1.4 Accessories

When supplied as part of a development kit, the DEVA028 colour camera module is
mounted in a compact enclosure with C-mount lens fitting and included with a 1m A to
mini-B USB cable.

Please contact Deva with your requirements.

2 Installation and configuration

2.1 Software support CDROM

The DEVA28 is supplied with a software support CDROM that also includes support
and information for many of Deva’s other products. The CDROM includes the
following items:

Windows XP32/Vista32 device drivers provide a coherent camera hardware
management layer.

Windows XP32/Vista32 DLLs and import libraries contain the Deva capture library
functions.

'C' language library routines and header files which provide constant, structure and
function definitions for access to the Deva capture library.

A Visual Basic module provides constant, structure and function definitions for access
to the Deva capture library.

Example programs illustrating use of the Deva capture library functions.
Demonstration image capture utility software.

2.2 System requirements

The camera requires an IBM PC compatible (Pentium 4 or above recommended)
running XP32 or Vista32 with one spare USB 2.0 connection.

2.2.1 Camera connection

An A to mini-B cable connects the camera to the PC USB 2.0 port.

2.3 Device driver installation

Plug ‘n’ Play software support for Windows XP32 and Vista32 enables simple
installation.

Installation is a two-stage procedure. After the camera is connected for the first time
windows will indicate that a new USB device has been found and will start the
standard driver installation procedure. If this does not occur it is possible to initiate
this process manually via the ‘add new hardware’ icon in the control panel or via the
windows device manager.

Follow the instructions and when requested select ‘have disk’ and then browse to the
directory on the installation CDROM containing the Deva028 drivers.

For example, for XP32/Vista32 select:
\PC interface products\Deva028\Issue1.x\Drivers\Win32
Click ok and follow instructions to complete the first stage of the installation. Windows

will indicate a second time that a new USB device has been found and will start the
standard driver installation procedure again and the process described above is
repeated.

The installation may be tested using the supplied demonstration image capture utility
software that may be found on the CD in the utils\win32 directory.

3 Software Development Kit

For development of general-purpose image capture applications, Deva provides a
suite of functions built into the Deva capture library. The library is designed to provide
the facilities necessary for the configuration and control of live and still image capture
from within a user application.

The Deva capture library functions are contained in a DLL that communicates with the
lower level device driver. The user must call library routines in the 32 bit 'camlib.dll' to
access the functions described in this manual from 32 bit Windows applications
written in Microsoft Visual Basic, Microsoft C++, Borland Delphi, etc.

Various ‘C’ header files and Visual Basic modules are provided to enable the
developer to interface to the Deva capture library and example source code is
provided to illustrate it’s use.

3.1 Common definitions

This section is a reference for various data types and values that are used throughout
the manual.

3.1.1 Data types

The functions and data structures defined in the library have parameters and values
made up of a set of standard data types. The exact representations of the data types
depend on the programming language being used, so generic abbreviations have
been assigned to the various data types.

The user should use the implementation of the data type appropriate to his
programming language. There are not always direct equivalents between the different
languages. For example, Visual Basic does not provide the pointer data type found in
‘C’, and so memory addresses of arrays and structures have to be passed as the
integer data type Long.

I8

8-bit signed byte ‘C’ type:

Visual Basic type:

char
Byte

U8

8-bit unsigned byte

‘C’ type:
Visual Basic equivalent:

unsigned char
Byte

I16

16-bit signed integer ‘C’ type:

Visual Basic type:

Short
Integer

U16

16-bit unsigned integer

‘C’ type:
Visual Basic equivalent:

unsigned short
Integer

I32

32-bit signed integer ‘C’ type:

Visual Basic type:

long
Long

U32

32-bit unsigned integer ‘C’ type:

Visual Basic equivalent:

unsigned long
Long

F32

32-bit single precision
floating point

‘C’ type:
Visual Basic type

float (single)
Single

F64

64-bit double precision
floating point

‘C’ type:
Visual Basic type:

double
Double

STR

handle (pointer) to
character array

‘C’ type:
Visual Basic equivalent:

char *
Long

HDL

handle (pointer) to
memory area

‘C’ type:
Visual Basic equivalent:

(type) *
Long

3.2 Programming definitions

Many of the functions and data structures in the system can accept a limited number
of predefined values to determine their operation. The library defines several sets of
constant definitions for the valid numeric values, and the user should make use of
these when assigning values to system data and function parameters rather than
using their numeric equivalents.

3.2.1 CAM_CLIENT_TYPES

Type Description

CAM_CLIENT_USER_TYPE The calling application is running in ‘User mode’
CAM_CLIENT_WDM_TYPE The calling application is running as a WDM in ‘Kernel

mode’

One of these values is passed in the call to function open_cam. In normal circumstances,
the calling application or dll is running in user mode and so CAM_CLIENT_USER_TYPE
is specified. Please contact Deva if more information is required regarding accessing the
motion library functions from a windows driver or WDM.

3.2.2 CAM_OPERATION_MODES

Type Description

CAM_STANDARD_RES_FULL
_SPEED

Specifies the camera operating with standard resolution
at full speed.

CAM_HIGH_RES_HALF_SPE
ED

This mode is not currently implemented

These values are used by functions such as setup_capture to specify the operating
mode for a capture stream.

3.2.3 CAM_CAPTURE_TYPES

Type Description

CAPTURE_STOP The capture stream is reset, image captures are no

longer triggered and the frame buffer cleared.

CAPTURE_IMMEDIATE The image capture is triggered each time the user

application specifies

CAPTURE_CONTROL_TYPE_PLAY or
CAPTURE_CONTROL_TYPE_FRAME_ADVANCE in a

call to capture_control.

CAPTURE_ON_PROBE A probe device connected to the probe input triggers

the image capture.
CAPTURE_REPEAT Images are captured repeatedly at the rate specified.
These values are used by functions such as setup_capture to specify the trigger event

for the image capture of a capture stream.

3.2.4 CAM_FORMAT_TYPES

Type Description

CAM_RAW Raw pixel data returned from the image sensor without

any image post-processing.

CAM_RGB32 A pixel is represented by 4 bytes in ascending order

red, green and blue. The 4th byte is not used.

CAM_RGB24 A pixel is represented by 3 bytes in ascending order

red, green and blue.

CAM_RGBBYTE A pixel is represented by 3 bytes in ascending order

blue, green and red.

CAM_RGBDOUBLE A pixel is represented by 3 doubles in ascending order

red, green and blue.
CAM_GREYBYTE There is one greyscale byte per pixel.
These values specify the different types of format available for the image capture data

contained in the frame returned by a call to copy_capture_buffer.

3.2.5 CAM_SYNC_TYPES

Type Description

CAM_SYNC_OFF The specified sync signal is disabled.
CAM_SYNC_CAPTURE_PUL

SE

The specified sync signal will pulse on then off

automatically.
CAM_SYNC_CAPTURE_SET The specified sync signal will latch on and must be

cleared by the user application.
These values are used by functions such as setup_sync to configure the operation of

signals on the camera sync connector.

3.2.6 CAPTURE_CONTROL_TYPES

Type Description

CAPTURE_CONTROL_TYPE_
STOP

The capture stream is stopped.

CAPTURE_CONTROL_TYPE_
PAUSE

The capture stream is paused.

CAPTURE_CONTROL_TYPE_
PLAY

The capture stream is started. In the case of a
CAPTURE_IMMEDIATE stream a single image capture
is triggered. Repeated images will be captured at the
specified rate for a CAPTURE_REPEAT stream.

CAPTURE_CONTROL_TYPE_
FRAME_ADVANCE

In the case of a paused CAPTURE_REPEAT stream or
a CAPTURE_IMMEDIATE stream, a single image
capture is triggered.

These values are used by the capture_control function to control the capture stream.

3.2.7 CAPTURE_COORDINATE_TYPES

Type Description

CAPTURE_COORDINATE_CA
M

Specifies that the associated values relate to captured
image pixels.

CAPTURE_COORDINATE_WI
NDOW

Specifies that the associated values relate to user’s
application window pixels.

These values are used by functions such as capture_overlay and capture_cursor to
determine whether parameter values specified relate to captured image pixels or user’s
application window pixels.

3.2.8 CAPTURE_CALLBACK_TYPES

Type Description

CAPTURE_CALLBACK_CAPT
URE_OCCURRED

An image capture has been triggered on the capture
stream.

CAPTURE_CALLBACK_CAPT
URE_ERROR

An error has occurred on the capture stream.

The callback_type member of the CAPTURE_CALLBACK_MSG structure is set to one
of these values to identify the reason that a user function, previously registered by a call
to hook_capture_callback, has been called.

3.2.9 CAPTURE_AUTO_ADJUST_MODES

Type Description

CAPTURE_AUTO_ADJUST_O
FF

The automatic adjustment of image and exposure is

disabled.
CAPTURE_AUTO_ADJUST_ON The automatic adjustment of image and/or exposure is

enabled.
The adjustment_mode member of the CAPTURE_AUTO_ADJUST_PARAMS structure

is set to one of these values to enable or disable the post-process image and exposure
adjustment.

3.2.10 CAPTURE_IMAGE_ADUSTMENT_TYPES

Type Description

CAPTURE_IMAGE_ADJUSTM
ENT_PER_COLOUR

The range of pixel values in the red, green and blue

channel histograms are maximised independently of

each other.
CAPTURE_IMAGE_ADJUSTM

ENT_COMBINED_COLOURS

The combined red, green and blue channel histogram is

maximised by applying the same adjustment to each

channel.
The adjustment_type member of the CAPTURE_AUTO_ADJUST_PARAMS structure is

set to one of these values to specify the type of post-process image adjustment applied
to the image.

3.2.11 CAPTURE_AUTO_EXPOSURE_MODES

Type Description

CAPTURE_AUTO_EXPOSUR
E_OFF

The automatic exposure adjustment is disabled.

CAPTURE_AUTO_EXPOSUR
E_GAIN

Whilst lighting conditions are such that the image
sensor gain remains within user specified limits, it is
adjusted as required whilst the integration time remains
fixed at its nominal value. However, if lighting conditions
are such that the adjusted gain reaches one of its limits,
the integration time is then adjusted as required within
its own user specified limits.

CAPTURE_AUTO_EXPOSUR
E_INTEGRATION_TIME

Whilst lighting conditions are such that the image
sensor integration time remains within user specified
limits, it is adjusted as required whilst the gain remains
fixed at its nominal value. However, if lighting conditions
are such that the adjusted integration time reaches one
of its limits, the gain is then adjusted as required within
its own user specified limits.

CAPTURE_AUTO_EXPOSUR
E_GAIN_AND_INTEGRATION
_RATIO

A user specified ratio determines how the image sensor
gain and integration time are adjusted from their
nominal values. The gain would change at twice the
rate of integration time with a ratio of 2.0 and at half the
rate with a ratio of 0.5. A ratio of 1.0 may be used to
specify equal adjustment of each parameter. Both
parameters are only adjusted within the user specified
limits.

CAPTURE_AUTO_EXPOSUR
E_GAIN_AND_INTEGRATION
_MIN_TO_MAX

The user specified limits are used to determine the
combined adjustment of gain and integration time. The
parameters are adjusted in a linear fashion between the
maximum and minimum limits.

The adjust_mode member of the CAPTURE_AUTO_ADJUST_PARAMS structure is set
to one of these values to specify the type of post-process exposure adjustment applied to
the image.

Within bounds specified by the user, automatic adjustments may be made to gain and/or
integration time so that image quality is maximised for different types of image and
lighting conditions. These values specify the different types of automatic exposure
adjustment that may be selected. Changes to the image sensor settings are made
following analysis of each image and it normally takes several frames before the optimum
settings are reached for a given image and lighting condition.

The following graph illustrates how the gain and integration time change under
varying lighting conditions for the different auto adjustment modes:

Integration

time

Adjust gain, integration time fixed

Integration

time

Gain

Max

Max

Min

Min

Nominal

Nominal

Adjust Integration time, gain fixed

Gain & integration time, ratio 2.0

Gain & integration time, ratio 0.5
Gain & integration time, min/max

3.2.12 CAPTURE_OVERLAY_TYPES

Type Description

CAPTURE_OVERLAY_OFF No overlay is applied to the capture stream.
CAPTURE_OVERLAY_STAN

DARD

A user supplied overlay is applied to the capture

stream.
CAPTURE_OVERLAY_RAW_

HISTOGRAM

A histogram representing the pixel data for the raw

image data is overlaid on the capture stream.
CAPTURE_OVERLAY_ADJUS

TED_HISTOGRAM

A histogram representing the pixel data for the post-

processed image adjusted data is overlaid on the

capture stream.
These values are used by functions such as capture_overlay to specify the type of

overlay.

3.2.13 CAPTURE_CURSOR_TYPES

Type Description

CAPTURE_CURSOR_OFF No cursor is applied to the capture stream.
CAPTURE_CURSOR_CROSS

_HAIRS

Cross hair cursors are overlaid on the capture screen.

These values are used by functions such as capture_cursor to specify the type of
cursor.

3.3 Data structures

3.3.1 CAM_IDENTIFICATION

Parameter Type Description

id U32 A non-zero value is the ID of a

camera and is used to identify the
camera in calls to functions that
perform operations on that camera.

max_capture_size U32 The maximum size of the image that

may be captured – nominally 3M
Pixels.

descr STR A descriptive ASCII text string that

identifies the camera. The description
is be used by the application
software to identify different
cameras. Application software or
utility programs may modify the
camera description.

An array of these structures is returned by the enumerate_cameras function to assist
with identification of the one or more cameras connected to the PC.

3.3.2 CAPTURE_COLOUR_ADJUSTMENT

Parameter Type Description

contrast F64 No adjustment is applied to the

image when a contrast value of 1.0 is
specified. Larger/smaller values
increase/decrease the contrast
proportionally.

brightness F64 No adjustment is applied to the

image brightness when a value of 0.0
is specified. Image brightness values
may be adjusted in the range from –
255 to 255.

The members of this structure define values for the post-process brightness and contrast
image adjustment applied to a colour channel or group of colour channels.

3.3.3 CAPTURE_IMAGE_ADJUSTMENT

Parameter Type Description

rgbColourAdjust CAPTURE_COLOUR_AD

JUSTMENT

Specifies the adjustment made
equally to all three of the colour
channels.

redColourAdjust CAPTURE_COLOUR_AD

JUSTMENT

Specifies the adjustment made
individually to the red colour channel.

greenColourAdjust CAPTURE_COLOUR_AD

JUSTMENT

Specifies the adjustment made
individually to the green colour
channel.

blueColourAdjust CAPTURE_COLOUR_AD

JUSTMENT

Specifies the adjustment made
individually to the blue colour
channel.

greyscale U32 Setting a non-zero value converts the

image to a monochromatic greyscale
image.

The members of this structure define the post-process image adjustments that are to be
applied or have been applied to the colour content of an image.

3.3.4 CAM_WINDOW

Parameter Type Description

cx I32 The horizontal position of the window

centre relative to the centre pixel of
the image sensor.

cy I32 The vertical position of the window

centre relative to the centre pixel of
the image sensor.

dx I32 The number of horizontal pixels

required in the captured image
accounting for current resolution.

dy I32 The number of vertical pixels

required in the captured image
accounting for current resolution.

The members of this structure define the size and position of a window on the image
sensor to be captured.

The cx and cy members relate to physical pixels on the image sensor.
The dx and dy members relate to the captured image pixels. As pixel binning and

skipping is employed at lower resolutions, the number of horizontal and vertical physical
pixels on the image sensor covered by the captured image pixels varies in relation to
resolution i.e. if setup_capture was called with the res parameter set to 2, an image with
a specified dx x dy of 512x384 would cover 1024x768 physical pixels on the image
sensor.

The following diagram illustrates the window sized and position in relation to the
image sensor.

Image
sensor

dx

cx

2048

1536

dy cy

Window

3.3.5 DEST_WINDOW

Parameter Type Description

hwnd U32 The handle to the application’s

window.

ox I32 The horizontal origin of the frame

destination within the window.

oy I32 The vertical origin of the frame

destination within the window.
dx I32 The width of the window.
dy I32 The height of the window.
The members of this structure passed in a call to setup_timer_capture define the size

and position in pixels of a window on the screen where a capture stream is to be
rendered.

3.3.6 CAPTURE_REQUIREMENT_PARAMS

Parameter Type Description

image_adjustment CAPTURE_IMAGE_ADJU

STMENT

The post-process image adjustments
applied to the colour content of an
image

cam CAM_WINDOW The size and position of a window on

the image sensor
gain F64 Camera gain setting.
integration_time F64 Camera integration setting (ms).
rate F64 Frame rate for capture streams with a

capture type of CAPTURE_REPEAT

defined.
cam_mode CAM_OPERATION_MOD

ES

The operating mode for the capture

stream
capture_type CAM_CAPTURE_TYPES The trigger event for the capture

stream
cam_format CAM_FORMAT_TYPES The format of the image capture

data.
res I32 The image resolution x1, x2, x4

values control pixel skip and bin

modes. If an image capture window

of 512x384 is specified with a

resolution of 2, then each pair of

adjacent pixels is combined so that

the resulting 512x384 captured

image pixels actually cover 1024x768

physical pixels on the image sensor.
frame_size I32 The size of the image capture data.
The members of this structure encapsulate the user-defined requirement for a capture

stream.

3.3.7 CAPTURE_AUTO_EXPOSURE_PARAMS

Parameter Type Description

flicker_frequency F64 A non-zero value set to the frequency

(i.e. 50/60Hz) of any artificial lighting
prevents image flicker by ensuring
integration times are a multiple of the
flicker period.

nominal_gain F64 The nominal gain used for auto

adjustment.

min_gain F64 The minimum value of gain that the

auto adjustment can employ.

max_gain F64 The maximum value of gain that the

auto adjustment can employ.

nominal_integration_ti
me

F64 The nominal integration time used for

auto adjustment.

min_integration_time F64 The minimum value of integration

time that the auto adjustment can
employ.

max_integration_time F64 The maximum value of integration

time that the auto adjustment can
employ.

gain_and_intgegratio
n_time_ratio

F64 The ratio between gain and

integration time employed when the
exposure mode is

CAPTURE_AUTO_EXPOSURE_GAI
N_AND_INTEGRATION_RATIO.

exposure_mode CAPTURE_AUTO_EXP

OSURE_MODES

Specifies the automatic exposure
adjustment mode that is selected

num_filter_frames I32 A non-zero value is used to specify

that adjustments are made using a
rolling average filter over the required
number of frames.

The members of this structure encapsulate the user-defined parameters for the automatic
exposure adjustment of a capture stream.

3.3.8 CAPTURE_AUTO_ADJUST_PARAMS

Parameter Type Description

exposure CAPTURE_AUTO_EXPO

SURE_PARAMS

User-defined parameters for the

post-process automatic exposure

adjustment of a capture stream
adjust_mode CAPTURE_AUTO_ADJU

ST_MODES

Enables or disables the post-process

image and exposure adjustment
adjustment_type CAPTURE_IMAGE_ADUS

TMENT_TYPES

Specifies the type of post-process

image adjustment applied to the

image
min_threshold F64 Specifies the percentage of pixels to

ignore and prevent bright pixels from

affecting the adjustment.
max_threshold F64 Specifies the percentage of pixels to

ignore and prevent dark pixels from

affecting the adjustment.
The members of this structure encapsulate the user-defined requirement for automatic

post-process image and exposure adjustment of capture stream.

3.3.9 CAPTURE_HISTOGRAM

Parameter Type Description

total I32 The total number of pixels in the

data.
sum I32 The sum of all the pixels.
min I32 The minimum pixel in the data.
max I32 The maximum pixel in the data.
mean I32 The mean of all the pixels.
clipped; I32 The number of clipped pixels.
bin I32 array An array of histogram data showing

the number of pixels at each value.
The members of this structure provide histogram information for the captured image data.

3.3.10 CAPTURE_FRAME_INFO

Parameter Type Description

params CAPTURE_REQUIREME

NT_PARAMS

The user-defined requirements for
the capture stream

auto_adjust CAPTURE_AUTO_ADJU

ST_PARAMS

The user-defined requirement for
post-process image and exposure
adjustment of the capture stream

rgbHist CAPTURE_HISTOGRAM Histogram data for the combined red,

green and blue colour channels.

redHist CAPTURE_HISTOGRAM Histogram data for the red colour

channel.

greenHist CAPTURE_HISTOGRAM Histogram data for the green colour

channel.

blueHist; CAPTURE_HISTOGRAM Histogram data for the b;ue colour

channel.

focus F64 A value representing the sharpness

of the image that may be used to
detect focus.

frame_number U32 The frame number for each capture

stream is incremented each time a
new capture is triggered on the
stream.

time_stamp U32 The time stamp value (ms) indicates

the time, measured from the start of
the camera drivers, at which the
frame capture was triggered.

num_missed_pixels U32 If there has been an error during the

image capture, this value is the
number of pixels that have been
missed. The size of the captured
image data is therefore reduced by
this amount.

frame_quality F64 A value ranging from 0.0 (low) to 1.0

(high) that represents the quality of
the frame.

actual_rate F64 Approximate frame rate (Hz) of the

capture stream.

The capture frame information structure contains data relating to the captured image.

3.3.11 CAPTURE_SYNC_PARAMETERS

Parameter Type Description

sync_type CAM_SYNC_TYPES Configures the operation of signals

on the camera sync connector.
invert_logic U32 A non-zero value inverts the logical

sense of the sync signal.
capture U32 Identifies the capture stream to be

associated with the sync signal.
The members of this structure associate the operation of a sync signal with a capture

stream.

3.3.12 CAPTURE_RENDER_CONFIG

Parameter Type Description

display_short_frames U32 A non-zero value is used to direct the

capture rendering functions to display

images where pixels have been lost

during the image capture due to an

error of some form.
The members of this structure configure the operation of the capture rendering functions

and are passed in a call to set_capture_render_config.

3.3.13 CAMERA_SETTINGS

Parameter Type Description

description STR Ascii null terminated character

descriptive text string read from a

camera
vertical_flip U32 A non-zero value indicates that the

image produced by the camera will

be flipped vertically
The members of this structure represent the settings of the camera typically configured

using the CameraSetup.exe utility and read by the get_camera_settings function. The
set_camera_settings functions is provided to allow the application to modify the settings.

3.4 Initialisation and camera setup functions

3.4.1 open_cam

result open_cam(client_type)
Parameter Type Description

client_type CAM_CLIENT_TYPES In normal circumstances, the calling application

or dll is running in user mode and so
CAM_CLIENT_USER_TYPE is specified.
Please contact Deva if more information is
required regarding accessing the motion library
functions from a windows driver or WDM.

result U32 0 = Operation failed

1 = Operation completed
Open the connection to the camera drivers.
This function should be called once, usually at the start of the application whilst a

corresponding call to close_cam is made when the application terminates.

3.4.2 close_cam

result close_cam()
Parameter Type Description

result U32 0 = Operation failed

1 = Operation completed

Closes the connection to the camera drivers.

This function should be called when the application terminates.

3.4.3 reset_cam

result reset_cam()
Parameter Type Description

result U32 0 = Operation failed

1 = Operation completed

Resets the camera drivers.

This function aborts any image capture in progress and stops all active capture streams
on all connected cameras. The image frame buffers are cleared.

Allocated capture stream handles remain valid.

3.4.4 num_cameras

result num_cameras ()
Parameter Type Description

result U32 The number of cameras detected
Returns the number of cameras detected as connected to the USB ports of the PC.

3.4.5 enumerate_cameras

result enumerate_cameras (ident, num_idents)
Parameter Type Description

ident HDL

Handle to an array of CAM_IDENTIFICATION
structures where identification information
about the connected cameras will be stored.

num_idents U32 Specifies the number of items in the array

referenced in the first ident parameter.
result U32 The number of cameras detected
Enumerate the cameras detected as connected to the USB ports of the PC.
This function fills an application supplied ident array with information about the cameras

connected to the PC. The num_ident parameter must be set to the number of items in
the application supplied array.

The information returned in the CAM_IDENTIFICATION array includes an id and
descriptive text string that may then be used to identify and reference specific cameras
connected to various ports. The application can search the returned array to locate the id
of cameras that it works with. This is particularly relevant in systems with more than one
camera that have different functions.

The set_camera_description function is provided to write the camera descriptive text
string.

The function returns the number of cameras detected.

3.4.6 get_camera_id

result get_camera_id (descr)
Parameter Type Description

descr STR Handle to descriptive text string or ‘name’ of

the camera for which the id is required.

result U32

A non-zero value is the id of the camera.

Returns the id of a camera with a descriptive text string that matches the application
supplied descr string.

As an alternative to the enumerate_cameras function, this function allows an application
to get the id of a camera using its descriptive text string alone. The id is used to identify
the camera in calls to functions that perform operations on that camera.

This function is useful if cameras are to be identified by a ‘name’ that has previously been
programmed into the camera using the set_camera_description function.

3.4.7 get_camera_description

result get_camera_description (camera, descr, descr_len)
Parameter Type Description

camera U32

The id of the camera for which the descriptive
text string is required.

descr STR Handle to application supplied string where the

descriptive text will be read.

descr_len U32 The maximum length of the application

supplied string.

result U32 0 = Operation failed

1 = Operation completed

Reads the descriptive text string read from a camera with the specified id into an
application supplied descr string.

This function may be used to read the descriptive text string that has previously been
programmed into the camera using the set_camera_description function.

The camera description is also included in the CAMERA_SETTINGS structure referenced
by the get_camera_description and set_camera_description functions.

3.4.8 set_camera_description

result set_camera_description (camera, descr)
Parameter Type Description

camera U32

The id of the camera for which the descriptive

text string is required to be written.
settings STR Handle to application supplied string from

where the descriptive text will be copied.
result U32 0 = Operation failed

1 = Operation completed
Writes the application supplied descr string into the descriptive text string of a camera

with the specified id.
This function may be used write the descriptive text string of a camera that may later be

used to identify that camera using functions such as enumerate_cameras and
get_camera_id.

The camera description is also included in the CAMERA_SETTINGS structure referenced
by the get_camera_description and set_camera_description functions.

3.4.9 get_camera_settings

result get_camera_settings(camera, settings)
Parameter Type Description

camera U32

The id of the camera.
settings HDL Handle to an application supplied

CAMERA_SETTINGS structure.
result U32 0 = Operation failed

1 = Operation completed
Reads the settings from a camera with the specified id into an application supplied

CAMERA_SETTINGS structure. This structure will include a copy of the descriptive text
string referenced by the get_camera_description and set_camera_description
functions.

This function may be used to read the settings that have previously been programmed
into the camera using the set_camera_settings function.

3.4.10 set_camera_settings

result set_camera_settings (camera, settings)
Parameter Type Description

camera U32

The id of the camera.

settings HDL Handle to an application supplied

CAMERA_SETTINGS structure.

result U32 0 = Operation failed

1 = Operation completed

Writes the application supplied CAMERA_SETTINGS structure to the camera with the
specified id. This structure includes a copy of and will over-write the descriptive text string
referenced by the get_camera_description and set_camera_description functions.

This function may be used write the settings to a camera that may later be used to
identify and configure camera operation.

3.5 Capture stream allocation and control functions

3.5.1 alloc_capture

result alloc_capture (camera)
Parameter Type Description

camera U32

The id of the camera on which the capture
stream is to be allocated.

result U32 0 if operation failed, otherwise the handle of

the allocated capture stream.
Allocates a capture stream on the camera with the specified id.
Currently up to 4 capture streams may operate simultaneously and independently on

each camera. For example, one stream might be high-speed low resolution with
automatic image and exposure adjustments for a live window on the screen. A second
stream might be for high-resolution still image capture with specific exposure and image
adjustment settings for measurement purposes.

This function allocates a single capture stream on the specified camera and returns a
handle that may be used to identify that capture stream in calls to other functions. Once
operations with the stream are completed, a call to free_capture releases the capture
stream and frees it for use by other tasks.

As capture streams are a limited resource, care should be taken to manage the allocation
and freeing of capture streams so that other tasks and applications are able to operate.

3.5.2 free_capture

result free_capture (capture)
Parameter Type Description

capture U32

The handle of the capture stream to be freed.

result U32 0 = Operation failed

1 = Operation completed
Frees the specified capture stream.
This function releases a capture stream previously allocated by a call to alloc_capture

and frees it for other tasks. Please see alloc_capture for more information on the
allocation and freeing of capture streams.

3.5.3 reset_capture

result reset_capture (capture)
Parameter Type Description

capture U32

The handle of the capture stream to be reset.
result U32 0 = Operation failed

1 = Operation completed
Resets the specified capture stream.
This function resets the capture stream aborting any image capture in progress, flushing

the image capture buffer and stopping the capture stream. In addition the post-process
image and exposure adjustment is turned off.

3.5.4 chain_capture

result chain_capture (capture, dest)
Parameter Type Description

capture U32

The handle of the source capture stream to be
chained.

dest U32

The handle of the destination capture stream.

result U32 0 = Operation failed

1 = Operation completed
Chains the specified capture stream to a destination capture stream.
This function allows the application to ‘chain’ one capture stream to another. The

destination stream receives image capture data from the source capture stream rather
than directly from the camera. The image capture data is passed to the destination
stream after it has been processed by the source via a call to copy_capture_buffer.

This facility is useful, if for example, it is required to retrieve the same image capture data
but with different formats or image adjustment settings.

3.5.5 capture_control

result capture_control (capture, control_type)
Parameter Type Description

capture U32

The handle of the capture stream.
control_type CAPTURE_CONTROL

_TYPES

Specifies the required control as one of the

valid CAPTURE_CONTROL_TYPES.
result U32 0 = Operation failed

1 = Operation completed
Controls the capture stream.
Valid CAPTURE_CONTROL_TYPES values passed in the control_type parameter allow

the application to play, pause, stop and single frame advance the capture stream.
In the case of a CAPTURE_IMMEDIATE stream a single image capture is triggered only

when play or frame advance is specified. The stream is effectively stopped by default.
In addition to image captures triggered by the probe input itself, image capture can also

be triggered on a CAPTURE_ON_PROBE stream when play or frame advance is
specified. The stream may be stopped, so that no image captures are triggered when the
probe input is activated.

The application may play, pause and stop a CAPTURE_REPEAT stream. When the
stream is paused, frame advance triggers a single image capture.

3.5.6 hook_capture_callback

result hook_capture_callback (capture, context, pCallback)
Parameter Type Description

capture U32

The handle of the capture stream.

context U32 Application defined parameter that will be

passed to the callback routine.

pCallback HDL Handle to the user defined callback routine or

NULL if the callback is to be disabled.

result U32 0 = Operation failed

1 = Operation completed
Hooks an application defined callback routine
This function hooks or registers an application defined callback routine that will be called

when events occur on the capture stream for example when a new image capture has
been completed.

The value passed to the context parameter may be used to pass application specific
data to the callback routine.

The callback is disabled when a call to this function is made with the pCallback
parameter set to NULL or 0 value.

3.6 Capture stream setup and image data functions

3.6.1 setup_capture

result setup_capture (capture, cam_mode, rate, cam, res, integration_time, gain,
capture_type, cam_format, frame_size, adj)

Parameter Type Description

capture U32

The handle of the capture stream.

cam_mode CAM_OPERATI

ON_MODES

Specifies operation mode for the camera, this
should be set to
CAM_STANDARD_RES_FULL_SPEED. Other
modes are not currently implemented.

rate F64 The required frame rate for capture streams

created with the capture_type parameter set to
CAPTURE_REPEAT. The frame rate that may be
achieved is determined by capture size and
integration time and is automatically reduced if it is
too high for the current system settings.

cam HDL

Handle to a CAM_WINDOW structure that defines
the size and position of a window on the image
sensor. This may be used to effectively pan a
capture window around the image sensor. The
window centre relates to physical pixels on the
image sensor. The window size relates to the
captured image pixels and therefore the physical
pixels covered by the image depend on image
resolution.

res I32 The image resolution x1, x2, x4 values control

pixel skip and bin modes. If an image capture
window of 512x384 is specified with a resolution
of 2, then each pair of adjacent pixels is combined
so that the resulting 512x384 captured image
pixels actually covers 1024x768 physical pixels on
the image sensor.

integration_time F64 Camera integration setting (ms) represent the

effective shutter speed, to be employed for the
capture.

gain F64 Values of camera gain setting from 0.125 to 8

may be selected without adversely affecting
image quality whilst larger values up to 128 may
be used in low-light situations at the expense of
image quality.

capture_type CAM_CAPTURE

_TYPES

The trigger event for the capture stream is
selected to specify whether an immediate,
repeated or probe triggered capture is required.

cam_format CAM_FORMAT_

TYPES

A variety of image capture frame data formats can
be specified according to the requirements of the
application.

frame_size HDL

A handle to an I32 value in which the resulting
size of the image capture data is returned.

adj HDL

Handle to a CAPTURE_IMAGE_ADJUSTMENT
structure that defines the post-process image
adjustments that are to be applied to the colour
content of an image.

result U32 0 = Operation failed

1 = Operation completed
Set up a capture stream.
This function is the principle method to setup and configure a capture stream on a

capture channel previously returned by a call to the alloc_capture function.
The capture_type parameter specifies whether the image capture is to be triggered

immediately by a user request, repeatedly on a regular timed basis or by a probe
connected to the external probe input connection. In the case of repeated capture, the
frame rate is determined by the rate parameter.

The cam parameter determines the size and position of the image to be captured and
may be used to pan a capture window around the image sensor. The res parameter sets
the pixel skip and modes so that lower resolution images may be captured at higher
speeds.

Various data format types may be specified by the cam_format parameter so that the
image capture data returned by a call to copy_capture_buffer is of the required type.
The size of the image capture data is returned in the frame_size parameter.

The default post-process brightness and contrast that are to be applied to the colour
content of an image are set by the adj parameter whilst default camera gain and
integration_time are also specified for the stream. The setup_auto_adjust function may
be used to change these parameters automatically to improve image quality

3.6.2 capture_occurred

result capture_occurred (capture, info)
Parameter Type Description

capture U32

The handle of the capture stream.

info HDL

Handle to a CAPTURE_FRAME_INFO
structure.

result U32 0 = No image capture occurred

1 = Image capture occurred

Checks whether new image capture data has been transferred to the image capture
buffer.

This function returns a non-zero value when new image data has been captured and
stored in the image capture buffer. The data may then be retrieved by a call to
copy_capture_buffer. Information regarding the captured image is stored in an
application defined structure passed to the info parameter.

3.6.3 copy_capture_buffer

result copy_capture_buffer(capture, buffer, info)
Parameter Type Description

capture U32

The handle of the capture stream.

buffer HDL Handle to an application defined memory area

where the image data will be transferred. The
format of the data is defined in the call to
setup_capture that originally setup the capture
stream.

info HDL

Handle to a CAPTURE_FRAME_INFO
structure.

result U32 0 = No image capture data available

1 = Image capture data transferred

Transfers image capture data from the image capture buffer to the application defined
memory area.

The application passes a handle to a memory area of sufficient size to receive the image
capture data. The format of the data is previously defined in the call to setup_capture
that setup the capture stream and this functions also returns the required size of the
memory area.

Information about the captured image is stored in an application defined structure passed
to the info parameter.

If the function returns 0, then there is no image capture data available in the image
capture buffer.

3.6.4 flush_capture_buffer

result flush_capture_buffer (capture)
Parameter Type Description

capture U32

The handle of the capture stream to be
flushed.

result U32 0 = Operation failed

1 = Operation completed
Flushes the specified capture stream.
This function flushes the image capture buffer of any image capture data that have not

been retrieved by a call to copy_capture_buffer.

3.6.5 get_capture_params

result get_capture_params (capture, params)
Parameter Type Description

capture U32

The handle of the capture stream to be
flushed.

params HDL HDL to a

CAPTURE_REQUIREMENT_PARAMS
structure.

result U32 0 = Operation failed

1 = Operation completed
Reads the parameters previously setup for the specified capture stream.
This function reads the parameters from the specified capture stream into the application

defined CAPTURE_REQUIREMENT_PARAMS structure passed to the params
parameter.

3.6.6 get_frame_info

result get_frame_info (capture, info)
Parameter Type Description

capture U32

The handle of the capture stream to be

flushed.
info HDL

HDL to a CAPTURE_FRAME_INFO structure.
result U32 0 = Operation failed

1 = Operation completed
Reads the most recent captured image information for the specified capture stream.
This function reads the most recent captured image information into the application

defined CAPTURE_FRAME_INFO structure passed to the info parameter.

3.7 Capture rendering functions

3.7.1 setup_timer_capture

result setup_timer_capture (capture, rate, dest, cam_mode, cam, res,
integration_time, gain, adj)

Parameter Type Description

capture U32

The handle of the capture stream.

rate F64 The required frame rate for the capture stream.

The frame rate that may be achieved is
determined by capture size and integration time
and is automatically reduced if it is too high for the
current system settings.

dest HDL

Handle to a DEST_WINDOW structure that
defines the size and position of a window on the
application screen where the capture stream is to
be displayed.

cam_mode CAM_OPERATI

ON_MODES

Specifies operation mode for the camera, this
should be set to
CAM_STANDARD_RES_FULL_SPEED. Other
modes are not currently implemented.

cam HDL

Handle to a CAM_WINDOW structure that defines
the size and position of a window on the image
sensor. This may be used to effectively pan a
capture window around the image sensor. The
window centre relates to physical pixels on the
image sensor. The window size relates to the
captured image pixels and therefore the physical
pixels covered by the image depend on image
resolution.

res I32 The image resolution x1, x2, x4 values control

pixel skip and bin modes. If an image capture
window of 512x384 is specified with a resolution
of 2, then each pair of adjacent pixels is combined
so that the resulting 512x384 captured image
pixels actually covers 1024x768 physical pixels on
the image sensor.

integration_time F64 Camera integration setting (ms) represent the

effective shutter speed, to be employed for the
capture.

gain F64 Values of camera gain setting from 0.125 to 8

may be selected without adversely affecting
image quality whilst larger values up to 128 may
be used in low-light situations at the expense of
image quality.

adj HDL

Handle to a CAPTURE_IMAGE_ADJUSTMENT
structure that defines the post-process image

adjustments that are to be applied to the colou

r

content of an image.

result U32 0 = Operation failed

1 = Operation completed
Set up a capture stream for automatic rendering to an application defined window.
This function is the principle method to setup and configure a capture stream for

rendering to an application defined window on a capture channel previously returned by a
call to the alloc_capture function.

The image capture is triggered repeatedly on a regular timed basis with the frame rate
determined by the rate parameter.

The dest parameter specifies the size and position of a window on the application screen
where the capture stream will be rendered.

The cam parameter determines the size and position of the image to be captured and
may be used to pan a capture window around the image sensor. The res parameter sets
the pixel skip and modes so that lower resolution images may be captured at higher
speeds.

The default post-process brightness and contrast that are to be applied to the colour
content of an image are set by the adj parameter whilst default camera gain and
integration_time are also specified for the stream. The setup_auto_adjust function may
be used to change these parameters automatically to improve image quality

3.7.2 set_capture_render_config

result set_capture_render_config (capture, config)
Parameter Type Description

capture U32

The handle of the capture stream.

config HDL

Handle to a CAPTURE_RENDER_CONFIG
structure that defines configuration to be used.

result U32 0 = Operation failed

1 = Operation completed
Sets the capture rendering function configuration for the capture stream.
This function may be used to change the default values of the capture rendering

functions configuration for the specified capture stream.
A corresponding call to get_capture_render_config may be made to read the current

configuration.

3.7.3 get_capture_render_config

result get_capture_render_config (capture, config)
Parameter Type Description

capture U32

The handle of the capture stream.

config HDL

Handle to a CAPTURE_RENDER_CONFIG
structure that defines configuration to be used.

result U32 0 = Operation failed

1 = Operation completed
Reads the capture rendering function configuration for the capture stream.
This function may be used to read the capture rendering functions configuration for the

specified capture stream.
A corresponding call to sget_capture_render_config may be made to write the

configuration.

3.7.4 start_capture_render

result start_capture_render (capture, dest)
Parameter Type Description

capture U32

The handle of the capture stream to be

flushed.
dest HDL

Handle to a DEST_WINDOW structure that

defines the size and position of a window on

the application screen where the capture

stream is to be displayed.
result U32 0 = Operation failed

1 = Operation completed
Renders the capture stream to an application defined window.
This function may be used as an alternative to the setup_timer_capture function to

render a capture stream to an application defined window. The setup_capture and
capture_control functions must be used to configure and control the capture stream.

Using this function permits automatic rendering of image captures triggered repeatedly on
a regular timed basis as well as those triggered immediately of by the probe hardware
input.

A corresponding call to stop_capture_render may be made to stop the capture render.

3.7.5 stop_capture_render

result stop_capture_render (capture, dest)
Parameter Type Description

capture U32

The handle of the capture stream to be
flushed.

result U32 0 = Operation failed

1 = Operation completed
Stops the rendering of an image capture to an application defined window.
This function is used to stop the rendering of an image capture previously started by a

call to start_capture_render.

3.7.6 capture_overlay

result capture_overlay (capture, coordinate_type, overlay_type, bitmap_handle, cx,
cy, transparent_colour)

Parameter Type Description

capture U32

The handle of the capture stream to be
flushed.

coordinate_ty
pe

CAPTURE_COORDIN
ATE_TYPES

Specifies whether the cy and cy parameters
relate to captured image pixels or user’s
application window pixels.

overlay_type CAPTURE_OVERLAY

_TYPES

The type of overlay.

bitmap_handle U32 Handle to an application define bitmap if the

overlay_type parameter is
CAPTURE_OVERLAY_STANDARD.

cx I32 The horizontal centre of the overlay relative to

the centre of the captured image pixels or the
user’s application window pixels depending on
coordinate_type.

cy I32 The vertical centre of the overlay relative to the

centre of the captured image pixels or the
user’s application window pixels depending on
coordinate_type.

transparent_
colour

U32 An RGB colour in the application defined

bitmap may be declared as transparent.

result U32 0 = Operation failed

1 = Operation completed
Applies an overlay to the capture stream being rendered.
This function is used to automatically overlay an application defined bitmap or built-in

histogram on a capture stream that is being rendered.

3.7.7 capture_cursor

result capture_cursor(capture, coordinate_type, cursor_type, cx, cy, cursor_colour,
angle)

Parameter Type Description

capture U32

The handle of the capture stream to be
flushed.

coordinate_ty
pe

CAPTURE_COORDIN
ATE_TYPES

Specifies whether the cy and cy parameters
relate to captured image pixels or user’s
application window pixels.

cursor_type CAPTURE_CURSOR_

TYPES

The type of cursor.

cx I32 The horizontal centre of the cursor relative to

the centre of the captured image pixels or the
user’s application window pixels depending on
coordinate_type.

cy I32 The vertical centre of the cursor relative to the

centre of the captured image pixels or the
user’s application window pixels depending on

coordinate_type.
cursor_colour U32 The RGB colour of the cursor.
angle F64 A cursor rotation angle may be specified.
result U32 0 = Operation failed

1 = Operation completed
Applies a cursor to the capture stream being rendered.
This function is used to automatically overlay one of the built-in cursor types such as a

cross hair on a capture stream that is being rendered. The angle parameter allows the
cross hairs to be rotated.

3.8 Automatic adjustment functions

3.8.1 setup_auto_adjust

result setup_auto_adjust (capture, params)
Parameter Type Description

capture U32

The handle of the capture stream.

params HDL Handle to a

CAPTURE_AUTO_ADJUST_PARAMS structure.

result U32 0 = Operation failed

1 = Operation completed
Setup the automatic post-process image and exposure adjustment for a capture stream.
An application defined CAPTURE_AUTO_ADJUST_PARAMS structure is passed to the

params parameter to setup and configure the automatic post-process image and
exposure adjustment for a capture stream.

The image and exposure adjustment is performed each time new image capture data is
received according to the specified requirements. If post-process exposure adjustment is
enabled, it is expected that a small number of image captures are performed before
stable settings of gain and integration time are calculated for a give image and lighting
conditions.

3.8.2 get_auto_adjust_params

result get_auto_adjust_params (capture, params)
Parameter Type Description

capture U32

The handle of the capture stream.
params HDL Handle to a

CAPTURE_AUTO_ADJUST_PARAMS structure.
result U32 0 = Operation failed

1 = Operation completed
Reads the automatic post-process image and exposure adjustment parameters

previously setup for the specified capture stream.
This function reads the parameters from the specified capture stream into the application

defined CAPTURE_AUTO_ADJUST_PARAMS structure passed to the params
parameter.

3.9 Hardware functions

3.9.1 setup_sync

result setup_sync (capture, params)
Parameter Type Description

camera U32

The id of the camera on which the sync hardware
is to be configured.

sync U32 The 0 based index of the sync signal that is to be

configured i.e. 0 for the first sync signal.

params HDL

Handle to a CAPTURE_SYNC_PARAMETERS
structure.

result U32 0 = Operation failed

1 = Operation completed
Setup the hardware sync signals on the specified camera.
An application defined CAPTURE_SYNC_PARAMETERS structure is passed to the

params parameter to setup and configure the hardware sync signal specified by the sync
parameter on the specified camera.

The hardware sync signals may be configured to latch or pulse high or low at the point an
image capture occurs. This allows external hardware and other cameras to synchronise
operation

52 Woodside Business Park

Birkenhead

Wirral CH41 1EL

United Kingdom

Tel [phone]

Fax [phone]

Email: [e-mail]

Web : www.deva.co.uk