BlackLevel

Controls the analog black level. More...

Functions
peak_access_status	peak_BlackLevel_Auto_GetAccessStatus (peak_camera_handle hCam)
	Query black level auto access status.
peak_status	peak_BlackLevel_Auto_Enable (peak_camera_handle hCam, peak_bool enable)
	Set the black level auto enable state.
peak_bool	peak_BlackLevel_Auto_IsEnabled (peak_camera_handle hCam)
	Get the black level auto enable state.
peak_access_status	peak_BlackLevel_Offset_GetAccessStatus (peak_camera_handle hCam)
	Query black level offset access status.
peak_status	peak_BlackLevel_Offset_Set (peak_camera_handle hCam, double offset)
	Set the black level offset.
peak_status	peak_BlackLevel_Offset_Get (peak_camera_handle hCam, double *offset)
	Get the current black level offset.
peak_status	peak_BlackLevel_Offset_GetRange (peak_camera_handle hCam, double *min, double *max, double *inc)
	Get the range for the black level offset.

Detailed Description

Controls the analog black level.

This feature is only applied in the camera.

The black level is an offset that is applied to all pixel values. To set the offset manually, the black level auto must be disabled with peak_BlackLevel_Auto_Enable. Some cameras also support adding a manual offset to the automatic black level. For these, the peak_BlackLevel_Offset_GetAccessStatus status stays PEAK_ACCESS_READWRITE even after enabling black level auto with peak_BlackLevel_Auto_Enable.

Note

It is advised to set the desired black level value again after changing the pixel format, as some cameras will change the range automatically to the new pixel depth.

For some cameras, this also applies after black level auto has been enabled.

Example to use the black level feature:

peak_access_status accessStatus = peak_BlackLevel_Auto_GetAccessStatus(hCam);
if (PEAK_IS_READABLE(accessStatus))
{
    peak_bool enabled = peak_BlackLevel_Auto_IsEnabled(hCam);
    if (enabled)
    {
        // do something
    }
}
if (PEAK_IS_WRITEABLE(accessStatus))
{
    // Enable
    peak_status status = peak_BlackLevel_Auto_Enable(hCam, PEAK_TRUE);
    if (PEAK_ERROR(status))
    {
        // handle error
    }
}
 
accessStatus = peak_BlackLevel_Offset_GetAccessStatus(hCam);
if (PEAK_IS_READABLE(accessStatus))
{
    double blackLevel = 0.0;
    peak_status status = peak_BlackLevel_Offset_Get(hCam, &blackLevel);
    if (PEAK_ERROR(status))
    {
        // handle error
    }
    // do something with black level offset
}
 
if (PEAK_IS_WRITEABLE(accessStatus))
{
    double blackLevelMin = 0.0, blackLevelMax = 0.0, blackLevelInc = 0.0;
    peak_status status = peak_BlackLevel_Offset_GetRange(hCam, &blackLevelMin, &blackLevelMax, &blackLevelInc);
    if (PEAK_ERROR(status))
    {
        // handle error
    }
 
    // Set max
    status = peak_BlackLevel_Offset_Set(hCam, blackLevelMax);
    if (PEAK_ERROR(status))
    {
        // handle error
    }
}
 

Function Documentation

peak_BlackLevel_Auto_Enable()

peak_status peak_BlackLevel_Auto_Enable	(	peak_camera_handle	hCam,
		peak_bool	enable )

Set the black level auto enable state.

Sets the auto black level to active / inactive.

Depending on the camera model the access status of black level auto may change. Check with peak_BlackLevel_Auto_GetAccessStatus.

Parameters

[in]	hCam	The camera handle.
[in]	enable	The auto state to set.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The black level auto property is not available for read access. Check the access status of the black level Auto via peak_BlackLevel_Auto_GetAccessStatus.

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.

Since

1.11

peak_BlackLevel_Auto_GetAccessStatus()

peak_access_status peak_BlackLevel_Auto_GetAccessStatus

(

peak_camera_handle

hCam

)

Query black level auto access status.

Provides the current access status for the black level auto feature. Depending on the camera model the access status of black level auto may change.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The black level auto feature is readable and writeable.

PEAK_ACCESS_GFA_LOCK The black level auto feature is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The black level auto feature is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The black level auto feature 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.

Since

1.11

peak_BlackLevel_Auto_IsEnabled()

peak_bool peak_BlackLevel_Auto_IsEnabled

(

peak_camera_handle

hCam

)

Get the black level auto enable state.

Queries whether the black level auto feature is currently enabled or disabled.

This function implements the Enabled Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_TRUE The black level auto feature is currently enabled.

PEAK_FALSE The black level auto feature is currently disabled or the query failed.

Since

1.11

peak_BlackLevel_Offset_Get()

peak_status peak_BlackLevel_Offset_Get	(	peak_camera_handle	hCam,
		double *	offset )

Get the current black level offset.

The offset may change when changing the pixel format of the camera.

Parameters

[in]	hCam	The camera handle.
[out]	offset	The current black level value.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The black level offset property is not available for read access. Check the access status of the black level offset via peak_BlackLevel_Offset_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER *offset 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.

Since

1.11

peak_BlackLevel_Offset_GetAccessStatus()

peak_access_status peak_BlackLevel_Offset_GetAccessStatus

(

peak_camera_handle

hCam

)

Query black level offset access status.

Provides the current access status for the black level offset feature. Depending on the camera model the access status of the black level offset may change.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The black level offset feature is readable and writeable.

PEAK_ACCESS_GFA_LOCK The black level offset feature is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The black level offset feature is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The black level offset feature 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.

Since

1.11

peak_BlackLevel_Offset_GetRange()

peak_status peak_BlackLevel_Offset_GetRange	(	peak_camera_handle	hCam,
		double *	min,
		double *	max,
		double *	inc )

Get the range for the black level offset.

Query the possible range for the black level offset. The range may change after a pixel format change, so it is advised to read it again before setting a new value with peak_BlackLevel_Offset_Set.

Parameters

[in]	hCam	The camera handle.
[out]	min	The minimum black level offset.
[out]	max	The maximum black level offset.
[out]	inc	The increment black level offset.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The black level offset property is not available for read access. Check the access status of the black level offset via peak_BlackLevel_Offset_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER *min, *max or *inc 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.

Since

1.11

peak_BlackLevel_Offset_Set()

peak_status peak_BlackLevel_Offset_Set	(	peak_camera_handle	hCam,
		double	offset )

Set the black level offset.

The offset may change when changing the pixel format of the camera. If peak_BlackLevel_Auto_IsEnabled is PEAK_TRUE, the value might not be changeable. This can be verified by a call to peak_BlackLevel_Offset_GetAccessStatus.

Parameters

[in]	hCam	The camera handle.
[in]	offset	The black level offset to set.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The black level offset property is not available for read access. Check the access status of the black level offset via peak_BlackLevel_Offset_GetAccessStatus.

PEAK_STATUS_OUT_OF_RANGE offset is out of range. Check the range of valid values via peak_BlackLevel_Offset_GetRange.

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.

Since

1.11