IAcquisitionEngine

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

Enumerations
enum	CVDWaitStatus { CVDWS_Ok , CVDWS_Canceled , CVDWS_Timeout }
	The status returned from a wait operation. More...

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

enum CVDWaitStatus

The status returned from a wait operation.

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]

Stream

Handle 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]

Stream

The 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]	Stream	The handle of a target data stream module.
[in]	BufferCountToAcquire	The 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]	Stream	The handle of a target data stream module.
[in]	Timeout	Expected 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]	Stream	The handle of a target data stream module.
[in]	Timeout	Duration to wait for a new composite is acquired; the unit is the millisecond. Set -1 for infinite.
[in]	CancelationToken	A cancelation token to stop the ongoing acquisition process.
[out]	WaitStatus	Current status of the acquisition process.
[out]	Composite	An 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