[Android][Client] Updating the calculations used for image overpanning

remoting/android/java/src/org/chromium/chromoting/DesktopCanvas.java

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 package org.chromium.chromoting;
 
 import android.graphics.Matrix;
 import android.graphics.PointF;
 import android.graphics.Rect;
 import android.graphics.RectF;
 
 /**
  * This class is responsible for transforming the desktop image matrix.
  */
 public class DesktopCanvas {
-    /**
-     * Maximum allowed zoom level - see {@link #scaleAndRepositionImage()}.
-     */
+    /** Used for floating point comparisons. */
+    private static final float EPSILON = 0.0001f;
+
+    /** Maximum allowed zoom level - see {@link #scaleAndRepositionImage()}. */
     private static final float MAX_ZOOM_FACTOR = 100.0f;
 
-    /**
-     * Used to smoothly reduce the amount of padding while the user is zooming.
-     */
-    private static final float PADDING_REDUCTION_FACTOR = 0.85f;
+    /** Used to smoothly reduce the viewport offset. */
+    private static final float VIEWPORT_OFFSET_REDUCTION_FACTOR = 0.85f;
+
+    /** Used to terminate the viewport offset animation once this value has been reached. */
+    private static final float MINIMUM_VIEWPORT_OFFSET_PIXELS = 1;
 
     private final RenderStub mRenderStub;
     private final RenderData mRenderData;
 
     /**
-     * Represents the actual center of the viewport in image space.  This value needs to be a pair
-     * of floats so the desktop image can be positioned with sub-pixel accuracy for smoother panning
-     * animations at high zoom levels.
-     */
-    // TODO(joedow): See if we can collapse Viewport and Cursor position members.  They were needed
-    // in the past due to how we calculated the center positions but may not be needed now.
-    private PointF mViewportPosition = new PointF();
-
-    /**
      * Represents the desired center of the viewport in image space.  This value may not represent
      * the actual center of the viewport as adjustments are made to ensure as much of the desktop is
      * visible as possible.  This value needs to be a pair of floats so the desktop image can be
      * positioned with sub-pixel accuracy for smoother panning animations at high zoom levels.
-     * Note: The internal cursor position may be placed outside of the image boundary, however the
-     * cursor position we inject on the host side is restricted to the actual image dimensions.
      */
     private PointF mCursorPosition = new PointF();

[Yuwei, 2016/10/25 08:25:26]

Maybe not for this CL. If this is the desired center of the viewport, could it
be better to call it mDesiredCenter? I think it is slightly weird to introduce
the idea of cursor position when changing viewport.

[joedow, 2016/10/25 16:49:50]

Lambros and I have talked about this a bit already, I'm fine changing the name
in this CL.

 
     /**
-     * Represents the amount of space, in pixels, used by System UI on each edge of the screen.
+     * If System UI exists, this contains the area of the screen which is unobscured by it,
+     * otherwise it is empty.
      */
-    // TODO(joedow): Update usage of this member so it is a true Rect instead of a set of offsets.
-    private Rect mSystemUiScreenSize = new Rect();
+    private Rect mSystemUiScreenRect = new Rect();
 
     /**
-     * Represents the amount of padding, in screen pixels, added to each edge of the desktop image.
-     * This extra space allows the user to reveal portions of the desktop image which are obscured
-     * by System UI.
+     * Represents the amount of space, in pixels, to shift the image under the viewport.  This value
+     * is used to allow panning the image further than would be possible when using the normal
+     * boundary values to account for System UI.  This functionality ensures the user can view and
+     * interact with any area of the remote image, even when System UI might otherwise obscure it.
      */
-    private RectF mVisibleImagePadding = new RectF();
+    private PointF mViewportOffset = new PointF();
 
     /**
-     * Tracks whether to adjust the viewport to account for System UI. If false, the viewport
-     * center is the center of the screen.  If true, then System UI offsets will be used to
-     * adjust the position of the viewport to ensure the cursor is visible.
+     * Tracks whether to adjust the size of the viewport to account for System UI. If false, the
+     * viewport center is mapped to the center of the screen.  If true, then System UI sizes will be
+     * used to determine the center of the viewport.
      */
-    private boolean mAdjustViewportForSystemUi = false;
+    private boolean mAdjustViewportSizeForSystemUi = false;
 
-    /**
-    * Represents the amount of space, in pixels, to adjust the cursor center along the y-axis.
-    */
-    private float mCursorOffsetScreenY = 0.0f;
+    /* Used to perform per-frame rendering tasks. */
+    private Event.ParameterCallback<Boolean, Void> mFrameRenderedCallback;
 
     public DesktopCanvas(RenderStub renderStub, RenderData renderData) {
         mRenderStub = renderStub;
         mRenderData = renderData;
     }
 
     /**
-     * Sets the desired center position of the viewport (a.k.a. the cursor position) and ensures
-     * the viewport is updated to include the cursor within it.
+     * Sets the desired center position of the viewport (a.k.a. the cursor position).
      *
      * @param newX The new x coordinate value for the desired center position.
      * @param newY The new y coordinate value for the desired center position.
      */
     public void setCursorPosition(float newX, float newY) {
-        // First set the cursor position since its potential values are a superset of the viewport.
-        mCursorPosition.set(newX, newY);
-        constrainPointToBounds(mCursorPosition, getImageBounds());
+        updateCursorPosition(newX, newY, getImageBounds());
+    }
 
-        // Now set the viewport position based on the cursor.
-        mViewportPosition.set(mCursorPosition);
-        constrainPointToBounds(mViewportPosition, getViewportBounds());
+    /**
+     * Sets the center of the viewport using an absolute position (in image coordinates).
+     *
+     * @param newX The new x coordinate value for the center position of the viewport.
+     * @param newY The new y coordinate value for the center position of the viewport.
+     */
+    public void setViewportCenter(float newX, float newY) {
+        updateCursorPosition(newX, newY, getViewportBounds());
+    }
 
-        repositionImage();
+    /**
+     * Shifts the cursor by the passed in values (in image coordinates).
+     *
+     * @param deltaX The distance (in image coordinates) to move the cursor along the x-axis.
+     * @param deltaY The distance (in image coordinates) to move the cursor along the y-axis.
+     * @return A point representing the new cursor position.
+     */
+    public PointF moveCursorPosition(float deltaX, float deltaY) {
+        updateCursorPosition(
+                mCursorPosition.x + deltaX, mCursorPosition.y + deltaY, getImageBounds());
+        return new PointF(mCursorPosition.x, mCursorPosition.y);
     }
 
     /**
      * Shifts the viewport by the passed in values (in image coordinates).
      *
      * @param deltaX The distance (in image coordinates) to move the viewport along the x-axis.
      * @param deltaY The distance (in image coordinates) to move the viewport along the y-axis.
      */
     public void moveViewportCenter(float deltaX, float deltaY) {
-        // Offset and adjust the viewport center position to fit the screen.
-        mViewportPosition.offset(deltaX, deltaY);
-        constrainPointToBounds(mViewportPosition, getViewportBounds());
-
-        // We don't need to constrain the cursor position as the viewport position is always within
-        // the bounds of the potential cursor positions.
-        mCursorPosition.set(mViewportPosition);
-
-        repositionImage();
-    }
-
-    /**
-     * Shifts the cursor by the passed in values (in image coordinates) and adjusts the viewport.
-     *
-     * @param deltaX The distance (in image coordinates) to move the cursor along the x-axis.
-     * @param deltaY The distance (in image coordinates) to move the cursor along the y-axis.
-     * @return A point representing the new cursor position.
-     */
-    public PointF moveCursorPosition(float deltaX, float deltaY) {
-        setCursorPosition(mCursorPosition.x + deltaX, mCursorPosition.y + deltaY);
-        return new PointF(mCursorPosition.x, mCursorPosition.y);
+        updateCursorPosition(
+                mCursorPosition.x + deltaX, mCursorPosition.y + deltaY, getViewportBounds());
     }
 
     /**
      * Handles System UI size and visibility changes.
      *
      * @param parameter The set of values defining the current System UI state.
      */
     public void onSystemUiVisibilityChanged(SystemUiVisibilityChangedEventParameter parameter) {
         if (parameter.softInputMethodVisible) {
-            mSystemUiScreenSize.set(parameter.left, parameter.top,
-                    mRenderData.screenWidth - parameter.right,
-                    mRenderData.screenHeight - parameter.bottom);
+            mSystemUiScreenRect.set(
+                    parameter.left, parameter.top, parameter.right, parameter.bottom);
 
-            if (mAdjustViewportForSystemUi) {
-                // Adjust the cursor position to ensure it's visible when large System UI (1/3 or
-                // more of the total screen size) is displayed (typically the Soft Keyboard).
-                // Without this change, it is difficult for users to enter text into edit controls
-                // which are located bottom of the screen and may not see the cursor at all.
-                if (mSystemUiScreenSize.bottom > (mRenderData.screenHeight / 3)) {
-                    // Center the cursor within the viewable area (not obscured by System UI).
-                    mCursorOffsetScreenY = (float) parameter.bottom / 2.0f;
-                } else {
-                    mCursorOffsetScreenY = 0.0f;
-                }
+            stopOffsetReductionAnimation();
+        } else {
+            mSystemUiScreenRect.setEmpty();
+            startOffsetReductionAnimation();
+        }
 
-                // Apply the cursor offset.
-                setCursorPosition(mCursorPosition.x, mCursorPosition.y);
-            }
-        } else {
-            mCursorOffsetScreenY = 0.0f;
-            mSystemUiScreenSize.setEmpty();
-        }
+        repositionImage();
     }
 
     public void adjustViewportForSystemUi(boolean adjustViewportForSystemUi) {
-        mAdjustViewportForSystemUi = adjustViewportForSystemUi;
+        mAdjustViewportSizeForSystemUi = adjustViewportForSystemUi;
+
+        // The viewport center may have changed so reposition the image to reflect the new value.
+        repositionImage();
     }
 
     /** Resizes the image by zooming it such that the image is displayed without borders. */
     public void resizeImageToFitScreen() {
         // Protect against being called before the image has been initialized.
         if (mRenderData.imageWidth == 0 || mRenderData.imageHeight == 0) {
             return;
         }
 
         float widthRatio = (float) mRenderData.screenWidth / mRenderData.imageWidth;
         float heightRatio = (float) mRenderData.screenHeight / mRenderData.imageHeight;
         float screenToImageScale = Math.max(widthRatio, heightRatio);
 
         // If the image is smaller than the screen in either dimension, then we want to scale it
         // up to fit both and fill the screen with the image of the remote desktop.
         if (screenToImageScale > 1.0f) {
             mRenderData.transform.setScale(screenToImageScale, screenToImageScale);
         }
     }
 
     /**
      * Repositions the image by translating and zooming it, to keep the zoom level within sensible
-     * limits. The minimum zoom level is chosen to avoid black space around all 4 sides. The
+     * limits. The minimum zoom level is chosen to avoid letterboxing on all 4 sides. The
      * maximum zoom level is set arbitrarily, so that the user can zoom out again in a reasonable
      * time, and to prevent arithmetic overflow problems from displaying the image.
      *
      * @param scaleFactor The factor used to zoom the canvas in or out.
      * @param px The center x coordinate for the scale action.
      * @param py The center y coordinate for the scale action.
      * @param centerOnCursor Determines whether the viewport will be translated to the desired
      *                       center position before being adjusted to fit the screen boundaries.
      */
     public void scaleAndRepositionImage(
@@ skipping 16 matching lines @@
         mRenderData.transform.mapVectors(imageSize);
 
         if (imageSize[0] < mRenderData.screenWidth && imageSize[1] < mRenderData.screenHeight) {
             // Displayed image is too small in both directions, so apply the minimum zoom
             // level needed to fit either the width or height.
             float scale = Math.min((float) mRenderData.screenWidth / mRenderData.imageWidth,
                                    (float) mRenderData.screenHeight / mRenderData.imageHeight);
             mRenderData.transform.setScale(scale, scale);
         }
 
-        // Trim the image padding if the user is zooming out.  This prevents cases where the image
-        // pops to the center when it reaches its minimum size.  Note that we do not need to do
-        // anything when the user is zooming in as the canvas will expand and absorb the padding.
-        if (scaleFactor < 1.0f) {
-            mVisibleImagePadding.set(mVisibleImagePadding.left * PADDING_REDUCTION_FACTOR,
-                    mVisibleImagePadding.top * PADDING_REDUCTION_FACTOR,
-                    mVisibleImagePadding.right * PADDING_REDUCTION_FACTOR,
-                    mVisibleImagePadding.bottom * PADDING_REDUCTION_FACTOR);
-        }
-
         if (centerOnCursor) {
             setCursorPosition(mCursorPosition.x, mCursorPosition.y);
         } else {
-            // Find the new screen center (it was probably changed during the zoom operation) and
-            // update the viewport and cursor.
-            float[] mappedPoints = {
-                    ((float) mRenderData.screenWidth / 2), ((float) mRenderData.screenHeight / 2)};
+            // Find the new screen center (it probably changed during the zoom operation) and update
+            // the viewport to smoothly track the zoom gesture.
+            float[] mappedPoints = {((float) mRenderData.screenWidth / 2) - mViewportOffset.x,
+                    ((float) mRenderData.screenHeight / 2) - mViewportOffset.y};
             Matrix screenToImage = new Matrix();
             mRenderData.transform.invert(screenToImage);
             screenToImage.mapPoints(mappedPoints);
             // The cursor is mapped to the center of the viewport in this case.
-            setCursorPosition(mappedPoints[0], mappedPoints[1]);
+            setViewportCenter(mappedPoints[0], mappedPoints[1]);
         }
     }
 
     /**
+     * Sets the new cursor position, bounded by the given rect, and updates the image transform to
+     * reflect the new position.
+     */
+    private void updateCursorPosition(float newX, float newY, RectF bounds) {
+        mCursorPosition.set(newX, newY);
+        constrainPointToBounds(mCursorPosition, bounds);
+
+        calculateViewportOffset(newX - mCursorPosition.x, newY - mCursorPosition.y);
+
+        repositionImage();
+    }
+
+    /**
+     * Returns the height of the screen (in screen coordinates) for use in calculations involving
+     * viewport positioning.
+     */
+    private float getAdjustedScreenHeight() {
+        float adjustedScreenHeight;
+        if (mAdjustViewportSizeForSystemUi && !mSystemUiScreenRect.isEmpty()) {
+            // Find the center point of the viewport on the screen.
+            adjustedScreenHeight = mSystemUiScreenRect.bottom;
+        } else {
+            adjustedScreenHeight = ((float) mRenderData.screenHeight);
+        }
+
+        return adjustedScreenHeight;
+    }
+
+    /**
+     * Returns the center position of the viewport (in screen coordinates) including adjustments.
+     */
+    private PointF getViewportCenter() {
+        return new PointF((float) mRenderData.screenWidth / 2, getAdjustedScreenHeight() / 2);
+    }
+
+    /**
      * Repositions the image by translating it (without affecting the zoom level).
      */
     private void repositionImage() {
-        // Map the current viewport position to screen coordinates and adjust the image position.
-        float[] viewportPosition = {mViewportPosition.x, mViewportPosition.y};
-        mRenderData.transform.mapPoints(viewportPosition);
+        PointF viewportPosition = new PointF(mCursorPosition.x, mCursorPosition.y);
+        constrainPointToBounds(viewportPosition, getViewportBounds());
+        float[] viewportAdjustment = {viewportPosition.x, viewportPosition.y};
+        mRenderData.transform.mapPoints(viewportAdjustment);
 
-        float viewportTransX = ((float) mRenderData.screenWidth / 2) - viewportPosition[0];
-        float viewportTransY =
-                ((float) mRenderData.screenHeight / 2) - viewportPosition[1] - mCursorOffsetScreenY;
+        // Adjust the viewport to include the overpan amount.
+        viewportAdjustment[0] += mViewportOffset.x;
+        viewportAdjustment[1] += mViewportOffset.y;
 
         // Translate the image to move the viewport to the expected screen location.
-        mRenderData.transform.postTranslate(viewportTransX, viewportTransY);
-
-        updateVisibleImagePadding();
+        PointF viewportCenter = getViewportCenter();
+        mRenderData.transform.postTranslate(
+                viewportCenter.x - viewportAdjustment[0], viewportCenter.y - viewportAdjustment[1]);
 
         mRenderStub.setTransformation(mRenderData.transform);
     }
 
     /**
      * Updates the given point such that it refers to a coordinate within the bounds provided.
      *
      * @param point The point to adjust, the original object is modified.
      * @param bounds The bounds used to constrain the point.
      */
     private void constrainPointToBounds(PointF point, RectF bounds) {
         if (point.x < bounds.left) {
             point.x = bounds.left;
         } else if (point.x > bounds.right) {
             point.x = bounds.right;
         }
 
         if (point.y < bounds.top) {
             point.y = bounds.top;
         } else if (point.y > bounds.bottom) {
             point.y = bounds.bottom;
         }
     }
 
     /** Returns a region which defines the set of valid cursor positions in image space. */
     private RectF getImageBounds() {
-        // The set of valid cursor positions includes any point on the image as well as the padding.
-        // Padding is additional space added to the image which is the larger value of:
-        //   - Potential overlap of the System UI and image content
-        //   - Actual amount of padding already being used
-        //
-        // By expanding the area, we allow the user to move the cursor 'under' the System UI which
-        // pulls the content out from under it and allows it to be visible.  Once the System UI has
-        // been dismissed or changes size, we use the actual padding value instead which prevents
-        // the desktop image from 'snapping' back to pre-System UI state.
-        RectF systemUiOverlap = getSystemUiOverlap();
-        float[] padding = {Math.max(mVisibleImagePadding.left, systemUiOverlap.left),
-                Math.max(mVisibleImagePadding.top + mCursorOffsetScreenY, systemUiOverlap.top),
-                Math.max(mVisibleImagePadding.right, systemUiOverlap.right),
-                Math.max(mVisibleImagePadding.bottom - mCursorOffsetScreenY,
-                        systemUiOverlap.bottom)};
-        Matrix screenToImage = new Matrix();
-        mRenderData.transform.invert(screenToImage);
-        screenToImage.mapVectors(padding);
-
-        return new RectF(-padding[0], -padding[1], mRenderData.imageWidth + padding[2],
-                mRenderData.imageHeight + padding[3]);
+        return new RectF(0, 0, mRenderData.imageWidth, mRenderData.imageHeight);
     }
 
     /** Returns a region which defines the set of valid viewport center values in image space. */
     private RectF getViewportBounds() {
         // The region of allowable viewport values is the imageBound rect, inset by the size of the
         // viewport itself.  This prevents over and under panning of the viewport while still
         // allowing the user to see and interact with all pixels one the desktop image.
         Matrix screenToImage = new Matrix();
         mRenderData.transform.invert(screenToImage);
 
-        float[] screenVectors = {(float) mRenderData.screenWidth, (float) mRenderData.screenHeight};
+        PointF viewportCenter = getViewportCenter();
+        float[] screenVectors = {viewportCenter.x, viewportCenter.y};
         screenToImage.mapVectors(screenVectors);
 
         PointF letterboxPadding = getLetterboxPadding();
         float[] letterboxPaddingVectors = {letterboxPadding.x, letterboxPadding.y};
         screenToImage.mapVectors(letterboxPaddingVectors);
 
         // screenCenter values are 1/2 of a particular screen dimension mapped to image space.
-        float screenCenterX = (screenVectors[0] / 2.0f) - letterboxPaddingVectors[0];
-        float screenCenterY = (screenVectors[1] / 2.0f) - letterboxPaddingVectors[1];
+        float screenCenterX = screenVectors[0] - letterboxPaddingVectors[0];
+        float screenCenterY = screenVectors[1] - letterboxPaddingVectors[1];
         RectF imageBounds = getImageBounds();
         imageBounds.inset(screenCenterX, screenCenterY);
         return imageBounds;
     }
 
     /**
+     * Returns a region defining the maximum offset distance required to view the entire image
+     * given the current amount of System UI overlapping it.
+     */
+    private RectF getViewportOffsetBounds() {
+        // The allowable region is determined by:
+        //   - Overlap of the System UI and image content
+        //   - Current viewport offset
+        //
+        // The System UI overlap represents the maximum allowable offset, this is used to bound the
+        // viewport movement in each direction.  The current offset is used to prevent 'snapping'
+        // the image when the System UI overlap is reduced.
+        RectF viewportOffsetRect = new RectF();
+        viewportOffsetRect.union(mViewportOffset.x, mViewportOffset.y);
+
+        RectF systemUiOverlap = getSystemUiOverlap();
+        return new RectF(Math.min(viewportOffsetRect.left, -systemUiOverlap.left),
+                Math.min(viewportOffsetRect.top, -systemUiOverlap.top),
+                Math.max(viewportOffsetRect.right, systemUiOverlap.right),
+                Math.max(viewportOffsetRect.bottom, systemUiOverlap.bottom));
+    }
+
+    /**
      * Provides the amount of padding needed to center the image content on the screen.
      */
     private PointF getLetterboxPadding() {
         float[] imageVectors = {mRenderData.imageWidth, mRenderData.imageHeight};
         mRenderData.transform.mapVectors(imageVectors);
 
         // We want to letterbox when the image is smaller than the screen in a specific dimension.
         // Since we center the image, split the difference so it is equally distributed.
-        float widthAdjust =
-                Math.max(((float) mRenderData.screenWidth - imageVectors[0]) / 2.0f, 0.0f);
-        float heightAdjust =
-                Math.max(((float) mRenderData.screenHeight - imageVectors[1]) / 2.0f, 0.0f);
+        float widthAdjust = Math.max(((float) mRenderData.screenWidth - imageVectors[0]) / 2, 0);
+        float heightAdjust = Math.max((getAdjustedScreenHeight() - imageVectors[1]) / 2, 0);
 
         return new PointF(widthAdjust, heightAdjust);
     }
 
     /**
      * Returns the amount of System UI along each edge of the screen which could overlap the remote
      * desktop image below it.  This is the maximum amount that could overlap, not the actual value.
      */
     private RectF getSystemUiOverlap() {
-        // letterBox padding represents the space added to the image to center it on the screen.
+        if (mSystemUiScreenRect.isEmpty()) {
+            return new RectF();
+        }
+
+        // LetterBox padding represents the space added to the image to center it on the screen.
         // Since it does not contain any interactable UI, we ignore it when calculating the overlap
         // between the System UI and the remote desktop image.
         // Note: Ignore negative padding (clamp to 0) since that means no overlap exists.
+        float adjustedScreenHeight = getAdjustedScreenHeight();
         PointF letterboxPadding = getLetterboxPadding();
-        return new RectF(Math.max(mSystemUiScreenSize.left - letterboxPadding.x, 0.0f),
-                Math.max(mSystemUiScreenSize.top - letterboxPadding.y + mCursorOffsetScreenY, 0.0f),
-                Math.max(mSystemUiScreenSize.right - letterboxPadding.x, 0.0f),
-                Math.max(mSystemUiScreenSize.bottom - letterboxPadding.y - mCursorOffsetScreenY,
+        return new RectF(Math.max(mSystemUiScreenRect.left - letterboxPadding.x, 0.0f),
+                Math.max(mSystemUiScreenRect.top - letterboxPadding.y, 0.0f),
+                Math.max(mRenderData.screenWidth - mSystemUiScreenRect.right - letterboxPadding.x,
+                        0.0f),
+                Math.max(adjustedScreenHeight - mSystemUiScreenRect.bottom - letterboxPadding.y,
                         0.0f));
     }
 
     /**
-     * Calculates the amount of padding visible on each edge of the desktop image.
+     * Applies the given offset, as needed, to allow moving the image outside its normal bounds.
      */
-    private void updateVisibleImagePadding() {
-        PointF letterboxPadding = getLetterboxPadding();
-        float[] imagePoints = {0.0f, 0.0f, mRenderData.imageWidth, mRenderData.imageHeight};
-        mRenderData.transform.mapPoints(imagePoints);
+    private void calculateViewportOffset(float offsetX, float offsetY) {
+        if (mSystemUiScreenRect.isEmpty()) {
+            // We only want to directly change the viewport offset when System UI is present.
+            return;
+        }
 
-        mVisibleImagePadding.set(Math.max(imagePoints[0] - letterboxPadding.x, 0.0f),
-                Math.max(imagePoints[1] - letterboxPadding.y, 0.0f),
-                Math.max(mRenderData.screenWidth - imagePoints[2] - letterboxPadding.x, 0.0f),
-                Math.max(mRenderData.screenHeight - imagePoints[3] - letterboxPadding.y, 0.0f));
+        float[] offsets = {offsetX, offsetY};
+        mRenderData.transform.mapVectors(offsets);
+
+        // Use a temporary variable here as {@link #getViewportOffsetBounds()} uses the current
+        // viewport offset as a maximum boundary.  If we add the offset first, the result ends up
+        // being unbounded.  Thus we use a temporary object for the boundary calculation.
+        PointF requestedOffset =
+                new PointF(mViewportOffset.x + offsets[0], mViewportOffset.y + offsets[1]);
+        constrainPointToBounds(requestedOffset, getViewportOffsetBounds());
+        mViewportOffset.set(requestedOffset);
+    }
+
+    /**
+     * Starts an animation to smoothly reduce the viewport offset.  Does nothing if an animation is
+     * already running or the offset is already 0.
+     */
+    private void startOffsetReductionAnimation() {
+        if (mFrameRenderedCallback != null || Math.abs(mViewportOffset.length()) < EPSILON) {
+            return;
+        }
+
+        mFrameRenderedCallback = new Event.ParameterCallback<Boolean, Void>() {
+            @Override
+            public Boolean run(Void p) {
+                mViewportOffset.set(mViewportOffset.x * VIEWPORT_OFFSET_REDUCTION_FACTOR,

[Yuwei, 2016/10/25 08:25:26]

The timing implicitly depends on the fact that the renderer (mostly. maybe try
the animation while playing YouTube video?) renders at 60Hz. I think it will be
safer to calculate the offset using time as parameter.

BTW have you tried Android's stock interpolators (e.g. DecelerateInterpolator)?

[joedow, 2016/10/25 16:49:50]

I didn't realize the renderer wasn't running at a consistent framerate, timing
based animation SGTM.

[Yuwei, 2016/10/25 18:19:59]

60Hz is more like the highest possible framerate of the renderer. It will drop
if the display thread gets blocked (say if uploading desktop image takes too
long).

+                        mViewportOffset.y * VIEWPORT_OFFSET_REDUCTION_FACTOR);
+
+                if (Math.abs(mViewportOffset.length()) < MINIMUM_VIEWPORT_OFFSET_PIXELS) {
+                    mViewportOffset.set(0.0f, 0.0f);
+                    mFrameRenderedCallback = null;
+                }
+
+                repositionImage();
+
+                return mFrameRenderedCallback != null;
+            }
+        };
+
+        mRenderStub.onCanvasRendered().addSelfRemovable(mFrameRenderedCallback);
+    }
+
+    /**
+     * Stops an existing animation if one is currently running.
+     */
+    private void stopOffsetReductionAnimation() {
+        if (mFrameRenderedCallback == null) {
+            return;
+        }
+
+        mRenderStub.onCanvasRendered().remove(mFrameRenderedCallback);

[Yuwei, 2016/10/25 08:25:26]

This line of code probably doesn't work. addSelfRemovable wraps the callback
with SelfRemovableParameterRunnable and adds it to the set so removing the raw
callback probably doesn't work.

Setting mFrameRenderedCallback to null should terminate the animation.
Null-checking it at the beginning of the callback can stop the animation in
time.

[joedow, 2016/10/25 16:49:50]

Thanks for pointing that out, I can see the intention behind this event type but
it feels like I should still be able to remove it manually (i.e. outside of the
runnable).  oh well.

[Yuwei, 2016/10/25 18:19:59]

Agreed. We may want to fix the self removable at some point. We can do something
like returning the SelfRemovableRunnable in addSelfRemovable() or playing with
the hash and equals functions of the runnable.

+        mFrameRenderedCallback = null;
     }
 }