Acquisition and buffer preparation

Modules
	Manual buffer preparation

Data Structures
struct	peak_acquisition_info
	peak Acquisition info More...

Functions
peak_status	peak_Acquisition_Start (peak_camera_handle hCam, uint32_t numberOfFrames)
	Start an acquisition. More...
peak_status	peak_Acquisition_Stop (peak_camera_handle hCam)
	Stops an acquisition. More...
peak_bool	peak_Acquisition_IsStarted (peak_camera_handle hCam)
	Check whether the acquisition is currently started or not. More...
peak_status	peak_Acquisition_WaitForFrame (peak_camera_handle hCam, uint32_t timeout_ms, peak_frame_handle *hFrame)
	Wait for an acquired frame. More...
peak_status	peak_Acquisition_GetInfo (peak_camera_handle hCam, peak_acquisition_info *acquisitionInfo)
	Query the acquisition info. More...

Detailed Description

Acquisition and buffer preparation related functions and types.

For a description of the libraries buffer preparation concept see Buffer Preparation.

Function Documentation

peak_Acquisition_GetInfo()

peak_status peak_Acquisition_GetInfo	(	peak_camera_handle	hCam,
		peak_acquisition_info *	acquisitionInfo
	)

Query the acquisition info.

Provides the status of the current acquisition session or, if there is no active acquisition at the time of the call, of the last acquisition session, if any.

Parameters

[in]	hCam	The camera handle.
[out]	acquisitionInfo	The acquisition info.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER acquisitionInfo is an invalid pointer.

PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.

PEAK_STATUS_ACCESS_DENIED There has been no acquisition session yet.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

peak_Acquisition_IsStarted()

peak_bool peak_Acquisition_IsStarted

(

peak_camera_handle

hCam

)

Check whether the acquisition is currently started or not.

Checks whether the acquisition is currently started or not.

This function implements the Valid Values Organization Query principle.

Parallel calls to peak_Acquisition_IsStarted return true until the blocking peak_Acquisition_Stop returns!

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_TRUE The acquisition is currently started.

PEAK_FALSE The acquisition is currently not started or the query failed.

peak_Acquisition_Start()

peak_status peak_Acquisition_Start	(	peak_camera_handle	hCam,
		uint32_t	numberOfFrames
	)

Start an acquisition.

Starts an acquisition session for the specified number of frames.

The acquisition can be stopped at any time via peak_Acquisition_Stop.
If numberOfFrames is not PEAK_INFINITE the acquisition is automatically stopped when the specified number of frames has been acquired.

Parameters

[in]	hCam	The camera handle.
[in]	numberOfFrames	The number of frames to acquire. PEAK_INFINITE for infinite.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED There is already a running acquisition or the camera does not provide a data stream or not all frames from a previous acquisition have been released.

PEAK_STATUS_INVALID_CONFIGURATION Only relevant in the Manual Buffer Preparation mode.
The buffers are not sufficiently sized to receive the image data that results from the current image properties (see peak_Acquisition_Buffer_GetRequiredSize) or the number of announced buffers is not sufficient to run an efficient data transfer (see peak_Acquisition_Buffer_GetRequiredCount).

PEAK_STATUS_INVALID_PARAMETER numberOfFrames is 0.

PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Note

Make sure that you have completed the configuration of all features, which have an impact on the image size, before you call peak_Acquisition_Start.

The library will automatically stop the acquisition when the number of requested frames has been received. This automatic acquisition stop is run asynchronously to have peak_Acquisition_WaitForFrame return the last frame without any delay. In order to be sure that a finite acquisition sequence is stopped, call peak_Acquisition_Stop, which will block until the acquisition has been stopped. As some features are not accessible while an acquisition is running, this is useful to synchronize the applications control flow with the libraries internal status.

The acquisition can not be started if there are any unreleased frames from an earlier acquisition sequence.

If you decide upon Manual Buffer Preparation make sure that all buffers are allocated and announced before you call peak_Acquisition_Start. The buffer memory must be valid for the time the acquisition runs.

peak_Acquisition_Stop()

peak_status peak_Acquisition_Stop

(

peak_camera_handle

hCam

)

Stops an acquisition.

Stops an acquisition before the number of frames that was specified for peak_Acquisition_Start has been acquired.

The acquisition is stopped immediately. If there is a frame in transmission at the time peak_Acquisition_Stop is called, this frame is discarded.

All pending calls to peak_Acquisition_WaitForFrame will immediately return with PEAK_STATUS_ABORTED.

This function will always block until the acquisition has actually been stopped.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Note

This function will return PEAK_STATUS_SUCCESS if there is no running acquisition.

peak_Acquisition_WaitForFrame()

peak_status peak_Acquisition_WaitForFrame	(	peak_camera_handle	hCam,
		uint32_t	timeout_ms,
		peak_frame_handle *	hFrame
	)

Wait for an acquired frame.

Delivers the oldest acquired frame.

The implementation queues the acquired frames in chronological order for delivery to the client application. peak_Acquisition_WaitForFrame delivers the oldest queued frame.

A frame that was received from peak_Acquisition_WaitForFrame is considered as 'delivered'.
The buffer that is bound to a delivered frame is locked for the reception of incoming image data until peak_Frame_Release has been called for the frame.
peak_Acquisition_Start will be rejected as long as there are unreleased frame handles for frames that were received from peak_Acquisition_WaitForFrame.

If there is no frame in the delivery queue by the time of the call the function blocks until a frame was acquired or the specified timeout has elapsed.

A pending call returns with PEAK_STATUS_ABORTED when the acquisition is stopped (automatically or by a call to peak_Acquisition_Stop).

Parameters

[in]	hCam	The camera handle.
[in]	timeout_ms	The wait timeout in milliseconds. PEAK_INFINITE for infinite.
[out]	hFrame	Handle to the acquired frame.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_TIMEOUT The wait timeout has elapsed and no frame has been acquired.

PEAK_STATUS_ABORTED The wait was abandoned because the acquisition was stopped.

PEAK_STATUS_ACCESS_DENIED There is no running acquisition.

PEAK_STATUS_INVALID_PARAMETER timeout_ms is 0 or hFrame is an invalid pointer.

PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.