C API Manual

Introduction to the API

The C API is the underlying API of Vimba X.

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.
- Enumerates interfaces and cameras and retrieves the Camera handle.
- Has an optional parameter. You can use this parameter to select which transport layers are used.
The function VmbShutdown():
- Blocks until all callbacks have finished execution.
- 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.

See also

For details about the optional parameter, see the SDK Manual, chapter TL activation and deactivation and the ListCameras example.

Listing cameras

See also

For a quick start, see the ListCameras example.

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 or extended ID
Camera model
Name or ID of the connected interface (for example, the NIC)

Extended ID

Tip

In most cases, the Extended ID is not needed. You can use it as needed.

If several TLs are available for one camera, the camera is listed several times. To avoid potential conflicts, the SDK automatically creates an extended ID string for each camera. extended ID string is provided in the struct VmbCameraInfo_t: cameraIdStringExtended.

Extended IDs use the following grammar:

extended_id : <tl_identifier-char-count> separator tl_identifier <interface_id-char-count>
separator interface_id <camera_id-char-count> separator camera_id separator   : ':'`

Note

Extended IDs always overwrite other ids. A non-extended ID may be unusable after other cameras are discovered.

Extended IDs
Placeholder	Description
tl_identifier	File path of the transport layer
interface_id	ID of the interface as reported by the transport layer
camera_id	Camera (non-extended) ID as reported by the interface
<tl_identifier-char-count>	Number of characters (TL ID) encoded as decimal integer
<interface_id-char-count>	Number of characters (interface ID) encoded as decimal integer
<camera_id-char-count>	Number of characters encoded as decimal integer

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 GigE cameras requires a certain amount of time. By default, GeVDiscoveryAllAuto(). is enabled. You can easily enable GeVDiscoveryAllOnce() in VmbC.xml if you want to reduce bandwidth.

USB 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 VmbSystem::Shutdown and VmbSystem::Startup consecutively.

MIPI CSI cameras

Cameras with MIPI CSI-2 interface are detected when the board is booted. To avoid damage to the hardware, do not plug in or out a camera while the board is powered.

List cameras code snippet

VmbUint32_t nCount;
VmbCameraInfo_t* pCameras;

// 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. You can query the struct with the functions VmbCamerasList() and VmbCameraInfoQueryByHandle().

To access all GenTL modules via this struct:

To access all GenTL modules via this struct, first open the camera and call VmbCameraInfoQuery().
Alternatively, use VmbFeatureIntValidValueSetQuery(), which uses a local or remote device handle. This function returns an error if the handle is invalid or the camera associated with the handle is no longer open.

VmbCameraInfo_t
Type	Field	Purpose
const char*	cameraIdString	Unique identifier for each camera
const char*	cameraIdStringExtended	Extended unique identifier for each camera
const char*	cameraName	Name of the camera
const char*	modelName	The model name
VmbAccessMode_t	permittedAccess	See VmbAccessModeType
VmbHandle_t	transportLayerHandle	Handle for the transport layer (system) module
VmbHandle_t	interfaceHandle	Handle for the interface module
VmbHandle_t	localDeviceHandle	Handle for the local device (camera) module
VmbHandle_t	streamHandles	Array of handles for the stream modules
VmbHandle_t	streamCount	Number of entries in the streamHandles array

Enabling notifications of changed camera states

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

See also

Getting notified about discovery events

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.

Note

The function VmbCameraOpen() returns a handle to the camera only.

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

Access modes
Enumeration Integer Value	Integer Value	Purpose
VmbAccessModeNone	0	No access
VmbAccessModeFull	1	Read and write access
VmbAccessModeRead	2	Read-only access

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

Closing a camera code snippet

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

Listing transport layers

The function VmbTransportLayersList() enumerates all found TLs.

See also

To control which TLs are loaded or ignored, see TL activation and deactivation.

See also

The AsynchrounousGrab example lists all loaded TLs.

Struct VmbTransportLayerInfo_t

The struct VmbTransportLayerInfo_t holds read-only information about a transport layer. You can use it to retrieve a handle to the transport layer. You can query the struct with the function VmbTransportLayersList().

Struct VmbTransportLayerInfo_t
Type	Field
const char*	transportLayerIdString
VmbInterface_t	transportLayerType
const char*	transportLayerName
const char*	transportLayerPath
VmbHandle_t	transportLayerHandle

Accessing features

See also

To quickly learn how to list features of the GenTL modules, see the ListFeatures example.

The function VmbCameraOpen() returns a handle to the camera, which can be used for accessing the camera features. The features of the other GenTL modules (system, interface, device, stream) can be accessed with the corresponding handle. These handles are part of the following structs:

VmbCameraInfo_t
VmbInterfaceInfo_t
VmbSystemInfo_t

Feature types

The 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

Struct VmbFeatureInfo_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 n	Namespace this feature resides in
VmbInt64_t intValue	Integer value of this enumeration entry

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
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 hidden

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

The C API provides separate access to the feature lists of all GenTL modules.

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 using VmbC

Image Capture

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

Optionally, you can activate the alloc and announce functionality for more efficient buffer allocation. To do this, use the optional parameter /x.

Note

CSI-2 cameras only:

We recommend using alloc and announce. If you want to use the announce mode with the CSI TL, you must take care of the buffer alignment (which is not necessary when using alloc and announce). To do this:

Query the required buffer alignment using the StreamBufferAlignment feature of the Stream module.
Use the returned value for buffer allocation, for example, with the function aligned_alloc.
Announce buffers as usual, see the description below.

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 convenience function VmbPayloadSizeGet() (to avoid errors, do not use 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 and discard all pending callbacks 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
VmbCaptureEnd

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
// For smooth image acquisition, perform the callback as fast as possible
void VMB_CALL FrameDoneCallback( const VmbHandle_t hCamera, const VmbHandle_t hStream, 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 = VmbPayloadSizeGet( hCamera , &nPLS );
for ( int i=0; i<FRAME_COUNT; ++i )
{
   // Allocate accordingly
   frames[i]. buffer = malloc( nPLS ); (B)
   frames[i]. bufferSize = nPLS; (B)
   // 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 X.
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

Getting notified about discovery events

Camera list notifications code snippet

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

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

   // 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 , "EventCameraDiscoveryType", &callbackReason );
   printf( "Event was fired by camera %s because %s\n", cameraName ,
           callbackReason );
}

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

Note

Per default, camera discovery events are only effective for the known interfaces. If you want to get notified about new cameras from a new interface we recommend registering the event EventInterfaceDiscovery, which will make sure that new interfaces are discovered.

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

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

Chunk

Note

To use the chunk feature, make sure your camera supports it. To activate the chunk camera feature, see the user documentation of your camera.

Chunk data are image metadata such as the exposure time that are available in the Frame that contains the chunk data. To access chunk data, use VmbChunkAccessCallback.

Required parameters:

The frame handle that contains the chunk data (VmbFrame_t)
Callback to access the chunk data
Pointer for passing custom data in and out the function

Chunk code snippet

// Data structure for passing Chunk data values to and from the Chunk Data Access Callback function
// This should be adjusted for the Chunk features that are available for a specific camera
// In this example, the camera supports the Chunk features:
// ChunkWidth, ChunkHeight, ChunkOffsetX, ChunkOffsetY
typedef struct
{
  VmbInt64_t m_width;
  VmbInt64_t m_height;
  VmbInt64_t m_offsetX;
  VmbInt64_t m_offsetY;
} ChunkData;

// We may use custom error codes as return values for the Chunk Data Access Callback function
static const VmbError_t ChunkOffsetAccessError = VmbErrorCustom + 0;
static const VmbError_t ChunkSizeAccessError = VmbErrorCustom + 1;

// Chunk features are only accessible in the Chunk Data Access Callback function
VmbError_t VMB_CALL MyChunkDataAccessCallback(VmbHandle_t featureAccessHandle, void* userContext)
{
  ChunkData* chunkData = ((ChunkData*)(userContext));

  // With the featureAccessHandle, Chunk features can be accessed like any other camera feature
  if ( (VmbFeatureIntGet(featureAccessHandle, "ChunkWidth", &chunkData.m_width) != VmbErrorSuccess)
      || (VmbFeatureIntGet(featureAccessHandle, "ChunkHeight", &chunkData.m_height) != VmbErrorSuccess) )
  {
      return ChunkSizeAccessError;
  }

  if ( (VmbFeatureIntGet(featureAccessHandle, "ChunkOffsetX", &chunkData.m_offsetX) != VmbErrorSuccess)
      || (VmbFeatureIntGet(featureAccessHandle, "ChunkOffsetY", &chunkData.m_offsetY) != VmbErrorSuccess) )
  {
      return ChunkOffsetAccessError;
  }

  return VmbErrorSuccess;
}

void VMB_CALL MyFrameCallback(const VmbHandle_t cameraHandle, const VmbHandle_t streamHandle, VmbFrame_t* frame)
{
  if (frame->chunkDataPresent)
  {
    ChunkData chunkData;

    // The function VmbChunkDataAccess will prepare the Chunk data access for the current frame
    // The Chunk features can be accessed in the passed Chunk Data Access Callback function
    // Chunk feature values are passed in the ChunkData struct
    VmbError_t err = VmbChunkDataAccess(frame, MyChunkDataAccessCallback, &chunkData);

    if (err == VmbErrorSuccess)
    {
      // Print the Chunk features for the current frame
      printf("Frame received: FrameId=%llu; Width=%lld; Height=%lld; OffsetX=%lld; OffsetY=%lld\n",
        frame->frameID, chunkData.m_width, chunkData.m_height, chunkData.m_offsetX, chunkData.m_offsetY);
    }
    else
    {
      // Error handling
      // VmbChunkDataAccess returns the same error value as the Chunk Data Access Callback function,
      // e.g. our custom error codes ChunkSizeAccessError and ChunkOffsetAccessError
    }
  }

  VmbCaptureFrameQueue(cameraHandle, frame, MyFrameCallback);
}

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 of the GenTL modules as an XML file to your host PC. 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 API supports saving and loading settings for every GenTL module. To specify which settings are saved and loaded when passing a camera handle, the API contains a set of (optional) flags.

Note

A settings XML file can only contain features for one instance of a module.

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.

Tip

If you pass a camera handle and activate all flags, the features of all GenTL modules including the transport layer and the interface are saved.

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 X, 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;

// USB: VmbInterfaceUsb
// CSI-2: VmbInterfaceCSI2

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

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 the event EventInterfaceDiscovery. Use the global Vmb handle for registration. The function pointer to the callback function has to be of type VmbInvalidationCallback(). The callback gets executed on the according interface discovery event.

TL enumerations

Tip

The CSI TL is listed as VmbTransportLayerTypeCustom.

Enum VmbTransportLayerType is represented as VmbUint32_t through VmbInterfaceInfo_t
Enumeration	Integer Value	Interface
VmbTransportLayerTypeUnknown	0	Interface is not known to the API
VmbTransportLayerTypeGEV	1	GigE Vision
VmbTransportLayerTypeCL	2	Camera Link
VmbTransportLayerTypeIIDC	3	IIDC 1394
VmbTransportLayerTypeUVC	4	USB video class
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.