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/display_luts.h> 32 #include <android/choreographer.h> 33 #include <android/data_space.h> 34 #include <android/hardware_buffer.h> 35 #include <android/hdr_metadata.h> 36 #include <android/native_window.h> 37 38 __BEGIN_DECLS 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 * \a 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 * By default the \a ASurfaceControl will be visible and display any buffer submitted. In 59 * addition, the default buffer submission control may release and not display all buffers 60 * that are submitted before receiving a callback for the previous buffer. See 61 * \a ASurfaceTransaction_setVisibility and \a ASurfaceTransaction_setEnableBackPressure to 62 * change the default behaviors after creation. 63 * 64 * Available since API level 29. 65 */ 66 ASurfaceControl* _Nullable ASurfaceControl_createFromWindow(ANativeWindow* _Nonnull parent, 67 const char* _Nonnull debug_name) 68 __INTRODUCED_IN(29); 69 70 /** 71 * See ASurfaceControl_createFromWindow. 72 * 73 * Available since API level 29. 74 */ 75 ASurfaceControl* _Nullable ASurfaceControl_create(ASurfaceControl* _Nonnull parent, 76 const char* _Nonnull debug_name) 77 __INTRODUCED_IN(29); 78 79 /** 80 * Acquires a reference on the given ASurfaceControl object. This prevents the object 81 * from being deleted until the reference is removed. 82 * 83 * To release the reference, use the ASurfaceControl_release function. 84 * 85 * Available since API level 31. 86 */ 87 void ASurfaceControl_acquire(ASurfaceControl* _Nonnull surface_control) __INTRODUCED_IN(31); 88 89 /** 90 * Removes a reference that was previously acquired with one of the following functions: 91 * ASurfaceControl_createFromWindow 92 * ASurfaceControl_create 93 * ANativeWindow_acquire 94 * The surface and its children may remain on display as long as their parent remains on display. 95 * 96 * Available since API level 29. 97 */ 98 void ASurfaceControl_release(ASurfaceControl* _Nonnull surface_control) __INTRODUCED_IN(29); 99 100 struct ASurfaceTransaction; 101 102 /** 103 * ASurfaceTransaction is a collection of updates to the surface tree that must 104 * be applied atomically. 105 */ 106 typedef struct ASurfaceTransaction ASurfaceTransaction; 107 108 /** 109 * The caller takes ownership of the transaction and must release it using 110 * ASurfaceTransaction_delete() below. 111 * 112 * Available since API level 29. 113 */ 114 ASurfaceTransaction* _Nonnull ASurfaceTransaction_create() __INTRODUCED_IN(29); 115 116 /** 117 * Destroys the \a transaction object. 118 * 119 * Available since API level 29. 120 */ 121 void ASurfaceTransaction_delete(ASurfaceTransaction* _Nullable transaction) __INTRODUCED_IN(29); 122 123 /** 124 * Applies the updates accumulated in \a transaction. 125 * 126 * Note that the transaction is guaranteed to be applied atomically. The 127 * transactions which are applied on the same thread are also guaranteed to be 128 * applied in order. 129 * 130 * Available since API level 29. 131 */ 132 void ASurfaceTransaction_apply(ASurfaceTransaction* _Nonnull transaction) __INTRODUCED_IN(29); 133 134 /** 135 * An opaque handle returned during a callback that can be used to query general stats and stats for 136 * surfaces which were either removed or for which buffers were updated after this transaction was 137 * applied. 138 */ 139 typedef struct ASurfaceTransactionStats ASurfaceTransactionStats; 140 141 /** 142 * Since the transactions are applied asynchronously, the 143 * ASurfaceTransaction_OnComplete callback can be used to be notified when a frame 144 * including the updates in a transaction was presented. 145 * 146 * Buffers which are replaced or removed from the scene in the transaction invoking 147 * this callback may be reused after this point. 148 * 149 * Starting with API level 36, prefer using \a ASurfaceTransaction_OnBufferRelease to listen 150 * to when a buffer is ready to be reused. 151 * 152 * \param context Optional context provided by the client that is passed into 153 * the callback. 154 * 155 * \param stats Opaque handle that can be passed to ASurfaceTransactionStats functions to query 156 * information about the transaction. The handle is only valid during the callback. 157 * 158 * THREADING 159 * The transaction completed callback can be invoked on any thread. 160 */ 161 typedef void (*ASurfaceTransaction_OnComplete)(void* _Null_unspecified context, 162 ASurfaceTransactionStats* _Nonnull stats); 163 164 /** 165 * The ASurfaceTransaction_OnCommit callback is invoked when transaction is applied and the updates 166 * are ready to be presented. This callback will be invoked before the 167 * ASurfaceTransaction_OnComplete callback. 168 * 169 * This callback does not mean buffers have been released! It simply means that any new 170 * transactions applied will not overwrite the transaction for which we are receiving 171 * a callback and instead will be included in the next frame. If you are trying to avoid 172 * dropping frames (overwriting transactions), and unable to use timestamps (Which provide 173 * a more efficient solution), then this method provides a method to pace your transaction 174 * application. 175 * 176 * \param context Optional context provided by the client that is passed into the callback. 177 * 178 * \param stats Opaque handle that can be passed to ASurfaceTransactionStats functions to query 179 * information about the transaction. The handle is only valid during the callback. 180 * Present and release fences are not available for this callback. Querying them using 181 * ASurfaceTransactionStats_getPresentFenceFd and ASurfaceTransactionStats_getPreviousReleaseFenceFd 182 * will result in failure. 183 * 184 * THREADING 185 * The transaction committed callback can be invoked on any thread. 186 */ 187 typedef void (*ASurfaceTransaction_OnCommit)(void* _Null_unspecified context, 188 ASurfaceTransactionStats* _Nonnull stats); 189 190 /** 191 * The ASurfaceTransaction_OnBufferRelease callback is invoked when a buffer that was passed in 192 * ASurfaceTransaction_setBuffer is ready to be reused. 193 * 194 * This callback is guaranteed to be invoked if ASurfaceTransaction_setBuffer is called with a non 195 * null buffer. If the buffer in the transaction is replaced via another call to 196 * ASurfaceTransaction_setBuffer, the callback will be invoked immediately. Otherwise the callback 197 * will be invoked before the ASurfaceTransaction_OnComplete callback after the buffer was 198 * presented. 199 * 200 * If this callback is set, caller should not release the buffer using the 201 * ASurfaceTransaction_OnComplete. 202 * 203 * \param context Optional context provided by the client that is passed into the callback. 204 * 205 * \param release_fence_fd Returns the fence file descriptor used to signal the release of buffer 206 * associated with this callback. If this fence is valid (>=0), the buffer has not yet been released 207 * and the fence will signal when the buffer has been released. If the fence is -1 , the buffer is 208 * already released. The recipient of the callback takes ownership of the fence fd and is 209 * responsible for closing it. 210 * 211 * THREADING 212 * The callback can be invoked on any thread. 213 */ 214 typedef void (*ASurfaceTransaction_OnBufferRelease)(void* _Null_unspecified context, 215 int release_fence_fd); 216 217 /** 218 * Returns the timestamp of when the frame was latched by the framework. Once a frame is 219 * latched by the framework, it is presented at the following hardware vsync. 220 * 221 * Available since API level 29. 222 */ 223 int64_t ASurfaceTransactionStats_getLatchTime( 224 ASurfaceTransactionStats* _Nonnull surface_transaction_stats) __INTRODUCED_IN(29); 225 226 /** 227 * Returns a sync fence that signals when the transaction has been presented. 228 * The recipient of the callback takes ownership of the fence and is responsible for closing 229 * it. If a device does not support present fences, a -1 will be returned. 230 * 231 * This query is not valid for ASurfaceTransaction_OnCommit callback. 232 * 233 * Available since API level 29. 234 */ 235 int ASurfaceTransactionStats_getPresentFenceFd( 236 ASurfaceTransactionStats* _Nonnull surface_transaction_stats) __INTRODUCED_IN(29); 237 238 /** 239 * \a outASurfaceControls returns an array of ASurfaceControl pointers that were updated during the 240 * transaction. Stats for the surfaces can be queried through ASurfaceTransactionStats functions. 241 * When the client is done using the array, it must release it by calling 242 * ASurfaceTransactionStats_releaseASurfaceControls. 243 * 244 * Available since API level 29. 245 * 246 * \a outASurfaceControlsSize returns the size of the ASurfaceControls array. 247 */ 248 void ASurfaceTransactionStats_getASurfaceControls( 249 ASurfaceTransactionStats* _Nonnull surface_transaction_stats, 250 ASurfaceControl* _Nullable* _Nullable* _Nonnull outASurfaceControls, 251 size_t* _Nonnull outASurfaceControlsSize) __INTRODUCED_IN(29); 252 /** 253 * Releases the array of ASurfaceControls that were returned by 254 * ASurfaceTransactionStats_getASurfaceControls(). 255 * 256 * Available since API level 29. 257 */ 258 void ASurfaceTransactionStats_releaseASurfaceControls( 259 ASurfaceControl* _Nonnull* _Nonnull surface_controls) __INTRODUCED_IN(29); 260 261 /** 262 * Returns the timestamp of when the CURRENT buffer was acquired. A buffer is considered 263 * acquired when its acquire_fence_fd has signaled. A buffer cannot be latched or presented until 264 * it is acquired. If no acquire_fence_fd was provided, this timestamp will be set to -1. 265 * 266 * Available since API level 29. 267 * 268 * @deprecated This may return SIGNAL_PENDING because the stats can arrive before the acquire 269 * fence has signaled, depending on internal timing differences. Therefore the caller should 270 * use the acquire fence passed in to setBuffer and query the signal time. 271 */ 272 int64_t ASurfaceTransactionStats_getAcquireTime( 273 ASurfaceTransactionStats* _Nonnull surface_transaction_stats, 274 ASurfaceControl* _Nonnull surface_control) __INTRODUCED_IN(29); 275 276 /** 277 * The returns the fence used to signal the release of the PREVIOUS buffer set on 278 * this surface. If this fence is valid (>=0), the PREVIOUS buffer has not yet been released and the 279 * fence will signal when the PREVIOUS buffer has been released. If the fence is -1, the PREVIOUS 280 * buffer is already released. The recipient of the callback takes ownership of the 281 * previousReleaseFenceFd and is responsible for closing it. 282 * 283 * Each time a buffer is set through ASurfaceTransaction_setBuffer() on a transaction 284 * which is applied, the framework takes a ref on this buffer. The framework treats the 285 * addition of a buffer to a particular surface as a unique ref. When a transaction updates or 286 * removes a buffer from a surface, or removes the surface itself from the tree, this ref is 287 * guaranteed to be released in the OnComplete callback for this transaction. The 288 * ASurfaceControlStats provided in the callback for this surface may contain an optional fence 289 * which must be signaled before the ref is assumed to be released. 290 * 291 * The client must ensure that all pending refs on a buffer are released before attempting to reuse 292 * this buffer, otherwise synchronization errors may occur. 293 * 294 * This query is not valid for ASurfaceTransaction_OnCommit callback. 295 * 296 * Available since API level 29. 297 */ 298 int ASurfaceTransactionStats_getPreviousReleaseFenceFd( 299 ASurfaceTransactionStats* _Nonnull surface_transaction_stats, 300 ASurfaceControl* _Nonnull surface_control) __INTRODUCED_IN(29); 301 302 /** 303 * Sets the callback that will be invoked when the updates from this transaction 304 * are presented. For details on the callback semantics and data, see the 305 * comments on the ASurfaceTransaction_OnComplete declaration above. 306 * 307 * Available since API level 29. 308 */ 309 void ASurfaceTransaction_setOnComplete(ASurfaceTransaction* _Nonnull transaction, 310 void* _Null_unspecified context, 311 ASurfaceTransaction_OnComplete _Nonnull func) 312 __INTRODUCED_IN(29); 313 314 /** 315 * Sets the callback that will be invoked when the updates from this transaction are applied and are 316 * ready to be presented. This callback will be invoked before the ASurfaceTransaction_OnComplete 317 * callback. 318 * 319 * Available since API level 31. 320 */ 321 void ASurfaceTransaction_setOnCommit(ASurfaceTransaction* _Nonnull transaction, 322 void* _Null_unspecified context, 323 ASurfaceTransaction_OnCommit _Nonnull func) 324 __INTRODUCED_IN(31); 325 326 /** 327 * Reparents the \a surface_control from its old parent to the \a new_parent surface control. 328 * Any children of the reparented \a surface_control will remain children of the \a surface_control. 329 * 330 * The \a new_parent can be null. Surface controls with a null parent do not appear on the display. 331 * 332 * Available since API level 29. 333 */ 334 void ASurfaceTransaction_reparent(ASurfaceTransaction* _Nonnull transaction, 335 ASurfaceControl* _Nonnull surface_control, 336 ASurfaceControl* _Nullable new_parent) __INTRODUCED_IN(29); 337 338 /** 339 * Parameter for ASurfaceTransaction_setVisibility(). 340 */ 341 enum ASurfaceTransactionVisibility : int8_t { 342 ASURFACE_TRANSACTION_VISIBILITY_HIDE = 0, 343 ASURFACE_TRANSACTION_VISIBILITY_SHOW = 1, 344 }; 345 /** 346 * Updates the visibility of \a surface_control. If show is set to 347 * ASURFACE_TRANSACTION_VISIBILITY_HIDE, the \a surface_control and all surfaces in its subtree will 348 * be hidden. 349 * 350 * Available since API level 29. 351 */ 352 void ASurfaceTransaction_setVisibility(ASurfaceTransaction* _Nonnull transaction, 353 ASurfaceControl* _Nonnull surface_control, 354 enum ASurfaceTransactionVisibility visibility) 355 __INTRODUCED_IN(29); 356 357 /** 358 * Updates the z order index for \a surface_control. Note that the z order for a surface 359 * is relative to other surfaces which are siblings of this surface. The behavior of sibilings with 360 * the same z order is undefined. 361 * 362 * Z orders may be from MIN_INT32 to MAX_INT32. A layer's default z order index is 0. 363 * 364 * Available since API level 29. 365 */ 366 void ASurfaceTransaction_setZOrder(ASurfaceTransaction* _Nonnull transaction, 367 ASurfaceControl* _Nonnull surface_control, int32_t z_order) 368 __INTRODUCED_IN(29); 369 370 /** 371 * Updates the AHardwareBuffer displayed for \a surface_control. If not -1, the 372 * acquire_fence_fd should be a file descriptor that is signaled when all pending work 373 * for the buffer is complete and the buffer can be safely read. 374 * 375 * The frameworks takes ownership of the \a acquire_fence_fd passed and is responsible 376 * for closing it. 377 * 378 * Note that the buffer must be allocated with AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE 379 * as the surface control might be composited using the GPU. 380 * 381 * Starting with API level 36, prefer using \a ASurfaceTransaction_setBufferWithRelease to 382 * set a buffer and a callback which will be invoked when the buffer is ready to be reused. 383 * 384 * Available since API level 29. 385 */ 386 void ASurfaceTransaction_setBuffer(ASurfaceTransaction* _Nonnull transaction, 387 ASurfaceControl* _Nonnull surface_control, 388 AHardwareBuffer* _Nonnull buffer, int acquire_fence_fd) 389 __INTRODUCED_IN(29); 390 391 /** 392 * Updates the AHardwareBuffer displayed for \a surface_control. If not -1, the 393 * acquire_fence_fd should be a file descriptor that is signaled when all pending work 394 * for the buffer is complete and the buffer can be safely read. 395 * 396 * The frameworks takes ownership of the \a acquire_fence_fd passed and is responsible 397 * for closing it. 398 * 399 * Note that the buffer must be allocated with AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE 400 * as the surface control might be composited using the GPU. 401 * 402 * When the buffer is ready to be reused, the ASurfaceTransaction_OnBufferRelease 403 * callback will be invoked. If the buffer is null, the callback will not be invoked. 404 * 405 * Available since API level 36. 406 */ 407 void ASurfaceTransaction_setBufferWithRelease(ASurfaceTransaction* _Nonnull transaction, 408 ASurfaceControl* _Nonnull surface_control, 409 AHardwareBuffer* _Nonnull buffer, 410 int acquire_fence_fd, void* _Null_unspecified context, 411 ASurfaceTransaction_OnBufferRelease _Nonnull func) 412 __INTRODUCED_IN(36); 413 414 /** 415 * Updates the color for \a surface_control. This will make the background color for the 416 * ASurfaceControl visible in transparent regions of the surface. Colors \a r, \a g, 417 * and \a b must be within the range that is valid for \a dataspace. \a dataspace and \a alpha 418 * will be the dataspace and alpha set for the background color layer. 419 * 420 * Available since API level 29. 421 */ 422 void ASurfaceTransaction_setColor(ASurfaceTransaction* _Nonnull transaction, 423 ASurfaceControl* _Nonnull surface_control, float r, float g, 424 float b, float alpha, enum ADataSpace dataspace) 425 __INTRODUCED_IN(29); 426 427 // These APIs (setGeometry and setCrop) were originally written in a 428 // C-incompatible form using references instead of pointers, and the OS shipped 429 // that version for years before it was noticed. Fortunately the compiled code 430 // for callers is the same regardless of whether it's a pointer or a reference, 431 // so we can declare this as a nonnull pointer for C and keep the existing C++ 432 // decl and definition. 433 // 434 // We could alternatively change the decl and the definition to both be a 435 // pointer (with an inline definition using references to preserve source compat 436 // for existing C++ callers), but that requires changing the definition of an 437 // API that has been in the OS for years. It's theoretically a safe change, but 438 // without being able to prove it that's a very big risk to take. By keeping the 439 // C-compatibility hack in the header, we can be sure that we haven't changed 440 // anything for existing callers. By definition there were no C users of the 441 // reference-based decl; if there were any C callers of the API at all, they were 442 // using the same workaround that is now used below. 443 // 444 // Even if this workaround turns out to not work for C, there's no permanent 445 // damage done to the platform (unlike if we were to change the definition). At 446 // worst it continues to work for C++ (since the preprocessed header as seen by 447 // C++ hasn't changed, nor has the definition) and continues to not work for C. 448 449 /** 450 * \param source The sub-rect within the buffer's content to be rendered inside the surface's area 451 * The surface's source rect is clipped by the bounds of its current buffer. The source rect's width 452 * and height must be > 0. 453 * 454 * \param destination Specifies the rect in the parent's space where this surface will be drawn. The 455 * post source rect bounds are scaled to fit the destination rect. The surface's destination rect is 456 * clipped by the bounds of its parent. The destination rect's width and height must be > 0. 457 * 458 * \param transform The transform applied after the source rect is applied to the buffer. This 459 * parameter should be set to 0 for no transform. To specify a transform use the 460 * NATIVE_WINDOW_TRANSFORM_* enum. 461 * 462 * Available since API level 29. 463 * 464 * @deprecated Use setCrop, setPosition, setBufferTransform, and setScale instead. Those functions 465 * provide well defined behavior and allows for more control by the apps. It also allows the caller 466 * to set different properties at different times, instead of having to specify all the desired 467 * properties at once. 468 */ 469 void ASurfaceTransaction_setGeometry(ASurfaceTransaction* _Nonnull transaction, 470 ASurfaceControl* _Nonnull surface_control, 471 #if defined(__cplusplus) 472 const ARect& source, const ARect& destination, 473 #else 474 const ARect* _Nonnull source, 475 const ARect* _Nonnull destination, 476 #endif 477 int32_t transform) __INTRODUCED_IN(29); 478 479 /** 480 * Bounds the surface and its children to the bounds specified. The crop and buffer size will be 481 * used to determine the bounds of the surface. If no crop is specified and the surface has no 482 * buffer, the surface bounds is only constrained by the size of its parent bounds. 483 * 484 * \param crop The bounds of the crop to apply. 485 * 486 * Available since API level 31. 487 */ 488 void ASurfaceTransaction_setCrop(ASurfaceTransaction* _Nonnull transaction, 489 ASurfaceControl* _Nonnull surface_control, 490 #if defined(__cplusplus) 491 const ARect& crop) 492 #else 493 const ARect* _Nonnull crop) 494 #endif 495 __INTRODUCED_IN(31); 496 497 /** 498 * Specifies the position in the parent's space where the surface will be drawn. 499 * 500 * \param x The x position to render the surface. 501 * \param y The y position to render the surface. 502 * 503 * Available since API level 31. 504 */ 505 void ASurfaceTransaction_setPosition(ASurfaceTransaction* _Nonnull transaction, 506 ASurfaceControl* _Nonnull surface_control, int32_t x, 507 int32_t y) __INTRODUCED_IN(31); 508 509 /** 510 * \param transform The transform applied after the source rect is applied to the buffer. This 511 * parameter should be set to 0 for no transform. To specify a transform use the 512 * NATIVE_WINDOW_TRANSFORM_* enum. 513 * 514 * Available since API level 31. 515 */ 516 void ASurfaceTransaction_setBufferTransform(ASurfaceTransaction* _Nonnull transaction, 517 ASurfaceControl* _Nonnull surface_control, 518 int32_t transform) __INTRODUCED_IN(31); 519 520 /** 521 * Sets an x and y scale of a surface with (0, 0) as the centerpoint of the scale. 522 * 523 * \param xScale The scale in the x direction. Must be greater than 0. 524 * \param yScale The scale in the y direction. Must be greater than 0. 525 * 526 * Available since API level 31. 527 */ 528 void ASurfaceTransaction_setScale(ASurfaceTransaction* _Nonnull transaction, 529 ASurfaceControl* _Nonnull surface_control, float xScale, 530 float yScale) __INTRODUCED_IN(31); 531 /** 532 * Parameter for ASurfaceTransaction_setBufferTransparency(). 533 */ 534 enum ASurfaceTransactionTransparency : int8_t { 535 ASURFACE_TRANSACTION_TRANSPARENCY_TRANSPARENT = 0, 536 ASURFACE_TRANSACTION_TRANSPARENCY_TRANSLUCENT = 1, 537 ASURFACE_TRANSACTION_TRANSPARENCY_OPAQUE = 2, 538 }; 539 /** 540 * Updates whether the content for the buffer associated with this surface is 541 * completely opaque. If true, every pixel of content inside the buffer must be 542 * opaque or visual errors can occur. 543 * 544 * Available since API level 29. 545 */ 546 void ASurfaceTransaction_setBufferTransparency(ASurfaceTransaction* _Nonnull transaction, 547 ASurfaceControl* _Nonnull surface_control, 548 enum ASurfaceTransactionTransparency transparency) 549 __INTRODUCED_IN(29); 550 551 /** 552 * Updates the region for the content on this surface updated in this 553 * transaction. If unspecified, the complete surface is assumed to be damaged. 554 * 555 * Available since API level 29. 556 */ 557 void ASurfaceTransaction_setDamageRegion(ASurfaceTransaction* _Nonnull transaction, 558 ASurfaceControl* _Nonnull surface_control, 559 const ARect* _Nullable rects, uint32_t count) 560 __INTRODUCED_IN(29); 561 562 /** 563 * Specifies a desiredPresentTime for the transaction. The framework will try to present 564 * the transaction at or after the time specified. 565 * 566 * Transactions will not be presented until all of their acquire fences have signaled even if the 567 * app requests an earlier present time. 568 * 569 * If an earlier transaction has a desired present time of x, and a later transaction has a desired 570 * present time that is before x, the later transaction will not preempt the earlier transaction. 571 * 572 * Available since API level 29. 573 */ 574 void ASurfaceTransaction_setDesiredPresentTime(ASurfaceTransaction* _Nonnull transaction, 575 int64_t desiredPresentTime) __INTRODUCED_IN(29); 576 577 /** 578 * Sets the alpha for the buffer. It uses a premultiplied blending. 579 * 580 * The \a alpha must be between 0.0 and 1.0. 581 * 582 * Available since API level 29. 583 */ 584 void ASurfaceTransaction_setBufferAlpha(ASurfaceTransaction* _Nonnull transaction, 585 ASurfaceControl* _Nonnull surface_control, float alpha) 586 __INTRODUCED_IN(29); 587 588 /** 589 * Sets the data space of the surface_control's buffers. 590 * 591 * If no data space is set, the surface control defaults to ADATASPACE_SRGB. 592 * 593 * Available since API level 29. 594 */ 595 void ASurfaceTransaction_setBufferDataSpace(ASurfaceTransaction* _Nonnull transaction, 596 ASurfaceControl* _Nonnull surface_control, 597 enum ADataSpace data_space) __INTRODUCED_IN(29); 598 599 /** 600 * SMPTE ST 2086 "Mastering Display Color Volume" static metadata 601 * 602 * When \a metadata is set to null, the framework does not use any smpte2086 metadata when rendering 603 * the surface's buffer. 604 * 605 * Available since API level 29. 606 */ 607 void ASurfaceTransaction_setHdrMetadata_smpte2086(ASurfaceTransaction* _Nonnull transaction, 608 ASurfaceControl* _Nonnull surface_control, 609 struct AHdrMetadata_smpte2086* _Nullable metadata) 610 __INTRODUCED_IN(29); 611 612 /** 613 * Sets the CTA 861.3 "HDR Static Metadata Extension" static metadata on a surface. 614 * 615 * When \a metadata is set to null, the framework does not use any cta861.3 metadata when rendering 616 * the surface's buffer. 617 * 618 * Available since API level 29. 619 */ 620 void ASurfaceTransaction_setHdrMetadata_cta861_3(ASurfaceTransaction* _Nonnull transaction, 621 ASurfaceControl* _Nonnull surface_control, 622 struct AHdrMetadata_cta861_3* _Nullable metadata) 623 __INTRODUCED_IN(29); 624 625 /** 626 * Sets the desired extended range brightness for the layer. This only applies for layers whose 627 * dataspace has RANGE_EXTENDED set on it. See: ASurfaceTransaction_setDesiredHdrHeadroom, prefer 628 * using this API for formats that encode an HDR/SDR ratio as part of generating the buffer. 629 * 630 * @param surface_control The layer whose extended range brightness is being specified 631 * @param currentBufferRatio The current HDR/SDR ratio of the current buffer as represented as 632 * peakHdrBrightnessInNits / targetSdrWhitePointInNits. For example if the 633 * buffer was rendered with a target SDR whitepoint of 100nits and a max 634 * display brightness of 200nits, this should be set to 2.0f. 635 * 636 * Default value is 1.0f. 637 * 638 * Transfer functions that encode their own brightness ranges, such as 639 * HLG or PQ, should also set this to 1.0f and instead communicate 640 * extended content brightness information via metadata such as CTA861_3 641 * or SMPTE2086. 642 * 643 * Must be finite && >= 1.0f 644 * 645 * @param desiredRatio The desired HDR/SDR ratio as represented as peakHdrBrightnessInNits / 646 * targetSdrWhitePointInNits. This can be used to communicate the max desired 647 * brightness range. This is similar to the "max luminance" value in other 648 * HDR metadata formats, but represented as a ratio of the target SDR whitepoint 649 * to the max display brightness. The system may not be able to, or may choose 650 * not to, deliver the requested range. 651 * 652 * While requesting a large desired ratio will result in the most 653 * dynamic range, voluntarily reducing the requested range can help 654 * improve battery life as well as can improve quality by ensuring 655 * greater bit depth is allocated to the luminance range in use. 656 * 657 * Default value is 1.0f and indicates that extended range brightness 658 * is not being used, so the resulting SDR or HDR behavior will be 659 * determined entirely by the dataspace being used (ie, typically SDR 660 * however PQ or HLG transfer functions will still result in HDR) 661 * 662 * When called after ASurfaceTransaction_setDesiredHdrHeadroom, the 663 * desiredRatio will override the desiredHeadroom provided by 664 * ASurfaceTransaction_setDesiredHdrHeadroom. Conversely, when called before 665 * ASurfaceTransaction_setDesiredHdrHeadroom, the desiredHeadroom provided by 666 *. ASurfaceTransaction_setDesiredHdrHeadroom will override the desiredRatio. 667 * 668 * Must be finite && >= 1.0f 669 * 670 * Available since API level 34. 671 */ 672 void ASurfaceTransaction_setExtendedRangeBrightness(ASurfaceTransaction* _Nonnull transaction, 673 ASurfaceControl* _Nonnull surface_control, 674 float currentBufferRatio, float desiredRatio) 675 __INTRODUCED_IN(__ANDROID_API_U__); 676 677 /** 678 * Sets the desired HDR headroom for the layer. See: ASurfaceTransaction_setExtendedRangeBrightness, 679 * prefer using this API for formats that conform to HDR standards like HLG or HDR10, that do not 680 * communicate a HDR/SDR ratio as part of generating the buffer. 681 * 682 * @param surface_control The layer whose desired HDR headroom is being specified 683 * 684 * @param desiredHeadroom The desired HDR/SDR ratio as represented as peakHdrBrightnessInNits / 685 * targetSdrWhitePointInNits. This can be used to communicate the max 686 * desired brightness range of the panel. The system may not be able to, or 687 * may choose not to, deliver the requested range. 688 * 689 * While requesting a large desired ratio will result in the most 690 * dynamic range, voluntarily reducing the requested range can help 691 * improve battery life as well as can improve quality by ensuring 692 * greater bit depth is allocated to the luminance range in use. 693 * 694 * Default value is 0.0f and indicates that the system will choose the best 695 * headroom for this surface control's content. Typically, this means that 696 * HLG/PQ encoded content will be displayed with some HDR headroom greater 697 * than 1.0. 698 * 699 * When called after ASurfaceTransaction_setExtendedRangeBrightness, the 700 * desiredHeadroom will override the desiredRatio provided by 701 * ASurfaceTransaction_setExtendedRangeBrightness. Conversely, when called 702 * before ASurfaceTransaction_setExtendedRangeBrightness, the desiredRatio 703 * provided by ASurfaceTransaction_setExtendedRangeBrightness will override 704 * the desiredHeadroom. 705 * 706 * Must be finite && >= 1.0f or 0.0f to indicate there is no desired 707 * headroom. 708 * 709 * Available since API level 35. 710 */ 711 void ASurfaceTransaction_setDesiredHdrHeadroom(ASurfaceTransaction* _Nonnull transaction, 712 ASurfaceControl* _Nonnull surface_control, 713 float desiredHeadroom) 714 __INTRODUCED_IN(__ANDROID_API_V__); 715 716 /** 717 * Sets the Lut(s) to be applied for the layer. 718 * 719 * The function makes a deep copy of the provided `luts`. 720 * Any modifications made to the `luts` object after calling this function 721 * will not affect the Lut(s) applied to the layer. 722 * 723 * @param surface_control The layer where Lut(s) is being applied 724 * @param luts The Lut(s) to be applied 725 * 726 * Available since API level 36. 727 */ 728 void ASurfaceTransaction_setLuts(ASurfaceTransaction* _Nonnull transaction, 729 ASurfaceControl* _Nonnull surface_control, 730 const struct ADisplayLuts* _Nullable luts) 731 __INTRODUCED_IN(36); 732 733 /** 734 * Same as ASurfaceTransaction_setFrameRateWithChangeStrategy(transaction, surface_control, 735 * frameRate, compatibility, ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS). 736 * 737 * See ASurfaceTransaction_setFrameRateWithChangeStrategy(). 738 * 739 * Available since API level 30. 740 */ 741 void ASurfaceTransaction_setFrameRate(ASurfaceTransaction* _Nonnull transaction, 742 ASurfaceControl* _Nonnull surface_control, float frameRate, 743 int8_t compatibility) __INTRODUCED_IN(30); 744 745 /** 746 * Sets the intended frame rate for \a surface_control. 747 * 748 * On devices that are capable of running the display at different refresh rates, the system may 749 * choose a display refresh rate to better match this surface's frame rate. Usage of this API won't 750 * directly affect the application's frame production pipeline. However, because the system may 751 * change the display refresh rate, calls to this function may result in changes to Choreographer 752 * callback timings, and changes to the time interval at which the system releases buffers back to 753 * the application. 754 * 755 * You can register for changes in the refresh rate using 756 * \a AChoreographer_registerRefreshRateCallback. 757 * 758 * See ASurfaceTransaction_clearFrameRate(). 759 * 760 * \param frameRate is the intended frame rate of this surface, in frames per second. 0 is a special 761 * value that indicates the app will accept the system's choice for the display frame rate, which is 762 * the default behavior if this function isn't called. The frameRate param does <em>not</em> need to 763 * be a valid refresh rate for this device's display - e.g., it's fine to pass 30fps to a device 764 * that can only run the display at 60fps. 765 * 766 * \param compatibility The frame rate compatibility of this surface. The compatibility value may 767 * influence the system's choice of display frame rate. To specify a compatibility use the 768 * ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_* enum. This parameter is ignored when frameRate is 0. 769 * 770 * \param changeFrameRateStrategy Whether display refresh rate transitions caused by this 771 * surface should be seamless. A seamless transition is one that doesn't have any visual 772 * interruptions, such as a black screen for a second or two. See the 773 * ANATIVEWINDOW_CHANGE_FRAME_RATE_* values. This parameter is ignored when frameRate is 0. 774 * 775 * Available since API level 31. 776 */ 777 void ASurfaceTransaction_setFrameRateWithChangeStrategy(ASurfaceTransaction* _Nonnull transaction, 778 ASurfaceControl* _Nonnull surface_control, 779 float frameRate, int8_t compatibility, 780 int8_t changeFrameRateStrategy) 781 __INTRODUCED_IN(31); 782 783 /** 784 * Clears the frame rate which is set for \a surface_control. 785 * 786 * This is equivalent to calling 787 * ASurfaceTransaction_setFrameRateWithChangeStrategy( 788 * transaction, 0, compatibility, changeFrameRateStrategy). 789 * 790 * Usage of this API won't directly affect the application's frame production pipeline. However, 791 * because the system may change the display refresh rate, calls to this function may result in 792 * changes to Choreographer callback timings, and changes to the time interval at which the system 793 * releases buffers back to the application. 794 * 795 * See ASurfaceTransaction_setFrameRateWithChangeStrategy() 796 * 797 * You can register for changes in the refresh rate using 798 * \a AChoreographer_registerRefreshRateCallback. 799 * 800 * See ASurfaceTransaction_setFrameRateWithChangeStrategy(). 801 * 802 * Available since API level 34. 803 */ 804 void ASurfaceTransaction_clearFrameRate(ASurfaceTransaction* _Nonnull transaction, 805 ASurfaceControl* _Nonnull surface_control) 806 __INTRODUCED_IN(__ANDROID_API_U__); 807 808 /** 809 * Indicate whether to enable backpressure for buffer submission to a given SurfaceControl. 810 * 811 * By default backpressure is disabled, which means submitting a buffer prior to receiving 812 * a callback for the previous buffer could lead to that buffer being "dropped". In cases 813 * where you are selecting for latency, this may be a desirable behavior! We had a new buffer 814 * ready, why shouldn't we show it? 815 * 816 * When back pressure is enabled, each buffer will be required to be presented 817 * before it is released and the callback delivered 818 * (absent the whole SurfaceControl being removed). 819 * 820 * Most apps are likely to have some sort of backpressure internally, e.g. you are 821 * waiting on the callback from frame N-2 before starting frame N. In high refresh 822 * rate scenarios there may not be much time between SurfaceFlinger completing frame 823 * N-1 (and therefore releasing buffer N-2) and beginning frame N. This means 824 * your app may not have enough time to respond in the callback. Using this flag 825 * and pushing buffers earlier for server side queuing will be advantageous 826 * in such cases. 827 * 828 * Available since API level 31. 829 * 830 * \param transaction The transaction in which to make the change. 831 * \param surface_control The ASurfaceControl on which to control buffer backpressure behavior. 832 * \param enableBackPressure Whether to enable back pressure. 833 */ 834 void ASurfaceTransaction_setEnableBackPressure(ASurfaceTransaction* _Nonnull transaction, 835 ASurfaceControl* _Nonnull surface_control, 836 bool enableBackPressure) __INTRODUCED_IN(31); 837 838 /** 839 * Sets the frame timeline to use in SurfaceFlinger. 840 * 841 * A frame timeline should be chosen based on the frame deadline the application 842 * can meet when rendering the frame and the application's desired presentation time. 843 * By setting a frame timeline, SurfaceFlinger tries to present the frame at the corresponding 844 * expected presentation time. 845 * 846 * To receive frame timelines, a callback must be posted to Choreographer using 847 * AChoreographer_postVsyncCallback(). The \c vsyncId can then be extracted from the 848 * callback payload using AChoreographerFrameCallbackData_getFrameTimelineVsyncId(). 849 * 850 * Available since API level 33. 851 * 852 * \param vsyncId The vsync ID received from AChoreographer, setting the frame's presentation target 853 * to the corresponding expected presentation time and deadline from the frame to be rendered. A 854 * stale or invalid value will be ignored. 855 */ 856 void ASurfaceTransaction_setFrameTimeline(ASurfaceTransaction* _Nonnull transaction, 857 AVsyncId vsyncId) __INTRODUCED_IN(33); 858 859 __END_DECLS 860 861 #endif // ANDROID_SURFACE_CONTROL_H 862 863 /** @} */ 864