xref: /aosp_15_r20/external/angle/src/android_system_settings/README.md (revision 8975f5c5ed3d1c378011245431ada316dfb6f244) 
1# ANGLE Settings UI
2
3## Introduction
4
5ANGLE Settings UI is a UI shipped as part of the ANGLE apk. The ANGLE apk can ship with a list rules
6of applications using different OpenGL ES driver. The UI provides two functionalities:
7
81) Enable to show a message when ANGLE is loaded into the launched application;
92) Allow to select driver choice in the UI for applications.
10
11## The rule file
12
13Currently the ANGLE apk supports two rules: ANGLE and native OpenGL ES driver.
14
15The rule file is a file that contains a JSON string, the format is shown below:
16
17```
18{
19    "rules":[
20        {
21            "description": "Applications in this list will use ANGLE",
22            "choice": "angle",
23            "apps": [
24                {
25                    "packageName": "com.android.example.a"
26                },
27                {
28                    "packageName": "com.android.example.b"
29                }
30            ]
31        },
32        {
33            "description": "Applications in this list will not use ANGLE",
34            "choice": "native",
35            "apps":[
36                {
37                    "packageName": "com.android.example.c"
38                }
39            ]
40        }
41    ]
42}
43```
44
45The ANGLE JSON rules are parsed only when `ACTION_BOOT_COMPLETED` or `ACTION_MY_PACKAGE_REPLACED` is
46received. After the JSON rules are parsed, the result will be stored in `SharedPreferences` as
47key-value pair, with the key being the package name and the value being the driver selection choice.
48The JSON parsing code is in `AngleRuleHelper`.
49
50After parsing, the rules are converted to global settings variables and applied to the system. This
51is done in `Receiver`.
52
53The UI logic is mainly in `MainFragment`, and the `GlobalSettings` is merely for manipulating
54settings global variables and updating `SharedPreferences`. When a user changes the driver choice
55of an application, the update will go into `GlobalSettings` and `SharedPreferences` respectively.
56
57The `SharedPreferences` is the source of truth and the code should always query the driver choice
58from it with the package name. The `SharedPreferences` should only be updated within
59`GlobalSettings` and `AngleRuleHelper`.
60
61The settings global variables may also be changed via `adb` command by the users, often time ANGLE
62for Android developers. Note that every time a boot event happens, it is expected that all previous
63values in settings global variables will be cleared and only values from the ANGLE JSON rule file
64will take effect.
65
66## Developer options
67
68The ANGLE Settings UI is registered as a dynamic setting entry in the development component via
69
70```
71<intent-filter>
72    <action android:name="com.android.settings.action.IA_SETTINGS" />
73</intent-filter>
74<meta-data android:name="com.android.settings.category"
75        android:value="com.android.settings.category.ia.development" />
76```
77
78And hence the UI shows up in Developer options. If the Developer options are disabled, all settings
79global variables will be cleared.
80