Image Manager (CVCDriver.dll) 14.0

Interface for grabbing images [Legacy API: 2nd generation]. More...

## Enumerations

enum  GRAB_INFO_CMD {
GRAB_INFO_NUMBER_IMAGES_AQCUIRED = 0 , GRAB_INFO_NUMBER_IMAGES_LOST = 1 , GRAB_INFO_NUMBER_IMAGES_LOST_LOCKED = 2 , GRAB_INFO_NUMBER_IMAGES_LOCKED = 3 ,
GRAB_INFO_NUMBER_IMAGES_PENDIG = 4 , GRAB_INFO_GRAB_ACTIVE = 5 , GRAB_INFO_TIMESTAMP = 6 , GRAB_INFO_NUMBER_TRIGGERS_LOST = 7 ,
GRAB_INFO_CAMERA_DETECTED = 8 , G2INFO_NumBuffersPending = 10 , G2INFO_NumBuffersDelivered = 11 , G2INFO_NumBuffersCorrupt = 12 ,
G2INFO_NumBuffersCorruptOnDelivery = 13 , G2INFO_NumBuffersLost = 14 , G2INFO_NumBuffersLostLocked = 15 , G2INFO_NumBuffersAcquired = 16 ,
G2INFO_NumBuffersQueued = 17 , G2INFO_NumBuffersAnnounced = 18 , G2INFO_NumBuffersInIncompleteList = 19 , G2INFO_NumPacketsReceived = 20 ,
G2INFO_NumResends = 21 , G2INFO_NumBuffersLocked = 22
}
Defines options for the function G2GetGrabStatus.

The number of images processed by an application can easily be calculated by counting the number of ImageSnaped events of the Common Vision Image Control or, if using DLL functions, by counting the number of successful calls to G2Wait.

The following formula describes the context of images acquired, pending, processed and lost:
NumImgAcquired = NumImgProcessed + NumImgPending + NumImgDropped
where NumImgDropped = NumImgLost + NumImgLostLocked. More...

## Functions

cvbbool_t CanGrab2 (void *Image)
This function verifies whether the image supports the Grab2 interface. More...

cvbres_t G2Freeze (IMG Image, cvbbool_t bKill)
Stops the current acquisition after the next image or immediately depending on the value of bKill. More...

cvbres_t G2GetGrabStatus (IMG Image, GRAB_INFO_CMD lRequestType, double &dRequestAnswer)
Inquire information about the status of the IGrab2 interface of the hardware and the last image acquired. More...

cvbres_t G2Grab (IMG Image)
Starts a continuous acquisition of images in a seperate thread. More...

cvbres_t G2Wait (IMG Image)
Waits for the next image to be acquired. More...

## Detailed Description

Interface for grabbing images [Legacy API: 2nd generation].

## ◆ GRAB_INFO_CMD

 enum GRAB_INFO_CMD

Defines options for the function G2GetGrabStatus.

The number of images processed by an application can easily be calculated by counting the number of ImageSnaped events of the Common Vision Image Control or, if using DLL functions, by counting the number of successful calls to G2Wait.

The following formula describes the context of images acquired, pending, processed and lost:
NumImgAcquired = NumImgProcessed + NumImgPending + NumImgDropped
where NumImgDropped = NumImgLost + NumImgLostLocked.

Attention
The list below descripes the specific constant declarations and typedefs. There are declared in the header file iCVCDriver.* .
Enumerator
GRAB_INFO_NUMBER_IMAGES_AQCUIRED

Inquire the number of acquired images since the last call to G2Grab. This number represents the number of images that have been transferred by the camera into the image acquisition device. It includes images that have been processed as well as images that have been lost for certain reasons.

GRAB_INFO_NUMBER_IMAGES_LOST

Inquire the number of lost images due to image acquisition device performance since the last call to G2Grab.

GRAB_INFO_NUMBER_IMAGES_LOST_LOCKED

Inquire the number of lost images due to the fact that all buffers were locked since the last call of G2Grab.

GRAB_INFO_NUMBER_IMAGES_LOCKED

Inquire the number of actually locked buffers.

GRAB_INFO_NUMBER_IMAGES_PENDIG

Inquire the number of pending buffers (buffers which contain new data but have not been delivered with G2Wait).
This basically defines a queue and contains the number of buffers in the ring buffer - 1.

GRAB_INFO_GRAB_ACTIVE

Inquire if a grab (acquisition) is active (0 indicates that no grab is active, all other values indicate an active grab)

GRAB_INFO_TIMESTAMP

Inquire the time stamp for the current image. This feature is optional and may not be supported by any driver.

GRAB_INFO_NUMBER_TRIGGERS_LOST

Inquire how many trigger signals are lost/ignored while acquisition was active (trigger frequency is too high).

Attention
At the moment only Dalsa grabbers can count how many triggers are lost.
GRAB_INFO_CAMERA_DETECTED

Inquire if a camera was detected or not.

Attention
Only SiSo and Dalsa grabbers support this feature. A grabber detects the pixel clock of a camera and inform the application
if a camera has a pixel clocks or not. This feature is not supported with GigE or fire wire.
G2INFO_NumBuffersPending

Inquire the number of images/buffers in the output queue, waiting for a call to G2Wait.

Attention
These images/buffers contain new data not yet seen by the application. The application must call G2Wait to receive the images. It is depending on the configuration of the driver if "not yet delivered, incomplete frames" are counted as pending or not. If the driver is configured to "Deliver corrupt frames" then then these frames are counted as being "Pending". If the driver is configured to discard corrupt frames then these frames are not counted as being pending.
G2INFO_NumBuffersDelivered

Inquire the number of images delivered through G2Wait no matter if these images are corrupt or not.

G2INFO_NumBuffersCorrupt

Inquire the number of images which were corrupt on arrival in the host no matter if or if not resend requests have been issued. This counter indicates if something is wrong with the transmission. In case the user wants to discard corrupt images he needs to configure his vin/tl accordingly. A corrupt image is an image which in the first run did not arrive properly. This includes also images which for example had missing packets and which have been completed later on using resend requests. So a corrupt image may not be corrupt on delivery because the transport mechanisms underneath corrected the failure.

G2INFO_NumBuffersCorruptOnDelivery

Inquire the number of images which were corrupt (not complete) when delivered through G2Wait. A corrupt delivered image cannot/will not be completed after delivery.

G2INFO_NumBuffersLost

Inquire the number of images lost locked + number of images lost because of other reasons For example the image was corrupt and the setting of the driver did not allow delivery of corrupt images.

G2INFO_NumBuffersLostLocked

Inquire the number of lost images due to an overrun in the acquisition because G2Wait was not called fast enough.

G2INFO_NumBuffersAcquired

Inquire the nNumImagesDelivered + NumImagesPending It is depending on the configuration of the driver if "not yet delivered incomplete frames" are counted as pending and therefore be part of NumImagesAcquired or not. See the explanation of "NumPendingImages".

G2INFO_NumBuffersQueued

Inquire the nNumber of buffers which, at a given point in time, can take new data. Only queued buffers can take new image data. Buffers which are not queued are basically locked. In CVB, before a G2Grab starts all announced buffers are also queued for acquisition. So until the first image starts the NumBuffersQueued = NumBuffersAnnounced. While the first image is transferred the number of queued images is one less than at the start. After the first image finished until the first call to G2Wait the NumBuffersQueued = NumBuffersAnnounced-1 and the NumBuffersPending = 1. After G2Wait and before the second image starts NumBuffersQueued = NumBuffersAnnounced-1, NumBufferDelivered=1, NumBufferPending=0. And so on.

G2INFO_NumBuffersAnnounced

Inquire the number of buffers which can hold image data. This has direct influence on the amount of memory allocated by the driver to hold image data. This value is equivalent to the number of buffers in the iRingBuffer interface.

G2INFO_NumBuffersInIncompleteList

Inquire the number of buffers which have been started to fill but are not yet done. In case this (internal) incomplete list is full the buffer will, depending on the configuration of the driver, be delivered as corrupt buffer to the host application or discarded.

This is related to GigE and indicates the number of data packets received on the GigE Vision streaming channel.

G2INFO_NumResends

This is related to GigE and indicates the number of resend requests issued by the host. If this number increases it indicates that something is wrong with the data transmission. Possible reasons may be: Settings of the network card, cpu-load on the host, cable/switch problems, bandwidth problems on the Link.

G2INFO_NumBuffersLocked

Inquire the number of buffers locked at a given point in time.

## ◆ CanGrab2()

 cvbbool_t CanGrab2 ( void * Image )

This function verifies whether the image supports the Grab2 interface.

Parameters
 [in] Image Handle of image object.
Returns
TRUE if the image supports the Grab2 interface, FALSE otherwise.
Supported platforms:
Win32
Win64
Linux
Examples:
Delphi - Delphi RingBuffer Example
Visual Basic - VB Driver Grab2 Example
Visual C++ - VC MDI Example (DLL only)

## ◆ G2Freeze()

 cvbres_t G2Freeze ( IMG Image, cvbbool_t bKill )

Stops the current acquisition after the next image or immediately depending on the value of bKill.

Parameters
 [in] Image Handle of image object. [in] bKill Specifies if the acquisition should end immediately or at the end of the next image if the image acquisition device SDK supports that feature.
Returns
0 : OK
<0 : an error occured
Supported platforms:
Win32
Win64
Linux
Examples:
Visual C++ - VC MDI Example (DLL only)

## ◆ G2GetGrabStatus()

 cvbres_t G2GetGrabStatus ( IMG Image, GRAB_INFO_CMD lRequestType, double & dRequestAnswer )

Inquire information about the status of the IGrab2 interface of the hardware and the last image acquired.

Parameters
 [in] Image Handle of image object. [in] lRequestType Command to execute (see GRAB_INFO_CMD for possible values). [out] dRequestAnswer Requested Information.
Returns
0 : OK
<0 : an error occured
Supported platforms:
Win32
Win64
Linux
Related Topics:
GRAB_INFO_CMD
Examples:
Visual Basic - VB Driver Grab2 Example
Visual C++ - VC MDI Example (DLL only)

## ◆ G2Grab()

 cvbres_t G2Grab ( IMG Image )

Starts a continuous acquisition of images in a seperate thread.

Use \ref G2Wait to sychronize to this thread. To stop the acquisition you have to call \ref G2Freeze.


Information about the images that have been acquired or lost can be retrieved using the G2GetGrabStatus.

Parameters
 [in] Image Handle of image object.
Returns
0 : OK
<0 : an error occured
Supported platforms:
Win32
Win64
Linux
Examples:
Visual C++ - VC MDI Example (DLL only)

## ◆ G2Wait()

 cvbres_t G2Wait ( IMG Image )

Waits for the next image to be acquired.

The function returns a value greater or equal \c 0 when a new image is available to be processed.


In all other cases including the case that there is no image left to be processed it returns values less than 0.

Parameters
 [in] Image Handle of image object.
Returns
0 : OK
<0 : an error occured
Supported platforms:
Win32
Win64
Linux
Examples:
Visual C++ - VC MDI Example (DLL only)