android-35/android/view/CutoutSpecification.java - platform/prebuilts/fullsdk/sources - Git at Google

 /*
  * Copyright (C) 2020 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package android.view;

 import static android.view.Gravity.BOTTOM;
 import static android.view.Gravity.LEFT;
 import static android.view.Gravity.RIGHT;
 import static android.view.Gravity.TOP;

 import static com.android.internal.annotations.VisibleForTesting.Visibility.PACKAGE;

 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.graphics.Insets;
 import android.graphics.Matrix;
 import android.graphics.Path;
 import android.graphics.Rect;
 import android.graphics.RectF;
 import android.graphics.Region;
 import android.text.TextUtils;
 import android.util.Log;
 import android.util.PathParser;

 import com.android.internal.annotations.VisibleForTesting;

 import java.util.Locale;
 import java.util.Objects;

 /**
  * In order to accept the cutout specification for all of edges in devices, the specification
  * parsing method is extracted from
  * {@link android.view.DisplayCutout#fromResourcesRectApproximation(Resources, int, int)} to be
  * the specified class for parsing the specification.
  * BNF definition:
  * <ul>
  *      <li>Cutouts Specification = ([Cutout Delimiter],Cutout Specification) {...}, [Dp] ; </li>
  *      <li>Cutout Specification  = [Vertical Position], (SVG Path Element), [Horizontal Position]
  *                                  [Bind Cutout] ;</li>
  *      <li>Vertical Position     = "@bottom" | "@center_vertical" ;</li>
  *      <li>Horizontal Position   = "@left" | "@right" ;</li>
  *      <li>Bind Cutout           = "@bind_left_cutout" | "@bind_right_cutout" ;</li>
  *      <li>Cutout Delimiter      = "@cutout" ;</li>
  *      <li>Dp                    = "@dp"</li>
  * </ul>
  *
  * <ul>
  *     <li>Vertical position is top by default if there is neither "@bottom" nor "@center_vertical"
  *     </li>
  *     <li>Horizontal position is center horizontal by default if there is neither "@left" nor
  *     "@right".</li>
  *     <li>@bottom make the cutout piece bind to bottom edge.</li>
  *     <li>both of @bind_left_cutout and @bind_right_cutout are use to claim the cutout belong to
  *     left or right edge cutout.</li>
  * </ul>
  *
  * @hide
  */
 @VisibleForTesting(visibility = PACKAGE)
 public class CutoutSpecification {
     private static final String TAG = "CutoutSpecification";
     private static final boolean DEBUG = false;

     private static final int MINIMAL_ACCEPTABLE_PATH_LENGTH = "H1V1Z".length();

     private static final char MARKER_START_CHAR = '@';
     private static final String DP_MARKER = MARKER_START_CHAR + "dp";

     private static final String BOTTOM_MARKER = MARKER_START_CHAR + "bottom";
     private static final String RIGHT_MARKER = MARKER_START_CHAR + "right";
     private static final String LEFT_MARKER = MARKER_START_CHAR + "left";
     private static final String CUTOUT_MARKER = MARKER_START_CHAR + "cutout";
     private static final String CENTER_VERTICAL_MARKER = MARKER_START_CHAR + "center_vertical";

     /* By default, it's top bound cutout. That's why TOP_BOUND_CUTOUT_MARKER is not defined */
     private static final String BIND_RIGHT_CUTOUT_MARKER = MARKER_START_CHAR + "bind_right_cutout";
     private static final String BIND_LEFT_CUTOUT_MARKER = MARKER_START_CHAR + "bind_left_cutout";

     private final Path mPath;
     private final Rect mLeftBound;
     private final Rect mTopBound;
     private final Rect mRightBound;
     private final Rect mBottomBound;
     private Insets mInsets;

     private CutoutSpecification(@NonNull Parser parser) {
         mPath = parser.mPath;
         mLeftBound = parser.mLeftBound;
         mTopBound = parser.mTopBound;
         mRightBound = parser.mRightBound;
         mBottomBound = parser.mBottomBound;
         mInsets = parser.mInsets;

         applyPhysicalPixelDisplaySizeRatio(parser.mPhysicalPixelDisplaySizeRatio);

         if (DEBUG) {
             Log.d(TAG, String.format(Locale.ENGLISH,
                     "left cutout = %s, top cutout = %s, right cutout = %s, bottom cutout = %s",
                     mLeftBound != null ? mLeftBound.toString() : "",
                     mTopBound != null ? mTopBound.toString() : "",
                     mRightBound != null ? mRightBound.toString() : "",
                     mBottomBound != null ? mBottomBound.toString() : ""));
         }
     }

     private void applyPhysicalPixelDisplaySizeRatio(float physicalPixelDisplaySizeRatio) {
         if (physicalPixelDisplaySizeRatio == 1f) {
             return;
         }

         if (mPath != null && !mPath.isEmpty()) {
             final Matrix matrix = new Matrix();
             matrix.postScale(physicalPixelDisplaySizeRatio, physicalPixelDisplaySizeRatio);
             mPath.transform(matrix);
         }

         scaleBounds(mLeftBound, physicalPixelDisplaySizeRatio);
         scaleBounds(mTopBound, physicalPixelDisplaySizeRatio);
         scaleBounds(mRightBound, physicalPixelDisplaySizeRatio);
         scaleBounds(mBottomBound, physicalPixelDisplaySizeRatio);
         mInsets = scaleInsets(mInsets, physicalPixelDisplaySizeRatio);
     }

     private void scaleBounds(Rect r, float ratio) {
         if (r != null && !r.isEmpty()) {
             r.scale(ratio);
         }
     }

     private Insets scaleInsets(Insets insets, float ratio) {
         return Insets.of(
                 (int) (insets.left * ratio + 0.5f),
                 (int) (insets.top * ratio + 0.5f),
                 (int) (insets.right * ratio + 0.5f),
                 (int) (insets.bottom * ratio + 0.5f));
     }

     @VisibleForTesting(visibility = PACKAGE)
     @Nullable
     public Path getPath() {
         return mPath;
     }

     @VisibleForTesting(visibility = PACKAGE)
     @Nullable
     public Rect getLeftBound() {
         return mLeftBound;
     }

     @VisibleForTesting(visibility = PACKAGE)
     @Nullable
     public Rect getTopBound() {
         return mTopBound;
     }

     @VisibleForTesting(visibility = PACKAGE)
     @Nullable
     public Rect getRightBound() {
         return mRightBound;
     }

     @VisibleForTesting(visibility = PACKAGE)
     @Nullable
     public Rect getBottomBound() {
         return mBottomBound;
     }

     /**
      * To count the safe inset according to the cutout bounds and waterfall inset.
      *
      * @return the safe inset.
      */
     @VisibleForTesting(visibility = PACKAGE)
     @NonNull
     public Rect getSafeInset() {
         return mInsets.toRect();
     }

     private static int decideWhichEdge(boolean isTopEdgeShortEdge,
             boolean isShortEdge, boolean isStart) {
         return (isTopEdgeShortEdge)
                 ? ((isShortEdge) ? (isStart ? TOP : BOTTOM) : (isStart ? LEFT : RIGHT))
                 : ((isShortEdge) ? (isStart ? LEFT : RIGHT) : (isStart ? TOP : BOTTOM));
     }

     /**
      * The CutoutSpecification Parser.
      */
     @VisibleForTesting(visibility = PACKAGE)
     public static class Parser {
         private final boolean mIsShortEdgeOnTop;
         private final float mStableDensity;
         private final int mPhysicalDisplayWidth;
         private final int mPhysicalDisplayHeight;
         private final float mPhysicalPixelDisplaySizeRatio;
         private final Matrix mMatrix;
         private Insets mInsets;
         private int mSafeInsetLeft;
         private int mSafeInsetTop;
         private int mSafeInsetRight;
         private int mSafeInsetBottom;

         private final Rect mTmpRect = new Rect();
         private final RectF mTmpRectF = new RectF();

         private boolean mInDp;

         private Path mPath;
         private Rect mLeftBound;
         private Rect mTopBound;
         private Rect mRightBound;
         private Rect mBottomBound;

         private boolean mPositionFromLeft = false;
         private boolean mPositionFromRight = false;
         private boolean mPositionFromBottom = false;
         private boolean mPositionFromCenterVertical = false;

         private boolean mBindLeftCutout = false;
         private boolean mBindRightCutout = false;
         private boolean mBindBottomCutout = false;

         private boolean mIsTouchShortEdgeStart;
         private boolean mIsTouchShortEdgeEnd;
         private boolean mIsCloserToStartSide;

         @VisibleForTesting(visibility = PACKAGE)
         public Parser(float stableDensity, int physicalDisplayWidth,
                 int physicalDisplayHeight) {
             this(stableDensity, physicalDisplayWidth, physicalDisplayHeight, 1f);
         }

         /**
          * The constructor of the CutoutSpecification parser to parse the specification of cutout.
          * @param stableDensity the display density.
          * @param physicalDisplayWidth the display width.
          * @param physicalDisplayHeight the display height.
          * @param physicalPixelDisplaySizeRatio the display size ratio based on stable display size.
          */
         Parser(float stableDensity, int physicalDisplayWidth, int physicalDisplayHeight,
                 float physicalPixelDisplaySizeRatio) {
             mStableDensity = stableDensity;
             mPhysicalDisplayWidth = physicalDisplayWidth;
             mPhysicalDisplayHeight = physicalDisplayHeight;
             mPhysicalPixelDisplaySizeRatio = physicalPixelDisplaySizeRatio;
             mMatrix = new Matrix();
             mIsShortEdgeOnTop = mPhysicalDisplayWidth < mPhysicalDisplayHeight;
         }

         private void computeBoundsRectAndAddToRegion(Path p, Region inoutRegion, Rect inoutRect) {
             mTmpRectF.setEmpty();
             p.computeBounds(mTmpRectF, false /* unused */);
             mTmpRectF.round(inoutRect);
             inoutRegion.op(inoutRect, Region.Op.UNION);
         }

         private void resetStatus(StringBuilder sb) {
             sb.setLength(0);
             mPositionFromBottom = false;
             mPositionFromLeft = false;
             mPositionFromRight = false;
             mPositionFromCenterVertical = false;

             mBindLeftCutout = false;
             mBindRightCutout = false;
             mBindBottomCutout = false;
         }

         private void translateMatrix() {
             final float offsetX;
             if (mPositionFromRight) {
                 offsetX = mPhysicalDisplayWidth;
             } else if (mPositionFromLeft) {
                 offsetX = 0;
             } else {
                 offsetX = mPhysicalDisplayWidth / 2f;
             }

             final float offsetY;
             if (mPositionFromBottom) {
                 offsetY = mPhysicalDisplayHeight;
             } else if (mPositionFromCenterVertical) {
                 offsetY = mPhysicalDisplayHeight / 2f;
             } else {
                 offsetY = 0;
             }

             mMatrix.reset();
             if (mInDp) {
                 mMatrix.postScale(mStableDensity, mStableDensity);
             }
             mMatrix.postTranslate(offsetX, offsetY);
         }

         private int computeSafeInsets(int gravity, Rect rect) {
             if (gravity == LEFT && rect.right > 0 && rect.right < mPhysicalDisplayWidth) {
                 return rect.right;
             } else if (gravity == TOP && rect.bottom > 0 && rect.bottom < mPhysicalDisplayHeight) {
                 return rect.bottom;
             } else if (gravity == RIGHT && rect.left > 0 && rect.left < mPhysicalDisplayWidth) {
                 return mPhysicalDisplayWidth - rect.left;
             } else if (gravity == BOTTOM && rect.top > 0 && rect.top < mPhysicalDisplayHeight) {
                 return mPhysicalDisplayHeight - rect.top;
             }
             return 0;
         }

         private void setSafeInset(int gravity, int inset) {
             if (gravity == LEFT) {
                 mSafeInsetLeft = inset;
             } else if (gravity == TOP) {
                 mSafeInsetTop = inset;
             } else if (gravity == RIGHT) {
                 mSafeInsetRight = inset;
             } else if (gravity == BOTTOM) {
                 mSafeInsetBottom = inset;
             }
         }

         private int getSafeInset(int gravity) {
             if (gravity == LEFT) {
                 return mSafeInsetLeft;
             } else if (gravity == TOP) {
                 return mSafeInsetTop;
             } else if (gravity == RIGHT) {
                 return mSafeInsetRight;
             } else if (gravity == BOTTOM) {
                 return mSafeInsetBottom;
             }
             return 0;
         }

         @NonNull
         private Rect onSetEdgeCutout(boolean isStart, boolean isShortEdge, @NonNull Rect rect) {
             final int gravity;
             if (isShortEdge) {
                 gravity = decideWhichEdge(mIsShortEdgeOnTop, true, isStart);
             } else {
                 if (mIsTouchShortEdgeStart && mIsTouchShortEdgeEnd) {
                     gravity = decideWhichEdge(mIsShortEdgeOnTop, false, isStart);
                 } else if (mIsTouchShortEdgeStart || mIsTouchShortEdgeEnd) {
                     gravity = decideWhichEdge(mIsShortEdgeOnTop, true,
                             mIsCloserToStartSide);
                 } else {
                     gravity = decideWhichEdge(mIsShortEdgeOnTop, isShortEdge, isStart);
                 }
             }

             int oldSafeInset = getSafeInset(gravity);
             int newSafeInset = computeSafeInsets(gravity, rect);
             if (oldSafeInset < newSafeInset) {
                 setSafeInset(gravity, newSafeInset);
             }

             return new Rect(rect);
         }

         private void setEdgeCutout(@NonNull Path newPath) {
             if (mBindRightCutout && mRightBound == null) {
                 mRightBound = onSetEdgeCutout(false, !mIsShortEdgeOnTop, mTmpRect);
             } else if (mBindLeftCutout && mLeftBound == null) {
                 mLeftBound = onSetEdgeCutout(true, !mIsShortEdgeOnTop, mTmpRect);
             } else if (mBindBottomCutout && mBottomBound == null) {
                 mBottomBound = onSetEdgeCutout(false, mIsShortEdgeOnTop, mTmpRect);
             } else if (!(mBindBottomCutout || mBindLeftCutout || mBindRightCutout)
                     && mTopBound == null) {
                 mTopBound = onSetEdgeCutout(true, mIsShortEdgeOnTop, mTmpRect);
             } else {
                 return;
             }

             if (mPath != null) {
                 mPath.addPath(newPath);
             } else {
                 mPath = newPath;
             }
         }

         private void parseSvgPathSpec(Region region, String spec) {
             if (TextUtils.length(spec) < MINIMAL_ACCEPTABLE_PATH_LENGTH) {
                 Log.e(TAG, "According to SVG definition, it shouldn't happen");
                 return;
             }
             translateMatrix();

             final Path newPath = PathParser.createPathFromPathData(spec);
             newPath.transform(mMatrix);
             computeBoundsRectAndAddToRegion(newPath, region, mTmpRect);

             if (DEBUG) {
                 Log.d(TAG, String.format(Locale.ENGLISH,
                         "hasLeft = %b, hasRight = %b, hasBottom = %b, hasCenterVertical = %b",
                         mPositionFromLeft, mPositionFromRight, mPositionFromBottom,
                         mPositionFromCenterVertical));
                 Log.d(TAG, "region = " + region);
                 Log.d(TAG, "spec = \"" + spec + "\" rect = " + mTmpRect + " newPath = " + newPath);
             }

             if (mTmpRect.isEmpty()) {
                 return;
             }

             if (mIsShortEdgeOnTop) {
                 mIsTouchShortEdgeStart = mTmpRect.top <= 0;
                 mIsTouchShortEdgeEnd = mTmpRect.bottom >= mPhysicalDisplayHeight;
                 mIsCloserToStartSide = mTmpRect.centerY() < mPhysicalDisplayHeight / 2;
             } else {
                 mIsTouchShortEdgeStart = mTmpRect.left <= 0;
                 mIsTouchShortEdgeEnd = mTmpRect.right >= mPhysicalDisplayWidth;
                 mIsCloserToStartSide = mTmpRect.centerX() < mPhysicalDisplayWidth / 2;
             }

             setEdgeCutout(newPath);
         }

         private void parseSpecWithoutDp(@NonNull String specWithoutDp) {
             Region region = Region.obtain();
             StringBuilder sb = null;
             int currentIndex = 0;
             int lastIndex = 0;
             while ((currentIndex = specWithoutDp.indexOf(MARKER_START_CHAR, lastIndex)) != -1) {
                 if (sb == null) {
                     sb = new StringBuilder(specWithoutDp.length());
                 }
                 sb.append(specWithoutDp, lastIndex, currentIndex);

                 if (specWithoutDp.startsWith(LEFT_MARKER, currentIndex)) {
                     if (!mPositionFromRight) {
                         mPositionFromLeft = true;
                     }
                     currentIndex += LEFT_MARKER.length();
                 } else if (specWithoutDp.startsWith(RIGHT_MARKER, currentIndex)) {
                     if (!mPositionFromLeft) {
                         mPositionFromRight = true;
                     }
                     currentIndex += RIGHT_MARKER.length();
                 } else if (specWithoutDp.startsWith(BOTTOM_MARKER, currentIndex)) {
                     parseSvgPathSpec(region, sb.toString());
                     currentIndex += BOTTOM_MARKER.length();

                     /* prepare to parse the rest path */
                     resetStatus(sb);
                     mBindBottomCutout = true;
                     mPositionFromBottom = true;
                 } else if (specWithoutDp.startsWith(CENTER_VERTICAL_MARKER, currentIndex)) {
                     parseSvgPathSpec(region, sb.toString());
                     currentIndex += CENTER_VERTICAL_MARKER.length();

                     /* prepare to parse the rest path */
                     resetStatus(sb);
                     mPositionFromCenterVertical = true;
                 } else if (specWithoutDp.startsWith(CUTOUT_MARKER, currentIndex)) {
                     parseSvgPathSpec(region, sb.toString());
                     currentIndex += CUTOUT_MARKER.length();

                     /* prepare to parse the rest path */
                     resetStatus(sb);
                 } else if (specWithoutDp.startsWith(BIND_LEFT_CUTOUT_MARKER, currentIndex)) {
                     mBindBottomCutout = false;
                     mBindRightCutout = false;
                     mBindLeftCutout = true;

                     currentIndex += BIND_LEFT_CUTOUT_MARKER.length();
                 } else if (specWithoutDp.startsWith(BIND_RIGHT_CUTOUT_MARKER, currentIndex)) {
                     mBindBottomCutout = false;
                     mBindLeftCutout = false;
                     mBindRightCutout = true;

                     currentIndex += BIND_RIGHT_CUTOUT_MARKER.length();
                 } else {
                     currentIndex += 1;
                 }

                 lastIndex = currentIndex;
             }

             if (sb == null) {
                 parseSvgPathSpec(region, specWithoutDp);
             } else {
                 sb.append(specWithoutDp, lastIndex, specWithoutDp.length());
                 parseSvgPathSpec(region, sb.toString());
             }

             region.recycle();
         }

         /**
          * To parse specification string as the CutoutSpecification.
          *
          * @param originalSpec the specification string
          * @return the CutoutSpecification instance
          */
         @VisibleForTesting(visibility = PACKAGE)
         public CutoutSpecification parse(@NonNull String originalSpec) {
             Objects.requireNonNull(originalSpec);

             int dpIndex = originalSpec.lastIndexOf(DP_MARKER);
             mInDp = (dpIndex != -1);
             final String spec;
             if (dpIndex != -1) {
                 spec = originalSpec.substring(0, dpIndex)
                         + originalSpec.substring(dpIndex + DP_MARKER.length());
             } else {
                 spec = originalSpec;
             }

             parseSpecWithoutDp(spec);
             mInsets = Insets.of(mSafeInsetLeft, mSafeInsetTop, mSafeInsetRight, mSafeInsetBottom);
             return new CutoutSpecification(this);
         }
     }
 }
	/*
	* Copyright (C) 2020 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package android.view;

	import static android.view.Gravity.BOTTOM;
	import static android.view.Gravity.LEFT;
	import static android.view.Gravity.RIGHT;
	import static android.view.Gravity.TOP;

	import static com.android.internal.annotations.VisibleForTesting.Visibility.PACKAGE;

	import android.annotation.NonNull;
	import android.annotation.Nullable;
	import android.graphics.Insets;
	import android.graphics.Matrix;
	import android.graphics.Path;
	import android.graphics.Rect;
	import android.graphics.RectF;
	import android.graphics.Region;
	import android.text.TextUtils;
	import android.util.Log;
	import android.util.PathParser;

	import com.android.internal.annotations.VisibleForTesting;

	import java.util.Locale;
	import java.util.Objects;

	/**
	* In order to accept the cutout specification for all of edges in devices, the specification
	* parsing method is extracted from
	* {@link android.view.DisplayCutout#fromResourcesRectApproximation(Resources, int, int)} to be
	* the specified class for parsing the specification.
	* BNF definition:
	* <ul>
	* <li>Cutouts Specification = ([Cutout Delimiter],Cutout Specification) {...}, [Dp] ; </li>
	* <li>Cutout Specification = [Vertical Position], (SVG Path Element), [Horizontal Position]
	* [Bind Cutout] ;</li>
	* <li>Vertical Position = "@bottom" \| "@center_vertical" ;</li>
	* <li>Horizontal Position = "@left" \| "@right" ;</li>
	* <li>Bind Cutout = "@bind_left_cutout" \| "@bind_right_cutout" ;</li>
	* <li>Cutout Delimiter = "@cutout" ;</li>
	* <li>Dp = "@dp"</li>
	* </ul>
	*
	* <ul>
	* <li>Vertical position is top by default if there is neither "@bottom" nor "@center_vertical"
	* </li>
	* <li>Horizontal position is center horizontal by default if there is neither "@left" nor
	* "@right".</li>
	* <li>@bottom make the cutout piece bind to bottom edge.</li>
	* <li>both of @bind_left_cutout and @bind_right_cutout are use to claim the cutout belong to
	* left or right edge cutout.</li>
	* </ul>
	*
	* @hide
	*/
	@VisibleForTesting(visibility = PACKAGE)
	public class CutoutSpecification {
	private static final String TAG = "CutoutSpecification";
	private static final boolean DEBUG = false;

	private static final int MINIMAL_ACCEPTABLE_PATH_LENGTH = "H1V1Z".length();

	private static final char MARKER_START_CHAR = '@';
	private static final String DP_MARKER = MARKER_START_CHAR + "dp";

	private static final String BOTTOM_MARKER = MARKER_START_CHAR + "bottom";
	private static final String RIGHT_MARKER = MARKER_START_CHAR + "right";
	private static final String LEFT_MARKER = MARKER_START_CHAR + "left";
	private static final String CUTOUT_MARKER = MARKER_START_CHAR + "cutout";
	private static final String CENTER_VERTICAL_MARKER = MARKER_START_CHAR + "center_vertical";

	/* By default, it's top bound cutout. That's why TOP_BOUND_CUTOUT_MARKER is not defined */
	private static final String BIND_RIGHT_CUTOUT_MARKER = MARKER_START_CHAR + "bind_right_cutout";
	private static final String BIND_LEFT_CUTOUT_MARKER = MARKER_START_CHAR + "bind_left_cutout";

	private final Path mPath;
	private final Rect mLeftBound;
	private final Rect mTopBound;
	private final Rect mRightBound;
	private final Rect mBottomBound;
	private Insets mInsets;

	private CutoutSpecification(@NonNull Parser parser) {
	mPath = parser.mPath;
	mLeftBound = parser.mLeftBound;
	mTopBound = parser.mTopBound;
	mRightBound = parser.mRightBound;
	mBottomBound = parser.mBottomBound;
	mInsets = parser.mInsets;

	applyPhysicalPixelDisplaySizeRatio(parser.mPhysicalPixelDisplaySizeRatio);

	if (DEBUG) {
	Log.d(TAG, String.format(Locale.ENGLISH,
	"left cutout = %s, top cutout = %s, right cutout = %s, bottom cutout = %s",
	mLeftBound != null ? mLeftBound.toString() : "",
	mTopBound != null ? mTopBound.toString() : "",
	mRightBound != null ? mRightBound.toString() : "",
	mBottomBound != null ? mBottomBound.toString() : ""));
	}
	}

	private void applyPhysicalPixelDisplaySizeRatio(float physicalPixelDisplaySizeRatio) {
	if (physicalPixelDisplaySizeRatio == 1f) {
	return;
	}

	if (mPath != null && !mPath.isEmpty()) {
	final Matrix matrix = new Matrix();
	matrix.postScale(physicalPixelDisplaySizeRatio, physicalPixelDisplaySizeRatio);
	mPath.transform(matrix);
	}

	scaleBounds(mLeftBound, physicalPixelDisplaySizeRatio);
	scaleBounds(mTopBound, physicalPixelDisplaySizeRatio);
	scaleBounds(mRightBound, physicalPixelDisplaySizeRatio);
	scaleBounds(mBottomBound, physicalPixelDisplaySizeRatio);
	mInsets = scaleInsets(mInsets, physicalPixelDisplaySizeRatio);
	}

	private void scaleBounds(Rect r, float ratio) {
	if (r != null && !r.isEmpty()) {
	r.scale(ratio);
	}
	}

	private Insets scaleInsets(Insets insets, float ratio) {
	return Insets.of(
	(int) (insets.left * ratio + 0.5f),
	(int) (insets.top * ratio + 0.5f),
	(int) (insets.right * ratio + 0.5f),
	(int) (insets.bottom * ratio + 0.5f));
	}

	@VisibleForTesting(visibility = PACKAGE)
	@Nullable
	public Path getPath() {
	return mPath;
	}

	@VisibleForTesting(visibility = PACKAGE)
	@Nullable
	public Rect getLeftBound() {
	return mLeftBound;
	}

	@VisibleForTesting(visibility = PACKAGE)
	@Nullable
	public Rect getTopBound() {
	return mTopBound;
	}

	@VisibleForTesting(visibility = PACKAGE)
	@Nullable
	public Rect getRightBound() {
	return mRightBound;
	}

	@VisibleForTesting(visibility = PACKAGE)
	@Nullable
	public Rect getBottomBound() {
	return mBottomBound;
	}

	/**
	* To count the safe inset according to the cutout bounds and waterfall inset.
	*
	* @return the safe inset.
	*/
	@VisibleForTesting(visibility = PACKAGE)
	@NonNull
	public Rect getSafeInset() {
	return mInsets.toRect();
	}

	private static int decideWhichEdge(boolean isTopEdgeShortEdge,
	boolean isShortEdge, boolean isStart) {
	return (isTopEdgeShortEdge)
	? ((isShortEdge) ? (isStart ? TOP : BOTTOM) : (isStart ? LEFT : RIGHT))
	: ((isShortEdge) ? (isStart ? LEFT : RIGHT) : (isStart ? TOP : BOTTOM));
	}

	/**
	* The CutoutSpecification Parser.
	*/
	@VisibleForTesting(visibility = PACKAGE)
	public static class Parser {
	private final boolean mIsShortEdgeOnTop;
	private final float mStableDensity;
	private final int mPhysicalDisplayWidth;
	private final int mPhysicalDisplayHeight;
	private final float mPhysicalPixelDisplaySizeRatio;
	private final Matrix mMatrix;
	private Insets mInsets;
	private int mSafeInsetLeft;
	private int mSafeInsetTop;
	private int mSafeInsetRight;
	private int mSafeInsetBottom;

	private final Rect mTmpRect = new Rect();
	private final RectF mTmpRectF = new RectF();

	private boolean mInDp;

	private Path mPath;
	private Rect mLeftBound;
	private Rect mTopBound;
	private Rect mRightBound;
	private Rect mBottomBound;

	private boolean mPositionFromLeft = false;
	private boolean mPositionFromRight = false;
	private boolean mPositionFromBottom = false;
	private boolean mPositionFromCenterVertical = false;

	private boolean mBindLeftCutout = false;
	private boolean mBindRightCutout = false;
	private boolean mBindBottomCutout = false;

	private boolean mIsTouchShortEdgeStart;
	private boolean mIsTouchShortEdgeEnd;
	private boolean mIsCloserToStartSide;

	@VisibleForTesting(visibility = PACKAGE)
	public Parser(float stableDensity, int physicalDisplayWidth,
	int physicalDisplayHeight) {
	this(stableDensity, physicalDisplayWidth, physicalDisplayHeight, 1f);
	}

	/**
	* The constructor of the CutoutSpecification parser to parse the specification of cutout.
	* @param stableDensity the display density.
	* @param physicalDisplayWidth the display width.
	* @param physicalDisplayHeight the display height.
	* @param physicalPixelDisplaySizeRatio the display size ratio based on stable display size.
	*/
	Parser(float stableDensity, int physicalDisplayWidth, int physicalDisplayHeight,
	float physicalPixelDisplaySizeRatio) {
	mStableDensity = stableDensity;
	mPhysicalDisplayWidth = physicalDisplayWidth;
	mPhysicalDisplayHeight = physicalDisplayHeight;
	mPhysicalPixelDisplaySizeRatio = physicalPixelDisplaySizeRatio;
	mMatrix = new Matrix();
	mIsShortEdgeOnTop = mPhysicalDisplayWidth < mPhysicalDisplayHeight;
	}

	private void computeBoundsRectAndAddToRegion(Path p, Region inoutRegion, Rect inoutRect) {
	mTmpRectF.setEmpty();
	p.computeBounds(mTmpRectF, false /* unused */);
	mTmpRectF.round(inoutRect);
	inoutRegion.op(inoutRect, Region.Op.UNION);
	}

	private void resetStatus(StringBuilder sb) {
	sb.setLength(0);
	mPositionFromBottom = false;
	mPositionFromLeft = false;
	mPositionFromRight = false;
	mPositionFromCenterVertical = false;

	mBindLeftCutout = false;
	mBindRightCutout = false;
	mBindBottomCutout = false;
	}

	private void translateMatrix() {
	final float offsetX;
	if (mPositionFromRight) {
	offsetX = mPhysicalDisplayWidth;
	} else if (mPositionFromLeft) {
	offsetX = 0;
	} else {
	offsetX = mPhysicalDisplayWidth / 2f;
	}

	final float offsetY;
	if (mPositionFromBottom) {
	offsetY = mPhysicalDisplayHeight;
	} else if (mPositionFromCenterVertical) {
	offsetY = mPhysicalDisplayHeight / 2f;
	} else {
	offsetY = 0;
	}

	mMatrix.reset();
	if (mInDp) {
	mMatrix.postScale(mStableDensity, mStableDensity);
	}
	mMatrix.postTranslate(offsetX, offsetY);
	}

	private int computeSafeInsets(int gravity, Rect rect) {
	if (gravity == LEFT && rect.right > 0 && rect.right < mPhysicalDisplayWidth) {
	return rect.right;
	} else if (gravity == TOP && rect.bottom > 0 && rect.bottom < mPhysicalDisplayHeight) {
	return rect.bottom;
	} else if (gravity == RIGHT && rect.left > 0 && rect.left < mPhysicalDisplayWidth) {
	return mPhysicalDisplayWidth - rect.left;
	} else if (gravity == BOTTOM && rect.top > 0 && rect.top < mPhysicalDisplayHeight) {
	return mPhysicalDisplayHeight - rect.top;
	}
	return 0;
	}

	private void setSafeInset(int gravity, int inset) {
	if (gravity == LEFT) {
	mSafeInsetLeft = inset;
	} else if (gravity == TOP) {
	mSafeInsetTop = inset;
	} else if (gravity == RIGHT) {
	mSafeInsetRight = inset;
	} else if (gravity == BOTTOM) {
	mSafeInsetBottom = inset;
	}
	}

	private int getSafeInset(int gravity) {
	if (gravity == LEFT) {
	return mSafeInsetLeft;
	} else if (gravity == TOP) {
	return mSafeInsetTop;
	} else if (gravity == RIGHT) {
	return mSafeInsetRight;
	} else if (gravity == BOTTOM) {
	return mSafeInsetBottom;
	}
	return 0;
	}

	@NonNull
	private Rect onSetEdgeCutout(boolean isStart, boolean isShortEdge, @NonNull Rect rect) {
	final int gravity;
	if (isShortEdge) {
	gravity = decideWhichEdge(mIsShortEdgeOnTop, true, isStart);
	} else {
	if (mIsTouchShortEdgeStart && mIsTouchShortEdgeEnd) {
	gravity = decideWhichEdge(mIsShortEdgeOnTop, false, isStart);
	} else if (mIsTouchShortEdgeStart \|\| mIsTouchShortEdgeEnd) {
	gravity = decideWhichEdge(mIsShortEdgeOnTop, true,
	mIsCloserToStartSide);
	} else {
	gravity = decideWhichEdge(mIsShortEdgeOnTop, isShortEdge, isStart);
	}
	}

	int oldSafeInset = getSafeInset(gravity);
	int newSafeInset = computeSafeInsets(gravity, rect);
	if (oldSafeInset < newSafeInset) {
	setSafeInset(gravity, newSafeInset);
	}

	return new Rect(rect);
	}

	private void setEdgeCutout(@NonNull Path newPath) {
	if (mBindRightCutout && mRightBound == null) {
	mRightBound = onSetEdgeCutout(false, !mIsShortEdgeOnTop, mTmpRect);
	} else if (mBindLeftCutout && mLeftBound == null) {
	mLeftBound = onSetEdgeCutout(true, !mIsShortEdgeOnTop, mTmpRect);
	} else if (mBindBottomCutout && mBottomBound == null) {
	mBottomBound = onSetEdgeCutout(false, mIsShortEdgeOnTop, mTmpRect);
	} else if (!(mBindBottomCutout \|\| mBindLeftCutout \|\| mBindRightCutout)
	&& mTopBound == null) {
	mTopBound = onSetEdgeCutout(true, mIsShortEdgeOnTop, mTmpRect);
	} else {
	return;
	}

	if (mPath != null) {
	mPath.addPath(newPath);
	} else {
	mPath = newPath;
	}
	}

	private void parseSvgPathSpec(Region region, String spec) {
	if (TextUtils.length(spec) < MINIMAL_ACCEPTABLE_PATH_LENGTH) {
	Log.e(TAG, "According to SVG definition, it shouldn't happen");
	return;
	}
	translateMatrix();

	final Path newPath = PathParser.createPathFromPathData(spec);
	newPath.transform(mMatrix);
	computeBoundsRectAndAddToRegion(newPath, region, mTmpRect);

	if (DEBUG) {
	Log.d(TAG, String.format(Locale.ENGLISH,
	"hasLeft = %b, hasRight = %b, hasBottom = %b, hasCenterVertical = %b",
	mPositionFromLeft, mPositionFromRight, mPositionFromBottom,
	mPositionFromCenterVertical));
	Log.d(TAG, "region = " + region);
	Log.d(TAG, "spec = \"" + spec + "\" rect = " + mTmpRect + " newPath = " + newPath);
	}

	if (mTmpRect.isEmpty()) {
	return;
	}

	if (mIsShortEdgeOnTop) {
	mIsTouchShortEdgeStart = mTmpRect.top <= 0;
	mIsTouchShortEdgeEnd = mTmpRect.bottom >= mPhysicalDisplayHeight;
	mIsCloserToStartSide = mTmpRect.centerY() < mPhysicalDisplayHeight / 2;
	} else {
	mIsTouchShortEdgeStart = mTmpRect.left <= 0;
	mIsTouchShortEdgeEnd = mTmpRect.right >= mPhysicalDisplayWidth;
	mIsCloserToStartSide = mTmpRect.centerX() < mPhysicalDisplayWidth / 2;
	}

	setEdgeCutout(newPath);
	}

	private void parseSpecWithoutDp(@NonNull String specWithoutDp) {
	Region region = Region.obtain();
	StringBuilder sb = null;
	int currentIndex = 0;
	int lastIndex = 0;
	while ((currentIndex = specWithoutDp.indexOf(MARKER_START_CHAR, lastIndex)) != -1) {
	if (sb == null) {
	sb = new StringBuilder(specWithoutDp.length());
	}
	sb.append(specWithoutDp, lastIndex, currentIndex);

	if (specWithoutDp.startsWith(LEFT_MARKER, currentIndex)) {
	if (!mPositionFromRight) {
	mPositionFromLeft = true;
	}
	currentIndex += LEFT_MARKER.length();
	} else if (specWithoutDp.startsWith(RIGHT_MARKER, currentIndex)) {
	if (!mPositionFromLeft) {
	mPositionFromRight = true;
	}
	currentIndex += RIGHT_MARKER.length();
	} else if (specWithoutDp.startsWith(BOTTOM_MARKER, currentIndex)) {
	parseSvgPathSpec(region, sb.toString());
	currentIndex += BOTTOM_MARKER.length();

	/* prepare to parse the rest path */
	resetStatus(sb);
	mBindBottomCutout = true;
	mPositionFromBottom = true;
	} else if (specWithoutDp.startsWith(CENTER_VERTICAL_MARKER, currentIndex)) {
	parseSvgPathSpec(region, sb.toString());
	currentIndex += CENTER_VERTICAL_MARKER.length();

	/* prepare to parse the rest path */
	resetStatus(sb);
	mPositionFromCenterVertical = true;
	} else if (specWithoutDp.startsWith(CUTOUT_MARKER, currentIndex)) {
	parseSvgPathSpec(region, sb.toString());
	currentIndex += CUTOUT_MARKER.length();

	/* prepare to parse the rest path */
	resetStatus(sb);
	} else if (specWithoutDp.startsWith(BIND_LEFT_CUTOUT_MARKER, currentIndex)) {
	mBindBottomCutout = false;
	mBindRightCutout = false;
	mBindLeftCutout = true;

	currentIndex += BIND_LEFT_CUTOUT_MARKER.length();
	} else if (specWithoutDp.startsWith(BIND_RIGHT_CUTOUT_MARKER, currentIndex)) {
	mBindBottomCutout = false;
	mBindLeftCutout = false;
	mBindRightCutout = true;

	currentIndex += BIND_RIGHT_CUTOUT_MARKER.length();
	} else {
	currentIndex += 1;
	}

	lastIndex = currentIndex;
	}

	if (sb == null) {
	parseSvgPathSpec(region, specWithoutDp);
	} else {
	sb.append(specWithoutDp, lastIndex, specWithoutDp.length());
	parseSvgPathSpec(region, sb.toString());
	}

	region.recycle();
	}

	/**
	* To parse specification string as the CutoutSpecification.
	*
	* @param originalSpec the specification string
	* @return the CutoutSpecification instance
	*/
	@VisibleForTesting(visibility = PACKAGE)
	public CutoutSpecification parse(@NonNull String originalSpec) {
	Objects.requireNonNull(originalSpec);

	int dpIndex = originalSpec.lastIndexOf(DP_MARKER);
	mInDp = (dpIndex != -1);
	final String spec;
	if (dpIndex != -1) {
	spec = originalSpec.substring(0, dpIndex)
	+ originalSpec.substring(dpIndex + DP_MARKER.length());
	} else {
	spec = originalSpec;
	}

	parseSpecWithoutDp(spec);
	mInsets = Insets.of(mSafeInsetLeft, mSafeInsetTop, mSafeInsetRight, mSafeInsetBottom);
	return new CutoutSpecification(this);
	}
	}
	}