Merge "[MQ] Clean up Media Quality APIs and JavaDoc" into main (64be046f) · Commits · e / os / android_frameworks_base

media/java/android/media/quality/MediaQualityContract.java

+43 −1

Original line number	Diff line number	Diff line
		@@ -21,11 +21,16 @@ import android.annotation.FlaggedApi;
		import android.media.tv.flags.Flags;

		/**
		* The contract between the media quality service and applications. Contains definitions for the
		* commonly used parameter names.
		* @hide
		*/
		@FlaggedApi(Flags.FLAG_MEDIA_QUALITY_FW)
		public class MediaQualityContract {

		/**
		* @hide
		*/
		public interface BaseParameters {
		String PARAMETER_ID = "_id";
		String PARAMETER_NAME = "_name";
		@@ -33,13 +38,50 @@ public class MediaQualityContract {
		String PARAMETER_INPUT_ID = "_input_id";

		}
		public static final class PictureQuality implements BaseParameters {

		/**
		* Parameters picture quality.
		* @hide
		*/
		public static final class PictureQuality {
		/**
		* The brightness.
		*
		* <p>Type: INTEGER
		*/
		public static final String PARAMETER_BRIGHTNESS = "brightness";

		/**
		* The contrast.
		*
		* <p>The ratio between the luminance of the brightest white and the darkest black.
		* <p>Type: INTEGER
		*/
		public static final String PARAMETER_CONTRAST = "contrast";

		/**
		* The sharpness.
		*
		* <p>Sharpness indicates the clarity of detail.
		* <p>Type: INTEGER
		*/
		public static final String PARAMETER_SHARPNESS = "sharpness";

		/**
		* The saturation.
		*
		* <p>Saturation indicates the intensity of the color.
		* <p>Type: INTEGER
		*/
		public static final String PARAMETER_SATURATION = "saturation";

		private PictureQuality() {
		}
		}

		/**
		* @hide
		*/
		public static final class SoundQuality implements BaseParameters {
		public static final String PARAMETER_BALANCE = "balance";
		public static final String PARAMETER_BASS = "bass";

media/java/android/media/quality/MediaQualityManager.java

+44 −7

Original line number	Diff line number	Diff line
		@@ -34,7 +34,8 @@ import java.util.List;
		import java.util.concurrent.Executor;

		/**
		* Expose TV setting APIs for the application to use
		* Central system API to the overall media quality, which arbitrates interaction between
		* applications and media quality service.
		* @hide
		*/
		@FlaggedApi(Flags.FLAG_MEDIA_QUALITY_FW)
		@@ -177,6 +178,7 @@ public final class MediaQualityManager {
		* Gets picture profile by given profile ID.
		* @return the corresponding picture profile if available; {@code null} if the ID doesn't
		* exist or the profile is not accessible to the caller.
		* @hide
		*/
		public PictureProfile getPictureProfileById(long profileId) {
		try {
		@@ -187,7 +189,10 @@ public final class MediaQualityManager {
		}


		/** @SystemApi gets profiles that available to the given package */
		/**
		* @SystemApi gets profiles that available to the given package
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
		public List<PictureProfile> getPictureProfilesByPackage(String packageName) {
		try {
		@@ -197,7 +202,10 @@ public final class MediaQualityManager {
		}
		}

		/** Gets profiles that available to the caller package */
		/**
		* Gets profiles that available to the caller.
		*/
		@NonNull
		public List<PictureProfile> getAvailablePictureProfiles() {
		try {
		return mService.getAvailablePictureProfiles();
		@@ -206,7 +214,10 @@ public final class MediaQualityManager {
		}
		}

		/** @SystemApi all stored picture profiles of all packages */
		/**
		* @SystemApi all stored picture profiles of all packages
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
		public List<PictureProfile> getAllPictureProfiles() {
		try {
		@@ -221,6 +232,7 @@ public final class MediaQualityManager {
		* Creates a picture profile and store it in the system.
		*
		* @return the stored profile with an assigned profile ID.
		* @hide
		*/
		public PictureProfile createPictureProfile(PictureProfile pp) {
		try {
		@@ -233,6 +245,7 @@ public final class MediaQualityManager {

		/**
		* Updates an existing picture profile and store it in the system.
		* @hide
		*/
		public void updatePictureProfile(long profileId, PictureProfile pp) {
		try {
		@@ -245,6 +258,7 @@ public final class MediaQualityManager {

		/**
		* Removes a picture profile from the system.
		* @hide
		*/
		public void removePictureProfile(long profileId) {
		try {
		@@ -291,6 +305,7 @@ public final class MediaQualityManager {
		* Gets sound profile by given profile ID.
		* @return the corresponding sound profile if available; {@code null} if the ID doesn't
		* exist or the profile is not accessible to the caller.
		* @hide
		*/
		public SoundProfile getSoundProfileById(long profileId) {
		try {
		@@ -301,7 +316,10 @@ public final class MediaQualityManager {
		}


		/** @SystemApi gets profiles that available to the given package */
		/**
		* @SystemApi gets profiles that available to the given package
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_SOUND_QUALITY_SERVICE)
		public List<SoundProfile> getSoundProfilesByPackage(String packageName) {
		try {
		@@ -311,7 +329,10 @@ public final class MediaQualityManager {
		}
		}

		/** Gets profiles that available to the caller package */
		/**
		* Gets profiles that available to the caller package
		* @hide
		*/
		public List<SoundProfile> getAvailableSoundProfiles() {
		try {
		return mService.getAvailableSoundProfiles();
		@@ -320,7 +341,10 @@ public final class MediaQualityManager {
		}
		}

		/** @SystemApi all stored sound profiles of all packages */
		/**
		* @SystemApi all stored sound profiles of all packages
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_SOUND_QUALITY_SERVICE)
		public List<SoundProfile> getAllSoundProfiles() {
		try {
		@@ -335,6 +359,7 @@ public final class MediaQualityManager {
		* Creates a sound profile and store it in the system.
		*
		* @return the stored profile with an assigned profile ID.
		* @hide
		*/
		public SoundProfile createSoundProfile(SoundProfile sp) {
		try {
		@@ -347,6 +372,7 @@ public final class MediaQualityManager {

		/**
		* Updates an existing sound profile and store it in the system.
		* @hide
		*/
		public void updateSoundProfile(long profileId, SoundProfile sp) {
		try {
		@@ -359,6 +385,7 @@ public final class MediaQualityManager {

		/**
		* Removes a sound profile from the system.
		* @hide
		*/
		public void removeSoundProfile(long profileId) {
		try {
		@@ -370,6 +397,7 @@ public final class MediaQualityManager {

		/**
		* Gets capability information of the given parameters.
		* @hide
		*/
		public List<ParamCapability> getParamCapabilities(List<String> names) {
		try {
		@@ -396,6 +424,7 @@ public final class MediaQualityManager {
		* different use cases.
		*
		* @param enabled {@code true} to enable, {@code false} to disable.
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
		public void setAutoPictureQualityEnabled(boolean enabled) {
		@@ -408,6 +437,7 @@ public final class MediaQualityManager {

		/**
		* Returns {@code true} if auto picture quality is enabled; {@code false} otherwise.
		* @hide
		*/
		public boolean isAutoPictureQualityEnabled() {
		try {
		@@ -422,6 +452,7 @@ public final class MediaQualityManager {
		* <p>Super resolution is a feature to improve resolution.
		*
		* @param enabled {@code true} to enable, {@code false} to disable.
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
		public void setSuperResolutionEnabled(boolean enabled) {
		@@ -434,6 +465,7 @@ public final class MediaQualityManager {

		/**
		* Returns {@code true} if super resolution is enabled; {@code false} otherwise.
		* @hide
		*/
		public boolean isSuperResolutionEnabled() {
		try {
		@@ -449,6 +481,7 @@ public final class MediaQualityManager {
		* different use cases.
		*
		* @param enabled {@code true} to enable, {@code false} to disable.
		* @hide
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_SOUND_QUALITY_SERVICE)
		public void setAutoSoundQualityEnabled(boolean enabled) {
		@@ -461,6 +494,7 @@ public final class MediaQualityManager {

		/**
		* Returns {@code true} if auto sound quality is enabled; {@code false} otherwise.
		* @hide
		*/
		public boolean isAutoSoundQualityEnabled() {
		try {
		@@ -507,6 +541,7 @@ public final class MediaQualityManager {
		* Set the ambient backlight settings.
		*
		* @param settings The settings to use for the backlight detector.
		* @hide
		*/
		public void setAmbientBacklightSettings(
		@NonNull AmbientBacklightSettings settings) {
		@@ -522,6 +557,7 @@ public final class MediaQualityManager {
		* Enables or disables the ambient backlight detection.
		*
		* @param enabled {@code true} to enable, {@code false} to disable.
		* @hide
		*/
		public void setAmbientBacklightEnabled(boolean enabled) {
		try {
		@@ -700,6 +736,7 @@ public final class MediaQualityManager {
		public abstract static class AmbientBacklightCallback {
		/**
		* Called when new ambient backlight event is emitted.
		* @hide
		*/
		public void onAmbientBacklightEvent(AmbientBacklightEvent event) {
		}

media/java/android/media/quality/PictureProfile.java

+137 −34

Original line number	Diff line number	Diff line
		@@ -17,6 +17,8 @@
		package android.media.quality;

		import android.annotation.FlaggedApi;
		import android.annotation.IntDef;
		import android.media.tv.TvInputInfo;
		import android.media.tv.flags.Flags;
		import android.os.Bundle;
		import android.os.Parcel;
		@@ -24,30 +26,55 @@ import android.os.Parcelable;

		import androidx.annotation.NonNull;
		import androidx.annotation.Nullable;
		import androidx.annotation.RequiresPermission;

		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;

		/**
		* Profile for picture quality.
		* @hide
		*/

		@FlaggedApi(Flags.FLAG_MEDIA_QUALITY_FW)
		public class PictureProfile implements Parcelable {
		public final class PictureProfile implements Parcelable {
		@Nullable
		private Long mId;
		private String mId;
		private final int mType;
		@NonNull
		private final String mName;
		@Nullable
		private final String mInputId;
		@Nullable
		@NonNull
		private final String mPackageName;
		@NonNull
		private final Bundle mParams;

		protected PictureProfile(Parcel in) {
		if (in.readByte() == 0) {
		mId = null;
		} else {
		mId = in.readLong();
		}
		/** @hide */
		@Retention(RetentionPolicy.SOURCE)
		@IntDef(flag = false, prefix = "TYPE_", value = {
		TYPE_SYSTEM,
		TYPE_APPLICATION})
		public @interface ProfileType {}

		/**
		* System profile type.
		*
		* <p>A profile of system type is managed by the system, and readable to the package define in
		* {@link #getPackageName()}.
		*/
		public static final int TYPE_SYSTEM = 1;
		/**
		* Application profile type.
		*
		* <p>A profile of application type is managed by the package define in
		* {@link #getPackageName()}.
		*/
		public static final int TYPE_APPLICATION = 2;


		private PictureProfile(@NonNull Parcel in) {
		mId = in.readString();
		mType = in.readInt();
		mName = in.readString();
		mInputId = in.readString();
		mPackageName = in.readString();
		@@ -55,13 +82,9 @@ public class PictureProfile implements Parcelable {
		}

		@Override
		public void writeToParcel(Parcel dest, int flags) {
		if (mId == null) {
		dest.writeByte((byte) 0);
		} else {
		dest.writeByte((byte) 1);
		dest.writeLong(mId);
		}
		public void writeToParcel(@NonNull Parcel dest, int flags) {
		dest.writeString(mId);
		dest.writeInt(mType);
		dest.writeString(mName);
		dest.writeString(mInputId);
		dest.writeString(mPackageName);
		@@ -73,6 +96,7 @@ public class PictureProfile implements Parcelable {
		return 0;
		}

		@NonNull
		public static final Creator<PictureProfile> CREATOR = new Creator<PictureProfile>() {
		@Override
		public PictureProfile createFromParcel(Parcel in) {
		@@ -92,95 +116,166 @@ public class PictureProfile implements Parcelable {
		* @hide
		*/
		public PictureProfile(
		@Nullable Long id,
		@Nullable String id,
		int type,
		@NonNull String name,
		@Nullable String inputId,
		@Nullable String packageName,
		@NonNull String packageName,
		@NonNull Bundle params) {
		this.mId = id;
		this.mType = type;
		this.mName = name;
		com.android.internal.util.AnnotationValidations.validate(NonNull.class, null, name);
		this.mInputId = inputId;
		this.mPackageName = packageName;
		this.mParams = params;
		}

		/**
		* Gets profile ID.
		*
		* <p>A profile ID is a globally unique ID generated and assigned by the system. For profile
		* objects retrieved from system (e.g {@link MediaQualityManager#getAvailablePictureProfiles()})
		* this profile ID is non-null; For profiles built locally with {@link Builder}, it's
		* {@code null}.
		*
		* @return the unique profile ID; {@code null} if the profile is built locally with
		* {@link Builder}.
		*/
		@Nullable
		public Long getProfileId() {
		public String getProfileId() {
		return mId;
		}

		/**
		* Only used by system to assign the ID.
		* @hide
		*/
		public void setProfileId(String id) {
		mId = id;
		}

		/**
		* Gets profile type.
		*/
		@ProfileType
		public int getProfileType() {
		return mType;
		}

		/**
		* Gets the profile name.
		*/
		@NonNull
		public String getName() {
		return mName;
		}

		/**
		* Gets the input ID if the profile is for a TV input.
		*
		* @return the corresponding TV input ID; {@code null} if the profile is not associated with a
		* TV input.
		*
		* @see TvInputInfo#getId()
		*/
		@Nullable
		public String getInputId() {
		return mInputId;
		}

		/**
		* Gets the package name of this profile.
		*
		* <p>The package name defines the user of a profile. Only this specific package and system app
		* can access to this profile.
		*
		* @return the package name; {@code null} if the profile is built locally using
		* {@link Builder} and the package is not set.
		*/
		@Nullable
		public String getPackageName() {
		return mPackageName;
		}

		/**
		* Gets the parameters of this profile.
		*
		* <p>The keys of commonly used parameters can be found in
		* {@link MediaQualityContract.PictureQuality}.
		*/
		@NonNull
		public Bundle getParameters() {
		return new Bundle(mParams);
		}

		/**
		* A builder for {@link PictureProfile}
		* A builder for {@link PictureProfile}.
		* @hide
		*/
		public static class Builder {
		public static final class Builder {
		@Nullable
		private Long mId;
		private String mId;
		private int mType = TYPE_APPLICATION;
		@NonNull
		private String mName;
		@Nullable
		private String mInputId;
		@Nullable
		@NonNull
		private String mPackageName;
		@NonNull
		private Bundle mParams;

		/**
		* Creates a new Builder.
		*
		* @hide
		*/
		public Builder(@NonNull String name) {
		mName = name;
		com.android.internal.util.AnnotationValidations.validate(NonNull.class, null, name);
		}

		/**
		* Copy constructor.
		*
		* @hide
		* Copy constructor of builder.
		*/
		public Builder(@NonNull PictureProfile p) {
		mId = null; // ID needs to be reset
		mType = p.getProfileType();
		mName = p.getName();
		mPackageName = p.getPackageName();
		mInputId = p.getInputId();
		mParams = p.getParameters();
		}

		/* @hide using by MediaQualityService */

		/**
		* Sets profile ID.
		* @hide using by MediaQualityService
		* Only used by system to assign the ID.
		* @hide
		*/
		@NonNull
		public Builder setProfileId(@Nullable Long id) {
		public Builder setProfileId(@Nullable String id) {
		mId = id;
		return this;
		}

		/**
		* Sets profile type.
		*
		* @hide @SystemApi
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
		@NonNull
		public Builder setProfileType(@ProfileType int value) {
		mType = value;
		return this;
		}

		/**
		* Sets input ID.
		*
		* @see PictureProfile#getInputId()
		*
		* @hide @SystemApi
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
		@NonNull
		public Builder setInputId(@NonNull String value) {
		mInputId = value;
		@@ -189,7 +284,12 @@ public class PictureProfile implements Parcelable {

		/**
		* Sets package name of the profile.
		*
		* @see PictureProfile#getPackageName()
		*
		* @hide @SystemApi
		*/
		@RequiresPermission(android.Manifest.permission.MANAGE_GLOBAL_PICTURE_QUALITY_SERVICE)
		@NonNull
		public Builder setPackageName(@NonNull String value) {
		mPackageName = value;
		@@ -198,6 +298,8 @@ public class PictureProfile implements Parcelable {

		/**
		* Sets profile parameters.
		*
		* @see PictureProfile#getParameters()
		*/
		@NonNull
		public Builder setParameters(@NonNull Bundle params) {
		@@ -213,6 +315,7 @@ public class PictureProfile implements Parcelable {

		PictureProfile o = new PictureProfile(
		mId,
		mType,
		mName,
		mInputId,
		mPackageName,