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 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 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 90 /** 91 * To flash the light using hardware assist, set flashMode to 92 * the hardware mode. 93 */ 94 #define LIGHT_FLASH_HARDWARE 2 95 96 /** 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 /** 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 113 * overridden by the HAL implementation. 114 * 115 * For an optimal HMD viewing experience, the display must meet the following 116 * criteria in this mode: 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. 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. 125 * - The display must update at 60 Hz at least, but higher refresh rates are 126 * recommended for low latency. 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 /** 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; 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; 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); 186 }; 187 188 189 __END_DECLS 190 191 #endif // ANDROID_LIGHTS_INTERFACE_H 192 193