diff --git a/core/api/current.txt b/core/api/current.txt index 85b6f5615f899..b40604ef3eb84 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 8bc86dac0a8c1..cbcef8604a9c1 100644 --- a/core/java/android/hardware/lights/LightsManager.java +++ b/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. + * + *

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