Merge "Add Builder to LightState." into sc-dev

core/api/current.txt

@@ -18964,22 +18964,27 @@ package android.hardware.lights {
     method public int getType();
     method public void writeToParcel(@NonNull android.os.Parcel, int);
     field @NonNull public static final android.os.Parcelable.Creator<android.hardware.lights.Light> CREATOR;
-    field public static final int LIGHT_TYPE_INPUT_PLAYER_ID = 10; // 0xa
+    field public static final int LIGHT_TYPE_INPUT_PLAYER_ID = 10002; // 0x2712
-    field public static final int LIGHT_TYPE_INPUT_RGB = 11; // 0xb
+    field public static final int LIGHT_TYPE_INPUT_RGB = 10003; // 0x2713
-    field public static final int LIGHT_TYPE_INPUT_SINGLE = 9; // 0x9
+    field public static final int LIGHT_TYPE_INPUT_SINGLE = 10001; // 0x2711
     field public static final int LIGHT_TYPE_MICROPHONE = 8; // 0x8
   }
 
   public final class LightState implements android.os.Parcelable {
     method public int describeContents();
-    method @NonNull public static android.hardware.lights.LightState forColor(@ColorInt int);
-    method @NonNull public static android.hardware.lights.LightState forPlayerId(int);
     method @ColorInt public int getColor();
     method public int getPlayerId();
     method public void writeToParcel(@NonNull android.os.Parcel, int);
     field @NonNull public static final android.os.Parcelable.Creator<android.hardware.lights.LightState> CREATOR;
   }
 
+  public static final class LightState.Builder {
+    ctor public LightState.Builder();
+    method @NonNull public android.hardware.lights.LightState build();
+    method @NonNull public android.hardware.lights.LightState.Builder setColor(@ColorInt int);
+    method @NonNull public android.hardware.lights.LightState.Builder setPlayerId(int);
+  }
+
   public abstract class LightsManager {
     method @NonNull public abstract android.hardware.lights.LightState getLightState(@NonNull android.hardware.lights.Light);
     method @NonNull public abstract java.util.List<android.hardware.lights.Light> getLights();
@@ -18995,6 +19000,7 @@ package android.hardware.lights {
   public final class LightsRequest {
     method @NonNull public java.util.List<android.hardware.lights.LightState> getLightStates();
     method @NonNull public java.util.List<java.lang.Integer> getLights();
+    method @NonNull public java.util.Map<java.lang.Integer,android.hardware.lights.LightState> getLightsAndStates();
   }
 
   public static final class LightsRequest.Builder {

core/java/android/hardware/lights/Light.java

@@ -37,20 +37,25 @@ public final class Light implements Parcelable {
     /** Type for lights that indicate microphone usage */
     public static final int LIGHT_TYPE_MICROPHONE = 8;
 
+    // These enum values start from 10001 to avoid collision with expanding of HAL light types.
     /**
      * Type for lights that indicate a monochrome color LED light.
      */
-    public static final int LIGHT_TYPE_INPUT_SINGLE = 9;
+    public static final int LIGHT_TYPE_INPUT_SINGLE = 10001;
 
     /**
      * Type for lights that indicate a group of LED lights representing player ID.
+     * Player ID lights normally present on game controllers are lights that consist of a row of
+     * LEDs.
+     * During multi-player game, the player ID for the current game controller is represented by
+     * one of the LED that is lit according to its position in the row.
      */
-    public static final int LIGHT_TYPE_INPUT_PLAYER_ID = 10;
+    public static final int LIGHT_TYPE_INPUT_PLAYER_ID = 10002;
 
     /**
      * Type for lights that indicate a color LED light.
      */
-    public static final int LIGHT_TYPE_INPUT_RGB = 11;
+    public static final int LIGHT_TYPE_INPUT_RGB = 10003;
 
     /** @hide */
     @Retention(RetentionPolicy.SOURCE)

core/java/android/hardware/lights/LightState.java

@@ -18,6 +18,7 @@ package android.hardware.lights;
 
 import android.annotation.ColorInt;
 import android.annotation.NonNull;
+import android.annotation.SuppressLint;
 import android.annotation.SystemApi;
 import android.os.Parcel;
 import android.os.Parcelable;
@@ -65,27 +66,61 @@ public final class LightState implements Parcelable {
     }
 
     /**
-     * Creates a new LightState with the desired color and intensity, for a light type
+     * Builder for creating device light change requests.
-     * of RBG color or single monochrome color.
-     *
-     * @param color the desired color and intensity in ARGB format.
-     * @return The LightState object contains the color.
      */
-    @NonNull
+    public static final class Builder {
-    public static LightState forColor(@ColorInt int color) {
+        private int mValue;
-        return new LightState(color, 0);
+        private boolean mIsForPlayerId;
-    }
 
-    /**
+        /** Creates a new {@link LightState.Builder}. */
-     * Creates a new LightState with the desired player id, for a light of type
+        public Builder() {
-     * {@link android.hardware.lights.Light#LIGHT_TYPE_INPUT_PLAYER_ID}.
+            mValue = 0;
-     *
+            mIsForPlayerId = false;
-     * @param playerId the desired player id.
+        }
-     * @return The LightState object contains the player id.
+
-     */
+        /**
-    @NonNull
+         * Set the desired color and intensity of the LightState Builder, for a light type
-    public static LightState forPlayerId(int playerId) {
+         * of RBG color or single monochrome color.
-        return new LightState(0, playerId);
+         *
+         * @param color the desired color and intensity in ARGB format.
+         * @return The {@link LightState.Builder} object contains the light color and intensity.
+         */
+        @SuppressLint("MissingGetterMatchingBuilder")
+        @NonNull
+        public Builder setColor(@ColorInt int color) {
+            mIsForPlayerId = false;
+            mValue = color;
+            return this;
+        }
+
+        /**
+         * Set the desired player id of the LightState Builder, for a light of type
+         * {@link android.hardware.lights.Light#LIGHT_TYPE_INPUT_PLAYER_ID}.
+         *
+         * @param playerId the desired player id.
+         * @return The {@link LightState.Builder} object contains the player id.
+         */
+        @SuppressLint("MissingGetterMatchingBuilder")
+        @NonNull
+        public Builder setPlayerId(int playerId) {
+            mIsForPlayerId = true;
+            mValue = playerId;
+            return this;
+        }
+
+        /**
+         * Create a LightState object used to control lights on the device.
+         *
+         * <p>The generated {@link LightState} should be used in
+         * {@link LightsRequest.Builder#addLight(Light, LightState)}.
+         */
+        public @NonNull LightState build() {
+            if (!mIsForPlayerId) {
+                return new LightState(mValue, 0);
+            } else {
+                return new LightState(0, mValue);
+            }
+        }
     }
 
     /**

core/java/android/hardware/lights/LightsManager.java

@@ -99,6 +99,15 @@ public abstract class LightsManager {
     /**
      * Encapsulates a session that can be used to control device lights and represents the lifetime
      * of the requests.
+     *
+     * <p>Any lights requests always live in a lights session which defines the lifecycle of the
+     * lights requests. A lights session is AutoCloseable that will get closed when leaving the
+     * session context.
+     *
+     * <p>Multiple sessions can make lights requests which contains same light. In the case the
+     * LightsManager implementation will arbitrate and honor one of the session's request. When
+     * the session hold the current light request closed, LightsManager implementation will choose
+     * another live session to honor its lights requests.
      */
     public abstract static class LightsSession implements AutoCloseable {
         private final IBinder mToken = new Binder();

core/java/android/hardware/lights/LightsRequest.java

@@ -24,7 +24,9 @@ import com.android.internal.util.Preconditions;
 
 import java.util.ArrayList;
 import java.util.Arrays;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 /**
  * Encapsulates a request to modify the state of multiple lights.
  *
@@ -51,7 +53,7 @@ public final class LightsRequest {
     }
 
     /**
-     * Get a list of Light as ids.  The ids will returned in same order as the lights passed
+     * Get a list of Light as ids. The ids will returned in same order as the lights passed
      * in Builder.
      *
      * @return List of light ids
@@ -74,6 +76,18 @@ public final class LightsRequest {
         return Arrays.asList(mLightStates);
     }
 
+    /**
+     * Get a map of light ids and states.  The map will contain all the light ids as keys and
+     * the corresponding LightState requested as values.
+     */
+    public @NonNull Map<Integer, LightState> getLightsAndStates() {
+        Map<Integer, LightState> map = new HashMap<>();
+        for (int i = 0; i < mLightIds.length; i++) {
+            map.put(mLightIds[i], mLightStates[i]);
+        }
+        return map;
+    }
+
     /**
      * Builder for creating device light change requests.
      */