# get\_gpu\_headroom

Source: [https://docs.qualcomm.com/doc/80-PK177-134/topic/qape_get_gpu_headroom.html](https://docs.qualcomm.com/doc/80-PK177-134/topic/qape_get_gpu_headroom.html)

Returns the available average/minimum GPU headroom in percentage for last ‘duration’ seconds. The get\_gpu\_headroom() API is used by applications to get feedback on the historical application rendering workload to know if the workload is GPU bound on the SoC. The purpose of this API is to help provide GPU performance information for the application content and help drive the workload, and other APIs to ensure smooth and sustained UX performance (minimize frame drops, reduce UI sluggishness). The application can monitor thermal. If the mobile device is approaching thermal limits; it can further check if the workload is GPU bound to decide if reducing the GPU load helps to reduce thermal status (<= LIGHT) and hence improve sustained performance.

get_gpu_headroom()Copy to clipboard

Note: Mitigated maximum GPU frequency is considered for GPU headroom calculation when mitigated by thermal.

Note: This API is only applicable for Game because games are considered as GPU heavy use cases. For regular applications, this API returns -1.

## Parameters

| Parameter | API type | Data type | Description |
| --- | --- | --- | --- |
| duration | Java | int | Defines the time for last how many seconds information is needed. The maximum supported duration is 60 sec.<br><br><br>                <br>The valid range is 1 to 60. |
| duration | Native | uint8 | Defines the time for last how many seconds information is needed. The maximum supported duration is 60 sec.<br><br><br>                <br>The valid range is 1 to 60. |
| type | Java | boolean | There are two supported modes:<br><br><br>                <ul class="ul"><br>                  <li class="li">FALSE: Minimum GPU headroom in last duration sec.</li><br><br>                  <li class="li">TRUE: Average GPU headroom in last duration sec.</li><br><br>                </ul> |
| type | Native | bool | There are two supported modes:<br><br><br>                <ul class="ul"><br>                  <li class="li">FALSE: Minimum GPU headroom in last duration sec.</li><br><br>                  <li class="li">TRUE: Average GPU headroom in last duration sec.</li><br><br>                </ul> |
| ret\_val | Native | int8\_t& | On success this is the actual return value from the API.<br><br><br>                <br><ul class="ul"><br>                    <li class="li">≥ 0: Headroom</li><br><br>                    <li class="li">-1: Failed to request GPU headroom</li><br><br>                    <li class="li">-2: Failed to establish session; call <a href="https://docs.qualcomm.com/doc/80-PK177-134/topic/qape_set_pkg.html">set_pkg</a> before this API </li><br><br>                  </ul> |
|  |  |  |  |

## Returns

| Return | API type | Data type | Description |
| --- | --- | --- | --- |
| response | Java | int | <ul class="ul"><br>                  <li class="li">≥ 0: Headroom</li><br><br>                  <li class="li">-1: Failed to request GPU headroom</li><br><br>                  <li class="li">-2: Failed to establish session; call <a href="https://docs.qualcomm.com/doc/80-PK177-134/topic/qape_set_pkg.html">set_pkg</a><br>                    before this API </li><br><br>                </ul> |
| response | Native | qesdk\_transaction\_status | See [QESDK transaction status for Native APIs](https://docs.qualcomm.com/doc/80-PK177-134/topic/native_qesdk_class.html) for usage details. Use qesdk\_transaction\_status to confirm API call invocation. If successful, use the `ret` value for the actual API return value object. |
|  |  |  |  |

**Parent Topic:** [QAPE subsystem APIs](https://docs.qualcomm.com/doc/80-PK177-134/topic/qape_apis.html)

Last Published: Nov 14, 2024

[Previous Topic
boost\_gpu](https://docs.qualcomm.com/bundle/publicresource/80-PK177-134/topics/qape_boost_gpu.md) [Next Topic
hint\_low\_latency](https://docs.qualcomm.com/bundle/publicresource/80-PK177-134/topics/qape_hint_low_latency.md)