include/hardware/lights.h

   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