From d398fb78a98240905fbe7c52a77d74eaf1041788 Mon Sep 17 00:00:00 2001 From: Chris Ye Date: Sun, 4 Apr 2021 15:34:08 -0700 Subject: [PATCH] Add Builder to LightState. Add Builder to LightState to replace the static constructors. Add documents for Player ID lights. Changed input device lights types definition to avoid future collsion with HAL light types. Bug: 181743615 Test: atest InputDeviceLightsManagerTest Change-Id: Ie47ef901006220d622677117c7ecd6ee41cf10f6 --- core/api/current.txt | 16 ++-- core/java/android/hardware/lights/Light.java | 11 ++- .../android/hardware/lights/LightState.java | 73 ++++++++++++++----- .../hardware/lights/LightsManager.java | 9 +++ .../hardware/lights/LightsRequest.java | 16 +++- 5 files changed, 97 insertions(+), 28 deletions(-) diff --git a/core/api/current.txt b/core/api/current.txt index 79ba209236b90..5a082e5439889 100644 --- a/core/api/current.txt +++ b/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 CREATOR; - field public static final int LIGHT_TYPE_INPUT_PLAYER_ID = 10; // 0xa - field public static final int LIGHT_TYPE_INPUT_RGB = 11; // 0xb - field public static final int LIGHT_TYPE_INPUT_SINGLE = 9; // 0x9 + field public static final int LIGHT_TYPE_INPUT_PLAYER_ID = 10002; // 0x2712 + field public static final int LIGHT_TYPE_INPUT_RGB = 10003; // 0x2713 + 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 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 getLights(); @@ -18995,6 +19000,7 @@ package android.hardware.lights { public final class LightsRequest { method @NonNull public java.util.List getLightStates(); method @NonNull public java.util.List getLights(); + method @NonNull public java.util.Map getLightsAndStates(); } public static final class LightsRequest.Builder { diff --git a/core/java/android/hardware/lights/Light.java b/core/java/android/hardware/lights/Light.java index 7bfff5d3af974..2c78fcb77b907 100644 --- a/core/java/android/hardware/lights/Light.java +++ b/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) diff --git a/core/java/android/hardware/lights/LightState.java b/core/java/android/hardware/lights/LightState.java index 650b383eeb0f6..c6d7f63d90e28 100644 --- a/core/java/android/hardware/lights/LightState.java +++ b/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 - * of RBG color or single monochrome color. - * - * @param color the desired color and intensity in ARGB format. - * @return The LightState object contains the color. + * Builder for creating device light change requests. */ - @NonNull - public static LightState forColor(@ColorInt int color) { - return new LightState(color, 0); - } + public static final class Builder { + private int mValue; + private boolean mIsForPlayerId; - /** - * Creates a new LightState with the desired player id, for a light of type - * {@link android.hardware.lights.Light#LIGHT_TYPE_INPUT_PLAYER_ID}. - * - * @param playerId the desired player id. - * @return The LightState object contains the player id. - */ - @NonNull - public static LightState forPlayerId(int playerId) { - return new LightState(0, playerId); + /** Creates a new {@link LightState.Builder}. */ + public Builder() { + mValue = 0; + mIsForPlayerId = false; + } + + /** + * Set the desired color and intensity of the LightState Builder, for a light type + * of RBG color or single monochrome color. + * + * @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. + * + *

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); + } + } } /** diff --git a/core/java/android/hardware/lights/LightsManager.java b/core/java/android/hardware/lights/LightsManager.java index 8fd56db33c4be..008b14e67f085 100644 --- a/core/java/android/hardware/lights/LightsManager.java +++ b/core/java/android/hardware/lights/LightsManager.java @@ -86,6 +86,15 @@ public abstract class LightsManager { /** * Encapsulates a session that can be used to control device lights and represents the lifetime * of the requests. + * + *

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. + * + *

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(); diff --git a/core/java/android/hardware/lights/LightsRequest.java b/core/java/android/hardware/lights/LightsRequest.java index 6fb0eb5df59ad..8d27dfd7487bf 100644 --- a/core/java/android/hardware/lights/LightsRequest.java +++ b/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 getLightsAndStates() { + Map 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. */