window.h revision a6c0e20ac89b1be29901a7200590bf7cb8b99f78
1/* 2 * Copyright (C) 2011 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 * 19 * IMPORTANT: 20 * 21 * There is an old copy of this file in system/core/include/system/window.h, which exists only 22 * for backward source compatibility. 23 * But there are binaries out there as well, so this version of window.h must stay binary 24 * backward compatible with the one found in system/core. 25 * 26 * 27 * Source compatibility is also required for now, because this is how we're handling the 28 * transition from system/core/include (global include path) to nativewindow/include. 29 * 30 *************************************************************************************************/ 31 32#pragma once 33 34#include <cutils/native_handle.h> 35#include <errno.h> 36#include <limits.h> 37#include <stdint.h> 38#include <string.h> 39#include <sys/cdefs.h> 40#include <system/graphics.h> 41#include <unistd.h> 42#include <stdbool.h> 43 44// system/window.h is a superset of the vndk 45#include <vndk/window.h> 46 47 48#ifndef __UNUSED 49#define __UNUSED __attribute__((__unused__)) 50#endif 51#ifndef __deprecated 52#define __deprecated __attribute__((__deprecated__)) 53#endif 54 55__BEGIN_DECLS 56 57/*****************************************************************************/ 58 59#ifdef __cplusplus 60#define ANDROID_NATIVE_UNSIGNED_CAST(x) static_cast<unsigned int>(x) 61#else 62#define ANDROID_NATIVE_UNSIGNED_CAST(x) ((unsigned int)(x)) 63#endif 64 65#define ANDROID_NATIVE_MAKE_CONSTANT(a,b,c,d) \ 66 ((ANDROID_NATIVE_UNSIGNED_CAST(a) << 24) | \ 67 (ANDROID_NATIVE_UNSIGNED_CAST(b) << 16) | \ 68 (ANDROID_NATIVE_UNSIGNED_CAST(c) << 8) | \ 69 (ANDROID_NATIVE_UNSIGNED_CAST(d))) 70 71#define ANDROID_NATIVE_WINDOW_MAGIC \ 72 ANDROID_NATIVE_MAKE_CONSTANT('_','w','n','d') 73 74#define ANDROID_NATIVE_BUFFER_MAGIC \ 75 ANDROID_NATIVE_MAKE_CONSTANT('_','b','f','r') 76 77// --------------------------------------------------------------------------- 78 79// This #define may be used to conditionally compile device-specific code to 80// support either the prior ANativeWindow interface, which did not pass libsync 81// fences around, or the new interface that does. This #define is only present 82// when the ANativeWindow interface does include libsync support. 83#define ANDROID_NATIVE_WINDOW_HAS_SYNC 1 84 85// --------------------------------------------------------------------------- 86 87typedef const native_handle_t* buffer_handle_t; 88 89// --------------------------------------------------------------------------- 90 91typedef struct android_native_rect_t 92{ 93 int32_t left; 94 int32_t top; 95 int32_t right; 96 int32_t bottom; 97} android_native_rect_t; 98 99// --------------------------------------------------------------------------- 100 101typedef struct android_native_base_t 102{ 103 /* a magic value defined by the actual EGL native type */ 104 int magic; 105 106 /* the sizeof() of the actual EGL native type */ 107 int version; 108 109 void* reserved[4]; 110 111 /* reference-counting interface */ 112 void (*incRef)(struct android_native_base_t* base); 113 void (*decRef)(struct android_native_base_t* base); 114} android_native_base_t; 115 116typedef struct ANativeWindowBuffer 117{ 118#ifdef __cplusplus 119 ANativeWindowBuffer() { 120 common.magic = ANDROID_NATIVE_BUFFER_MAGIC; 121 common.version = sizeof(ANativeWindowBuffer); 122 memset(common.reserved, 0, sizeof(common.reserved)); 123 } 124 125 // Implement the methods that sp<ANativeWindowBuffer> expects so that it 126 // can be used to automatically refcount ANativeWindowBuffer's. 127 void incStrong(const void* /*id*/) const { 128 common.incRef(const_cast<android_native_base_t*>(&common)); 129 } 130 void decStrong(const void* /*id*/) const { 131 common.decRef(const_cast<android_native_base_t*>(&common)); 132 } 133#endif 134 135 struct android_native_base_t common; 136 137 int width; 138 int height; 139 int stride; 140 int format; 141 int usage; 142 uintptr_t layerCount; 143 144 void* reserved[1]; 145 146 buffer_handle_t handle; 147 148 void* reserved_proc[8]; 149} ANativeWindowBuffer_t; 150 151// Old typedef for backwards compatibility. 152typedef ANativeWindowBuffer_t android_native_buffer_t; 153 154// --------------------------------------------------------------------------- 155 156/* attributes queriable with query() */ 157enum { 158 NATIVE_WINDOW_WIDTH = 0, 159 NATIVE_WINDOW_HEIGHT = 1, 160 NATIVE_WINDOW_FORMAT = 2, 161 162 /* The minimum number of buffers that must remain un-dequeued after a buffer 163 * has been queued. This value applies only if set_buffer_count was used to 164 * override the number of buffers and if a buffer has since been queued. 165 * Users of the set_buffer_count ANativeWindow method should query this 166 * value before calling set_buffer_count. If it is necessary to have N 167 * buffers simultaneously dequeued as part of the steady-state operation, 168 * and this query returns M then N+M buffers should be requested via 169 * native_window_set_buffer_count. 170 * 171 * Note that this value does NOT apply until a single buffer has been 172 * queued. In particular this means that it is possible to: 173 * 174 * 1. Query M = min undequeued buffers 175 * 2. Set the buffer count to N + M 176 * 3. Dequeue all N + M buffers 177 * 4. Cancel M buffers 178 * 5. Queue, dequeue, queue, dequeue, ad infinitum 179 */ 180 NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS = 3, 181 182 /* Check whether queueBuffer operations on the ANativeWindow send the buffer 183 * to the window compositor. The query sets the returned 'value' argument 184 * to 1 if the ANativeWindow DOES send queued buffers directly to the window 185 * compositor and 0 if the buffers do not go directly to the window 186 * compositor. 187 * 188 * This can be used to determine whether protected buffer content should be 189 * sent to the ANativeWindow. Note, however, that a result of 1 does NOT 190 * indicate that queued buffers will be protected from applications or users 191 * capturing their contents. If that behavior is desired then some other 192 * mechanism (e.g. the GRALLOC_USAGE_PROTECTED flag) should be used in 193 * conjunction with this query. 194 */ 195 NATIVE_WINDOW_QUEUES_TO_WINDOW_COMPOSER = 4, 196 197 /* Get the concrete type of a ANativeWindow. See below for the list of 198 * possible return values. 199 * 200 * This query should not be used outside the Android framework and will 201 * likely be removed in the near future. 202 */ 203 NATIVE_WINDOW_CONCRETE_TYPE = 5, 204 205 206 /* 207 * Default width and height of ANativeWindow buffers, these are the 208 * dimensions of the window buffers irrespective of the 209 * NATIVE_WINDOW_SET_BUFFERS_DIMENSIONS call and match the native window 210 * size unless overridden by NATIVE_WINDOW_SET_BUFFERS_USER_DIMENSIONS. 211 */ 212 NATIVE_WINDOW_DEFAULT_WIDTH = 6, 213 NATIVE_WINDOW_DEFAULT_HEIGHT = 7, 214 215 /* 216 * transformation that will most-likely be applied to buffers. This is only 217 * a hint, the actual transformation applied might be different. 218 * 219 * INTENDED USE: 220 * 221 * The transform hint can be used by a producer, for instance the GLES 222 * driver, to pre-rotate the rendering such that the final transformation 223 * in the composer is identity. This can be very useful when used in 224 * conjunction with the h/w composer HAL, in situations where it 225 * cannot handle arbitrary rotations. 226 * 227 * 1. Before dequeuing a buffer, the GL driver (or any other ANW client) 228 * queries the ANW for NATIVE_WINDOW_TRANSFORM_HINT. 229 * 230 * 2. The GL driver overrides the width and height of the ANW to 231 * account for NATIVE_WINDOW_TRANSFORM_HINT. This is done by querying 232 * NATIVE_WINDOW_DEFAULT_{WIDTH | HEIGHT}, swapping the dimensions 233 * according to NATIVE_WINDOW_TRANSFORM_HINT and calling 234 * native_window_set_buffers_dimensions(). 235 * 236 * 3. The GL driver dequeues a buffer of the new pre-rotated size. 237 * 238 * 4. The GL driver renders to the buffer such that the image is 239 * already transformed, that is applying NATIVE_WINDOW_TRANSFORM_HINT 240 * to the rendering. 241 * 242 * 5. The GL driver calls native_window_set_transform to apply 243 * inverse transformation to the buffer it just rendered. 244 * In order to do this, the GL driver needs 245 * to calculate the inverse of NATIVE_WINDOW_TRANSFORM_HINT, this is 246 * done easily: 247 * 248 * int hintTransform, inverseTransform; 249 * query(..., NATIVE_WINDOW_TRANSFORM_HINT, &hintTransform); 250 * inverseTransform = hintTransform; 251 * if (hintTransform & HAL_TRANSFORM_ROT_90) 252 * inverseTransform ^= HAL_TRANSFORM_ROT_180; 253 * 254 * 255 * 6. The GL driver queues the pre-transformed buffer. 256 * 257 * 7. The composer combines the buffer transform with the display 258 * transform. If the buffer transform happens to cancel out the 259 * display transform then no rotation is needed. 260 * 261 */ 262 NATIVE_WINDOW_TRANSFORM_HINT = 8, 263 264 /* 265 * Boolean that indicates whether the consumer is running more than 266 * one buffer behind the producer. 267 */ 268 NATIVE_WINDOW_CONSUMER_RUNNING_BEHIND = 9, 269 270 /* 271 * The consumer gralloc usage bits currently set by the consumer. 272 * The values are defined in hardware/libhardware/include/gralloc.h. 273 */ 274 NATIVE_WINDOW_CONSUMER_USAGE_BITS = 10, 275 276 /** 277 * Transformation that will by applied to buffers by the hwcomposer. 278 * This must not be set or checked by producer endpoints, and will 279 * disable the transform hint set in SurfaceFlinger (see 280 * NATIVE_WINDOW_TRANSFORM_HINT). 281 * 282 * INTENDED USE: 283 * Temporary - Please do not use this. This is intended only to be used 284 * by the camera's LEGACY mode. 285 * 286 * In situations where a SurfaceFlinger client wishes to set a transform 287 * that is not visible to the producer, and will always be applied in the 288 * hardware composer, the client can set this flag with 289 * native_window_set_buffers_sticky_transform. This can be used to rotate 290 * and flip buffers consumed by hardware composer without actually changing 291 * the aspect ratio of the buffers produced. 292 */ 293 NATIVE_WINDOW_STICKY_TRANSFORM = 11, 294 295 /** 296 * The default data space for the buffers as set by the consumer. 297 * The values are defined in graphics.h. 298 */ 299 NATIVE_WINDOW_DEFAULT_DATASPACE = 12, 300 301 /* 302 * Returns the age of the contents of the most recently dequeued buffer as 303 * the number of frames that have elapsed since it was last queued. For 304 * example, if the window is double-buffered, the age of any given buffer in 305 * steady state will be 2. If the dequeued buffer has never been queued, its 306 * age will be 0. 307 */ 308 NATIVE_WINDOW_BUFFER_AGE = 13, 309 310 /* 311 * Returns the duration of the last dequeueBuffer call in microseconds 312 */ 313 NATIVE_WINDOW_LAST_DEQUEUE_DURATION = 14, 314 315 /* 316 * Returns the duration of the last queueBuffer call in microseconds 317 */ 318 NATIVE_WINDOW_LAST_QUEUE_DURATION = 15, 319 320 /* 321 * Returns the number of image layers that the ANativeWindow buffer 322 * contains. By default this is 1, unless a buffer is explicitly allocated 323 * to contain multiple layers. 324 */ 325 NATIVE_WINDOW_LAYER_COUNT = 16, 326 327 /* 328 * Returns 1 if the native window is valid, 0 otherwise. native window is valid 329 * if it is safe (i.e. no crash will occur) to call any method on it. 330 */ 331 NATIVE_WINDOW_IS_VALID = 17, 332}; 333 334/* Valid operations for the (*perform)() hook. 335 * 336 * Values marked as 'deprecated' are supported, but have been superceded by 337 * other functionality. 338 * 339 * Values marked as 'private' should be considered private to the framework. 340 * HAL implementation code with access to an ANativeWindow should not use these, 341 * as it may not interact properly with the framework's use of the 342 * ANativeWindow. 343 */ 344enum { 345// clang-format off 346 NATIVE_WINDOW_SET_USAGE = 0, 347 NATIVE_WINDOW_CONNECT = 1, /* deprecated */ 348 NATIVE_WINDOW_DISCONNECT = 2, /* deprecated */ 349 NATIVE_WINDOW_SET_CROP = 3, /* private */ 350 NATIVE_WINDOW_SET_BUFFER_COUNT = 4, 351 NATIVE_WINDOW_SET_BUFFERS_GEOMETRY = 5, /* deprecated */ 352 NATIVE_WINDOW_SET_BUFFERS_TRANSFORM = 6, 353 NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP = 7, 354 NATIVE_WINDOW_SET_BUFFERS_DIMENSIONS = 8, 355 NATIVE_WINDOW_SET_BUFFERS_FORMAT = 9, 356 NATIVE_WINDOW_SET_SCALING_MODE = 10, /* private */ 357 NATIVE_WINDOW_LOCK = 11, /* private */ 358 NATIVE_WINDOW_UNLOCK_AND_POST = 12, /* private */ 359 NATIVE_WINDOW_API_CONNECT = 13, /* private */ 360 NATIVE_WINDOW_API_DISCONNECT = 14, /* private */ 361 NATIVE_WINDOW_SET_BUFFERS_USER_DIMENSIONS = 15, /* private */ 362 NATIVE_WINDOW_SET_POST_TRANSFORM_CROP = 16, /* private */ 363 NATIVE_WINDOW_SET_BUFFERS_STICKY_TRANSFORM = 17,/* private */ 364 NATIVE_WINDOW_SET_SIDEBAND_STREAM = 18, 365 NATIVE_WINDOW_SET_BUFFERS_DATASPACE = 19, 366 NATIVE_WINDOW_SET_SURFACE_DAMAGE = 20, /* private */ 367 NATIVE_WINDOW_SET_SHARED_BUFFER_MODE = 21, 368 NATIVE_WINDOW_SET_AUTO_REFRESH = 22, 369 NATIVE_WINDOW_GET_REFRESH_CYCLE_DURATION= 23, 370 NATIVE_WINDOW_GET_NEXT_FRAME_ID = 24, 371 NATIVE_WINDOW_ENABLE_FRAME_TIMESTAMPS = 25, 372 NATIVE_WINDOW_GET_COMPOSITOR_TIMING = 26, 373 NATIVE_WINDOW_GET_FRAME_TIMESTAMPS = 27, 374 NATIVE_WINDOW_GET_WIDE_COLOR_SUPPORT = 28, 375 NATIVE_WINDOW_GET_HDR_SUPPORT = 29, 376// clang-format on 377}; 378 379/* parameter for NATIVE_WINDOW_[API_][DIS]CONNECT */ 380enum { 381 /* Buffers will be queued by EGL via eglSwapBuffers after being filled using 382 * OpenGL ES. 383 */ 384 NATIVE_WINDOW_API_EGL = 1, 385 386 /* Buffers will be queued after being filled using the CPU 387 */ 388 NATIVE_WINDOW_API_CPU = 2, 389 390 /* Buffers will be queued by Stagefright after being filled by a video 391 * decoder. The video decoder can either be a software or hardware decoder. 392 */ 393 NATIVE_WINDOW_API_MEDIA = 3, 394 395 /* Buffers will be queued by the the camera HAL. 396 */ 397 NATIVE_WINDOW_API_CAMERA = 4, 398}; 399 400/* parameter for NATIVE_WINDOW_SET_BUFFERS_TRANSFORM */ 401enum { 402 /* flip source image horizontally */ 403 NATIVE_WINDOW_TRANSFORM_FLIP_H = HAL_TRANSFORM_FLIP_H , 404 /* flip source image vertically */ 405 NATIVE_WINDOW_TRANSFORM_FLIP_V = HAL_TRANSFORM_FLIP_V, 406 /* rotate source image 90 degrees clock-wise, and is applied after TRANSFORM_FLIP_{H|V} */ 407 NATIVE_WINDOW_TRANSFORM_ROT_90 = HAL_TRANSFORM_ROT_90, 408 /* rotate source image 180 degrees */ 409 NATIVE_WINDOW_TRANSFORM_ROT_180 = HAL_TRANSFORM_ROT_180, 410 /* rotate source image 270 degrees clock-wise */ 411 NATIVE_WINDOW_TRANSFORM_ROT_270 = HAL_TRANSFORM_ROT_270, 412 /* transforms source by the inverse transform of the screen it is displayed onto. This 413 * transform is applied last */ 414 NATIVE_WINDOW_TRANSFORM_INVERSE_DISPLAY = 0x08 415}; 416 417/* parameter for NATIVE_WINDOW_SET_SCALING_MODE 418 * keep in sync with Surface.java in frameworks/base */ 419enum { 420 /* the window content is not updated (frozen) until a buffer of 421 * the window size is received (enqueued) 422 */ 423 NATIVE_WINDOW_SCALING_MODE_FREEZE = 0, 424 /* the buffer is scaled in both dimensions to match the window size */ 425 NATIVE_WINDOW_SCALING_MODE_SCALE_TO_WINDOW = 1, 426 /* the buffer is scaled uniformly such that the smaller dimension 427 * of the buffer matches the window size (cropping in the process) 428 */ 429 NATIVE_WINDOW_SCALING_MODE_SCALE_CROP = 2, 430 /* the window is clipped to the size of the buffer's crop rectangle; pixels 431 * outside the crop rectangle are treated as if they are completely 432 * transparent. 433 */ 434 NATIVE_WINDOW_SCALING_MODE_NO_SCALE_CROP = 3, 435}; 436 437/* values returned by the NATIVE_WINDOW_CONCRETE_TYPE query */ 438enum { 439 NATIVE_WINDOW_FRAMEBUFFER = 0, /* FramebufferNativeWindow */ 440 NATIVE_WINDOW_SURFACE = 1, /* Surface */ 441}; 442 443/* parameter for NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP 444 * 445 * Special timestamp value to indicate that timestamps should be auto-generated 446 * by the native window when queueBuffer is called. This is equal to INT64_MIN, 447 * defined directly to avoid problems with C99/C++ inclusion of stdint.h. 448 */ 449static const int64_t NATIVE_WINDOW_TIMESTAMP_AUTO = (-9223372036854775807LL-1); 450 451struct ANativeWindow 452{ 453#ifdef __cplusplus 454 ANativeWindow() 455 : flags(0), minSwapInterval(0), maxSwapInterval(0), xdpi(0), ydpi(0) 456 { 457 common.magic = ANDROID_NATIVE_WINDOW_MAGIC; 458 common.version = sizeof(ANativeWindow); 459 memset(common.reserved, 0, sizeof(common.reserved)); 460 } 461 462 /* Implement the methods that sp<ANativeWindow> expects so that it 463 can be used to automatically refcount ANativeWindow's. */ 464 void incStrong(const void* /*id*/) const { 465 common.incRef(const_cast<android_native_base_t*>(&common)); 466 } 467 void decStrong(const void* /*id*/) const { 468 common.decRef(const_cast<android_native_base_t*>(&common)); 469 } 470#endif 471 472 struct android_native_base_t common; 473 474 /* flags describing some attributes of this surface or its updater */ 475 const uint32_t flags; 476 477 /* min swap interval supported by this updated */ 478 const int minSwapInterval; 479 480 /* max swap interval supported by this updated */ 481 const int maxSwapInterval; 482 483 /* horizontal and vertical resolution in DPI */ 484 const float xdpi; 485 const float ydpi; 486 487 /* Some storage reserved for the OEM's driver. */ 488 intptr_t oem[4]; 489 490 /* 491 * Set the swap interval for this surface. 492 * 493 * Returns 0 on success or -errno on error. 494 */ 495 int (*setSwapInterval)(struct ANativeWindow* window, 496 int interval); 497 498 /* 499 * Hook called by EGL to acquire a buffer. After this call, the buffer 500 * is not locked, so its content cannot be modified. This call may block if 501 * no buffers are available. 502 * 503 * The window holds a reference to the buffer between dequeueBuffer and 504 * either queueBuffer or cancelBuffer, so clients only need their own 505 * reference if they might use the buffer after queueing or canceling it. 506 * Holding a reference to a buffer after queueing or canceling it is only 507 * allowed if a specific buffer count has been set. 508 * 509 * Returns 0 on success or -errno on error. 510 * 511 * XXX: This function is deprecated. It will continue to work for some 512 * time for binary compatibility, but the new dequeueBuffer function that 513 * outputs a fence file descriptor should be used in its place. 514 */ 515 int (*dequeueBuffer_DEPRECATED)(struct ANativeWindow* window, 516 struct ANativeWindowBuffer** buffer); 517 518 /* 519 * hook called by EGL to lock a buffer. This MUST be called before modifying 520 * the content of a buffer. The buffer must have been acquired with 521 * dequeueBuffer first. 522 * 523 * Returns 0 on success or -errno on error. 524 * 525 * XXX: This function is deprecated. It will continue to work for some 526 * time for binary compatibility, but it is essentially a no-op, and calls 527 * to it should be removed. 528 */ 529 int (*lockBuffer_DEPRECATED)(struct ANativeWindow* window, 530 struct ANativeWindowBuffer* buffer); 531 532 /* 533 * Hook called by EGL when modifications to the render buffer are done. 534 * This unlocks and post the buffer. 535 * 536 * The window holds a reference to the buffer between dequeueBuffer and 537 * either queueBuffer or cancelBuffer, so clients only need their own 538 * reference if they might use the buffer after queueing or canceling it. 539 * Holding a reference to a buffer after queueing or canceling it is only 540 * allowed if a specific buffer count has been set. 541 * 542 * Buffers MUST be queued in the same order than they were dequeued. 543 * 544 * Returns 0 on success or -errno on error. 545 * 546 * XXX: This function is deprecated. It will continue to work for some 547 * time for binary compatibility, but the new queueBuffer function that 548 * takes a fence file descriptor should be used in its place (pass a value 549 * of -1 for the fence file descriptor if there is no valid one to pass). 550 */ 551 int (*queueBuffer_DEPRECATED)(struct ANativeWindow* window, 552 struct ANativeWindowBuffer* buffer); 553 554 /* 555 * hook used to retrieve information about the native window. 556 * 557 * Returns 0 on success or -errno on error. 558 */ 559 int (*query)(const struct ANativeWindow* window, 560 int what, int* value); 561 562 /* 563 * hook used to perform various operations on the surface. 564 * (*perform)() is a generic mechanism to add functionality to 565 * ANativeWindow while keeping backward binary compatibility. 566 * 567 * DO NOT CALL THIS HOOK DIRECTLY. Instead, use the helper functions 568 * defined below. 569 * 570 * (*perform)() returns -ENOENT if the 'what' parameter is not supported 571 * by the surface's implementation. 572 * 573 * See above for a list of valid operations, such as 574 * NATIVE_WINDOW_SET_USAGE or NATIVE_WINDOW_CONNECT 575 */ 576 int (*perform)(struct ANativeWindow* window, 577 int operation, ... ); 578 579 /* 580 * Hook used to cancel a buffer that has been dequeued. 581 * No synchronization is performed between dequeue() and cancel(), so 582 * either external synchronization is needed, or these functions must be 583 * called from the same thread. 584 * 585 * The window holds a reference to the buffer between dequeueBuffer and 586 * either queueBuffer or cancelBuffer, so clients only need their own 587 * reference if they might use the buffer after queueing or canceling it. 588 * Holding a reference to a buffer after queueing or canceling it is only 589 * allowed if a specific buffer count has been set. 590 * 591 * XXX: This function is deprecated. It will continue to work for some 592 * time for binary compatibility, but the new cancelBuffer function that 593 * takes a fence file descriptor should be used in its place (pass a value 594 * of -1 for the fence file descriptor if there is no valid one to pass). 595 */ 596 int (*cancelBuffer_DEPRECATED)(struct ANativeWindow* window, 597 struct ANativeWindowBuffer* buffer); 598 599 /* 600 * Hook called by EGL to acquire a buffer. This call may block if no 601 * buffers are available. 602 * 603 * The window holds a reference to the buffer between dequeueBuffer and 604 * either queueBuffer or cancelBuffer, so clients only need their own 605 * reference if they might use the buffer after queueing or canceling it. 606 * Holding a reference to a buffer after queueing or canceling it is only 607 * allowed if a specific buffer count has been set. 608 * 609 * The libsync fence file descriptor returned in the int pointed to by the 610 * fenceFd argument will refer to the fence that must signal before the 611 * dequeued buffer may be written to. A value of -1 indicates that the 612 * caller may access the buffer immediately without waiting on a fence. If 613 * a valid file descriptor is returned (i.e. any value except -1) then the 614 * caller is responsible for closing the file descriptor. 615 * 616 * Returns 0 on success or -errno on error. 617 */ 618 int (*dequeueBuffer)(struct ANativeWindow* window, 619 struct ANativeWindowBuffer** buffer, int* fenceFd); 620 621 /* 622 * Hook called by EGL when modifications to the render buffer are done. 623 * This unlocks and post the buffer. 624 * 625 * The window holds a reference to the buffer between dequeueBuffer and 626 * either queueBuffer or cancelBuffer, so clients only need their own 627 * reference if they might use the buffer after queueing or canceling it. 628 * Holding a reference to a buffer after queueing or canceling it is only 629 * allowed if a specific buffer count has been set. 630 * 631 * The fenceFd argument specifies a libsync fence file descriptor for a 632 * fence that must signal before the buffer can be accessed. If the buffer 633 * can be accessed immediately then a value of -1 should be used. The 634 * caller must not use the file descriptor after it is passed to 635 * queueBuffer, and the ANativeWindow implementation is responsible for 636 * closing it. 637 * 638 * Returns 0 on success or -errno on error. 639 */ 640 int (*queueBuffer)(struct ANativeWindow* window, 641 struct ANativeWindowBuffer* buffer, int fenceFd); 642 643 /* 644 * Hook used to cancel a buffer that has been dequeued. 645 * No synchronization is performed between dequeue() and cancel(), so 646 * either external synchronization is needed, or these functions must be 647 * called from the same thread. 648 * 649 * The window holds a reference to the buffer between dequeueBuffer and 650 * either queueBuffer or cancelBuffer, so clients only need their own 651 * reference if they might use the buffer after queueing or canceling it. 652 * Holding a reference to a buffer after queueing or canceling it is only 653 * allowed if a specific buffer count has been set. 654 * 655 * The fenceFd argument specifies a libsync fence file decsriptor for a 656 * fence that must signal before the buffer can be accessed. If the buffer 657 * can be accessed immediately then a value of -1 should be used. 658 * 659 * Note that if the client has not waited on the fence that was returned 660 * from dequeueBuffer, that same fence should be passed to cancelBuffer to 661 * ensure that future uses of the buffer are preceded by a wait on that 662 * fence. The caller must not use the file descriptor after it is passed 663 * to cancelBuffer, and the ANativeWindow implementation is responsible for 664 * closing it. 665 * 666 * Returns 0 on success or -errno on error. 667 */ 668 int (*cancelBuffer)(struct ANativeWindow* window, 669 struct ANativeWindowBuffer* buffer, int fenceFd); 670}; 671 672 /* Backwards compatibility: use ANativeWindow (struct ANativeWindow in C). 673 * android_native_window_t is deprecated. 674 */ 675typedef struct ANativeWindow ANativeWindow; 676typedef struct ANativeWindow android_native_window_t __deprecated; 677 678/* 679 * native_window_set_usage(..., usage) 680 * Sets the intended usage flags for the next buffers 681 * acquired with (*lockBuffer)() and on. 682 * By default (if this function is never called), a usage of 683 * GRALLOC_USAGE_HW_RENDER | GRALLOC_USAGE_HW_TEXTURE 684 * is assumed. 685 * Calling this function will usually cause following buffers to be 686 * reallocated. 687 */ 688 689static inline int native_window_set_usage( 690 struct ANativeWindow* window, int usage) 691{ 692 return window->perform(window, NATIVE_WINDOW_SET_USAGE, usage); 693} 694 695/* deprecated. Always returns 0. Don't call. */ 696static inline int native_window_connect( 697 struct ANativeWindow* window __UNUSED, int api __UNUSED) __deprecated; 698 699static inline int native_window_connect( 700 struct ANativeWindow* window __UNUSED, int api __UNUSED) { 701 return 0; 702} 703 704/* deprecated. Always returns 0. Don't call. */ 705static inline int native_window_disconnect( 706 struct ANativeWindow* window __UNUSED, int api __UNUSED) __deprecated; 707 708static inline int native_window_disconnect( 709 struct ANativeWindow* window __UNUSED, int api __UNUSED) { 710 return 0; 711} 712 713/* 714 * native_window_set_crop(..., crop) 715 * Sets which region of the next queued buffers needs to be considered. 716 * Depending on the scaling mode, a buffer's crop region is scaled and/or 717 * cropped to match the surface's size. This function sets the crop in 718 * pre-transformed buffer pixel coordinates. 719 * 720 * The specified crop region applies to all buffers queued after it is called. 721 * 722 * If 'crop' is NULL, subsequently queued buffers won't be cropped. 723 * 724 * An error is returned if for instance the crop region is invalid, out of the 725 * buffer's bound or if the window is invalid. 726 */ 727static inline int native_window_set_crop( 728 struct ANativeWindow* window, 729 android_native_rect_t const * crop) 730{ 731 return window->perform(window, NATIVE_WINDOW_SET_CROP, crop); 732} 733 734/* 735 * native_window_set_post_transform_crop(..., crop) 736 * Sets which region of the next queued buffers needs to be considered. 737 * Depending on the scaling mode, a buffer's crop region is scaled and/or 738 * cropped to match the surface's size. This function sets the crop in 739 * post-transformed pixel coordinates. 740 * 741 * The specified crop region applies to all buffers queued after it is called. 742 * 743 * If 'crop' is NULL, subsequently queued buffers won't be cropped. 744 * 745 * An error is returned if for instance the crop region is invalid, out of the 746 * buffer's bound or if the window is invalid. 747 */ 748static inline int native_window_set_post_transform_crop( 749 struct ANativeWindow* window, 750 android_native_rect_t const * crop) 751{ 752 return window->perform(window, NATIVE_WINDOW_SET_POST_TRANSFORM_CROP, crop); 753} 754 755/* 756 * native_window_set_active_rect(..., active_rect) 757 * 758 * This function is deprecated and will be removed soon. For now it simply 759 * sets the post-transform crop for compatibility while multi-project commits 760 * get checked. 761 */ 762static inline int native_window_set_active_rect( 763 struct ANativeWindow* window, 764 android_native_rect_t const * active_rect) __deprecated; 765 766static inline int native_window_set_active_rect( 767 struct ANativeWindow* window, 768 android_native_rect_t const * active_rect) 769{ 770 return native_window_set_post_transform_crop(window, active_rect); 771} 772 773/* 774 * native_window_set_buffer_count(..., count) 775 * Sets the number of buffers associated with this native window. 776 */ 777static inline int native_window_set_buffer_count( 778 struct ANativeWindow* window, 779 size_t bufferCount) 780{ 781 return window->perform(window, NATIVE_WINDOW_SET_BUFFER_COUNT, bufferCount); 782} 783 784/* 785 * native_window_set_buffers_geometry(..., int w, int h, int format) 786 * All buffers dequeued after this call will have the dimensions and format 787 * specified. A successful call to this function has the same effect as calling 788 * native_window_set_buffers_size and native_window_set_buffers_format. 789 * 790 * XXX: This function is deprecated. The native_window_set_buffers_dimensions 791 * and native_window_set_buffers_format functions should be used instead. 792 */ 793static inline int native_window_set_buffers_geometry( 794 struct ANativeWindow* window, 795 int w, int h, int format) __deprecated; 796 797static inline int native_window_set_buffers_geometry( 798 struct ANativeWindow* window, 799 int w, int h, int format) 800{ 801 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_GEOMETRY, 802 w, h, format); 803} 804 805/* 806 * native_window_set_buffers_dimensions(..., int w, int h) 807 * All buffers dequeued after this call will have the dimensions specified. 808 * In particular, all buffers will have a fixed-size, independent from the 809 * native-window size. They will be scaled according to the scaling mode 810 * (see native_window_set_scaling_mode) upon window composition. 811 * 812 * If w and h are 0, the normal behavior is restored. That is, dequeued buffers 813 * following this call will be sized to match the window's size. 814 * 815 * Calling this function will reset the window crop to a NULL value, which 816 * disables cropping of the buffers. 817 */ 818static inline int native_window_set_buffers_dimensions( 819 struct ANativeWindow* window, 820 int w, int h) 821{ 822 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_DIMENSIONS, 823 w, h); 824} 825 826/* 827 * native_window_set_buffers_user_dimensions(..., int w, int h) 828 * 829 * Sets the user buffer size for the window, which overrides the 830 * window's size. All buffers dequeued after this call will have the 831 * dimensions specified unless overridden by 832 * native_window_set_buffers_dimensions. All buffers will have a 833 * fixed-size, independent from the native-window size. They will be 834 * scaled according to the scaling mode (see 835 * native_window_set_scaling_mode) upon window composition. 836 * 837 * If w and h are 0, the normal behavior is restored. That is, the 838 * default buffer size will match the windows's size. 839 * 840 * Calling this function will reset the window crop to a NULL value, which 841 * disables cropping of the buffers. 842 */ 843static inline int native_window_set_buffers_user_dimensions( 844 struct ANativeWindow* window, 845 int w, int h) 846{ 847 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_USER_DIMENSIONS, 848 w, h); 849} 850 851/* 852 * native_window_set_buffers_format(..., int format) 853 * All buffers dequeued after this call will have the format specified. 854 * 855 * If the specified format is 0, the default buffer format will be used. 856 */ 857static inline int native_window_set_buffers_format( 858 struct ANativeWindow* window, 859 int format) 860{ 861 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_FORMAT, format); 862} 863 864/* 865 * native_window_set_buffers_data_space(..., int dataSpace) 866 * All buffers queued after this call will be associated with the dataSpace 867 * parameter specified. 868 * 869 * dataSpace specifies additional information about the buffer that's dependent 870 * on the buffer format and the endpoints. For example, it can be used to convey 871 * the color space of the image data in the buffer, or it can be used to 872 * indicate that the buffers contain depth measurement data instead of color 873 * images. The default dataSpace is 0, HAL_DATASPACE_UNKNOWN, unless it has been 874 * overridden by the consumer. 875 */ 876static inline int native_window_set_buffers_data_space( 877 struct ANativeWindow* window, 878 android_dataspace_t dataSpace) 879{ 880 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_DATASPACE, 881 dataSpace); 882} 883 884/* 885 * native_window_set_buffers_transform(..., int transform) 886 * All buffers queued after this call will be displayed transformed according 887 * to the transform parameter specified. 888 */ 889static inline int native_window_set_buffers_transform( 890 struct ANativeWindow* window, 891 int transform) 892{ 893 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_TRANSFORM, 894 transform); 895} 896 897/* 898 * native_window_set_buffers_sticky_transform(..., int transform) 899 * All buffers queued after this call will be displayed transformed according 900 * to the transform parameter specified applied on top of the regular buffer 901 * transform. Setting this transform will disable the transform hint. 902 * 903 * Temporary - This is only intended to be used by the LEGACY camera mode, do 904 * not use this for anything else. 905 */ 906static inline int native_window_set_buffers_sticky_transform( 907 struct ANativeWindow* window, 908 int transform) 909{ 910 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_STICKY_TRANSFORM, 911 transform); 912} 913 914/* 915 * native_window_set_buffers_timestamp(..., int64_t timestamp) 916 * All buffers queued after this call will be associated with the timestamp 917 * parameter specified. If the timestamp is set to NATIVE_WINDOW_TIMESTAMP_AUTO 918 * (the default), timestamps will be generated automatically when queueBuffer is 919 * called. The timestamp is measured in nanoseconds, and is normally monotonically 920 * increasing. The timestamp should be unaffected by time-of-day adjustments, 921 * and for a camera should be strictly monotonic but for a media player may be 922 * reset when the position is set. 923 */ 924static inline int native_window_set_buffers_timestamp( 925 struct ANativeWindow* window, 926 int64_t timestamp) 927{ 928 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP, 929 timestamp); 930} 931 932/* 933 * native_window_set_scaling_mode(..., int mode) 934 * All buffers queued after this call will be associated with the scaling mode 935 * specified. 936 */ 937static inline int native_window_set_scaling_mode( 938 struct ANativeWindow* window, 939 int mode) 940{ 941 return window->perform(window, NATIVE_WINDOW_SET_SCALING_MODE, 942 mode); 943} 944 945/* 946 * native_window_api_connect(..., int api) 947 * connects an API to this window. only one API can be connected at a time. 948 * Returns -EINVAL if for some reason the window cannot be connected, which 949 * can happen if it's connected to some other API. 950 */ 951static inline int native_window_api_connect( 952 struct ANativeWindow* window, int api) 953{ 954 return window->perform(window, NATIVE_WINDOW_API_CONNECT, api); 955} 956 957/* 958 * native_window_api_disconnect(..., int api) 959 * disconnect the API from this window. 960 * An error is returned if for instance the window wasn't connected in the 961 * first place. 962 */ 963static inline int native_window_api_disconnect( 964 struct ANativeWindow* window, int api) 965{ 966 return window->perform(window, NATIVE_WINDOW_API_DISCONNECT, api); 967} 968 969/* 970 * native_window_dequeue_buffer_and_wait(...) 971 * Dequeue a buffer and wait on the fence associated with that buffer. The 972 * buffer may safely be accessed immediately upon this function returning. An 973 * error is returned if either of the dequeue or the wait operations fail. 974 */ 975static inline int native_window_dequeue_buffer_and_wait(ANativeWindow *anw, 976 struct ANativeWindowBuffer** anb) { 977 return anw->dequeueBuffer_DEPRECATED(anw, anb); 978} 979 980/* 981 * native_window_set_sideband_stream(..., native_handle_t*) 982 * Attach a sideband buffer stream to a native window. 983 */ 984static inline int native_window_set_sideband_stream( 985 struct ANativeWindow* window, 986 native_handle_t* sidebandHandle) 987{ 988 return window->perform(window, NATIVE_WINDOW_SET_SIDEBAND_STREAM, 989 sidebandHandle); 990} 991 992/* 993 * native_window_set_surface_damage(..., android_native_rect_t* rects, int numRects) 994 * Set the surface damage (i.e., the region of the surface that has changed 995 * since the previous frame). The damage set by this call will be reset (to the 996 * default of full-surface damage) after calling queue, so this must be called 997 * prior to every frame with damage that does not cover the whole surface if the 998 * caller desires downstream consumers to use this optimization. 999 * 1000 * The damage region is specified as an array of rectangles, with the important 1001 * caveat that the origin of the surface is considered to be the bottom-left 1002 * corner, as in OpenGL ES. 1003 * 1004 * If numRects is set to 0, rects may be NULL, and the surface damage will be 1005 * set to the full surface (the same as if this function had not been called for 1006 * this frame). 1007 */ 1008static inline int native_window_set_surface_damage( 1009 struct ANativeWindow* window, 1010 const android_native_rect_t* rects, size_t numRects) 1011{ 1012 return window->perform(window, NATIVE_WINDOW_SET_SURFACE_DAMAGE, 1013 rects, numRects); 1014} 1015 1016/* 1017 * native_window_set_shared_buffer_mode(..., bool sharedBufferMode) 1018 * Enable/disable shared buffer mode 1019 */ 1020static inline int native_window_set_shared_buffer_mode( 1021 struct ANativeWindow* window, 1022 bool sharedBufferMode) 1023{ 1024 return window->perform(window, NATIVE_WINDOW_SET_SHARED_BUFFER_MODE, 1025 sharedBufferMode); 1026} 1027 1028/* 1029 * native_window_set_auto_refresh(..., autoRefresh) 1030 * Enable/disable auto refresh when in shared buffer mode 1031 */ 1032static inline int native_window_set_auto_refresh( 1033 struct ANativeWindow* window, 1034 bool autoRefresh) 1035{ 1036 return window->perform(window, NATIVE_WINDOW_SET_AUTO_REFRESH, autoRefresh); 1037} 1038 1039static inline int native_window_get_refresh_cycle_duration( 1040 struct ANativeWindow* window, 1041 int64_t* outRefreshDuration) 1042{ 1043 return window->perform(window, NATIVE_WINDOW_GET_REFRESH_CYCLE_DURATION, 1044 outRefreshDuration); 1045} 1046 1047static inline int native_window_get_next_frame_id( 1048 struct ANativeWindow* window, uint64_t* frameId) 1049{ 1050 return window->perform(window, NATIVE_WINDOW_GET_NEXT_FRAME_ID, frameId); 1051} 1052 1053static inline int native_window_enable_frame_timestamps( 1054 struct ANativeWindow* window, bool enable) 1055{ 1056 return window->perform(window, NATIVE_WINDOW_ENABLE_FRAME_TIMESTAMPS, 1057 enable); 1058} 1059 1060static inline int native_window_get_compositor_timing( 1061 struct ANativeWindow* window, 1062 int64_t* compositeDeadline, int64_t* compositeInterval, 1063 int64_t* compositeToPresentLatency) 1064{ 1065 return window->perform(window, NATIVE_WINDOW_GET_COMPOSITOR_TIMING, 1066 compositeDeadline, compositeInterval, compositeToPresentLatency); 1067} 1068 1069static inline int native_window_get_frame_timestamps( 1070 struct ANativeWindow* window, uint64_t frameId, 1071 int64_t* outRequestedPresentTime, int64_t* outAcquireTime, 1072 int64_t* outLatchTime, int64_t* outFirstRefreshStartTime, 1073 int64_t* outLastRefreshStartTime, int64_t* outGpuCompositionDoneTime, 1074 int64_t* outDisplayPresentTime, int64_t* outDequeueReadyTime, 1075 int64_t* outReleaseTime) 1076{ 1077 return window->perform(window, NATIVE_WINDOW_GET_FRAME_TIMESTAMPS, 1078 frameId, outRequestedPresentTime, outAcquireTime, outLatchTime, 1079 outFirstRefreshStartTime, outLastRefreshStartTime, 1080 outGpuCompositionDoneTime, outDisplayPresentTime, 1081 outDequeueReadyTime, outReleaseTime); 1082} 1083 1084static inline int native_window_get_wide_color_support( 1085 struct ANativeWindow* window, bool* outSupport) { 1086 return window->perform(window, NATIVE_WINDOW_GET_WIDE_COLOR_SUPPORT, 1087 outSupport); 1088} 1089 1090static inline int native_window_get_hdr_support(struct ANativeWindow* window, 1091 bool* outSupport) { 1092 return window->perform(window, NATIVE_WINDOW_GET_HDR_SUPPORT, outSupport); 1093} 1094 1095__END_DECLS 1096