window.h revision a5e65d86a2a07997b92f83cfac2f0ee37feeee6f
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 59typedef const native_handle_t* buffer_handle_t; 60 61// --------------------------------------------------------------------------- 62 63typedef 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 73typedef 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 88typedef 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. 123typedef ANativeWindowBuffer_t android_native_buffer_t; 124 125// --------------------------------------------------------------------------- 126 127/* attributes queriable with query() */ 128enum { 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/* Valid operations for the (*perform)() hook. 268 * 269 * Values marked as 'deprecated' are supported, but have been superceded by 270 * other functionality. 271 * 272 * Values marked as 'private' should be considered private to the framework. 273 * HAL implementation code with access to an ANativeWindow should not use these, 274 * as it may not interact properly with the framework's use of the 275 * ANativeWindow. 276 */ 277enum { 278 NATIVE_WINDOW_SET_USAGE = 0, 279 NATIVE_WINDOW_CONNECT = 1, /* deprecated */ 280 NATIVE_WINDOW_DISCONNECT = 2, /* deprecated */ 281 NATIVE_WINDOW_SET_CROP = 3, /* private */ 282 NATIVE_WINDOW_SET_BUFFER_COUNT = 4, 283 NATIVE_WINDOW_SET_BUFFERS_GEOMETRY = 5, /* deprecated */ 284 NATIVE_WINDOW_SET_BUFFERS_TRANSFORM = 6, 285 NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP = 7, 286 NATIVE_WINDOW_SET_BUFFERS_DIMENSIONS = 8, 287 NATIVE_WINDOW_SET_BUFFERS_FORMAT = 9, 288 NATIVE_WINDOW_SET_SCALING_MODE = 10, /* private */ 289 NATIVE_WINDOW_LOCK = 11, /* private */ 290 NATIVE_WINDOW_UNLOCK_AND_POST = 12, /* private */ 291 NATIVE_WINDOW_API_CONNECT = 13, /* private */ 292 NATIVE_WINDOW_API_DISCONNECT = 14, /* private */ 293 NATIVE_WINDOW_SET_BUFFERS_USER_DIMENSIONS = 15, /* private */ 294 NATIVE_WINDOW_SET_POST_TRANSFORM_CROP = 16, /* private */ 295 NATIVE_WINDOW_SET_BUFFERS_STICKY_TRANSFORM = 17,/* private */ 296}; 297 298/* parameter for NATIVE_WINDOW_[API_][DIS]CONNECT */ 299enum { 300 /* Buffers will be queued by EGL via eglSwapBuffers after being filled using 301 * OpenGL ES. 302 */ 303 NATIVE_WINDOW_API_EGL = 1, 304 305 /* Buffers will be queued after being filled using the CPU 306 */ 307 NATIVE_WINDOW_API_CPU = 2, 308 309 /* Buffers will be queued by Stagefright after being filled by a video 310 * decoder. The video decoder can either be a software or hardware decoder. 311 */ 312 NATIVE_WINDOW_API_MEDIA = 3, 313 314 /* Buffers will be queued by the the camera HAL. 315 */ 316 NATIVE_WINDOW_API_CAMERA = 4, 317}; 318 319/* parameter for NATIVE_WINDOW_SET_BUFFERS_TRANSFORM */ 320enum { 321 /* flip source image horizontally */ 322 NATIVE_WINDOW_TRANSFORM_FLIP_H = HAL_TRANSFORM_FLIP_H , 323 /* flip source image vertically */ 324 NATIVE_WINDOW_TRANSFORM_FLIP_V = HAL_TRANSFORM_FLIP_V, 325 /* rotate source image 90 degrees clock-wise, and is applied after TRANSFORM_FLIP_{H|V} */ 326 NATIVE_WINDOW_TRANSFORM_ROT_90 = HAL_TRANSFORM_ROT_90, 327 /* rotate source image 180 degrees */ 328 NATIVE_WINDOW_TRANSFORM_ROT_180 = HAL_TRANSFORM_ROT_180, 329 /* rotate source image 270 degrees clock-wise */ 330 NATIVE_WINDOW_TRANSFORM_ROT_270 = HAL_TRANSFORM_ROT_270, 331 /* transforms source by the inverse transform of the screen it is displayed onto. This 332 * transform is applied last */ 333 NATIVE_WINDOW_TRANSFORM_INVERSE_DISPLAY = 0x08 334}; 335 336/* parameter for NATIVE_WINDOW_SET_SCALING_MODE */ 337enum { 338 /* the window content is not updated (frozen) until a buffer of 339 * the window size is received (enqueued) 340 */ 341 NATIVE_WINDOW_SCALING_MODE_FREEZE = 0, 342 /* the buffer is scaled in both dimensions to match the window size */ 343 NATIVE_WINDOW_SCALING_MODE_SCALE_TO_WINDOW = 1, 344 /* the buffer is scaled uniformly such that the smaller dimension 345 * of the buffer matches the window size (cropping in the process) 346 */ 347 NATIVE_WINDOW_SCALING_MODE_SCALE_CROP = 2, 348 /* the window is clipped to the size of the buffer's crop rectangle; pixels 349 * outside the crop rectangle are treated as if they are completely 350 * transparent. 351 */ 352 NATIVE_WINDOW_SCALING_MODE_NO_SCALE_CROP = 3, 353}; 354 355/* values returned by the NATIVE_WINDOW_CONCRETE_TYPE query */ 356enum { 357 NATIVE_WINDOW_FRAMEBUFFER = 0, /* FramebufferNativeWindow */ 358 NATIVE_WINDOW_SURFACE = 1, /* Surface */ 359}; 360 361/* parameter for NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP 362 * 363 * Special timestamp value to indicate that timestamps should be auto-generated 364 * by the native window when queueBuffer is called. This is equal to INT64_MIN, 365 * defined directly to avoid problems with C99/C++ inclusion of stdint.h. 366 */ 367static const int64_t NATIVE_WINDOW_TIMESTAMP_AUTO = (-9223372036854775807LL-1); 368 369struct ANativeWindow 370{ 371#ifdef __cplusplus 372 ANativeWindow() 373 : flags(0), minSwapInterval(0), maxSwapInterval(0), xdpi(0), ydpi(0) 374 { 375 common.magic = ANDROID_NATIVE_WINDOW_MAGIC; 376 common.version = sizeof(ANativeWindow); 377 memset(common.reserved, 0, sizeof(common.reserved)); 378 } 379 380 /* Implement the methods that sp<ANativeWindow> expects so that it 381 can be used to automatically refcount ANativeWindow's. */ 382 void incStrong(const void* /*id*/) const { 383 common.incRef(const_cast<android_native_base_t*>(&common)); 384 } 385 void decStrong(const void* /*id*/) const { 386 common.decRef(const_cast<android_native_base_t*>(&common)); 387 } 388#endif 389 390 struct android_native_base_t common; 391 392 /* flags describing some attributes of this surface or its updater */ 393 const uint32_t flags; 394 395 /* min swap interval supported by this updated */ 396 const int minSwapInterval; 397 398 /* max swap interval supported by this updated */ 399 const int maxSwapInterval; 400 401 /* horizontal and vertical resolution in DPI */ 402 const float xdpi; 403 const float ydpi; 404 405 /* Some storage reserved for the OEM's driver. */ 406 intptr_t oem[4]; 407 408 /* 409 * Set the swap interval for this surface. 410 * 411 * Returns 0 on success or -errno on error. 412 */ 413 int (*setSwapInterval)(struct ANativeWindow* window, 414 int interval); 415 416 /* 417 * Hook called by EGL to acquire a buffer. After this call, the buffer 418 * is not locked, so its content cannot be modified. This call may block if 419 * no buffers are available. 420 * 421 * The window holds a reference to the buffer between dequeueBuffer and 422 * either queueBuffer or cancelBuffer, so clients only need their own 423 * reference if they might use the buffer after queueing or canceling it. 424 * Holding a reference to a buffer after queueing or canceling it is only 425 * allowed if a specific buffer count has been set. 426 * 427 * Returns 0 on success or -errno on error. 428 * 429 * XXX: This function is deprecated. It will continue to work for some 430 * time for binary compatibility, but the new dequeueBuffer function that 431 * outputs a fence file descriptor should be used in its place. 432 */ 433 int (*dequeueBuffer_DEPRECATED)(struct ANativeWindow* window, 434 struct ANativeWindowBuffer** buffer); 435 436 /* 437 * hook called by EGL to lock a buffer. This MUST be called before modifying 438 * the content of a buffer. The buffer must have been acquired with 439 * dequeueBuffer first. 440 * 441 * Returns 0 on success or -errno on error. 442 * 443 * XXX: This function is deprecated. It will continue to work for some 444 * time for binary compatibility, but it is essentially a no-op, and calls 445 * to it should be removed. 446 */ 447 int (*lockBuffer_DEPRECATED)(struct ANativeWindow* window, 448 struct ANativeWindowBuffer* buffer); 449 450 /* 451 * Hook called by EGL when modifications to the render buffer are done. 452 * This unlocks and post the buffer. 453 * 454 * The window holds a reference to the buffer between dequeueBuffer and 455 * either queueBuffer or cancelBuffer, so clients only need their own 456 * reference if they might use the buffer after queueing or canceling it. 457 * Holding a reference to a buffer after queueing or canceling it is only 458 * allowed if a specific buffer count has been set. 459 * 460 * Buffers MUST be queued in the same order than they were dequeued. 461 * 462 * Returns 0 on success or -errno on error. 463 * 464 * XXX: This function is deprecated. It will continue to work for some 465 * time for binary compatibility, but the new queueBuffer function that 466 * takes a fence file descriptor should be used in its place (pass a value 467 * of -1 for the fence file descriptor if there is no valid one to pass). 468 */ 469 int (*queueBuffer_DEPRECATED)(struct ANativeWindow* window, 470 struct ANativeWindowBuffer* buffer); 471 472 /* 473 * hook used to retrieve information about the native window. 474 * 475 * Returns 0 on success or -errno on error. 476 */ 477 int (*query)(const struct ANativeWindow* window, 478 int what, int* value); 479 480 /* 481 * hook used to perform various operations on the surface. 482 * (*perform)() is a generic mechanism to add functionality to 483 * ANativeWindow while keeping backward binary compatibility. 484 * 485 * DO NOT CALL THIS HOOK DIRECTLY. Instead, use the helper functions 486 * defined below. 487 * 488 * (*perform)() returns -ENOENT if the 'what' parameter is not supported 489 * by the surface's implementation. 490 * 491 * The valid operations are: 492 * NATIVE_WINDOW_SET_USAGE 493 * NATIVE_WINDOW_CONNECT (deprecated) 494 * NATIVE_WINDOW_DISCONNECT (deprecated) 495 * NATIVE_WINDOW_SET_CROP (private) 496 * NATIVE_WINDOW_SET_BUFFER_COUNT 497 * NATIVE_WINDOW_SET_BUFFERS_GEOMETRY (deprecated) 498 * NATIVE_WINDOW_SET_BUFFERS_TRANSFORM 499 * NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP 500 * NATIVE_WINDOW_SET_BUFFERS_DIMENSIONS 501 * NATIVE_WINDOW_SET_BUFFERS_FORMAT 502 * NATIVE_WINDOW_SET_SCALING_MODE (private) 503 * NATIVE_WINDOW_LOCK (private) 504 * NATIVE_WINDOW_UNLOCK_AND_POST (private) 505 * NATIVE_WINDOW_API_CONNECT (private) 506 * NATIVE_WINDOW_API_DISCONNECT (private) 507 * NATIVE_WINDOW_SET_BUFFERS_USER_DIMENSIONS (private) 508 * NATIVE_WINDOW_SET_POST_TRANSFORM_CROP (private) 509 * 510 */ 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 */ 611typedef struct ANativeWindow ANativeWindow; 612typedef 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 625static 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. */ 632static inline int native_window_connect( 633 struct ANativeWindow* window __UNUSED, int api __UNUSED) __deprecated; 634 635static 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. */ 641static inline int native_window_disconnect( 642 struct ANativeWindow* window __UNUSED, int api __UNUSED) __deprecated; 643 644static 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 */ 663static 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 */ 684static 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 */ 698static inline int native_window_set_active_rect( 699 struct ANativeWindow* window, 700 android_native_rect_t const * active_rect) __deprecated; 701 702static 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 */ 713static 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 */ 729static inline int native_window_set_buffers_geometry( 730 struct ANativeWindow* window, 731 int w, int h, int format) __deprecated; 732 733static 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 */ 754static 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 */ 779static 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 */ 793static 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_transform(..., int transform) 802 * All buffers queued after this call will be displayed transformed according 803 * to the transform parameter specified. 804 */ 805static inline int native_window_set_buffers_transform( 806 struct ANativeWindow* window, 807 int transform) 808{ 809 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_TRANSFORM, 810 transform); 811} 812 813/* 814 * native_window_set_buffers_sticky_transform(..., int transform) 815 * All buffers queued after this call will be displayed transformed according 816 * to the transform parameter specified applied on top of the regular buffer 817 * transform. Setting this transform will disable the transform hint. 818 * 819 * Temporary - This is only intended to be used by the LEGACY camera mode, do 820 * not use this for anything else. 821 */ 822static inline int native_window_set_buffers_sticky_transform( 823 struct ANativeWindow* window, 824 int transform) 825{ 826 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_STICKY_TRANSFORM, 827 transform); 828} 829 830/* 831 * native_window_set_buffers_timestamp(..., int64_t timestamp) 832 * All buffers queued after this call will be associated with the timestamp 833 * parameter specified. If the timestamp is set to NATIVE_WINDOW_TIMESTAMP_AUTO 834 * (the default), timestamps will be generated automatically when queueBuffer is 835 * called. The timestamp is measured in nanoseconds, and is normally monotonically 836 * increasing. The timestamp should be unaffected by time-of-day adjustments, 837 * and for a camera should be strictly monotonic but for a media player may be 838 * reset when the position is set. 839 */ 840static inline int native_window_set_buffers_timestamp( 841 struct ANativeWindow* window, 842 int64_t timestamp) 843{ 844 return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP, 845 timestamp); 846} 847 848/* 849 * native_window_set_scaling_mode(..., int mode) 850 * All buffers queued after this call will be associated with the scaling mode 851 * specified. 852 */ 853static inline int native_window_set_scaling_mode( 854 struct ANativeWindow* window, 855 int mode) 856{ 857 return window->perform(window, NATIVE_WINDOW_SET_SCALING_MODE, 858 mode); 859} 860 861/* 862 * native_window_api_connect(..., int api) 863 * connects an API to this window. only one API can be connected at a time. 864 * Returns -EINVAL if for some reason the window cannot be connected, which 865 * can happen if it's connected to some other API. 866 */ 867static inline int native_window_api_connect( 868 struct ANativeWindow* window, int api) 869{ 870 return window->perform(window, NATIVE_WINDOW_API_CONNECT, api); 871} 872 873/* 874 * native_window_api_disconnect(..., int api) 875 * disconnect the API from this window. 876 * An error is returned if for instance the window wasn't connected in the 877 * first place. 878 */ 879static inline int native_window_api_disconnect( 880 struct ANativeWindow* window, int api) 881{ 882 return window->perform(window, NATIVE_WINDOW_API_DISCONNECT, api); 883} 884 885/* 886 * native_window_dequeue_buffer_and_wait(...) 887 * Dequeue a buffer and wait on the fence associated with that buffer. The 888 * buffer may safely be accessed immediately upon this function returning. An 889 * error is returned if either of the dequeue or the wait operations fail. 890 */ 891static inline int native_window_dequeue_buffer_and_wait(ANativeWindow *anw, 892 struct ANativeWindowBuffer** anb) { 893 return anw->dequeueBuffer_DEPRECATED(anw, anb); 894} 895 896 897__END_DECLS 898 899#endif /* SYSTEM_CORE_INCLUDE_ANDROID_WINDOW_H */ 900