1 /*
2  * Copyright (C) 2020 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.view;
18 
19 import android.annotation.NonNull;
20 import android.annotation.Nullable;
21 import android.graphics.Point;
22 import android.graphics.Rect;
23 
24 /**
25  * A session represents the scope of interaction between a {@link ScrollCaptureCallback} and the
26  * system during an active scroll capture operation. During the scope of a session, a callback
27  * will receive a series of requests for image data. Resources provided here are valid for use
28  * until {@link ScrollCaptureCallback#onScrollCaptureEnd(Runnable)}.
29  *
30  * @hide
31  */
32 public class ScrollCaptureSession {
33 
34     private final Surface mSurface;
35     private final Rect mScrollBounds;
36     private final Point mPositionInWindow;
37 
38     @Nullable
39     private ScrollCaptureClient mClient;
40 
41     /** @hide */
ScrollCaptureSession(Surface surface, Rect scrollBounds, Point positionInWindow, ScrollCaptureClient client)42     public ScrollCaptureSession(Surface surface, Rect scrollBounds, Point positionInWindow,
43             ScrollCaptureClient client) {
44         mSurface = surface;
45         mScrollBounds = scrollBounds;
46         mPositionInWindow = positionInWindow;
47         mClient = client;
48     }
49 
50     /**
51      * Returns a
52      * <a href="https://source.android.com/devices/graphics/arch-bq-gralloc">BufferQueue</a> in the
53      * form of a {@link Surface} for transfer of image buffers.
54      *
55      * @return the surface for transferring image buffers
56      * @throws IllegalStateException if the session has been closed
57      */
58     @NonNull
getSurface()59     public Surface getSurface() {
60         return mSurface;
61     }
62 
63     /**
64      * Returns the {@code scroll bounds}, as provided by
65      * {@link ScrollCaptureCallback#onScrollCaptureSearch}.
66      *
67      * @return the area of scrolling content within the containing view
68      */
69     @NonNull
getScrollBounds()70     public Rect getScrollBounds() {
71         return mScrollBounds;
72     }
73 
74     /**
75      * Returns the offset of {@code scroll bounds} within the window.
76      *
77      * @return the area of scrolling content within the containing view
78      */
79     @NonNull
getPositionInWindow()80     public Point getPositionInWindow() {
81         return mPositionInWindow;
82     }
83 
84     /**
85      * Notify the system that an a buffer has been posted via the getSurface() channel.
86      *
87      * @param frameNumber  the frame number of the queued buffer
88      * @param capturedArea the area captured, relative to scroll bounds
89      */
notifyBufferSent(long frameNumber, @NonNull Rect capturedArea)90     public void notifyBufferSent(long frameNumber, @NonNull Rect capturedArea) {
91         if (mClient != null) {
92             mClient.onRequestImageCompleted(frameNumber, capturedArea);
93         }
94     }
95 
96     /**
97      * @hide
98      */
disconnect()99     public void disconnect() {
100         mClient = null;
101         if (mSurface.isValid()) {
102             mSurface.release();
103         }
104     }
105 }
106