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