The Android Open Source Project | 65f2d3a | 2009-03-18 17:39:47 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2008 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 | |
| 17 | #ifndef ANDROID_LIGHTS_INTERFACE_H |
| 18 | #define ANDROID_LIGHTS_INTERFACE_H |
| 19 | |
| 20 | #include <stdint.h> |
| 21 | #include <sys/cdefs.h> |
| 22 | #include <sys/types.h> |
| 23 | |
| 24 | #include <hardware/hardware.h> |
| 25 | |
| 26 | __BEGIN_DECLS |
| 27 | |
| 28 | /** |
| 29 | * The id of this module |
| 30 | */ |
| 31 | #define LIGHTS_HARDWARE_MODULE_ID "lights" |
| 32 | |
Ruben Brunk | 0a99522 | 2015-12-15 15:42:11 -0800 | [diff] [blame] | 33 | /** |
| 34 | * Header file version. |
| 35 | */ |
| 36 | #define LIGHTS_HEADER_VERSION 1 |
| 37 | |
| 38 | /** |
| 39 | * Device API version 0.0-1.0 |
| 40 | * |
| 41 | * Base version for the device API in the lights HAL: all versions less than |
| 42 | * 2.0 are treated as being this version. |
| 43 | */ |
| 44 | #define LIGHTS_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION_2(1, 0, LIGHTS_HEADER_VERSION) |
| 45 | |
| 46 | /** |
| 47 | * Device API version 2.0 |
| 48 | * |
| 49 | * Devices reporting this version or higher may additionally support the |
| 50 | * following modes: |
| 51 | * - BRIGHTNESS_MODE_LOW_PERSISTENCE |
| 52 | */ |
| 53 | #define LIGHTS_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION_2(2, 0, LIGHTS_HEADER_VERSION) |
| 54 | |
The Android Open Source Project | 65f2d3a | 2009-03-18 17:39:47 -0700 | [diff] [blame] | 55 | /* |
| 56 | * These light IDs correspond to logical lights, not physical. |
| 57 | * So for example, if your INDICATOR light is in line with your |
| 58 | * BUTTONS, it might make sense to also light the INDICATOR |
| 59 | * light to a reasonable color when the BUTTONS are lit. |
| 60 | */ |
| 61 | #define LIGHT_ID_BACKLIGHT "backlight" |
| 62 | #define LIGHT_ID_KEYBOARD "keyboard" |
| 63 | #define LIGHT_ID_BUTTONS "buttons" |
| 64 | #define LIGHT_ID_BATTERY "battery" |
| 65 | #define LIGHT_ID_NOTIFICATIONS "notifications" |
| 66 | #define LIGHT_ID_ATTENTION "attention" |
| 67 | |
| 68 | /* |
| 69 | * These lights aren't currently supported by the higher |
| 70 | * layers, but could be someday, so we have the constants |
| 71 | * here now. |
| 72 | */ |
| 73 | #define LIGHT_ID_BLUETOOTH "bluetooth" |
| 74 | #define LIGHT_ID_WIFI "wifi" |
| 75 | |
| 76 | /* ************************************************************************ |
| 77 | * Flash modes for the flashMode field of light_state_t. |
| 78 | */ |
| 79 | |
| 80 | #define LIGHT_FLASH_NONE 0 |
| 81 | |
| 82 | /** |
| 83 | * To flash the light at a given rate, set flashMode to LIGHT_FLASH_TIMED, |
| 84 | * and then flashOnMS should be set to the number of milliseconds to turn |
| 85 | * the light on, followed by the number of milliseconds to turn the light |
| 86 | * off. |
| 87 | */ |
| 88 | #define LIGHT_FLASH_TIMED 1 |
| 89 | |
Dan Murphy | e00013c | 2009-07-21 08:56:12 -0500 | [diff] [blame] | 90 | /** |
Eric Olsen | a58556d | 2009-11-04 17:51:56 -0800 | [diff] [blame] | 91 | * To flash the light using hardware assist, set flashMode to |
| 92 | * the hardware mode. |
| 93 | */ |
| 94 | #define LIGHT_FLASH_HARDWARE 2 |
| 95 | |
| 96 | /** |
Mike Lockwood | baf2143 | 2009-11-10 07:51:33 -0500 | [diff] [blame] | 97 | * Light brightness is managed by a user setting. |
| 98 | */ |
| 99 | #define BRIGHTNESS_MODE_USER 0 |
| 100 | |
| 101 | /** |
| 102 | * Light brightness is managed by a light sensor. |
| 103 | */ |
| 104 | #define BRIGHTNESS_MODE_SENSOR 1 |
| 105 | |
| 106 | /** |
Ruben Brunk | 0a99522 | 2015-12-15 15:42:11 -0800 | [diff] [blame] | 107 | * Use a low-persistence mode for display backlights. |
| 108 | * |
| 109 | * When set, the device driver must switch to a mode optimized for low display |
| 110 | * persistence that is intended to be used when the device is being treated as a |
| 111 | * head mounted display (HMD). The actual display brightness in this mode is |
| 112 | * implementation dependent, and any value set for color in light_state may be |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 113 | * overridden by the HAL implementation. |
Ruben Brunk | 0a99522 | 2015-12-15 15:42:11 -0800 | [diff] [blame] | 114 | * |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 115 | * For an optimal HMD viewing experience, the display must meet the following |
Ruben Brunk | 0a99522 | 2015-12-15 15:42:11 -0800 | [diff] [blame] | 116 | * criteria in this mode: |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 117 | * - Gray-to-Gray, White-to-Black, and Black-to-White switching time must be ≤ 3 ms. |
| 118 | * - The display must support low-persistence with ≤ 3.5 ms persistence. |
| 119 | * Persistence is defined as the amount of time for which a pixel is |
| 120 | * emitting light for a single frame. |
Ruben Brunk | 0a99522 | 2015-12-15 15:42:11 -0800 | [diff] [blame] | 121 | * - Any "smart panel" or other frame buffering options that increase display |
| 122 | * latency are disabled. |
| 123 | * - Display brightness is set so that the display is still visible to the user |
| 124 | * under normal indoor lighting. |
Ruben Brunk | e0eb33f | 2016-05-02 19:29:57 -0700 | [diff] [blame] | 125 | * - The display must update at 60 Hz at least, but higher refresh rates are |
| 126 | * recommended for low latency. |
Ruben Brunk | 0a99522 | 2015-12-15 15:42:11 -0800 | [diff] [blame] | 127 | * |
| 128 | * This mode will only be used with light devices of type LIGHT_ID_BACKLIGHT, |
| 129 | * and will only be called by the Android framework for light_device_t |
| 130 | * implementations that report a version >= 2.0 in their hw_device_t common |
| 131 | * fields. If the device version is >= 2.0 and this mode is unsupported, calling |
| 132 | * set_light with this mode must return the negative error code -ENOSYS (-38) |
| 133 | * without altering any settings. |
| 134 | * |
| 135 | * Available only for version >= LIGHTS_DEVICE_API_VERSION_2_0 |
| 136 | */ |
| 137 | #define BRIGHTNESS_MODE_LOW_PERSISTENCE 2 |
| 138 | |
| 139 | /** |
The Android Open Source Project | 65f2d3a | 2009-03-18 17:39:47 -0700 | [diff] [blame] | 140 | * The parameters that can be set for a given light. |
| 141 | * |
| 142 | * Not all lights must support all parameters. If you |
| 143 | * can do something backward-compatible, you should. |
| 144 | */ |
| 145 | struct light_state_t { |
| 146 | /** |
| 147 | * The color of the LED in ARGB. |
| 148 | * |
| 149 | * Do your best here. |
| 150 | * - If your light can only do red or green, if they ask for blue, |
| 151 | * you should do green. |
| 152 | * - If you can only do a brightness ramp, then use this formula: |
| 153 | * unsigned char brightness = ((77*((color>>16)&0x00ff)) |
| 154 | * + (150*((color>>8)&0x00ff)) + (29*(color&0x00ff))) >> 8; |
| 155 | * - If you can only do on or off, 0 is off, anything else is on. |
| 156 | * |
| 157 | * The high byte should be ignored. Callers will set it to 0xff (which |
| 158 | * would correspond to 255 alpha). |
| 159 | */ |
| 160 | unsigned int color; |
| 161 | |
| 162 | /** |
| 163 | * See the LIGHT_FLASH_* constants |
| 164 | */ |
| 165 | int flashMode; |
| 166 | int flashOnMS; |
| 167 | int flashOffMS; |
Mike Lockwood | baf2143 | 2009-11-10 07:51:33 -0500 | [diff] [blame] | 168 | |
| 169 | /** |
| 170 | * Policy used by the framework to manage the light's brightness. |
| 171 | * Currently the values are BRIGHTNESS_MODE_USER and BRIGHTNESS_MODE_SENSOR. |
| 172 | */ |
| 173 | int brightnessMode; |
The Android Open Source Project | 65f2d3a | 2009-03-18 17:39:47 -0700 | [diff] [blame] | 174 | }; |
| 175 | |
| 176 | struct light_device_t { |
| 177 | struct hw_device_t common; |
| 178 | |
| 179 | /** |
| 180 | * Set the provided lights to the provided values. |
| 181 | * |
| 182 | * Returns: 0 on succes, error code on failure. |
| 183 | */ |
| 184 | int (*set_light)(struct light_device_t* dev, |
| 185 | struct light_state_t const* state); |
The Android Open Source Project | 65f2d3a | 2009-03-18 17:39:47 -0700 | [diff] [blame] | 186 | }; |
| 187 | |
| 188 | |
| 189 | __END_DECLS |
| 190 | |
| 191 | #endif // ANDROID_LIGHTS_INTERFACE_H |
| 192 | |