1 /**
2  * Copyright (C) 2020 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.lights;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 import android.annotation.Nullable;
22 import android.annotation.TestApi;
23 import android.os.Parcel;
24 import android.os.Parcelable;
25 
26 import java.lang.annotation.Retention;
27 import java.lang.annotation.RetentionPolicy;
28 
29 /**
30  * Represents a logical light on the device.
31  *
32  */
33 public final class Light implements Parcelable {
34     // These enum values copy the values from {@link com.android.server.lights.LightsManager}
35     // and the light HAL. Since 0-7 are lights reserved for system use, 8 for microphone light is
36     // defined in {@link android.hardware.lights.LightsManager}, following types are available
37     // through this API.
38     /** Type for lights that indicate microphone usage */
39     public static final int LIGHT_TYPE_MICROPHONE = 8;
40 
41     /** Type for lights that indicate camera usage
42      *
43      * @hide
44      */
45     public static final int LIGHT_TYPE_CAMERA = 9;
46 
47     // These enum values start from 10001 to avoid collision with expanding of HAL light types.
48     /**
49      * Type for lights that indicate a monochrome color LED light.
50      */
51     public static final int LIGHT_TYPE_INPUT = 10001;
52 
53     /**
54      * Type for lights that indicate a group of LED lights representing player id.
55      * Player id lights normally present on game controllers are lights that consist of a row of
56      * LEDs.
57      * During multi-player game, the player id for the current game controller is represented by
58      * one of the LED that is lit according to its position in the row.
59      */
60     public static final int LIGHT_TYPE_PLAYER_ID = 10002;
61 
62     /**
63      * Type for lights that illuminate keyboard keys.
64      */
65     public static final int LIGHT_TYPE_KEYBOARD_BACKLIGHT = 10003;
66 
67     /**
68      * Capability for lights that could adjust its LED brightness. If the capability is not present
69      * the LED can only be turned either on or off.
70      */
71     public static final int LIGHT_CAPABILITY_BRIGHTNESS = 1 << 0;
72 
73     /**
74      * Capability for lights that have red, green and blue LEDs to control the light's color.
75      */
76     public static final int LIGHT_CAPABILITY_COLOR_RGB = 1 << 1;
77 
78     /**
79      * Capability for lights that have red, green and blue LEDs to control the light's color.
80      *
81      * @deprecated Wrong int based flag with value 0. Use capability flag {@code
82      * LIGHT_CAPABILITY_COLOR_RGB} instead.
83      */
84     @Deprecated
85     public static final int LIGHT_CAPABILITY_RGB = 0;
86 
87     /** @hide */
88     @Retention(RetentionPolicy.SOURCE)
89     @IntDef(prefix = {"LIGHT_TYPE_"},
90         value = {
91             LIGHT_TYPE_MICROPHONE,
92             LIGHT_TYPE_INPUT,
93             LIGHT_TYPE_PLAYER_ID,
94             LIGHT_TYPE_KEYBOARD_BACKLIGHT,
95         })
96     public @interface LightType {}
97 
98     /** @hide */
99     @Retention(RetentionPolicy.SOURCE)
100     @IntDef(flag = true, prefix = {"LIGHT_CAPABILITY_"},
101         value = {
102             LIGHT_CAPABILITY_BRIGHTNESS,
103             LIGHT_CAPABILITY_COLOR_RGB,
104             LIGHT_CAPABILITY_RGB,
105         })
106     public @interface LightCapability {}
107 
108     private final int mId;
109     private final String mName;
110     private final int mOrdinal;
111     private final int mType;
112     private final int mCapabilities;
113     @Nullable
114     private final int[] mPreferredBrightnessLevels;
115 
116     /**
117      * Creates a new light with the given data.
118      *
119      * @hide
120      */
Light(int id, int ordinal, int type)121     public Light(int id, int ordinal, int type) {
122         this(id, "Light", ordinal, type, 0, null);
123     }
124 
125     /**
126      * Creates a new light with the given data.
127      *
128      * @hide
129      */
Light(int id, String name, int ordinal, int type, int capabilities)130     public Light(int id, String name, int ordinal, int type, int capabilities) {
131         this(id, name, ordinal, type, capabilities, null);
132     }
133 
134     /**
135      * Creates a new light with the given data.
136      *
137      * @hide
138      */
Light(int id, String name, int ordinal, int type, int capabilities, @Nullable int[] preferredBrightnessLevels)139     public Light(int id, String name, int ordinal, int type, int capabilities,
140             @Nullable int[] preferredBrightnessLevels) {
141         mId = id;
142         mName = name;
143         mOrdinal = ordinal;
144         mType = type;
145         mCapabilities = capabilities;
146         mPreferredBrightnessLevels = preferredBrightnessLevels;
147     }
148 
Light(@onNull Parcel in)149     private Light(@NonNull Parcel in) {
150         mId = in.readInt();
151         mName = in.readString();
152         mOrdinal = in.readInt();
153         mType = in.readInt();
154         mCapabilities = in.readInt();
155         mPreferredBrightnessLevels = in.createIntArray();
156     }
157 
158     /** Implement the Parcelable interface */
159     @Override
writeToParcel(@onNull Parcel dest, int flags)160     public void writeToParcel(@NonNull Parcel dest, int flags) {
161         dest.writeInt(mId);
162         dest.writeString(mName);
163         dest.writeInt(mOrdinal);
164         dest.writeInt(mType);
165         dest.writeInt(mCapabilities);
166         dest.writeIntArray(mPreferredBrightnessLevels);
167     }
168 
169     /** Implement the Parcelable interface */
170     @Override
describeContents()171     public int describeContents() {
172         return 0;
173     }
174 
175     /** Implement the Parcelable interface */
176     public static final @android.annotation.NonNull Parcelable.Creator<Light> CREATOR =
177             new Parcelable.Creator<Light>() {
178                 public Light createFromParcel(Parcel in) {
179                     return new Light(in);
180                 }
181 
182                 public Light[] newArray(int size) {
183                     return new Light[size];
184                 }
185             };
186 
187     @Override
equals(@ullable Object obj)188     public boolean equals(@Nullable Object obj) {
189         if (obj instanceof Light) {
190             Light light = (Light) obj;
191             return mId == light.mId && mOrdinal == light.mOrdinal && mType == light.mType
192                     && mCapabilities == light.mCapabilities;
193         }
194         return false;
195     }
196 
197     @Override
hashCode()198     public int hashCode() {
199         return mId;
200     }
201 
202     @Override
toString()203     public String toString() {
204         return "[Name=" + mName + " Id=" + mId + " Type=" + mType + " Capabilities="
205                 + mCapabilities + " Ordinal=" + mOrdinal + "]";
206     }
207 
208     /**
209      * Returns the id of the light.
210      *
211      * <p>This is an opaque value used as a unique identifier for the light.
212      */
getId()213     public int getId() {
214         return mId;
215     }
216 
217     /**
218      * Returns the name of the light.
219      */
220     @NonNull
getName()221     public String getName() {
222         return mName;
223     }
224 
225     /**
226      * Returns the ordinal of the light.
227      *
228      * <p>This is a sort key that represents the physical order of lights on the device with the
229      * same type. In the case of multiple lights arranged in a line, for example, the ordinals
230      * could be [1, 2, 3, 4], or [0, 10, 20, 30], or any other values that have the same sort order.
231      */
getOrdinal()232     public int getOrdinal() {
233         return mOrdinal;
234     }
235 
236     /**
237      * Returns the logical type of the light.
238      */
getType()239     public @LightType int getType() {
240         return mType;
241     }
242 
243     /**
244      * Returns the capabilities of the light.
245      * @hide
246      */
247     @TestApi
getCapabilities()248     public @LightCapability int getCapabilities() {
249         return mCapabilities;
250     }
251 
252     /**
253      * Check whether the light has led brightness control.
254      *
255      * @return True if the hardware can control the led brightness, otherwise false.
256      */
hasBrightnessControl()257     public boolean hasBrightnessControl() {
258         return (mCapabilities & LIGHT_CAPABILITY_BRIGHTNESS) == LIGHT_CAPABILITY_BRIGHTNESS;
259     }
260 
261     /**
262      * Check whether the light has RGB led control.
263      *
264      * @return True if the hardware can control the RGB led, otherwise false.
265      */
hasRgbControl()266     public boolean hasRgbControl() {
267         return (mCapabilities & LIGHT_CAPABILITY_COLOR_RGB) == LIGHT_CAPABILITY_COLOR_RGB;
268     }
269 
270     /**
271      * Returns preferred brightness levels for the light which will be used when user
272      * increase/decrease brightness levels for the light (currently only used for Keyboard
273      * backlight control using backlight up/down keys).
274      *
275      * The values in the preferred brightness level array are in the range [0, 255].
276      *
277      * @hide
278      */
279     @Nullable
getPreferredBrightnessLevels()280     public int[] getPreferredBrightnessLevels() {
281         return mPreferredBrightnessLevels;
282     }
283 }
284