light/2.0/types.hal

   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
  17 package android.hardware.light@2.0;
  18
  19 enum Status : int32_t {
  20     SUCCESS,
  21     LIGHT_NOT_SUPPORTED,
  22     BRIGHTNESS_NOT_SUPPORTED,
  23     UNKNOWN,
  24 };
  25
  26 enum 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
  43 enum 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  */
  86 enum 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  */
 105 struct 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 };