Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 86c4ec64 authored by Vishnu Nair's avatar Vishnu Nair
Browse files

Update TrustedPresentationListener docs and update exceptions 

Document what kind of tokens can be passed into the API
registerTrustedPresentationListener (and @link the APIs where you can get those tokens)
Add docs for  registerTrustedPresentationListener methods (copied
from similar API from SurfaceControl)
Change rethrowAsRuntimeException to rethrowFromSystemServer for remote
expections caught when calling into WMS

Test: presubmit
Fixes: 316093854
Change-Id: I102cf5ed4ceda1ea726ddda1e842b58a4a3c0388
parent 27393542

core/java/android/view/WindowManager.java

+55 −8
Original line number Original line Diff line number Diff line
@@ -6016,16 +6016,63 @@ public interface WindowManager extends ViewManager { 
    }

    }





    /**

    /**

     * 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

     * <p> If this listener is already registered then the window and thresholds will be updated.

     * {@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)

     *

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

     *<p>

     * @param thresholds The {@link TrustedPresentationThresholds} that will specify

     * We first start by computing fr=xscale*yscale=0.9*0.9=0.81, indicating

     *                   when the to invoke the callback.

     * 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 executor   The {@link Executor} where the callback will be invoked on.

     * @param listener   The {@link Consumer} that will receive the callbacks

     * @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)

    @FlaggedApi(Flags.FLAG_TRUSTED_PRESENTATION_LISTENER_FOR_WINDOW)

    default void registerTrustedPresentationListener(@NonNull IBinder window,

    default void registerTrustedPresentationListener(@NonNull IBinder window,

core/java/android/view/WindowManagerGlobal.java

+2 −2
Original line number Original line Diff line number Diff line
@@ -950,7 +950,7 @@ public final class WindowManagerGlobal { 
                    WindowManagerGlobal.getWindowManagerService()

                    WindowManagerGlobal.getWindowManagerService()

                            .registerTrustedPresentationListener(window, this, thresholds, id);

                            .registerTrustedPresentationListener(window, this, thresholds, id);

                } catch (RemoteException e) {

                } catch (RemoteException e) {

                    e.rethrowAsRuntimeException();

                    e.rethrowFromSystemServer();

                }

                }

            }

            }

        }

        }
@@ -967,7 +967,7 @@ public final class WindowManagerGlobal { 
                    WindowManagerGlobal.getWindowManagerService()

                    WindowManagerGlobal.getWindowManagerService()

                            .unregisterTrustedPresentationListener(this, removedListener.first);

                            .unregisterTrustedPresentationListener(this, removedListener.first);

                } catch (RemoteException e) {

                } catch (RemoteException e) {

                    e.rethrowAsRuntimeException();

                    e.rethrowFromSystemServer();

                }

                }

            }

            }

        }

        }