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