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