1 /* 2 * Copyright 2018 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 /** 18 * @addtogroup NativeActivity Native Activity 19 * @{ 20 */ 21 22 /** 23 * @file surface_control.h 24 */ 25 26 #ifndef ANDROID_SURFACE_CONTROL_H 27 #define ANDROID_SURFACE_CONTROL_H 28 29 #include <sys/cdefs.h> 30 31 #include <android/data_space.h> 32 #include <android/hardware_buffer.h> 33 #include <android/hdr_metadata.h> 34 #include <android/native_window.h> 35 36 __BEGIN_DECLS 37 38 #if __ANDROID_API__ >= 29 39 40 struct ASurfaceControl; 41 42 /** 43 * The SurfaceControl API can be used to provide a hierarchy of surfaces for 44 * composition to the system compositor. ASurfaceControl represents a content node in 45 * this hierarchy. 46 */ 47 typedef struct ASurfaceControl ASurfaceControl; 48 49 /** 50 * Creates an ASurfaceControl with either ANativeWindow or an ASurfaceControl as its parent. 51 * |debug_name| is a debug name associated with this surface. It can be used to 52 * identify this surface in the SurfaceFlinger's layer tree. It must not be 53 * null. 54 * 55 * The caller takes ownership of the ASurfaceControl returned and must release it 56 * using ASurfaceControl_release below. 57 * 58 * Available since API level 29. 59 */ 60 ASurfaceControl* ASurfaceControl_createFromWindow(ANativeWindow* parent, const char* debug_name) 61 __INTRODUCED_IN(29); 62 63 /** 64 * See ASurfaceControl_createFromWindow. 65 * 66 * Available since API level 29. 67 */ 68 ASurfaceControl* ASurfaceControl_create(ASurfaceControl* parent, const char* debug_name) 69 __INTRODUCED_IN(29); 70 71 /** 72 * Releases the |surface_control| object. After releasing the ASurfaceControl the caller no longer 73 * has ownership of the AsurfaceControl. The surface and it's children may remain on display as long 74 * as their parent remains on display. 75 * 76 * Available since API level 29. 77 */ 78 void ASurfaceControl_release(ASurfaceControl* surface_control) __INTRODUCED_IN(29); 79 80 struct ASurfaceTransaction; 81 82 /** 83 * ASurfaceTransaction is a collection of updates to the surface tree that must 84 * be applied atomically. 85 */ 86 typedef struct ASurfaceTransaction ASurfaceTransaction; 87 88 /** 89 * The caller takes ownership of the transaction and must release it using 90 * ASurfaceControl_delete below. 91 * 92 * Available since API level 29. 93 */ 94 ASurfaceTransaction* ASurfaceTransaction_create() __INTRODUCED_IN(29); 95 96 /** 97 * Destroys the |transaction| object. 98 * 99 * Available since API level 29. 100 */ 101 void ASurfaceTransaction_delete(ASurfaceTransaction* transaction) __INTRODUCED_IN(29); 102 103 /** 104 * Applies the updates accumulated in |transaction|. 105 * 106 * Note that the transaction is guaranteed to be applied atomically. The 107 * transactions which are applied on the same thread are also guaranteed to be 108 * applied in order. 109 * 110 * Available since API level 29. 111 */ 112 void ASurfaceTransaction_apply(ASurfaceTransaction* transaction) __INTRODUCED_IN(29); 113 114 /** 115 * An opaque handle returned during a callback that can be used to query general stats and stats for 116 * surfaces which were either removed or for which buffers were updated after this transaction was 117 * applied. 118 */ 119 typedef struct ASurfaceTransactionStats ASurfaceTransactionStats; 120 121 /** 122 * Since the transactions are applied asynchronously, the 123 * ASurfaceTransaction_OnComplete callback can be used to be notified when a frame 124 * including the updates in a transaction was presented. 125 * 126 * |context| is the optional context provided by the client that is passed into 127 * the callback. 128 * 129 * |stats| is an opaque handle that can be passed to ASurfaceTransactionStats functions to query 130 * information about the transaction. The handle is only valid during the callback. 131 * 132 * THREADING 133 * The transaction completed callback can be invoked on any thread. 134 * 135 * Available since API level 29. 136 */ 137 typedef void (*ASurfaceTransaction_OnComplete)(void* context, ASurfaceTransactionStats* stats) 138 __INTRODUCED_IN(29); 139 140 /** 141 * Returns the timestamp of when the frame was latched by the framework. Once a frame is 142 * latched by the framework, it is presented at the following hardware vsync. 143 * 144 * Available since API level 29. 145 */ 146 int64_t ASurfaceTransactionStats_getLatchTime(ASurfaceTransactionStats* surface_transaction_stats) 147 __INTRODUCED_IN(29); 148 149 /** 150 * Returns a sync fence that signals when the transaction has been presented. 151 * The recipient of the callback takes ownership of the fence and is responsible for closing 152 * it. 153 * 154 * Available since API level 29. 155 */ 156 int ASurfaceTransactionStats_getPresentFenceFd(ASurfaceTransactionStats* surface_transaction_stats) 157 __INTRODUCED_IN(29); 158 159 /** 160 * |outASurfaceControls| returns an array of ASurfaceControl pointers that were updated during the 161 * transaction. Stats for the surfaces can be queried through ASurfaceTransactionStats functions. 162 * When the client is done using the array, it must release it by calling 163 * ASurfaceTransactionStats_releaseASurfaceControls. 164 * 165 * Available since API level 29. 166 * 167 * |outASurfaceControlsSize| returns the size of the ASurfaceControls array. 168 */ 169 void ASurfaceTransactionStats_getASurfaceControls(ASurfaceTransactionStats* surface_transaction_stats, 170 ASurfaceControl*** outASurfaceControls, 171 size_t* outASurfaceControlsSize) 172 __INTRODUCED_IN(29); 173 /** 174 * Releases the array of ASurfaceControls that were returned by 175 * ASurfaceTransactionStats_getASurfaceControls. 176 * 177 * Available since API level 29. 178 */ 179 void ASurfaceTransactionStats_releaseASurfaceControls(ASurfaceControl** surface_controls) 180 __INTRODUCED_IN(29); 181 182 /** 183 * Returns the timestamp of when the CURRENT buffer was acquired. A buffer is considered 184 * acquired when its acquire_fence_fd has signaled. A buffer cannot be latched or presented until 185 * it is acquired. If no acquire_fence_fd was provided, this timestamp will be set to -1. 186 * 187 * Available since API level 29. 188 */ 189 int64_t ASurfaceTransactionStats_getAcquireTime(ASurfaceTransactionStats* surface_transaction_stats, 190 ASurfaceControl* surface_control) 191 __INTRODUCED_IN(29); 192 193 /** 194 * The returns the fence used to signal the release of the PREVIOUS buffer set on 195 * this surface. If this fence is valid (>=0), the PREVIOUS buffer has not yet been released and the 196 * fence will signal when the PREVIOUS buffer has been released. If the fence is -1 , the PREVIOUS 197 * buffer is already released. The recipient of the callback takes ownership of the 198 * previousReleaseFenceFd and is responsible for closing it. 199 * 200 * Each time a buffer is set through ASurfaceTransaction_setBuffer()/_setCachedBuffer() on a 201 * transaction which is applied, the framework takes a ref on this buffer. The framework treats the 202 * addition of a buffer to a particular surface as a unique ref. When a transaction updates or 203 * removes a buffer from a surface, or removes the surface itself from the tree, this ref is 204 * guaranteed to be released in the OnComplete callback for this transaction. The 205 * ASurfaceControlStats provided in the callback for this surface may contain an optional fence 206 * which must be signaled before the ref is assumed to be released. 207 * 208 * The client must ensure that all pending refs on a buffer are released before attempting to reuse 209 * this buffer, otherwise synchronization errors may occur. 210 * 211 * Available since API level 29. 212 */ 213 int ASurfaceTransactionStats_getPreviousReleaseFenceFd( 214 ASurfaceTransactionStats* surface_transaction_stats, 215 ASurfaceControl* surface_control) 216 __INTRODUCED_IN(29); 217 218 /** 219 * Sets the callback that will be invoked when the updates from this transaction 220 * are presented. For details on the callback semantics and data, see the 221 * comments on the ASurfaceTransaction_OnComplete declaration above. 222 * 223 * Available since API level 29. 224 */ 225 void ASurfaceTransaction_setOnComplete(ASurfaceTransaction* transaction, void* context, 226 ASurfaceTransaction_OnComplete func) __INTRODUCED_IN(29); 227 228 /** 229 * Reparents the |surface_control| from its old parent to the |new_parent| surface control. 230 * Any children of the* reparented |surface_control| will remain children of the |surface_control|. 231 * 232 * The |new_parent| can be null. Surface controls with a null parent do not appear on the display. 233 * 234 * Available since API level 29. 235 */ 236 void ASurfaceTransaction_reparent(ASurfaceTransaction* transaction, 237 ASurfaceControl* surface_control, ASurfaceControl* new_parent) 238 __INTRODUCED_IN(29); 239 240 /* Parameter for ASurfaceTransaction_setVisibility */ 241 enum { 242 ASURFACE_TRANSACTION_VISIBILITY_HIDE = 0, 243 ASURFACE_TRANSACTION_VISIBILITY_SHOW = 1, 244 }; 245 /** 246 * Updates the visibility of |surface_control|. If show is set to 247 * ASURFACE_TRANSACTION_VISIBILITY_HIDE, the |surface_control| and all surfaces in its subtree will 248 * be hidden. 249 * 250 * Available since API level 29. 251 */ 252 void ASurfaceTransaction_setVisibility(ASurfaceTransaction* transaction, 253 ASurfaceControl* surface_control, int8_t visibility) 254 __INTRODUCED_IN(29); 255 256 /** 257 * Updates the z order index for |surface_control|. Note that the z order for a surface 258 * is relative to other surfaces which are siblings of this surface. The behavior of sibilings with 259 * the same z order is undefined. 260 * 261 * Z orders may be from MIN_INT32 to MAX_INT32. A layer's default z order index is 0. 262 * 263 * Available since API level 29. 264 */ 265 void ASurfaceTransaction_setZOrder(ASurfaceTransaction* transaction, 266 ASurfaceControl* surface_control, int32_t z_order) 267 __INTRODUCED_IN(29); 268 269 /** 270 * Updates the AHardwareBuffer displayed for |surface_control|. If not -1, the 271 * acquire_fence_fd should be a file descriptor that is signaled when all pending work 272 * for the buffer is complete and the buffer can be safely read. 273 * 274 * The frameworks takes ownership of the |acquire_fence_fd| passed and is responsible 275 * for closing it. 276 * 277 * Available since API level 29. 278 */ 279 void ASurfaceTransaction_setBuffer(ASurfaceTransaction* transaction, 280 ASurfaceControl* surface_control, AHardwareBuffer* buffer, 281 int acquire_fence_fd = -1) __INTRODUCED_IN(29); 282 283 /** 284 * Updates the color for |surface_control|. This will make the background color for the 285 * ASurfaceControl visible in transparent regions of the surface. Colors |r|, |g|, 286 * and |b| must be within the range that is valid for |dataspace|. |dataspace| and |alpha| 287 * will be the dataspace and alpha set for the background color layer. 288 * 289 * Available since API level 29. 290 */ 291 void ASurfaceTransaction_setColor(ASurfaceTransaction* transaction, 292 ASurfaceControl* surface_control, float r, float g, float b, 293 float alpha, ADataSpace dataspace) 294 __INTRODUCED_IN(29); 295 296 /** 297 * |source| the sub-rect within the buffer's content to be rendered inside the surface's area 298 * The surface's source rect is clipped by the bounds of its current buffer. The source rect's width 299 * and height must be > 0. 300 * 301 * |destination| specifies the rect in the parent's space where this surface will be drawn. The post 302 * source rect bounds are scaled to fit the destination rect. The surface's destination rect is 303 * clipped by the bounds of its parent. The destination rect's width and height must be > 0. 304 * 305 * |transform| the transform applied after the source rect is applied to the buffer. This parameter 306 * should be set to 0 for no transform. To specify a transfrom use the NATIVE_WINDOW_TRANSFORM_* 307 * enum. 308 * 309 * Available since API level 29. 310 */ 311 void ASurfaceTransaction_setGeometry(ASurfaceTransaction* transaction, 312 ASurfaceControl* surface_control, const ARect& source, 313 const ARect& destination, int32_t transform) 314 __INTRODUCED_IN(29); 315 316 317 /* Parameter for ASurfaceTransaction_setBufferTransparency */ 318 enum { 319 ASURFACE_TRANSACTION_TRANSPARENCY_TRANSPARENT = 0, 320 ASURFACE_TRANSACTION_TRANSPARENCY_TRANSLUCENT = 1, 321 ASURFACE_TRANSACTION_TRANSPARENCY_OPAQUE = 2, 322 }; 323 /** 324 * Updates whether the content for the buffer associated with this surface is 325 * completely opaque. If true, every pixel of content inside the buffer must be 326 * opaque or visual errors can occur. 327 * 328 * Available since API level 29. 329 */ 330 void ASurfaceTransaction_setBufferTransparency(ASurfaceTransaction* transaction, 331 ASurfaceControl* surface_control, 332 int8_t transparency) 333 __INTRODUCED_IN(29); 334 335 /** 336 * Updates the region for the content on this surface updated in this 337 * transaction. If unspecified, the complete surface is assumed to be damaged. 338 * 339 * Available since API level 29. 340 */ 341 void ASurfaceTransaction_setDamageRegion(ASurfaceTransaction* transaction, 342 ASurfaceControl* surface_control, const ARect rects[], 343 uint32_t count) __INTRODUCED_IN(29); 344 345 /** 346 * Specifies a desiredPresentTime for the transaction. The framework will try to present 347 * the transaction at or after the time specified. 348 * 349 * Transactions will not be presented until all of their acquire fences have signaled even if the 350 * app requests an earlier present time. 351 * 352 * If an earlier transaction has a desired present time of x, and a later transaction has a desired 353 * present time that is before x, the later transaction will not preempt the earlier transaction. 354 * 355 * Available since API level 29. 356 */ 357 void ASurfaceTransaction_setDesiredPresentTime(ASurfaceTransaction* transaction, 358 int64_t desiredPresentTime) __INTRODUCED_IN(29); 359 360 /** 361 * Sets the alpha for the buffer. It uses a premultiplied blending. 362 * 363 * The |alpha| must be between 0.0 and 1.0. 364 * 365 * Available since API level 29. 366 */ 367 void ASurfaceTransaction_setBufferAlpha(ASurfaceTransaction* transaction, 368 ASurfaceControl* surface_control, float alpha) 369 __INTRODUCED_IN(29); 370 371 /** 372 * Sets the data space of the surface_control's buffers. 373 * 374 * If no data space is set, the surface control defaults to ADATASPACE_SRGB. 375 * 376 * Available since API level 29. 377 */ 378 void ASurfaceTransaction_setBufferDataSpace(ASurfaceTransaction* transaction, 379 ASurfaceControl* surface_control, ADataSpace data_space) 380 __INTRODUCED_IN(29); 381 382 /* 383 * SMPTE ST 2086 "Mastering Display Color Volume" static metadata 384 * 385 * When |metadata| is set to null, the framework does not use any smpte2086 metadata when rendering 386 * the surface's buffer. 387 * 388 * Available since API level 29. 389 */ 390 void ASurfaceTransaction_setHdrMetadata_smpte2086(ASurfaceTransaction* transaction, 391 ASurfaceControl* surface_control, 392 struct AHdrMetadata_smpte2086* metadata) 393 __INTRODUCED_IN(29); 394 395 /* 396 * Sets the CTA 861.3 "HDR Static Metadata Extension" static metadata on a surface. 397 * 398 * When |metadata| is set to null, the framework does not use any cta861.3 metadata when rendering 399 * the surface's buffer. 400 * 401 * Available since API level 29. 402 */ 403 void ASurfaceTransaction_setHdrMetadata_cta861_3(ASurfaceTransaction* transaction, 404 ASurfaceControl* surface_control, 405 struct AHdrMetadata_cta861_3* metadata) 406 __INTRODUCED_IN(29); 407 408 #endif // __ANDROID_API__ >= 29 409 410 __END_DECLS 411 412 #endif // ANDROID_SURFACE_CONTROL_H 413