include/android_stub/system/window.h

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