C API Manual¶

Introduction to the API¶

The C API is Vimba’s underlying API. It can also be used as API for C++ applications, especially if you prefer an API with less design patterns than the C++ API.

For accessing functionality of either Vimba or the connected cameras, you have two ways of control: You can use the fixed set of API functions and you can use GenICam Features by calling functions such as VmbFeatureXXXSet or VmbFeatureXXXGet on entities like Vimba or the cameras. This manual mainly deals with the API functions.

See also

To understand the API, read the SDK Manual first: It contains essential information. For a quick start, use the examples.

API usage¶

API version¶

Even if new features are introduced to the C API, your software remains backward compatible. Use VmbVersionQuery() to check the version number of the C API. You can run this function without initializing the API.

API startup and shutdown¶

To start and shut down the API, use these paired functions:

The function VmbStartup() initializes the API.
The function VmbShutdown() shuts down the API as soon as all callbacks are finished.

The functions VmbStartup() and VmbShutdown() must always be paired. Calling the pair several times within the same program is possible, but not recommended. To free resources, shut down the API when you don’t use it. Shutting down the API closes all opened cameras.

Listing cameras¶

See also

For a quick start, see the ListCameras example of the Vimba SDK.

The function VmbCamerasList() enumerates all cameras recognized by the underlying transport layers. With this command, you can fetch all static details of a camera such as:

Camera ID
Camera model
Name or ID of the connected interface (for example, the NIC)

The order in which the detected cameras are listed is determined by the order of camera discovery and therefore not deterministic. Moreover, the order may change depending on your system configuration and the accessories (for example, hubs or long cables).

GigE cameras¶

Listing cameras over the network is a two-step process:

To enable camera discovery events, run one of the following commands: GeVDiscoveryAllOnce discovers all connected cameras once. GeVDiscoveryAllAuto continually emits discovery packets and thus constantly consumes bandwidth. Use it only if you need to stay aware of changes to your network structure and new cameras.

Both commands require a certain amount of time (GeVDiscoveryAllDuration) before returning.
To stop the camera discovery, run command GeVDiscoveryAllOff.

USB and 1394 cameras:¶

Changes to the plugged cameras are detected automatically. Therefore, all changes to the camera list are announced via discovery event. All listed commands are applied to all network interfaces, see the code snippet below.

Camera Link cameras:¶

The specifications of Camera Link and GenCP do not support plug & play or discovery events. To detect changes to the camera list, shutdown and startup the API by calling VmbShutdown and VmbStartup consecutively.

Get cameras code snippet¶

bool bGigE;
VmbUint32_t nCount;
VmbCameraInfo_t* pCameras;

// We ask Vimba for the presence of a GigE transport layer
VmbError_t err = VmbFeatureBoolGet( gVimbaHandle , "GeVTLIsPresent", &bGigE );
if ( VmbErrorSuccess == err )
  {
  if ( true == bGigE )
  {
    // We use all network interfaces using the global Vimba handle
    err = VmbFeatureCommandRun( gVimbaHandle , "GeVDiscoveryAllOnce" );
  }
}
if ( VmbErrorSuccess == err )
{   // Get the number of connected cameras
    err = VmbCamerasList( NULL , 0, &nCount , sizeof *pCameras );

    if ( VmbErrorSuccess == err )
    {

        // Allocate accordingly
        pCameras = (VmbCameraInfo_t *) malloc( nCount * sizeof *pCameras );
        // Get the cameras
        err = VmbCamerasList( pCameras , nCount , &nCount , sizeof *pCameras );
        // Print out each camera 's name
        for ( VmbUint32_t i=0; i<nCount; ++i )
        {
           printf( " %s\n", pCameras[i]. cameraName );
        }
    }
}

Struct VmbCameraInfo_t¶

Struct VmbCameraInfo_t provides the entries listed in the table below for obtaining information about a camera.

Struct VmbCameraInfo_t¶
Type	Field	Purpose
const char*	cameraIdString	Unique identifier for each camera
const char*	cameraName	Name of the camera
const char*	modelName	The model name
const char*	serialString	The serial number
VmbAccessMode_t	permittedAccess	See VmbAccessModeType
const char*	interfaceIdString	Unique value for each interface or bus

Similiar to listing available cameras, VmbInterfacesList() can be used to list available interfaces, see Listing interfaces.

Enabling notifications of changed camera states¶

To get notified whenever a camera is detected, disconnected, or changes its open state:

Run command feature GeVDiscoveryAllAuto on the System entity (GigE cameras only).
Use VmbFeatureInvalidationRegister() to register a callback with the Vimba System that gets executed on the according event. The function pointer to the callback function has to be of type VmbInvalidationCallback*.

Note

VmbShutdown() blocks until all callbacks have finished execution.

Note

Functions that must not be called within the camera notification callback:

VmbStartup
VmbShutdown
VmbCameraOpen
VmbCameraClose
VmbFeatureIntSet (and any other VmbFeature*Set function)
VmbFeatureCommandRun

Opening and closing a camera¶

A camera must be opened to control it and to capture images. Call VmbCameraOpen() and provide the ID of the camera and the desired access mode.

The API provides several access modes:

VmbAccessModeFull: read and write access. Use this mode to configure the camera features and to acquire images (Goldeye CL cameras: configuration only).
VmbAccessModeConfig: enables configuring the IP address of your GigE camera.
VmbAccessModeRead: read-only access. Setting features is not possible. However, for GigE cameras that are already in use by another application, the acquired images can be transferred to the API (Multicast).

The enumerations are defined in VmbAccessModeType (or its VmbUint32_t representation VmbAccessMode_t).

Enum VmbAccessModeType is represented as VmbUint32_t through VmbAccessMode_t¶
Enumeration Integer Value	Integer Value	Purpose
VmbAccessModeNone	0	No access
VmbAccessModeFull	1	Read and write access
VmbAccessModeRead	2	Read-only access
VmbAccessModeConfig	4	Configuration access (GigE)

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 the code snippet below.

Open a camera code snippet¶

VmbCameraInfo_t *pCameras;
VmbHandle_t hCamera;

// Get all known cameras as described in chapter "Listing available cameras"

// Open the first camera
if ( VmbErrorSuccess == VmbCameraOpen( pCameras [0]. cameraIdString ,
                                       VmbAccessModeFull , hCamera ) )
{
printf( "Camera opened , handle [0x%p] retrieved .\n", hCamera );
}

The code snippet below shows how to close a camera using VmbCameraClose and the previously retrieved handle.

Close a camera code snippet¶

if ( VmbErrorSuccess == VmbCameraClose( hCamera ) )
{
printf( "Camera closed .\n" );
}

Accessing features¶

See also

For a quick start, see the ListFeatures example of the Vimba SDK.

Feature types¶

The Vimba C API provides several feature types, which all have their specific properties and functionalities. The API provides its own set of access functions for every feature data type.

Feature types and functions for reading and writing features¶
Feature Type	Operation	Function
Enumeration	Set	VmbFeatureEnumSet
Enumeration	Get	Get VmbFeatureEnumGet
Range	Range	VmbFeatureEnumRangeQuery
Other		VmbFeatureEnumIsAvailable
		VmbFeatureEnumAsInt
		VmbFeatureEnumAsString
		VmbFeatureEnumEntryGet
Integer	Set	VmbFeatureIntSet
	Get	VmbFeatureIntGet
	Range	VmbFeatureIntRangeQuery
	Other	VmbFeatureIntIncrementQuery
Float	Set	VmbFeatureFloatSet
Float	Get	VmbFeatureFloatGet
String	Set	VmbFeatureStringSet
	Get	VmbFeatureStringGet
	Range	VmbFeatureStringMaxlengthQuery
Boolean	Set	VmbFeatureBoolSet
Boolean	Get	VmbFeatureBoolGet
Command	Set	VmbFeatureCommandRun
Command	Get	VmbFeatureCommandIsDone
Raw data	Set	VmbFeatureRawSet
	Get	VmbFeatureRawGet
	Range	VmbFeatureRawLengthQuery

Struct VmbFeatureInfo_t¶

The static properties of a feature are held in struct VmbFeatureInfo_t.

Struct VmbFeatureInfo_t¶
Struct Entry	Purpose
const char* name	Name used in the API
VmbFeatureData_t featureDataType	Data type of this feature
VmbFeatureFlags_t featureFlags	Access flags for this feature
const char* category	Category this feature can be found in
const char* displayName	Feature name to be used in GUIs
VmbUint32_t pollingTime	Predefined polling time for volatile features
const char* unit	Measuring unit as given in the XML file
const char* representation	const char* representation
VmbFeatureVisibility_t visibility	GUI visibility
const char* tooltip	Short description, e.g. for a tooltip
const char* description	Longer description
const char* sfncNamespace	Namespace this feature resides in
VmbBool_t isStreamable	Indicates if a feature can be stored to or loaded from a file
VmbBool_t hasAffectedFeatures	Indicates if the feature potentially affects other features
VmbBool_t hasSelectedFeatures	Indicates if the feature selects other features

Enum VmbFeatureDataType is represented as VmbUint32_t through VmbFeatureData_t¶
Enumeration	Integer Value	Purpose
VmbFeatureDataInt	1	64-bit integer feature
VmbFeatureDataFloat	2	64-bit floating point feature
VmbFeatureDataEnum	3	Enumeration feature
VmbFeatureDataString	4	String feature
VmbFeatureDataBool	5	Boolean feature
VmbFeatureDataCommand	6	Command feature
VmbFeatureDataRaw	7	Raw (direct register access) feature
VmbFeatureDataNone	8	Feature with no data

Enum VmbFeatureFlagsType is represented as VmbUint32_t through VmbFeatureFlags_t¶
Enumeration	Integer Value	Purpose
VmbFeatureFlagsNone	0	No additional information is provided
VmbFeatureFlagsRead	1	Static info about read access. Current status depends on access mode, check with VmbFeatureAccessQuery()
VmbFeatureFlagsWrite	2	Static info about write access. Current status depends on access mode, check with VmbFeatureAccessQuery()
VmbFeatureFlagsVolatile	8	Value may change at any time
VmbFeatureFlagsModifyWrite	16	Value may change after a write

Enum VmbFeatureVisibilityType is represented as VmbUint32_t through VmbFeatureVisibility_t¶
Enumeration	Integer value	Purpose
VmbFeatureVisibilityUnknown	0	Feature visibility is not known
VmbFeatureVisibilityBeginner	1	Feature is visible in feature list (beginner)
VmbFeatureVisibilityExpert	2	Feature is visible in feature list (expert level)
VmbFeatureVisibilityGuru	3	Feature is visible in feature list (guru level)
VmbFeatureVisibilityInvisible	4	Feature is not visible in feature list

Get features code snippet¶

VmbFeatureInfo_t *pFeatures;
VmbUint32_t nCount = 0;
VmbHandle_t hCamera;

// Open the camera as shown in chapter "Opening and closing a camera"

// Get the number of features
VmbError_t err = VmbFeaturesList( hCamera , NULL , 0, &nCount , sizeof *pFeatures );

if ( VmbErrorSuccess == err && 0 < nCount )
{
   // Allocate accordingly
   pFeatures = (VmbFeatureInfo_t *) malloc( nCount * sizeof *pFeatures );

   // Get the features
   err = VmbFeaturesList( hCamera , pFeatures , nCount , &nCount ,
   sizeof *pFeatures );

   // Print out their name and data type
   for ( int i=0; i<nCount; ++i )
   {
   printf( "Feature '%s' of type: %d\n", pFeatures[i].name ,
   pFeatures[i]. featureDataType );
   }
}

Reading a camera feature code snippet¶

VmbHandle_t hCamera;

// Open the camera as shown in chapter "Opening a camera"
VmbInt64_t nWidth;
if ( VmbErrorSuccess == VmbFeatureIntGet( hCamera , "Width", &nWidth ))
{
   printf("Width: %ld\n", nWidth );
}

Writing features and running command features¶

VmbHandle_t hCamera;

// Open the camera as shown in chapter "Opening a camera"
if ( VmbErrorSuccess == VmbFeatureEnumSet( hCamera , "AcquisitionMode",
                                           "Continuous" ))
{
   if ( VmbErrorSuccess = VmbFeatureCommandRun( hCamera , "AcquisitionStart" ))
   {
   printf( "Acquisition successfully started\n" );
   }
}

Camera features¶

To query all available features of a camera, use VmbFeaturesList(). This list does not change while the camera is opened. Information about enumeration features, such as string and integer representation, is held in struct VmbFeatureEnumEntry_t.

Struct VmbFeatureEnumEntry_t¶

Struct VmbFeatureEnumEntry_t¶
Struct entry	Purpose
const char* name	Name used in the API
const char* displayName	Enumeration entry name to be used in GUIs
VmbFeatureVisibility_t visibility	GUI visibility
const char* tooltip	Short description, e.g. for a tooltip
const char* description	Longer description
const char* sfncNamespace	Namespace this feature resides in
VmbInt64_t intValue	Integer value of this enumeration entry

Note

Some features aren’t always available. For example, some features cannot be accessed while the camera is acquiring images. To query the current accessibility of a feature, call VmbFeatureAccessQuery().

The following table shows basic features of all cameras. A feature has a name, a type, and access flags such as read-permitted and write-permitted.

Basic features on all cameras¶
Feature Type	Type	Access flags	Description
AcquisitionMode	Enumeration	R/W	Acquisition mode of the camera. Value set: Continuous, SingleFrame, MultiFrame.
AcquisitionStart	Command		Start acquiring images.
AcquisitionStop	Command		Stop acquiring images.
PixelFormat	Enumeration	R/W	The image format (Mono8 etc.)
Width		Uint32	Image width, in pixels.
Height		Uint32	Image height, in pixels.
PayloadSize (do not use)		Uint32	Recommendation: Use VmbPayloadSizeGet() instead of this feature

To get notified whenever a feature value changes, use VmbFeatureInvalidationRegister() to register a callback that gets executed on the according event. For camera features, use the camera handle for registration. The function pointer to the callback function has to be of type VmbInvalidationCallback*().

Acquiring images¶

See also

The SDK Manual describes synchronous and asynchronous image acquisition.

See also

For a quick start, see the SynchronousGrab example.

Image Capture vs. Image Acquisition¶

Image capture and image acquisition are two independent operations: The API captures images, the camera acquires images. To obtain an image from your camera, setup the API to capture images before starting the acquisition on the camera:

Typical asynchronous application with the C API¶

Image Capture¶

To enable image capture, frame buffers must be allocated and the API must be prepared for incoming frames.

To capture images sent by the camera, follow these steps:

Open the camera as described in chapter Opening and closing a camera.
Query the necessary buffer size through the PayloadSize() function.
Announce the frame buffers. If you announce NULL buffers, the TL announces buffers with a suitable value.
Start the capture engine.
Queue the frame you have just created with VmbCaptureFrameQueue(), so that the buffer can be filled when the acquisition has started.

The API is now ready. Start and stop image acquisition on the camera as described in chapter Image Acquisition. How you proceed depends on the acquisition model you need:

Synchronous: Use VmbCaptureFrameWait to receive an image frame while blocking your execution thread.
Asynchronous: Register a callback that gets executed when capturing is complete. Use the camera handle for registration. The function pointer to the callback function has to be of type VmbFrameCallback*`(). Within the callback routine, queue the frame again after you have processed it.

Stop the capture engine with VmbCaptureEnd().
Call VmbCaptureQueueFlush() to cancel all frames on the queue.
Revoke the frames with VmbFrameRevokeAll() to clear the buffers.

To assure correct continuous image capture, queue at least two or three frames. The appropriate number of frames to be queued in your application depends on the frames per second the camera delivers and on the speed with which you are able to re-queue frames (also depending on the load of your operating system). The image frames are filled in the same order in which they were queued.

Note

Always check that VmbFrame_t.receiveStatus equals VmbFrameStatusComplete when a frame is returned to ensure the data is valid.

Note

Functions that must not be called within the Frame callback routine:

VmbStartup
VmbShutdown
VmbCameraOpen
VmbCameraClose
VmbFrameAnnounce
VmbFrameRevoke
VmbFrameRevokeAll
VmbCaptureStart
VmbCaptureStop

Image Acquisition¶

As soon as the API is prepared (see Image Capture, you can start image acquisition on your camera:

Set the feature AcquisitionMode (for example, Continuous).
Run the command AcquisitionStart.
To stop image acquisition, run command AcquisitionStop.

Image streaming code snippet¶

#define FRAME_COUNT 3 // We choose to use 3 frames
VmbError_t err;                  // Functions return an error code to
                                 // check for VmbErrorSuccess
VmbHandle_t hCamera              // A handle to our opened camera
VmbFrame_t frames[FRAME_COUNT]; // A list of frames for streaming
VmbUInt64_t nPLS;                // The payload size of one frame

// The callback that gets executed on every filled frame
void VMB_CALL FrameDoneCallback( const VmbHandle_t hCamera, VmbFrame_t *pFrame )
{
   if ( VmbFrameStatusComplete == pFrame ->receiveStatus )
   {
      printf( "Frame successfully received\n" );
   }
   else
   {
      printf( "Error receiving frame\n" );
   }
   VmbCaptureFrameQueue( hCamera , pFrame , FrameDoneCallback );
}

// Get all known cameras, see chapter "List available cameras"
// and open the camera as shown in chapter "Opening a camera"

// Get the required size for one image
err = VmbFeatureIntGet( hCamera , "PayloadSize", &nPLS );
for ( int i=0; i<FRAME_COUNT; ++i )
{
   // Allocate accordingly
   frames[i]. buffer = malloc( nPLS );
   frames[i]. bufferSize = nPLS;
   // Anounce the frame
   VmbFrameAnnounce( hCamera , frames[i], sizeof(VmbFrame_t) );
}

// Start capture engine on the host
err = VmbCaptureStart( hCamera );

// Queue frames and register callback
for ( int i=0; i<FRAME_COUNT; ++i )
{
   VmbCaptureFrameQueue( hCamera , frames[i],
                         FrameDoneCallback );
}

// Start acquisition on the camera
err = VmbFeatureCommandRun( hCamera , "AcquisitionStart" );

// Program runtime ...

// When finished , tear down the acquisition chain , close the camera and Vimba.
err = VmbFeatureCommandRun( hCamera , "AcquisitionStop" );
err = VmbCaptureEnd( hCamera );
err = VmbCaptureQueueFlush( hCamera );
err = VmbFrameRevokeAll( hCamera );
err = VmbCameraClose( hCamera );
err = VmbShutdown ();

Struct VmbFrame_t¶

The struct VmbFrame_t represents not only the actual image data, but also additional information. You can find the referenced data types in the tables below.

Tip

The field “void* buffer” of the struct can be NULL when the struct ist passed to VmbFrameAnnounce. In this case, the “alloc and announce” function of the TL allocates buffer memory.

VmbFrame_t¶
Struct entry	Type
void* buffer	Pointer to the actual image data including chunk data. Can be NULL.
VmbUint32_t bufferSize	Size of the data buffer
void* context[4]	4 void pointers that can be employed by the user (e.g., for storing handles)
VmbFrameStatus_t receiveStatus	Resulting status of the receive operation
VmbFrameFlags_t receiveFlags	Flags indicating which additional frame information is available
VmbUint32_t chunkSize	Size of the chunk data inside the data buffer
VmbPixelFormat_t pixelFormat	Pixel format of the image
VmbUint32_t width	Width of an image
VmbUint32_t height	Height of an image
VmbUint32_t offsetX	Horizontal offset of an image
VmbUint32_t offsetY	Vertical offset of an image
VmbUint64_t frameID	Unique ID of this frame in this stream
VmbUint64_t timestamp	Timestamp set by the camera

Enum *VmbFrameStatusType* is represented as VmbInt32_t through VmbFrameStatus_t¶
Enumeration	Integer Value	Purpose
VmbFrameStatusComplete	0	Frame was completed without errors
VmbFrameStatusIncomplete	-1	Frame could not be filled to the end
VmbFrameStatusInvalid	-3	Frame buffer was invalid

Enum VmbFrameFlagsType is represented as VmbUint32_t through VmbFrameFlags_t¶
Enumeration	Integer Value	Purpose
VmbFrameFlagsNone	0	No additional information is provided
VmbFrameFlagsDimension	1	Frame’s dimension is provided
VmbFrameFlagsOffset	2	Frame’s offset is provided (ROI)
VmbFrameFlagsFrameID	4	Frame’s ID is provided
VmbFrameFlagsTimestamp	8	Frame’s timestamp is provided

Transforming images¶

To transform images received via the API into common image formats, use the Image Transform Library.

See also

For a quick start, see the AsynchrounousGrab example, which contains an image transformation.

Using Events¶

Events serve many purposes and can have several origins such as generic camera events or just feature changes. All of these cases are handled in the C API uniformly with the same mechanism: You simply register a notification callback with VmbFeatureInvalidationRegister() for the feature of your choice which gets called when there is a change to that feature.

Three examples are listed in this chapter:

Camera list notifications
Camera event features
Tracking invalidations of features

Camera list notifications code snippet¶

// 1. define callback function
void VMB_CALL CameraListCB( VmbHandle_t handle , const char* name , void* context )
{
   char cameraName [255];
   char callbackReason [255];

   // Get the name of the camera due to which the callback was triggered
   VmbFeatureStringGet( handle , "DiscoveryCameraIdent", cameraName );

   // Get the reason why the callback was triggered. Possible values:
   // Missing (0), a known camera disappeared from the bus
   // Detected (1), a new camera was discovered
   // Reachable (2), a known camera can be accessed
   // Unreachable (3), a known camera cannot be accessed anymore

   VmbFeatureEnumGet( handle , "DiscoveryCameraEvent", callbackReason );
   printf( "Event was fired by camera %s because %s\n", cameraName ,
           callbackReason );
}

// 2. register the callback for that event
VmbFeatureInvalidationRegister( gVimbaHandle , "DiscoveryCameraEvent",
                                CameraListCB , NULL );

// 3. for GigE cameras , invoke "GeVDiscoveryAllOnce"
VmbFeatureCommandRun( gVimbaHandle , "GeVDiscoveryAllOnce" );

Getting notified about feature changes:

Notifications about feature changes code snippet (C)¶

void VMB_CALL WidthChangeCB( VmbHandle_t handle , const char* name , void* context )
{
printf( "Feature changed: %s\n", name );
}

// 2. register callback for changes to Width
VmbFeatureInvalidationRegister( cameraHandle , "Width", WidthChangeCB , NULL );

// as an example , binning is changed , so the callback will be run
VmbFeatureIntegerSet( cameraHandle , "Binning", 4 );

Getting notified about feature invalidations:

Notifications about feature invalidations code snippet¶

// 1. define callback function
void VMB_CALL WidthChangeCB( VmbHandle_t handle , const char* name , void* context )

   printf( "Feature changed: %s\n", name );
}

// 2. register callback for changes to Width
VmbFeatureInvalidationRegister( cameraHandle , "Width", WidthChangeCB , NULL );

// as an example , binning is changed , so the callback will be run
VmbFeatureIntegerSet( cameraHandle , "Binning", 4 );

Getting notified about camera events:

GigE camera events are also handled with the same mechanism of feature invalidation.

Getting notified about camera events code snippet¶

// 1. define callback function
void VMB_CALL EventCB( VmbHandle_t handle , const char* name , void* context )
{
   printf( "Event was fired: %s\n", name );
}
// 2. select "AcquisitionStart" event
VmbFeatureEnumSet( cameraHandle , "EventSelector", "AcquisitionStart" );

// 3. switch on the event notification
VmbFeatureEnumSet ( cameraHandle , "EventNotification", "On" );

// 4. register the callback for that event
VmbFeatureInvalidationRegister( cameraHandle , "EventAcquisitionStart",
                                EventCB , NULL );

Saving and loading settings¶

See also

For a quick start, see the LoadSaveSettings example.

Additionally to the user sets stored inside the cameras, you can save the feature values as an XML file to your host PC. For example, you can configure your camera with Vimba Viewer, save the settings as a file, and load them with Vimba API. To do this, use the functions VmbSettingsLoad and VmbSettingsSave.

To control which features are saved, use the (optional) flags and struct listed below. You can manually edit the XML file if you want only certain features to be restored.

Note

Saving and loading all features including look-up tables may take several minutes.

The struct VmbFeaturePersistSettings_t contains the optional member cameraPersistFlags. It is only evaluated if a cameraHandle is passed to the load/save functions and ignored for the other module handles.

Struct VmbFeaturePersistSettings_t¶
Struct Entry	Purpose
VmbFeaturePersist_t persistType	Controls which features are saved. Valid values: VmbFeaturePersistAll (all features) VmbFeaturePersistStreamable (streamable features only, excluding look-up tables VmbFeaturePersistNoLUT (default, all features except look-up tables
VmbCameraPersistFlags_t	Optional flags, see above
Vmbuint32_t maxIterations	Number of iterations. LoadCameraSettings iterates through all given features of the XML file and tries to set each value to the camera. Because of complex feature dependencies, writing a feature value may impact another feature that has already been set by LoadCameraSettings. To ensure all values are written as desired, the feature list can be looped several times, given by this parameter. Default value: 5, valid values: 1…10
VmbUint32_t	Logging level

Enum VmbCameraPersistFlagsType is represented as VmbUint32_t through VmbCameraPersistFlags_t¶
VmbCameraPersistFlagsNone	0x00
VmbCameraPersistFlagsTransportLayer	0x01
VmbCameraPersistFlagsInterface	0x02
VmbCameraPersistFlagsRemoteDevice	0x04
VmbCameraPersistFlagsLocalDevice	0x08
VmbCameraPersistFlagsStreams	0x10
VmbCameraPersistFlagsAll	0ff

If the flags are not set (=VmbCameraPersistFlagsNone), the default behavior is to only save/load the remote device features. The same behavior is applied if no VmbFeaturePersistSettings_t parameter is passed to the save/load functions.

Triggering¶

Note

Before triggering, startup the API and open the camera(s).

External trigger¶

The following code snippet shows how to trigger your camera with an external device.

External trigger code snippet¶

// Startup Vimba, get cameras and open cameras as usual
// Trigger cameras according to their interface
// Configure trigger input line and selector , switch trigger on
switch( pInterfacetype )
{
case VmbInterfaceEthernet:
   VmbFeatureEnumSet( pCameraHandle , "TriggerSelector", "FrameStart" );
   VmbFeatureEnumSet( pCameraHandle , "TriggerSource", "Line1" );
   VmbFeatureEnumSet( pCameraHandle , "TriggerMode", "On" );
   break;

case VmbInterfaceUsb:
   VmbFeatureEnumSet( pCameraHandle , "LineSelector", "Line0" );
   VmbFeatureEnumSet( pCameraHandle , "LineMode", "Input" );
   VmbFeatureEnumSet( pCameraHandle , "TriggerSelector", "FrameStart" );
   VmbFeatureEnumSet( pCameraHandle , "TriggerSource", "Line0" );
   VmbFeatureEnumSet( pCameraHandle , "TriggerMode", "On" );
   break;
}

Trigger over Ethernet – Action Commands¶

See also

For a quick start, see the ActionCommands example.

See also

Find more details in the application note: Trigger over Ethernet (ToE) - Action Commands

Triggering via the AcquisitionStart command is supported by all cameras. However, it is less precise than triggering with an external device connected to the camera’s I/O port. Some GigE cameras additionally support Action Commands. With Action Commands, you can broadcast a trigger signal simultaneously to multiple GigE cameras via GigE cable. Action Commands must be set first to the camera(s) and then to the TL, which sends the Action Commands to the camera(s). As trigger source, select Action0 or Action1.

ActionControl parameters

The following ActionControl parameters must be configured on the camera(s) and on the TL.

ActionDeviceKey must be equal on the camera and on the host PC. Before a camera accepts an Action Command, it verifies if the received key is identical with its configured key. Note that ActionDeviceKey must be set each time the camera is opened. Range (camera and host PC): 0 to 4294967295
ActionGroupKey means that each camera can be assigned to exactly one group for Action0 and a different group for Action1. All grouped cameras perform an action at the same time. If this key is identical on the sender and the receiving camera, the camera performs the assigned action. Range (camera and host PC): 0 to 4294967295
ActionGroupMask serves as filter that specifies which cameras within a group react on an Action Command. It can be used to create sub-groups. Range (camera): 0 to 4294967295 Range (host PC): 1 to 4294967295

Executing the feature ActionCommands sends the ActionControl parameters to the cameras and triggers the assigned action, for example, image acquisition. Before an Action Command is executed, each camera validates the received ActionControl parameter values against its configured values. If they are not equal, the camera ignores the command.

Action Commands code snippet¶

// Additionally to this code snippet:
// Configure the trigger settings and add image streaming

VmbUint32_t count;
VmbCameraInfo_t* cameras;
VmbHandle_t* handles;

int deviceKey = 11, groupKey = 22, groupMask = 33;

// Start Vimba and discover GigE cameras
VmbStartup( NULL );

// Get cameras
VmbCamerasList( NULL, 0, &count, sizeof(*cameras) );
cameras = (VmbCameraInfo_t *) malloc( count * sizeof(*cameras) );
VmbCamerasList( cameras, count, &count, sizeof(*cameras) );

// Allocate space for handles
handles = (VmbHandle_t*) malloc( count * sizeof(VmbHandle_t) );

for( int i=0; i<count; ++i )
{
    const char* cameraId = cameras[i].cameraIdString;

    // Open camera
    VmbCameraOpen( cameraId, VmbAccessModeFull, &handles[i] );

    // Set device key, group key and group mask
    // Configure trigger settings (see programming example)
    VmbFeatureIntSet( handles[i], "ActionDeviceKey", deviceKey );
    VmbFeatureIntSet( handles[i], "ActionGroupKey", groupKey );
    VmbFeatureIntSet( handles[i], "ActionGroupMask", groupMask );
}

// Set Action Command to API
// Allocate buffers and enable streaming (see programming example)
VmbFeatureIntSet( gVmbHandle, "ActionDeviceKey", deviceKey );
VmbFeatureIntSet( gVmbHandle, "ActionGroupKey", groupKey );
VmbFeatureIntSet( gVmbHandle, "ActionGroupMask", groupMask );

// Send Action Command
VmbFeatureCommandRun( gVmbHandle, "ActionCommand" );

// If no further Actions will be applied: close cameras, shutdown API, and
// free allocated space as usual

Listing interfaces¶

You can list all found interfaces such as frame grabbers or NICs. VmbInterfacesList() enumerates all interfaces recognized by the underlying transport layers.

List interfaces code snippet¶

VmbUint32_t nCount;
VmbInterfaceInfo_t *pInterfaces;

// Get the number of connected interfaces
VmbInterfacesList( NULL , 0, &nCount , sizeof *pInterfaces );

// Allocate accordingly
pInterfaces = (VmbInterfaceInfo_t *) malloc( nCount * sizeof *pInterfaces );

// Get the interfaces
VmbInterfacesList( pCameras , nCount , &nCount , sizeof *pInterfaces );

Struct VmbInterfaceInfo_t¶

Struct VmbInterfaceInfo_t provides the entries listed in the table below for obtaining read-only information about an interface.

VmbInterfaceInfo_t¶
Type	Field	Purpose
const char*	interfaceIdString	Unique identifier for each interface
VmbTransportLayerType_t	interfaceType	See VmbTransportLayerType
const char*	interfaceName	Given by the TL
VmbHandle_t	transportLayerHandle	For TL system module feature access
VmbHandle_t	interfaceHandle	For interface module feature access

Enabling notifications of changed interface states¶

To get notified whenever an interface is detected or disconnected, use VmbFeatureInvalidationRegister() to register a callback that gets executed on the according event. Use the global Vmb handle for registration. The function pointer to the callback function has to be of type VmbInvalidationCallback().

Interface enumerations¶

Enum VmbInterfaceType is represented as VmbUint32_t through VmbInterfaceInfo_t¶
Enumeration	Integer Value	Interface
VmbInterfaceUnknown	0	Interface is not known to the API
VmbInterfaceFirewire	1	IEEE 1394
VmbInterfaceEthernet	2	GigE
VmbInterfaceUsb	3	USB
VVmbInterfaceCl	4	Camera Link
VmbTransportLayerTypeCXP	5	CoaXPress
VmbTransportLayerTypeCLHS	6	Camera Link HS
VmbTransportLayerTypeU3V	7	USB3 Vision Standard
VmbTransportLayerTypeEthernet	8	Generic Ethernet
VmbTransportLayerTypePCI	9	PCI / PCIe
VmbTransportLayerTypeCustom	10	Non standard
VmbTransportLayerTypeMixed	11	Mixed (System module only)

Note

Functions that must not be called be called within the callback routine:

VmbStartup
VmbShutdown
VmbFeatureIntSet (and any other VmbFeature*Set function)
VmbFeatureCommandRun

Error codes¶

Error codes¶
Error Code	Value	Description
VmbErrorSuccess	0	No error
VmbErrorInternalFault	-1	Unexpected fault in Vmb or driver
VmbErrorApiNotStarted	-2	VmbStartup was not called before the current command
VmbErrorNotFound	-3	The designated instance (camera, feature, etc.) cannot be found
VmbErrorBadHandle	-4	The given handle is not valid
VmbErrorDeviceNotOpen	-5	Device was not opened for usage
VmbErrorInvalidAccess	-6	Operation is invalid with the current access mode
VmbErrorBadParameter	-7	One of the parameters is invalid (usually an illegal pointer)
VmbErrorStructSize	-8	The given struct size is not valid for this version of the API
VmbErrorMoreData	-9	More data available in a string/list than space is provided
VmbErrorWrongType	-10	Wrong feature type for this access function
VmbErrorInvalidValue	-11	The value is not valid; either out of bounds or not an increment of the minimum
VmbErrorTimeout	-12	Timeout during wait
VmbErrorOther	-13	Other error
VmbErrorResources	-14	Resources not available (e.g., memory)
VmbErrorInvalidCall	-15	Call is invalid in the current context (e.g. callback)
VmbErrorNoTL	-16	No transport layers are found
VmbErrorNotImplemented	-17	API feature is not implemented
VmbErrorNotSupported	-18	API feature is not supported
VmbErrorIncomplete	-19	The current operation was not completed (e.g. a multiple registers read or write)
VmbErrorIO	-20	There was an error during read or write with devices (camera or disk)

See also

If your TL or camera is not found or if you experience other issues, see Troubleshooting.