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