Skip to content

Commit e9970bf

Browse files
defold-servicesdefold-services
committed
Site changes [skip-ci]
1 parent ea8961c commit e9970bf

File tree

5 files changed

+280
-0
lines changed

5 files changed

+280
-0
lines changed

‎_data/extensions/extension-adpf_adpf.json

+169
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
{
2+
"elements": [
3+
{
4+
"description": "Initialise performance hints",
5+
"examples": "",
6+
"name": "adpf.hint.initialize",
7+
"parameters": [
8+
{
9+
"doc": "",
10+
"name": "target_fps_nanos",
11+
"types": [
12+
"number"
13+
]
14+
}
15+
],
16+
"returnvalues": [
17+
{
18+
"doc": "Return true if the PerformanceHintManager API is available on the device",
19+
"name": "boolean"
20+
}
21+
],
22+
"type": "FUNCTION"
23+
},
24+
{
25+
"description": "Update the target fps",
26+
"examples": "",
27+
"name": "adpf.hint.update_target_fps",
28+
"parameters": [
29+
{
30+
"doc": "",
31+
"name": "target_fps_nanos",
32+
"types": [
33+
"number"
34+
]
35+
}
36+
],
37+
"returnvalues": [],
38+
"type": "FUNCTION"
39+
},
40+
{
41+
"description": "Functions and constants for interacting with the PerformanceHintManager",
42+
"examples": "",
43+
"parameters": [],
44+
"returnvalues": [],
45+
"type": "TABLE"
46+
},
47+
{
48+
"description": "Initialise thermal",
49+
"examples": "",
50+
"name": "adpf.thermal.initialize",
51+
"parameters": [
52+
{
53+
"doc": "Return true if the Thermal API is available on the device",
54+
"name": "available",
55+
"types": [
56+
"boolean"
57+
]
58+
}
59+
],
60+
"returnvalues": [],
61+
"type": "FUNCTION"
62+
},
63+
{
64+
"description": "Provides an estimate of how much thermal headroom the device currently has before hitting severe throttling.",
65+
"examples": "",
66+
"name": "adpf.thermal.get_headroom",
67+
"parameters": [
68+
{
69+
"doc": "how many seconds in the future to forecast",
70+
"name": "forecast_seconds",
71+
"types": [
72+
"number"
73+
]
74+
}
75+
],
76+
"returnvalues": [
77+
{
78+
"doc": "a value greater than or equal to 0.0 where 1.0 indicates the SEVERE throttling threshold",
79+
"name": "number"
80+
}
81+
],
82+
"type": "FUNCTION"
83+
},
84+
{
85+
"description": "Get the current thermal status of the device",
86+
"examples": "",
87+
"name": "adpf.thermal.get_status",
88+
"parameters": [],
89+
"returnvalues": [
90+
{
91+
"doc": "The current thermal status of the device. One of THERMAL_STATUS_XYZ.",
92+
"name": "number"
93+
}
94+
],
95+
"type": "FUNCTION"
96+
},
97+
{
98+
"description": "Platform has done everything to reduce power.",
99+
"examples": "",
100+
"name": "THERMAL_STATUS_CRITICAL",
101+
"parameters": [],
102+
"returnvalues": [],
103+
"type": "VARIABLE"
104+
},
105+
{
106+
"description": "Key components in platform are shutting down due to thermal condition.",
107+
"examples": "",
108+
"name": "THERMAL_STATUS_EMERGENCY",
109+
"parameters": [],
110+
"returnvalues": [],
111+
"type": "VARIABLE"
112+
},
113+
{
114+
"description": "Light throttling where UX is not impacted.",
115+
"examples": "",
116+
"name": "THERMAL_STATUS_LIGHT",
117+
"parameters": [],
118+
"returnvalues": [],
119+
"type": "VARIABLE"
120+
},
121+
{
122+
"description": "Moderate throttling where UX is not largely impacted.",
123+
"examples": "",
124+
"name": "THERMAL_STATUS_MODERATE",
125+
"parameters": [],
126+
"returnvalues": [],
127+
"type": "VARIABLE"
128+
},
129+
{
130+
"description": "Not under throttling.",
131+
"examples": "",
132+
"name": "THERMAL_STATUS_NONE",
133+
"parameters": [],
134+
"returnvalues": [],
135+
"type": "VARIABLE"
136+
},
137+
{
138+
"description": "Severe throttling where UX is largely impacted.",
139+
"examples": "",
140+
"name": "THERMAL_STATUS_SEVERE",
141+
"parameters": [],
142+
"returnvalues": [],
143+
"type": "VARIABLE"
144+
},
145+
{
146+
"description": "Need shutdown immediately",
147+
"examples": "",
148+
"name": "THERMAL_STATUS_SHUTDOWN",
149+
"parameters": [],
150+
"returnvalues": [],
151+
"type": "VARIABLE"
152+
},
153+
{
154+
"description": "Functions and constants for interacting with the PowerManager ThermalAPI",
155+
"examples": "",
156+
"parameters": [],
157+
"returnvalues": [],
158+
"type": "TABLE"
159+
}
160+
],
161+
"info": {
162+
"api": "extension-adpf/adpf_api",
163+
"brief": "adpf",
164+
"description": "Functions and constants for interacting with the Android Device Performance Framework",
165+
"group": "EXTENSIONS",
166+
"name": "extension-adpf",
167+
"namespace": "adpf"
168+
}
169+
}

‎_data/refindex.json

+21
Original file line numberDiff line numberDiff line change
@@ -737,6 +737,27 @@
737737
"type": "extension",
738738
"url": "/extension-admob/admob_api"
739739
},
740+
{
741+
"branch": "alpha",
742+
"name": "extension-adpf",
743+
"namespace": "adpf",
744+
"type": "extension",
745+
"url": "/extension-adpf/adpf_api"
746+
},
747+
{
748+
"branch": "beta",
749+
"name": "extension-adpf",
750+
"namespace": "adpf",
751+
"type": "extension",
752+
"url": "/extension-adpf/adpf_api"
753+
},
754+
{
755+
"branch": "stable",
756+
"name": "extension-adpf",
757+
"namespace": "adpf",
758+
"type": "extension",
759+
"url": "/extension-adpf/adpf_api"
760+
},
740761
{
741762
"branch": "alpha",
742763
"name": "extension-camera",

‎extension-adpf/add-dependency.png

107 KB
Loading

‎extension-adpf/adpf_api.html

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
layout: api
3+
branch: stable
4+
ref: extension-adpf_adpf
5+
type: extension
6+
title: API reference (extension-adpf)
7+
---
8+
{% include anchor_headings.html html=content %}

‎extension-adpf/index.md

+82
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
layout: manual
3+
language: en
4+
github: https://github.com/defold/extension-adpf
5+
title: Android Device Performance Framework extension for Defold
6+
brief: This manual covers how to use the Android Device Performance Framework in Defold
7+
---
8+
9+
# Android Device Performance Framework extension for Defold
10+
11+
Android Dynamic Performance Framework (ADPF) is a set of APIs that allow games and to interact more directly with power and thermal systems of Android devices. It is possible to monitor the dynamic behavior on Android systems and optimize game performance at a sustainable level that doesn't overheat devices.
12+
13+
This extension currently support the following ADPF features:
14+
15+
* [Performance Hint API](https://developer.android.com/games/optimize/adpf/performance-hint-api)
16+
* [Thermal API](https://developer.android.com/games/optimize/adpf/thermal)
17+
18+
19+
## Installation
20+
To use ADPF in your Defold project, add a version of the ADPF extension to your `game.project` dependencies from the list of available [Releases](https://github.com/defold/extension-adpf/releases). Find the version you want, copy the URL to ZIP archive of the release and add it to the project dependencies.
21+
22+
![](add-dependency.png)
23+
24+
Select `Project->Fetch Libraries` once you have added the version to `game.project` to download the version and make it available in your project.
25+
26+
27+
## Usage
28+
29+
### Performance Hint API
30+
31+
With CPU performance hints, a game can influence dynamic CPU performance behavior to better match its needs. On most devices, Android dynamically adjusts the CPU clock speed and core type for a workload based on the previous demands. If a workload uses more CPU resources, the clock speed is increased and the workload is eventually moved to a larger core. If the workload uses less resources, then Android lowers resource allocation. With ADPF, the application or game can send an additional signal about its performance and deadlines. This helps the system ramp up more aggressively (improving performance) and lower the clocks quickly when the workload is complete (saving power usage).
32+
33+
The extension will create a `PerformanceHintManager` instance and a `PerformanceHintManager.Session` instance for the main thread only. The Defold extension system currently doesn't allow extensions to list and measure threads which the engine creates, for instance the audio and network threads.
34+
35+
```lua
36+
37+
-- initialize performance hint manager with a target FPS in nanosecond (60 fps)
38+
local available = adpf.hint.init((1 / 60) * 1000 * 1000)
39+
40+
-- update target FPS for the performance hint manager (30 fps)
41+
adpf.hint.update_target_fps((1 / 30) * 1000 * 1000)
42+
43+
-- the extension will automatically report actual work duration each frame
44+
```
45+
46+
47+
### Thermal API
48+
49+
The potential performance of your app is limited by the thermal state of the device, which can vary based on characteristics such as weather, recent usage, and the device's thermal design. Devices can only maintain a high level of performance for a limited amount of time before being thermally throttled. A key goal of your implementation should be to achieve performance goals without exceeding thermal limitations. Thermal API makes it possible without the need for device specific optimizations. Furthermore, when debugging performance issues, knowing if the thermal state of your device is limiting performance is important.
50+
51+
You can monitor the thermal state of the device by polling the `adpf.thermal.get_headroom()` function. This function predicts how long the device can maintain the current performance level without overheating. If the time is less than the amount needed to run the workload, then your game should decrease the workload to a sustainable level. For example, the game can reduce the frame rate using `adpf.hint.update_target_fps()`, or lower graphics fidelity.
52+
53+
54+
```lua
55+
-- initialize the extension to use the Thermal API
56+
local available = adp.thermal.init()
57+
if not available then
58+
print("Thermal API is not available")
59+
return
60+
end
61+
62+
-- get thermal status
63+
local status = adpf.thermal.get_status()
64+
65+
-- get thermal headroom forecast for 3 seconds ahead
66+
local headroom = adpf.thermal.get_headroom(3)
67+
```
68+
69+
70+
71+
## Example
72+
73+
[Refer to the example project](https://github.com/defold/extension-adpf/blob/master/example/example.script) to see a complete example of how the intergation works.
74+
75+
76+
## Source code
77+
78+
The source code is available on [GitHub](https://github.com/defold/extension-adpf)
79+
80+
81+
## API reference
82+
[API Reference - adpf](/extension-adpf/adpf_api)

0 commit comments

Comments
 (0)