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.UiThread; 21 import android.graphics.Rect; 22 import android.graphics.Region; 23 import android.hardware.HardwareBuffer; 24 import android.window.SurfaceSyncGroup; 25 26 import java.util.concurrent.Executor; 27 import java.util.function.Consumer; 28 29 /** 30 * Provides an interface to the root-Surface of a View Hierarchy or Window. This 31 * is used in combination with the {@link android.view.SurfaceControl} API to enable 32 * attaching app created SurfaceControl to the SurfaceControl hierarchy used 33 * by the app, and enable SurfaceTransactions to be performed in sync with the 34 * View hierarchy drawing. 35 * 36 * This object is obtained from {@link android.view.View#getRootSurfaceControl} and 37 * {@link android.view.Window#getRootSurfaceControl}. It must be used from the UI thread of 38 * the object it was obtained from. 39 */ 40 @UiThread 41 public interface AttachedSurfaceControl { 42 /** 43 * Create a transaction which will reparent {@param child} to the View hierarchy 44 * root SurfaceControl. See 45 * {@link SurfaceControl.Transaction#reparent}. This transacton must be applied 46 * or merged in to another transaction by the caller, otherwise it will have 47 * no effect. 48 * 49 * @param child The SurfaceControl to reparent. 50 * @return A new transaction which performs the reparent operation when applied. 51 */ buildReparentTransaction(@onNull SurfaceControl child)52 @Nullable SurfaceControl.Transaction buildReparentTransaction(@NonNull SurfaceControl child); 53 54 /** 55 * Consume the passed in transaction, and request the View hierarchy to apply it atomically 56 * with the next draw. This transaction will be merged with the buffer transaction from the 57 * ViewRoot and they will show up on-screen atomically synced. 58 * 59 * This will not cause a draw to be scheduled, and if there are no other changes 60 * to the View hierarchy you may need to call {@link android.view.View#invalidate} 61 */ applyTransactionOnDraw(@onNull SurfaceControl.Transaction t)62 boolean applyTransactionOnDraw(@NonNull SurfaceControl.Transaction t); 63 64 /** 65 * The transform hint can be used by a buffer producer to pre-rotate the rendering such that the 66 * final transformation in the system composer is identity. This can be very useful when used in 67 * conjunction with the h/w composer HAL in situations where it cannot handle rotations or 68 * handle them with an additional power cost. 69 * 70 * The transform hint should be used with ASurfaceControl APIs when submitting buffers. 71 * Example usage: 72 * 73 * 1. After a configuration change, before dequeuing a buffer, the buffer producer queries the 74 * function for the transform hint. 75 * 76 * 2. The desired buffer width and height is rotated by the transform hint. 77 * 78 * 3. The producer dequeues a buffer of the new pre-rotated size. 79 * 80 * 4. The producer renders to the buffer such that the image is already transformed, that is 81 * applying the transform hint to the rendering. 82 * 83 * 5. The producer applies the inverse transform hint to the buffer it just rendered. 84 * 85 * 6. The producer queues the pre-transformed buffer with the buffer transform. 86 * 87 * 7. The composer combines the buffer transform with the display transform. If the buffer 88 * transform happens to cancel out the display transform then no rotation is needed and there 89 * will be no performance penalties. 90 * 91 * Note, when using ANativeWindow APIs in conjunction with a NativeActivity Surface or 92 * SurfaceView Surface, the buffer producer will already have access to the transform hint and 93 * no additional work is needed. 94 * 95 * @see HardwareBuffer 96 */ getBufferTransformHint()97 default @SurfaceControl.BufferTransform int getBufferTransformHint() { 98 return SurfaceControl.BUFFER_TRANSFORM_IDENTITY; 99 } 100 101 /** 102 * Buffer transform hint change listener. 103 * @see #getBufferTransformHint 104 */ 105 @UiThread 106 interface OnBufferTransformHintChangedListener { 107 /** 108 * @param hint new surface transform hint 109 * @see #getBufferTransformHint 110 */ onBufferTransformHintChanged(@urfaceControl.BufferTransform int hint)111 void onBufferTransformHintChanged(@SurfaceControl.BufferTransform int hint); 112 } 113 114 /** 115 * Registers a {@link OnBufferTransformHintChangedListener} to receive notifications about when 116 * the transform hint changes. 117 * 118 * @see #getBufferTransformHint 119 * @see #removeOnBufferTransformHintChangedListener 120 */ addOnBufferTransformHintChangedListener( @onNull OnBufferTransformHintChangedListener listener)121 default void addOnBufferTransformHintChangedListener( 122 @NonNull OnBufferTransformHintChangedListener listener) { 123 } 124 125 /** 126 * Unregisters a {@link OnBufferTransformHintChangedListener}. 127 * 128 * @see #addOnBufferTransformHintChangedListener 129 */ removeOnBufferTransformHintChangedListener( @onNull OnBufferTransformHintChangedListener listener)130 default void removeOnBufferTransformHintChangedListener( 131 @NonNull OnBufferTransformHintChangedListener listener) { 132 } 133 134 /** 135 * Sets the touchable region for this SurfaceControl, expressed in surface local 136 * coordinates. By default the touchable region is the entire Layer, indicating 137 * that if the layer is otherwise eligible to receive touch it receives touch 138 * on the entire surface. Setting the touchable region allows the SurfaceControl 139 * to receive touch in some regions, while allowing for pass-through in others. 140 * 141 * @param r The region to use or null to use the entire Layer bounds 142 */ setTouchableRegion(@ullable Region r)143 default void setTouchableRegion(@Nullable Region r) { 144 } 145 146 /** 147 * Returns a SurfaceSyncGroup that can be used to sync {@link AttachedSurfaceControl} in a 148 * {@link SurfaceSyncGroup} 149 * 150 * @hide 151 */ 152 @Nullable getOrCreateSurfaceSyncGroup()153 default SurfaceSyncGroup getOrCreateSurfaceSyncGroup() { 154 return null; 155 } 156 157 /** 158 * Set a crop region on all children parented to the layer represented by this 159 * AttachedSurfaceControl. This includes SurfaceView, and an example usage may 160 * be to ensure that SurfaceView with {@link android.view.SurfaceView#setZOrderOnTop} 161 * are cropped to a region not including the app bar. 162 * <p> 163 * This cropped is expressed in terms of insets in window-space. Negative insets 164 * are considered invalid and will produce an exception. Insets of zero will produce 165 * the same result as if this function had never been called. 166 * 167 * @param insets The insets in each direction by which to bound the children 168 * expressed in window-space. 169 * @throws IllegalArgumentException If negative insets are provided. 170 */ setChildBoundingInsets(@onNull Rect insets)171 default void setChildBoundingInsets(@NonNull Rect insets) { 172 } 173 174 /** 175 * Add a trusted presentation listener on the SurfaceControl associated with this window. 176 * 177 * @param t Transaction that the trusted presentation listener is added on. This should 178 * be applied by the caller. 179 * @param thresholds The {@link SurfaceControl.TrustedPresentationThresholds} that will specify 180 * when the to invoke the callback. 181 * @param executor The {@link Executor} where the callback will be invoked on. 182 * @param listener The {@link Consumer} that will receive the callbacks when entered or 183 * exited the threshold. 184 * 185 * @see SurfaceControl.Transaction#setTrustedPresentationCallback(SurfaceControl, 186 * SurfaceControl.TrustedPresentationThresholds, Executor, Consumer) 187 * 188 * @hide b/287076178 un-hide with API bump 189 */ addTrustedPresentationCallback(@onNull SurfaceControl.Transaction t, @NonNull SurfaceControl.TrustedPresentationThresholds thresholds, @NonNull Executor executor, @NonNull Consumer<Boolean> listener)190 default void addTrustedPresentationCallback(@NonNull SurfaceControl.Transaction t, 191 @NonNull SurfaceControl.TrustedPresentationThresholds thresholds, 192 @NonNull Executor executor, @NonNull Consumer<Boolean> listener) { 193 } 194 195 /** 196 * Remove a trusted presentation listener on the SurfaceControl associated with this window. 197 * 198 * @param t Transaction that the trusted presentation listener removed on. This should 199 * be applied by the caller. 200 * @param listener The {@link Consumer} that was previously registered with 201 * addTrustedPresentationCallback that should be removed. 202 * 203 * @see SurfaceControl.Transaction#clearTrustedPresentationCallback(SurfaceControl) 204 * @hide b/287076178 un-hide with API bump 205 */ removeTrustedPresentationCallback(@onNull SurfaceControl.Transaction t, @NonNull Consumer<Boolean> listener)206 default void removeTrustedPresentationCallback(@NonNull SurfaceControl.Transaction t, 207 @NonNull Consumer<Boolean> listener) { 208 } 209 } 210