• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2021 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 package android.view;
17 
18 import android.annotation.NonNull;
19 import android.annotation.Nullable;
20 import android.annotation.SystemApi;
21 import android.annotation.UiThread;
22 import android.graphics.Region;
23 import android.hardware.HardwareBuffer;
24 
25 /**
26  * Provides an interface to the root-Surface of a View Hierarchy or Window. This
27  * is used in combination with the {@link android.view.SurfaceControl} API to enable
28  * attaching app created SurfaceControl to the SurfaceControl hierarchy used
29  * by the app, and enable SurfaceTransactions to be performed in sync with the
30  * View hierarchy drawing.
31  *
32  * This object is obtained from {@link android.view.View#getRootSurfaceControl} and
33  * {@link android.view.Window#getRootSurfaceControl}. It must be used from the UI thread of
34  * the object it was obtained from.
35  */
36 @UiThread
37 public interface AttachedSurfaceControl {
38     /**
39      * Create a transaction which will reparent {@param child} to the View hierarchy
40      * root SurfaceControl. See
41      * {@link SurfaceControl.Transaction#reparent}. This transacton must be applied
42      * or merged in to another transaction by the caller, otherwise it will have
43      * no effect.
44      *
45      * @param child The SurfaceControl to reparent.
46      * @return A new transaction which performs the reparent operation when applied.
47      */
buildReparentTransaction(@onNull SurfaceControl child)48     @Nullable SurfaceControl.Transaction buildReparentTransaction(@NonNull SurfaceControl child);
49 
50     /**
51      * Consume the passed in transaction, and request the View hierarchy to apply it atomically
52      * with the next draw. This transaction will be merged with the buffer transaction from the
53      * ViewRoot and they will show up on-screen atomically synced.
54      *
55      * This will not cause a draw to be scheduled, and if there are no other changes
56      * to the View hierarchy you may need to call {@link android.view.View#invalidate}
57      */
applyTransactionOnDraw(@onNull SurfaceControl.Transaction t)58     boolean applyTransactionOnDraw(@NonNull SurfaceControl.Transaction t);
59 
60     /**
61      * The transform hint can be used by a buffer producer to pre-rotate the rendering such that the
62      * final transformation in the system composer is identity. This can be very useful when used in
63      * conjunction with the h/w composer HAL in situations where it cannot handle rotations or
64      * handle them with an additional power cost.
65      *
66      * The transform hint should be used with ASurfaceControl APIs when submitting buffers.
67      * Example usage:
68      *
69      * 1. After a configuration change, before dequeuing a buffer, the buffer producer queries the
70      *    function for the transform hint.
71      *
72      * 2. The desired buffer width and height is rotated by the transform hint.
73      *
74      * 3. The producer dequeues a buffer of the new pre-rotated size.
75      *
76      * 4. The producer renders to the buffer such that the image is already transformed, that is
77      *    applying the transform hint to the rendering.
78      *
79      * 5. The producer applies the inverse transform hint to the buffer it just rendered.
80      *
81      * 6. The producer queues the pre-transformed buffer with the buffer transform.
82      *
83      * 7. The composer combines the buffer transform with the display transform.  If the buffer
84      *    transform happens to cancel out the display transform then no rotation is needed and there
85      *    will be no performance penalties.
86      *
87      * Note, when using ANativeWindow APIs in conjunction with a NativeActivity Surface or
88      * SurfaceView Surface, the buffer producer will already have access to the transform hint and
89      * no additional work is needed.
90      *
91      * @see HardwareBuffer
92      */
getBufferTransformHint()93     default @SurfaceControl.BufferTransform int getBufferTransformHint() {
94         return SurfaceControl.BUFFER_TRANSFORM_IDENTITY;
95     }
96 
97     /**
98      * Buffer transform hint change listener.
99      * @see #getBufferTransformHint
100      */
101     @UiThread
102     interface OnBufferTransformHintChangedListener {
103         /**
104          * @param hint new surface transform hint
105          * @see #getBufferTransformHint
106          */
onBufferTransformHintChanged(@urfaceControl.BufferTransform int hint)107         void onBufferTransformHintChanged(@SurfaceControl.BufferTransform int hint);
108     }
109 
110     /**
111      * Registers a {@link OnBufferTransformHintChangedListener} to receive notifications about when
112      * the transform hint changes.
113      *
114      * @see #getBufferTransformHint
115      * @see #removeOnBufferTransformHintChangedListener
116      */
addOnBufferTransformHintChangedListener( @onNull OnBufferTransformHintChangedListener listener)117     default void addOnBufferTransformHintChangedListener(
118             @NonNull OnBufferTransformHintChangedListener listener) {
119     }
120 
121     /**
122      * Unregisters a {@link OnBufferTransformHintChangedListener}.
123      *
124      * @see #addOnBufferTransformHintChangedListener
125      */
removeOnBufferTransformHintChangedListener( @onNull OnBufferTransformHintChangedListener listener)126     default void removeOnBufferTransformHintChangedListener(
127             @NonNull OnBufferTransformHintChangedListener listener) {
128     }
129 
130     /**
131      * Sets the touchable region for this SurfaceControl, expressed in surface local
132      * coordinates. By default the touchable region is the entire Layer, indicating
133      * that if the layer is otherwise eligible to receive touch it receives touch
134      * on the entire surface. Setting the touchable region allows the SurfaceControl
135      * to receive touch in some regions, while allowing for pass-through in others.
136      *
137      * @param r The region to use or null to use the entire Layer bounds
138      */
setTouchableRegion(@ullable Region r)139     default void setTouchableRegion(@Nullable Region r) {
140     }
141 }
142