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