Merge "Update TrustedPresentationListener docs and update exceptions" into main
diff --git a/core/java/android/view/WindowManager.java b/core/java/android/view/WindowManager.java
index ac2a66e..58fb273 100644
--- a/core/java/android/view/WindowManager.java
+++ b/core/java/android/view/WindowManager.java
@@ -6016,16 +6016,63 @@
}
/**
- * Add a trusted presentation listener associated with a window.
+ * Sets a callback to receive feedback about the presentation of a {@link Window}.
+ * When the {@link Window} is presented according to the passed in
+ * {@link TrustedPresentationThresholds}, it is said to "enter the state", and receives the
+ * callback with {@code true}. When the conditions fall out of thresholds, it is then
+ * said to leave the state and the caller will receive a callback with {@code false}. The
+ * callbacks be sent for every state transition thereafter.
+ * <p>
+ * There are a few simple thresholds:
+ * <ul>
+ * <li>minAlpha: Lower bound on computed alpha</li>
+ * <li>minFractionRendered: Lower bounds on fraction of pixels that were rendered</li>
+ * <li>stabilityThresholdMs: A time that alpha and fraction rendered must remain within
+ * bounds before we can "enter the state" </li>
+ * </ul>
+ * <p>
+ * The fraction of pixels rendered is a computation based on scale, crop
+ * and occlusion. The calculation may be somewhat counterintuitive, so we
+ * can work through an example. Imagine we have a Window with a 100x100 buffer
+ * which is occluded by (10x100) pixels on the left, and cropped by (100x10) pixels
+ * on the top. Furthermore imagine this Window is scaled by 0.9 in both dimensions.
+ * (c=crop,o=occluded,b=both,x=none)
*
- * <p> If this listener is already registered then the window and thresholds will be updated.
+ * <blockquote>
+ * <table>
+ * <caption></caption>
+ * <tr><td>b</td><td>c</td><td>c</td><td>c</td></tr>
+ * <tr><td>o</td><td>x</td><td>x</td><td>x</td></tr>
+ * <tr><td>o</td><td>x</td><td>x</td><td>x</td></tr>
+ * <tr><td>o</td><td>x</td><td>x</td><td>x</td></tr>
+ * </table>
+ * </blockquote>
*
- * @param window The Window to add the trusted presentation listener for
- * @param thresholds The {@link TrustedPresentationThresholds} that will specify
- * when the to invoke the callback.
+ *<p>
+ * We first start by computing fr=xscale*yscale=0.9*0.9=0.81, indicating
+ * that "81%" of the pixels were rendered. This corresponds to what was 100
+ * pixels being displayed in 81 pixels. This is somewhat of an abuse of
+ * language, as the information of merged pixels isn't totally lost, but
+ * we err on the conservative side.
+ * <p>
+ * We then repeat a similar process for the crop and covered regions and
+ * accumulate the results: fr = fr * (fractionNotCropped) * (fractionNotCovered)
+ * So for this example we would get 0.9*0.9*0.9*0.9=0.65...
+ * <p>
+ * Notice that this is not completely accurate, as we have double counted
+ * the region marked as b. However we only wanted a "lower bound" and so it
+ * is ok to err in this direction. Selection of the threshold will ultimately
+ * be somewhat arbitrary, and so there are some somewhat arbitrary decisions in
+ * this API as well.
+ * <p>
+ * @param window The Window to add the trusted presentation listener for. This can be
+ * retrieved from {@link View#getWindowToken()}.
+ * @param thresholds The {@link TrustedPresentationThresholds} that will specify when the to
+ * invoke the callback.
* @param executor The {@link Executor} where the callback will be invoked on.
* @param listener The {@link Consumer} that will receive the callbacks
- * when entered or exited trusted presentation per the thresholds.
+ * when entered or exited trusted presentation per the thresholds.
+ * @see TrustedPresentationThresholds
*/
@FlaggedApi(Flags.FLAG_TRUSTED_PRESENTATION_LISTENER_FOR_WINDOW)
default void registerTrustedPresentationListener(@NonNull IBinder window,
diff --git a/core/java/android/view/WindowManagerGlobal.java b/core/java/android/view/WindowManagerGlobal.java
index 848261d..f92c31b 100644
--- a/core/java/android/view/WindowManagerGlobal.java
+++ b/core/java/android/view/WindowManagerGlobal.java
@@ -950,7 +950,7 @@
WindowManagerGlobal.getWindowManagerService()
.registerTrustedPresentationListener(window, this, thresholds, id);
} catch (RemoteException e) {
- e.rethrowAsRuntimeException();
+ e.rethrowFromSystemServer();
}
}
}
@@ -967,7 +967,7 @@
WindowManagerGlobal.getWindowManagerService()
.unregisterTrustedPresentationListener(this, removedListener.first);
} catch (RemoteException e) {
- e.rethrowAsRuntimeException();
+ e.rethrowFromSystemServer();
}
}
}