Image Manager (CVCDriver.dll) 14.0
IAcquisitionEngine

Interface for controlling an image acquisition engine. More...

Enumerations

enum  CVDWaitStatus { CVDWS_Ok , CVDWS_Canceled , CVDWS_Timeout }
 

Functions

cvbbool_t CVDCanAcquisitionEngine (CVDSTREAM Stream)
 This function verifies if the handle implements IAcquisitionEngine. More...
 
cvbres_t CVDStreamAcquisitionEngineAbort (CVDSTREAM Stream)
 Attempts to stop the data stream acquisition engine. More...
 
cvbres_t CVDStreamAcquisitionEngineStart (CVDSTREAM Stream, cvbint64_t BufferCountToAcquire)
 Attempts to start the data stream acquisition engine. More...
 
cvbres_t CVDStreamAcquisitionEngineStop (CVDSTREAM Stream, cvbint64_t Timeout)
 Attempts to stop the data stream acquisition engine. More...
 
cvbres_t CVDStreamAcquisitionEngineWaitForNextComposite (CVDSTREAM Stream, cvbint64_t Timeout, CVCANCELLATIONTOKEN CancelationToken, CVDWaitStatus &WaitStatus, CVCOMPOSITE &Composite)
 Attempts to acquire a new complete composite. More...
 

Detailed Description

Interface for controlling an image acquisition engine.

Data acquisition is done by the data acquisition engine and this interface offers a set of features such as starting or stopping the engine. Note that the data stream module will also need to be controlled in parallel to achieve data acquisition.

See also
IStreamControl IStreamEnum

Enumeration Type Documentation

◆ CVDWaitStatus

Enumerator
CVDWS_Ok 

The wait returned successfully with data.

CVDWS_Canceled 

The wait returned successfully without data as it was canceled.

CVDWS_Timeout 

The wait returned successfully without data as timed out.

Function Documentation

◆ CVDCanAcquisitionEngine()

cvbbool_t CVDCanAcquisitionEngine ( CVDSTREAM  Stream)

This function verifies if the handle implements IAcquisitionEngine.

Parameters
[in]DeviceObjectHandle to be examined.
Returns
TRUE if the handle implements IAcquisitionEngine, FALSE otherwise.
Supported platforms:
Win32
Win64
Linux

◆ CVDStreamAcquisitionEngineAbort()

cvbres_t CVDStreamAcquisitionEngineAbort ( CVDSTREAM  Stream)

Attempts to stop the data stream acquisition engine.

Unlike CVDStreamAcquisitionEngineStop, this function forcibly aborts, i.e., terminates the ongoing acquisition processes so this function call always returns.

Parameters
[in]StreamThe handle of a target data stream module.
Returns
  • #CVC_ERROR (#CVC_E_OK) if the abort operation was completed successfully.
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if Stream is not a CVDSTREAM.
Note
This function can be even called while a CVDStreamAcquisitionEngineStop function call is in progress. To learn the detailed behavior of this case, please refer to the section for CVDStreamAcquisitionEngineStop.
See also
CVDStreamAcquisitionEngineStop

◆ CVDStreamAcquisitionEngineStart()

cvbres_t CVDStreamAcquisitionEngineStart ( CVDSTREAM  Stream,
cvbint64_t  BufferCountToAcquire 
)

Attempts to start the data stream acquisition engine.

In computer vision applications, in most of the cases images are needed as the input of the application and they are taken by imaging devices in the given system that also work as "streaming" devices since they deliver images through the given transport layer as a logical stream. In general, however, most of the GenICam compliant data streaming devices such as cameras do not start streaming until they get a cue from their requesting entity and it is better to be aware of the responsibility. To let a data streaming device start streaming, call CVDStreamControlStart.

Note that the data stream acquisition engine should be started first so that it does not drop the data that is transmitted from the streaming device. Once the acquisition engine was started, the data stream module can start streaming anytime.

Parameters
[in]StreamThe handle of a target data stream module.
[in]BufferCountToAcquireThe number of complete buffers to acquire; set -1 for infinite acquisition.
Returns
  • #CVC_ERROR (#CVC_E_OK) if the acquisition engine has started successfully.
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if Stream is not a CVDSTREAM.
  • #CVC_ERROR (#CVC_E_PARAMETER) if BufferCountToAcquire is invalid.
Note
Once the engine acquired the number of complete buffers specified by BufferCountToAcquire it automatically stops the data stream acquisition engine. In that case, it is not necessary to call neither of CVDStreamAcquisitionEngineStop or CVDStreamAcquisitionEngineAbort even though it is absolutely legal to call them; note that neither of them has any other additional effect.
See also
CVDStreamControlStart CVDStreamAcquisitionEngineStop CVDStreamAcquisitionEngineAbort

◆ CVDStreamAcquisitionEngineStop()

cvbres_t CVDStreamAcquisitionEngineStop ( CVDSTREAM  Stream,
cvbint64_t  Timeout 
)

Attempts to stop the data stream acquisition engine.

How is this function different from CVDStreamAcquisitionEngineAbort? It is an absolutely valid concern; the difference is if the ongoing acquisition process waits until the acquisition process is completed or is immediately terminated no matter if the acquisition process was not yet completed.

Call this function instead of CVDStreamAcquisitionEngineStop if the acquisition process needs to be confirmed if it is completed at the timing where the execution steps out from the function call.

Having heard that the function call waits until the acquisition process is completed, another question may come: What would it happen if the acquisition process is NEVER completed. This is not a special case and is rather entirely valid: There should be a case where this function is called with no timeout and the expected number of complete buffers is never reach out to the expected number. In this case, the function call never returns! Having that nature, it can lead a rational reason to disable the timeout detection.

In addition, since this function call waits for the completion of the acquisition process, the data stream module should be stopped data streaming AFTER this function call calling CVDStreamControlStop or CVDStreamControlAbort. Otherwise, the acquisition process will miss the chance to be completed because the source has already stopped data streaming.

Parameters
[in]StreamThe handle of a target data stream module.
[in]TimeoutExpected period in milliseconds by which the acquisition must finish to collect the number of complete buffers that has been specified before starting it; set -1 if timeout detection is not required.
Returns
  • #CVC_ERROR (#CVC_E_OK) if the stop operation was completed successfully.
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if Stream is not a CVDSTREAM.
  • #CVC_ERROR (#CVC_E_GRABABORTED) if the stop operation was aborted while the stop operation had been in progress.
Note
This is also valid to call CVDStreamAcquisitionEngineAbort while CVDStreamAcquisitionEngineStop is under progress. In this case, the stop process is immediately canceled, and the allocated resource for the image acquisition will be released. To explicitly report that the stop process was aborted by the abort function call, #CVC_E_GRABABORTED will be returned from the stop function call.
See also
CVDStreamAcquisitionEngineAbort

◆ CVDStreamAcquisitionEngineWaitForNextComposite()

cvbres_t CVDStreamAcquisitionEngineWaitForNextComposite ( CVDSTREAM  Stream,
cvbint64_t  Timeout,
CVCANCELLATIONTOKEN  CancelationToken,
CVDWaitStatus WaitStatus,
CVCOMPOSITE &  Composite 
)

Attempts to acquire a new complete composite.

The code execution is blocked until a new composite, i.e., a target acquisition unit such as a 2D image is acquired.

Once it's returned a new composite must be available but note that there could also be a case where none of them is available if the acquisition process has timed out.

Parameters
[in]StreamThe handle of a target data stream module.
[in]TimeoutDuration to wait for a new composite is acquired; the unit is the millisecond. Set -1 for infinite.
[in]CancelationTokenA cancelation token to stop the ongoing acquisition process.
[out]WaitStatusCurrent status of the acquisition process.
[out]CompositeAn aquired composite; could be nullptr and WaitStatus should be diagnosed.
Returns
  • #CVC_ERROR (#CVC_E_OK) if composite was received successfully.
  • #CVC_ERROR (#CVC_E_WRONGOBJECT) if Stream is not a CVDSTREAM.
Note
The data stream acquisition engine should be started BEFORE calling this function otherwise the engine will have to be waiting for something that never comes. It is highly recommended to remember this when a similar case is troubleshooted; this may sound trivial but it can actually happen.
See also
CVDStreamAcquisitionEngineStart