Allied Vision Technologies Vimba C API Operating and maintenance manual

Vimba C API
Vimba C API
Programmer's Manual
V1.2
2013-Aug-28
Allied Vision Technologies GmbH
Taschenweg 2a
D-07646 Stadtroda / Germany

Legal Notice
Trademarks
Unless stated otherwise, all trademarks appearing in this document of Allied Vision Technologies are
brands protected by law.
Warranty
The information provided by Allied Vision Technologies is supplied without any guarantees or warranty
whatsoever, be it specific or implicit. Also excluded are all implicit warranties concerning the
negotiability, the suitability for specific applications or the non-breaking of laws and patents. Even if we
assume that the information supplied to us is accurate, errors and inaccuracy may still occur.
Copyright
All texts, pictures and graphics are protected by copyright and other laws protecting intellectual property.
It is not permitted to copy or modify them for trade use or transfer, nor may they be used on websites.
Allied Vision Technologies GmbH 08/2013
All rights reserved.
Managing Director: Mr. Frank Grube
Tax ID: DE 184383113
Headquarters:
Taschenweg 2a
D-07646 Stadtroda, Germany
Tel.: [phone]
Fax: [phone]
e-mail: [email protected]
Vimba C API - Programmer's Manual
2 / 19

Contents
Contents
1 Contacting Allied Vision Technologies 5
2 Introduction 6
2.1 Documenthistory.................................... 6
2.2 Conventions used in this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2.1 Styles...................................... 6
2.2.2 Symbols..................................... 6
3 General aspects of the API 7
4 Module Version 7
5 Module Initialization 7
6 List available cameras 8
7 Opening a camera 10
8 Feature Access 11
9 Image Acquisition and Capture 14
9.1 ImageCapture...................................... 14
9.2 ImageAcquisition.................................... 15
10 Additional configuration: List available interfaces 17
11 Error Codes 18
12 Function reference 19
Vimba C API - Programmer's Manual
3 / 19

Listings
Listings
1 GetCameras....................................... 8
2 OpenCamera ...................................... 10
3 CloseCamera ...................................... 10
4 AcquisitionStart .................................... 11
5 PayloadSize....................................... 11
6 GetFeatures....................................... 12
7 Streaming........................................ 16
8 GetInterfaces...................................... 17
Vimba C API - Programmer's Manual
4 / 19

1 Contacting Allied Vision Technologies
1 Contacting Allied Vision
Technologies
Note
L
•Technical Information
http://www.alliedvisiontec.com
•Support
[e-mail]
Allied Vision Technologies GmbH (Headquarters)
Taschenweg 2a
07646 Stadtroda, Germany
Tel.: [phone]
Fax.: [phone]
Email: [email protected]
Allied Vision Technologies Canada Inc.
101-3750 North Fraser Way
Burnaby, BC, V5J 5E9, Canada
Tel: [phone]
Fax: [phone]
Email: [email protected]
Allied Vision Technologies Inc.
38 Washington Street
Newburyport, MA 01950, USA
Toll Free number +1 877-USA-1394
Tel.: [phone]
Fax: [phone]
Email: [email protected]
Allied Vision Technologies Asia Pte. Ltd.
82 Playfair Road
#07-02 D'Lithium
Singapore 368001
Tel. [phone]
Fax:[phone]
Email: [email protected]
Allied Vision Technologies (Shanghai) Co., Ltd.
2-2109 Hongwell International Plaza
1602#ZhongShanXi Road
Shanghai 200235, China
Tel: [phone]
Fax: [phone]
Email: [email protected]
Vimba C API - Programmer's Manual
5 / 19

2 Introduction
2 Introduction
2.1 Document history
Version Date Changes
1.0 2012-Nov-15 Initial version
1.1 2013-Feb-22 Different links, small changes
1.2 2013-Jun-18 Small corrections, layout changes
2.2 Conventions used in this manual
To give this manual an easily understood layout and to emphasize important information, the following
typographical styles and symbols are used:
2.2.1 Styles
Style Function Example
Bold Programs, inputs or highlight-
ing important things
bold
Courier Code listings etc. Input
Upper case Constants CONSTANT
Italics Modes, fields Mode
Parentheses and/or blue Links ( Link )
2.2.2 Symbols
Note
LThis symbol highlights important information.
Caution
aThis symbol highlights important instructions. You have to follow these instruc-
tions to avoid malfunctions.
www
Ý
This symbol highlights URLs for further information. The URL itself is shown in
blue.
Example: http://www.alliedvisiontec.com
Vimba C API - Programmer's Manual
6 / 19

5 Module Initialization
3 General aspects of the API
The purpose of AVT Vimba APIs is to enable programmers to interact with AVT cameras independent of the
interface technology (1394, Gigabit Ethernet). To achieve this, Vimba API utilizes different transport
layers to connect to the various camera interfaces and is therefore considered generic in terms of camera
interfaces. For accessing functionality of either Vimba or the connected cameras, you have two ways of
control: the generic functions on the one hand and feature access to Vimba, the transport layers, and the
cameras on the other. This manual deals only with the functional part.
4 Module Version
As new features are introduced to Vimba API, your software remains backward compatible. Use
VmbVersionQuery to check the version number of Vimba C API.
5 Module Initialization
Using Vimba API always begins with a call to VmbStartup. Before using any Vimba API functions (other
than VmbVersionQuery), you must initialize the API with this call. When you have finished using Vimba
API, call VmbShutdown to free resources. These two API functions must always be paired. It is possible,
although not recommended, to call the pair several times within the same program.
Vimba C API - Programmer's Manual
7 / 19

6 List available cameras
6 List available cameras
For a quick start see ListCameras example of the Vimba SDK.
VmbCamerasList will enumerate all cameras recognized by the underlying transport layers. With this
command, the programmer can fetch all static details of a camera such as its ID, its model and vendor
name or the ID of the interface (e.g. the network or 1394 adapter) it is connected to. For 1394 cameras
this attempt is straightforward, as opposed to GigE; due to its asynchronous nature, listing cameras over
the network is a two-step process. First a device discovery request has to be sent out before Vimba API
can be aware of all GigE devices that answered that request. Vimba API puts the developer in charge of
deciding how to send out discovery packets. However, this can be achieved through the command features
GeVDiscoveryAllOnce and GeVDiscoveryAllAuto, whereby the latter constantly emits discovery commands.
To stop discovery, use the command feature GeVDiscoveryAllNone. Note that these features can be applied
to all network interfaces as well as to one particular interface only. See Listing 1for an example.
Listing 1: Get Cameras
1bool bGigE ;
2VmbUint32_t nCount ;
3VmbCameraInfo_t *pCameras ;
4
5// We ask Vimba for the presence of a GigE transport layer
6VmbError_t err = VmbFeatureBoolGet( gVimbaHandle , " GeVTLIsPresent ", &bGigE );
7if ( VmbErrorSuccess == err )
8{
9if (true == bGigE )
10 {
11 // We query all network interfaces using the global Vimba handle
12 err = VmbFeatureCommandRun ( gVimbaHandle , " GeVDiscoveryAllOnce" );
13 // Wait for the discovery packets to return
14 Sleep( 200 );
15 }
16 }
17 if ( VmbErrorSuccess == err )
18 {// Get the amount of connected cameras
19 err = VmbCamerasList( NULL , 0, &nCount , sizeof * pCameras );
20
21 if ( VmbErrorSuccess == err )
22 {
23 // Allocate accordingly
24 pCameras = new VmbCameraInfo_t[ nCount ];
25 // Get the cameras
26 err = VmbCamerasList( pCameras , nCount , &nCount , sizeof *pCameras );
27 // Print out each camera 's name
28 for ( VmbUint32_t i=0; i<nCount ; ++i )
29 {
30 std :: cout << pCameras [i ]. ca meraNa me << std :: endl ;
31 }
32 }
33 }
The VmbCameraInfo_t struct provides the entries listed in Table 1for obtaining information about a
camera.
To get notified whenever a camera is detected, disconnected, or changes its open state, use
VmbFeatureInvalidationRegister to register a callback that gets executed on the according event.
Vimba C API - Programmer's Manual
8 / 19

6 List available cameras
Struct Entry Purpose
const char* cameraIdString The unique ID
const char* cameraName The name
const char* modelName The model name
const char* serialString The serial number
VmbAccessMode_t permittedAccess The mode to open the camera
const char* interfaceIdString The ID of the interface the camera is connected to
Table 1: VmbCameraInfo_t struct
Use the global Vimba handle for registration. The function pointer to the callback function has to be of
type VmbInvalidationCallback*. Note that the continuous sending of discovery packages has to be
turned on to enable Vimba to recognize GigE camera events. Please note that VmbShutdown blocks until
all callbacks have finished execution. Below you find a list of functions that cannot be called within the
callback routine.
•VmbStartup
•VmbShutdown
•VmbFeatureIntSet (and any other VmbFeature*Set function)
•VmbFeatureCommandRun
Vimba C API - Programmer's Manual
9 / 19

7 Opening a camera
7 Opening a camera
A camera must be opened to control it and to capture images. To open a camera, call VmbCameraOpen
and provide the ID of the camera as well as the desired access mode. GigE cameras may also be identified
by their IP or MAC address. When a camera has been opened successfully, a handle for further access is
returned. An example for opening a camera retrieved from the camera list is shown in Listing 2.
Listing 2: Open Camera
1VmbCameraInfo_t *pCameras ;
2VmbHandle_t hCamera ;
3
4// Get all known cameras as described in chapter " List available cameras"
5
6// Open the first camera
7if ( VmbErrorSuccess == VmbCameraOpen ( pCameras [0]. cameraIdString ,
8VmbAccessModeFull , hCamera ) )
9{
10 std ::cout << "Camera opened , handle [" << hCamera << "] retrieved .";
11 }
Listing 3shows how to close a camera using VmbCameraClose and the previously retrieved handle.
Listing 3: Close Camera
1if ( VmbErrorSuccess == VmbCameraClose( hCamera ) )
2{
3std :: cout << "Camera closed ." << std::endl;
4}
Vimba C API - Programmer's Manual
10 / 19