Buffer handling

Enumerations
enum	peak_buffer_handling_mode {   PEAK_BUFFER_HANDLING_MODE_INVALID , PEAK_BUFFER_HANDLING_MODE_OLDEST_FIRST , PEAK_BUFFER_HANDLING_MODE_NEWEST_ONLY , PEAK_BUFFER_HANDLING_MODE_OLDEST_FIRST_SINGLE_BUFFER ,   PEAK_BUFFER_HANDLING_MODE_OLDEST_FIRST_DEPEND_ON_CAMERA_FIFO }
	peak buffer handling modes More...

Functions
peak_access_status	peak_Acquisition_BufferHandling_Mode_GetAccessStatus (peak_camera_handle hCam)
	Query the buffer handling mode access status.
peak_status	peak_Acquisition_BufferHandling_Mode_GetList (peak_camera_handle hCam, peak_buffer_handling_mode *bufferHandlingModeList, size_t *bufferHandlingModesCount)
	Get the list of currently usable buffer handling modes.
peak_status	peak_Acquisition_BufferHandling_Mode_Set (peak_camera_handle hCam, peak_buffer_handling_mode mode)
	Set the buffer handling mode.
peak_status	peak_Acquisition_BufferHandling_Mode_Get (peak_camera_handle hCam, peak_buffer_handling_mode *mode)
	Get the buffer handling mode.

Detailed Description

Buffer handling related functions and types.
Buffer handling mode of this Data Stream.

Enumeration Type Documentation

peak_buffer_handling_mode

enum peak_buffer_handling_mode

peak buffer handling modes

Enumerator
PEAK_BUFFER_HANDLING_MODE_INVALID	Invalid buffer handling mode. Use this value for the initialization of variables of type peak_buffer_handling_mode.
PEAK_BUFFER_HANDLING_MODE_OLDEST_FIRST	Oldest First Mode. The application always gets the buffer from the head of the Output Buffer Queue (thus, the oldest available one). If the Output Buffer Queue is empty, the application waits for a newly acquired buffer until the timeout expires. When data for a new buffer is available, the acquisition engine looks for any available buffer in the Input Buffer Pool, fills it, and appends it to the tail of the Output Buffer Queue. If the Input Buffer Pool is empty, the new data is dropped in the host. This results in an Underrun frame (a.k.a Lost frame). This buffer handling mode is typically used if every image frame is to be acquired and the mean processing time is lower than the acquisition time. No buffer is discarded or overwritten in the Output Buffer Queue and all filled buffers are delivered in the order they were acquired.
PEAK_BUFFER_HANDLING_MODE_NEWEST_ONLY	Newest Only Mode. The application always gets the latest completed buffer (the newest one). If the Output Buffer Queue is empty, the application waits for a newly acquired buffer until the timeout expires. This buffer handling mode is typically used in a live display GUI where it is important that there is no lag between camera and display.
PEAK_BUFFER_HANDLING_MODE_OLDEST_FIRST_SINGLE_BUFFER	Oldest First Single Buffer Mode. The application always gets the buffer from the head of the Output Buffer Queue (thus, the oldest available one). If the Output Buffer Queue is empty, the application waits for a newly acquired buffer until the timeout expires. When data for a new buffer is available, the acquisition engine looks for any available buffer in the Input Buffer Pool, fills it, and appends it to the tail of the Output Buffer Queue. If the Input Buffer Pool is empty, the acquisition engine stops receiving data until a buffer has been queued. This mode allows announcing one single buffer only. In this case there will be no double buffering in the transfer channel. This results in the camera dropping frames (Dropped Frames) if the camera has insufficient buffering capabilities. This buffer handling mode is typically used if the image frames are to be acquired to a predictable memory address. The mean processing time must be lower than the acquisition time. No buffer is discarded or overwritten in the Output Buffer Queue and all filled buffers are delivered in the order they were acquired.
PEAK_BUFFER_HANDLING_MODE_OLDEST_FIRST_DEPEND_ON_CAMERA_FIFO	Oldest First Depend On Camera FIFO Mode. The application always gets the buffer from the head of the Output Buffer Queue (thus, the oldest available one). If the Output Buffer Queue is empty, the application waits for a newly acquired buffer until the timeout expires. When data for a new buffer is available, the acquisition engine looks for any available buffer in the Input Buffer Pool, fills it, and appends it to the tail of the Output Buffer Queue. If the Input Buffer Pool is empty, the acquisition engine stops receiving data until a buffer has been queued. This results in the camera dropping frames (Dropped Frames) or discarding data (Incomplete Frames) if the camera has insufficient buffering capabilities. This buffer handling mode is typically used if every image frame is to be acquired and the mean processing time is lower than the acquisition time. No buffer is discarded or overwritten in the Output Buffer Queue and all filled buffers are delivered in the order they were acquired.

Function Documentation

peak_Acquisition_BufferHandling_Mode_Get()

peak_status peak_Acquisition_BufferHandling_Mode_Get	(	peak_camera_handle	hCam,
		peak_buffer_handling_mode *	mode
	)

Get the buffer handling mode.

Reads the current buffer handling mode.

Parameters

[in]	hCam	The camera handle.
[out]	mode	The buffer handling mode.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The buffer handling mode property is not available for write access. Check the access status of the buffer handling mode via peak_Acquisition_BufferHandling_Mode_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER mode 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.

peak_Acquisition_BufferHandling_Mode_GetAccessStatus()

peak_access_status peak_Acquisition_BufferHandling_Mode_GetAccessStatus

(

peak_camera_handle

hCam

)

Query the buffer handling mode access status.

Provides the current access status for the buffer handling mode.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The buffer handling mode property is readable and writeable.

PEAK_ACCESS_READONLY The buffer handling mode property can be applied only.

PEAK_ACCESS_WRITEONLY The buffer handling mode property can be stored only.

PEAK_ACCESS_GFA_LOCK The buffer handling mode property is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The buffer handling mode property is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The buffer handling mode property is not supported.

PEAK_ACCESS_INVALID The function failed. Call peak_Library_GetLastError to get the error code and description.

If the function indicates an error by returning PEAK_ACCESS_INVALID, these are the possible errors:

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

peak_Acquisition_BufferHandling_Mode_GetList()

peak_status peak_Acquisition_BufferHandling_Mode_GetList	(	peak_camera_handle	hCam,
		peak_buffer_handling_mode *	bufferHandlingModeList,
		size_t *	bufferHandlingModesCount
	)

Get the list of currently usable buffer handling modes.

Queries the list of currently selectable buffer handling modes.

The list of usable buffer handling modes may depend on the camera configuration and interface technology.

This function implements the Two Staged Data Query principle.

Parameters

[in]	hCam	The camera handle.
[out]	bufferHandlingModeList	Pointer to a user allocated array buffer to receive the buffer handling mode list. If this parameter is NULL, bufferHandlingModesCount will contain the current number of buffer handling modes. The required size of bufferHandlingModeList in bytes is bufferHandlingModesCount x sizeof(peak_buffer_handling_mode).
[in,out]	bufferHandlingModesCount	bufferHandlingModeList equal NULL: out: minimal number of buffer handling modes bufferHandlingModeList must be large enough to hold bufferHandlingModeList unequal NULL: in: number of buffer handling modes bufferHandlingModeList can hold out: number of buffer handling modes filled by the function

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_BUFFER_TOO_SMALL bufferHandlingModeList is not NULL and the value of *bufferHandlingModesCount is too small to receive the expected amount of data.

PEAK_STATUS_ACCESS_DENIED The buffer handling mode feature is not supported or the GFA write mode is enabled.

PEAK_STATUS_INVALID_PARAMETER bufferHandlingModesCount 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.

peak_Acquisition_BufferHandling_Mode_Set()

peak_status peak_Acquisition_BufferHandling_Mode_Set	(	peak_camera_handle	hCam,
		peak_buffer_handling_mode	mode
	)

Set the buffer handling mode.

Writes the desired buffer handling mode.

Parameters

[in]	hCam	The camera handle.
[in]	mode	The buffer handling mode to set.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The buffer handling mode property is not available for write access. Check the access status of the buffer handling mode via peak_Acquisition_BufferHandling_Mode_GetAccessStatus.

PEAK_STATUS_OUT_OF_RANGE mode is out of range. Check the range of valid values via peak_Acquisition_BufferHandling_Mode_GetList.

PEAK_STATUS_INVALID_PARAMETER mode is an invalid buffer handling mode. Check peak_buffer_handling_mode.

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.