1/*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.hardware.light@2.0;
18
19enum Status : int32_t {
20    SUCCESS,
21    LIGHT_NOT_SUPPORTED,
22    BRIGHTNESS_NOT_SUPPORTED,
23    UNKNOWN,
24};
25
26enum Flash : int32_t {
27    /**
28     * Keep the light steady on or off.
29     */
30    NONE,
31
32    /**
33     * Flash the light at specified rate.
34     */
35    TIMED,
36
37    /**
38     * Flash the light using hardware assist.
39     */
40    HARDWARE,
41};
42
43enum Brightness : int32_t {
44    /**
45     * Light brightness is managed by a user setting.
46     */
47    USER,
48
49    /**
50     * Light brightness is managed by a light sensor.
51     */
52    SENSOR,
53
54    /**
55     * Use a low-persistence mode for display backlights.
56     *
57     * When set, the device driver must switch to a mode optimized for low display
58     * persistence that is intended to be used when the device is being treated as a
59     * head mounted display (HMD). The actual display brightness in this mode is
60     * implementation dependent, and any value set for color in LightState may be
61     * overridden by the HAL implementation.
62     *
63     * For an optimal HMD viewing experience, the display must meet the following
64     * criteria in this mode:
65     * - Gray-to-Gray, White-to-Black, and Black-to-White switching time must be ≤ 3 ms.
66     * - The display must support low-persistence with ≤ 3.5 ms persistence.
67     *   Persistence is defined as the amount of time for which a pixel is
68     *   emitting light for a single frame.
69     * - Any "smart panel" or other frame buffering options that increase display
70     *   latency are disabled.
71     * - Display brightness is set so that the display is still visible to the user
72     *   under normal indoor lighting.
73     * - The display must update at 60 Hz at least, but higher refresh rates are
74     *   recommended for low latency.
75     *
76     */
77    LOW_PERSISTENCE,
78};
79
80/**
81 * These light IDs correspond to logical lights, not physical.
82 * So for example, if your INDICATOR light is in line with your
83 * BUTTONS, it might make sense to also light the INDICATOR
84 * light to a reasonable color when the BUTTONS are lit.
85 */
86enum Type : int32_t {
87    BACKLIGHT,
88    KEYBOARD,
89    BUTTONS,
90    BATTERY,
91    NOTIFICATIONS,
92    ATTENTION,
93    BLUETOOTH,
94    WIFI,
95
96    COUNT,
97};
98
99/**
100 * The parameters that can be set for a given light.
101 *
102 * Not all lights must support all parameters. If you
103 * can do something backward-compatible, do it.
104 */
105struct LightState {
106    /**
107     * The color of the LED in ARGB.
108     *
109     * Do your best here.
110     *   - If your light can only do red or green, if they ask for blue,
111     *     you should do green.
112     *   - If you can only do a brightness ramp, then use this formula:
113     *      unsigned char brightness = ((77*((color>>16)&0x00ff))
114     *              + (150*((color>>8)&0x00ff)) + (29*(color&0x00ff))) >> 8;
115     *   - If you can only do on or off, 0 is off, anything else is on.
116     *
117     * The high byte should be ignored. Callers will set it to 0xff (which
118     * would correspond to 255 alpha).
119     */
120    uint32_t color;
121
122    /**
123     * To flash the light at a given rate, set flashMode to LIGHT_FLASH_TIMED,
124     * and then flashOnMS should be set to the number of milliseconds to turn
125     * the light on, followed by the number of milliseconds to turn the light
126     * off.
127     */
128    Flash flashMode;
129
130    int32_t flashOnMs;
131    int32_t flashOffMs;
132
133    Brightness brightnessMode;
134};
135