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