Bandwidth

Bandwidth related functions and types. More...

Topics
	Link speed constants
	Common constants for the link speed.

Functions
peak_access_status	peak_Bandwidth_LinkSpeed_GetAccessStatus (peak_camera_handle hCam)
	Query the link speed access status.
peak_status	peak_Bandwidth_LinkSpeed_Get (peak_camera_handle hCam, int64_t *linkSpeed_Bps)
	Get the link speed.
peak_access_status	peak_Bandwidth_ThroughputLimit_GetAccessStatus (peak_camera_handle hCam)
	Query the throughput limit access status.
peak_status	peak_Bandwidth_ThroughputLimit_GetRange (peak_camera_handle hCam, int64_t *minThroughputLimit_Bps, int64_t *maxThroughputLimit_Bps, int64_t *incThroughputLimit_Bps)
	Get the current range of valid throughput limit values.
peak_status	peak_Bandwidth_ThroughputLimit_Set (peak_camera_handle hCam, int64_t throughputLimit_Bps)
	Set the throughput limit.
peak_status	peak_Bandwidth_ThroughputLimit_Get (peak_camera_handle hCam, int64_t *throughputLimit_Bps)
	Get the throughput limit.
peak_access_status	peak_Bandwidth_ThroughputFrameRateLimit_GetAccessStatus (peak_camera_handle hCam)
	Query the throughput frame rate limit access status.
peak_status	peak_Bandwidth_ThroughputFrameRateLimit_Get (peak_camera_handle hCam, double *throughputFrameRateLimit_fps)
	Get the throughput frame rate limit.
peak_access_status	peak_Bandwidth_ThroughputCalculated_GetAccessStatus (peak_camera_handle hCam)
	Query the throughput calculated access status.
peak_status	peak_Bandwidth_ThroughputCalculated_Get (peak_camera_handle hCam, int64_t *throughputCalculated_Bps)
	Get the throughput calculated.

Detailed Description

Bandwidth related functions and types.

Bandwidth control involves regulating the rate at which data is transferred from the camera to the host, ensuring that the data does not exceed the network's capacity, and optimizing performance to prevent issues like data congestion, frame loss, and latency. This is essential for maintaining precise image capture and smooth operation in industrial applications.

Note

For each sub feature the corresponding AccessStatus functions should be called first, as not all camera types support each sub feature.

Link Speed

The maximum data transfer rate negotiated between the camera and the network after connection. It helps determine if the camera is connected via SuperSpeed or Hi-Speed USB for USB cameras or the network speed for ethernet cameras.

The following example shows how to check the camera link speed and compare it with the nominal interface speed.

const peak_access_status access = peak_Bandwidth_LinkSpeed_GetAccessStatus(hCam);
if (!PEAK_IS_READABLE(access))
{
    return;
}
 
int64_t linkSpeed = 0;
peak_status status = peak_Bandwidth_LinkSpeed_Get(hCam, &linkSpeed);
if (PEAK_ERROR(status))
{
    return;
}
 
peak_camera_descriptor descriptor = { 0 };
status = peak_Camera_GetDescriptor(peak_Camera_ID_FromHandle(hCam), &descriptor);
if (PEAK_ERROR(status))
{
    return;
}
 
if (descriptor.cameraType == PEAK_CAMERA_TYPE_UEYE_USB || descriptor.cameraType == PEAK_CAMERA_TYPE_UEYE_PLUS_U3V)
{
    if (linkSpeed < PEAK_LINKSPEED_USB3_SUPER_SPEED)
    {
        // camera running with USB 2 HighSpeed or lower
    }
    else
    {
        // camera running with USB 3 SuperSpeed or higher
    }
}
else if (descriptor.cameraType == PEAK_CAMERA_TYPE_UEYE_ETH || descriptor.cameraType == PEAK_CAMERA_TYPE_UEYE_PLUS_GEV)
{
    if (linkSpeed < PEAK_LINKSPEED_ETH_1G)
    {
        // camera running with 100 Mbit/s or lower
    }
    else
    {
        // camera running with 1 Gbit/s or higher
    }
}

Throughput

The throughput has the following parameters:

ThroughputFrameRateLimit

Specifies the maximum frame rate achievable with the bandwidth set by ThroughputLimit.

ThroughputCalculated

The calculated theoretical bandwidth for the data stream based on current settings, but actual bandwidth is limited by the ThroughputLimit.

ThroughputLimit

Sets an upper limit to the bandwidth for data sent from the camera. For GigE Vision cameras, it calculates packet delays and the maximum achievable frame rate. For USB 3 cameras, it can make data transfer via USB2 possible but may reduce sensor readout speed and increase rolling shutter effects, especially with high image widths. In general, using the ThroughputLimit allows precise and intuitive bandwidth control, ensuring optimal data transfer rates while balancing performance and stability.

Note

It is advised to reserve a small portion of bandwidth for packet resends and commands on the control channel.

The following sample sets the throughput limit to half the possible value and sets the corresponding framerate if it is supported by the camera model:

peak_access_status access = peak_Bandwidth_ThroughputLimit_GetAccessStatus(hCam);
if (access != PEAK_ACCESS_READWRITE)
{
    return;
}
 
int64_t min = 0, max = 0, inc = 0;
peak_status status = peak_Bandwidth_ThroughputLimit_GetRange(hCam, &min, &max, &inc);
if (PEAK_ERROR(status))
{
    return;
}
 
int64_t halfValue = max / 2;
halfValue -= halfValue % inc;
 
status = peak_Bandwidth_ThroughputLimit_Set(hCam, halfValue);
if (PEAK_ERROR(status))
{
    return;
}
 
access = peak_Bandwidth_ThroughputFrameRateLimit_GetAccessStatus(hCam);
if (PEAK_IS_READABLE(access))
{
    double maxFrameRate = 0.0;
    status = peak_Bandwidth_ThroughputFrameRateLimit_Get(hCam, &maxFrameRate);
    if (PEAK_ERROR(status))
    {
        return;
    }
    status = peak_FrameRate_Set(hCam, maxFrameRate * 0.95);
    if (PEAK_ERROR(status))
    {
        return;
    }
}

Function Documentation

peak_Bandwidth_LinkSpeed_Get()

peak_status peak_Bandwidth_LinkSpeed_Get	(	peak_camera_handle	hCam,
		int64_t *	linkSpeed_Bps )

Get the link speed.

Read the maximum data transfer rate negotiated between the camera and the network after connection. For a list of possible values see Link speed constants.

This value is informative only and shouldn't be set with peak_Bandwidth_ThroughputLimit_Set

Parameters

[in]	hCam	The camera handle.
[out]	linkSpeed_Bps	The link speed in bytes per second.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The link speed control is not available for read access. Check the access status via peak_Bandwidth_LinkSpeed_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER linkSpeed_Bps 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_Bandwidth_LinkSpeed_GetAccessStatus()

peak_access_status peak_Bandwidth_LinkSpeed_GetAccessStatus

(

peak_camera_handle

hCam

)

Query the link speed access status.

Provides the current access status for the link speed control.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The link speed control is readable and writeable.

PEAK_ACCESS_READONLY The link speed control is readable only.

PEAK_ACCESS_GFA_LOCK The link speed control is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The link speed control is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The link speed control 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_Bandwidth_ThroughputCalculated_Get()

peak_status peak_Bandwidth_ThroughputCalculated_Get	(	peak_camera_handle	hCam,
		int64_t *	throughputCalculated_Bps )

Get the throughput calculated.

The calculated theoretical bandwidth for the data stream based on current settings, but actual bandwidth is limited by the ThroughputLimit.

Parameters

[in]	hCam	The camera handle.
[out]	throughputCalculated_Bps	The throughput calculated in bytes per second.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The throughput calculated control is not available for read access. Check the access status via peak_Bandwidth_ThroughputCalculated_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER throughputCalculated_Bps 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_Bandwidth_ThroughputCalculated_GetAccessStatus()

peak_access_status peak_Bandwidth_ThroughputCalculated_GetAccessStatus

(

peak_camera_handle

hCam

)

Query the throughput calculated access status.

Provides the current access status for the throughput calculated control.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The throughput calculated control is readable and writeable.

PEAK_ACCESS_READONLY The throughput calculated control is readable only.

PEAK_ACCESS_GFA_LOCK The throughput calculated control is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The throughput calculated control is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The throughput calculated control 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_Bandwidth_ThroughputFrameRateLimit_Get()

peak_status peak_Bandwidth_ThroughputFrameRateLimit_Get	(	peak_camera_handle	hCam,
		double *	throughputFrameRateLimit_fps )

Get the throughput frame rate limit.

Specifies the maximum frame rate achievable with the bandwidth set by ThroughputLimit.

Parameters

[in]	hCam	The camera handle.
[out]	throughputFrameRateLimit_fps	The throughput frame rate limit in frames per second.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The throughput frame rate limit control is not available for read access. Check the access status via peak_Bandwidth_ThroughputFrameRateLimit_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER throughputFrameRateLimit_Bps 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_Bandwidth_ThroughputFrameRateLimit_GetAccessStatus()

peak_access_status peak_Bandwidth_ThroughputFrameRateLimit_GetAccessStatus

(

peak_camera_handle

hCam

)

Query the throughput frame rate limit access status.

Provides the current access status for the throughput frame rate limit control.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The throughput frame rate limit control is readable and writeable.

PEAK_ACCESS_READONLY The throughput frame rate limit control is readable only.

PEAK_ACCESS_GFA_LOCK The throughput frame rate limit control is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The throughput frame rate limit control is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The throughput frame rate limit control 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_Bandwidth_ThroughputLimit_Get()

peak_status peak_Bandwidth_ThroughputLimit_Get	(	peak_camera_handle	hCam,
		int64_t *	throughputLimit_Bps )

Get the throughput limit.

Gets the current upper limit to the bandwidth for data sent from the camera.

Parameters

[in]	hCam	The camera handle.
[out]	throughputLimit_Bps	The throughput limit in bytes per second.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The throughput limit control is not available for read access. Check the access status via peak_Bandwidth_ThroughputLimit_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER throughputLimit_Bps 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_Bandwidth_ThroughputLimit_GetAccessStatus()

peak_access_status peak_Bandwidth_ThroughputLimit_GetAccessStatus

(

peak_camera_handle

hCam

)

Query the throughput limit access status.

Provides the current access status for the throughput limit control.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The throughput limit control is readable and writeable.

PEAK_ACCESS_READONLY The throughput limit control is readable only.

PEAK_ACCESS_GFA_LOCK The throughput limit control is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The throughput limit control is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The throughput limit control 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_Bandwidth_ThroughputLimit_GetRange()

peak_status peak_Bandwidth_ThroughputLimit_GetRange	(	peak_camera_handle	hCam,
		int64_t *	minThroughputLimit_Bps,
		int64_t *	maxThroughputLimit_Bps,
		int64_t *	incThroughputLimit_Bps )

Get the current range of valid throughput limit values.

Queries the range of valid values for the throughput limit control.

The range of valid throughput limit values may depend on the camera configuration and the camera status.

Parameters

[in]	hCam	The camera handle.
[out]	minThroughputLimit_Bps	The minimum throughput limit in bytes per second.
[out]	maxThroughputLimit_Bps	The maximum throughput limit in bytes per second.
[out]	incThroughputLimit_Bps	The throughput limit increment in bytes per second.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The throughput limit control is not accessible. Check the access status via peak_Bandwidth_ThroughputLimit_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER At least one of minThroughputLimit_Bps, maxThroughputLimit_Bps, and incThroughputLimit_Bps 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_Bandwidth_ThroughputLimit_Set()

peak_status peak_Bandwidth_ThroughputLimit_Set	(	peak_camera_handle	hCam,
		int64_t	throughputLimit_Bps )

Set the throughput limit.

Sets the upper limit for the bandwidth used for data sent from the camera. The possible range can be retrieved by calling peak_Bandwidth_ThroughputLimit_GetRange.

Parameters

[in]	hCam	The camera handle.
[in]	throughputLimit_Bps	The throughput limit to set in bytes per second.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_VALUE_ADJUSTED Value was automatically adjusted.

PEAK_STATUS_OUT_OF_RANGE throughputLimit_Bps is out of range. Check the range of valid values via peak_Bandwidth_ThroughputLimit_GetRange.

PEAK_STATUS_ACCESS_DENIED The throughput limit control is not available for write access. Check the access status via peak_Bandwidth_ThroughputLimit_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