window.h revision 453effd1f144fb5a6ae89a7c377d20a845c49080
1/* 2 * Copyright (C) 2017 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 ANDROID_VNDK_NATIVEWINDOW_ANATIVEWINDOW_H 18#define ANDROID_VNDK_NATIVEWINDOW_ANATIVEWINDOW_H 19 20#include <stdint.h> 21#include <stdbool.h> 22#include <sys/cdefs.h> 23#include <system/graphics-base.h> 24#include <cutils/native_handle.h> 25 26// vndk is a superset of the NDK 27#include <android/native_window.h> 28 29__BEGIN_DECLS 30 31/*****************************************************************************/ 32 33#ifdef __cplusplus 34#define ANDROID_NATIVE_UNSIGNED_CAST(x) static_cast<unsigned int>(x) 35#else 36#define ANDROID_NATIVE_UNSIGNED_CAST(x) ((unsigned int)(x)) 37#endif 38 39#define ANDROID_NATIVE_MAKE_CONSTANT(a,b,c,d) \ 40 ((ANDROID_NATIVE_UNSIGNED_CAST(a) << 24) | \ 41 (ANDROID_NATIVE_UNSIGNED_CAST(b) << 16) | \ 42 (ANDROID_NATIVE_UNSIGNED_CAST(c) << 8) | \ 43 (ANDROID_NATIVE_UNSIGNED_CAST(d))) 44 45#define ANDROID_NATIVE_BUFFER_MAGIC ANDROID_NATIVE_MAKE_CONSTANT('_','b','f','r') 46 47 48/*****************************************************************************/ 49 50typedef struct android_native_base_t 51{ 52 /* a magic value defined by the actual EGL native type */ 53 int magic; 54 55 /* the sizeof() of the actual EGL native type */ 56 int version; 57 58 void* reserved[4]; 59 60 /* reference-counting interface */ 61 void (*incRef)(struct android_native_base_t* base); 62 void (*decRef)(struct android_native_base_t* base); 63} android_native_base_t; 64 65typedef struct ANativeWindowBuffer 66{ 67#ifdef __cplusplus 68 ANativeWindowBuffer() { 69 common.magic = ANDROID_NATIVE_BUFFER_MAGIC; 70 common.version = sizeof(ANativeWindowBuffer); 71 memset(common.reserved, 0, sizeof(common.reserved)); 72 } 73 74 // Implement the methods that sp<ANativeWindowBuffer> expects so that it 75 // can be used to automatically refcount ANativeWindowBuffer's. 76 void incStrong(const void* /*id*/) const { 77 common.incRef(const_cast<android_native_base_t*>(&common)); 78 } 79 void decStrong(const void* /*id*/) const { 80 common.decRef(const_cast<android_native_base_t*>(&common)); 81 } 82#endif 83 84 struct android_native_base_t common; 85 86 int width; 87 int height; 88 int stride; 89 int format; 90 int usage; 91 uintptr_t layerCount; 92 93 void* reserved[1]; 94 95 const native_handle_t* handle; 96 97 void* reserved_proc[8]; 98} ANativeWindowBuffer_t; 99 100typedef struct ANativeWindowBuffer ANativeWindowBuffer; 101 102/* 103 * Convert this ANativeWindowBuffer into a AHardwareBuffer 104 */ 105AHardwareBuffer* ANativeWindowBuffer_getHardwareBuffer(ANativeWindowBuffer* anwb); 106 107/*****************************************************************************/ 108 109/* 110 * Stores a value into one of the 4 available slots 111 * Retrieve the value with ANativeWindow_OemStorageGet() 112 * 113 * slot: 0 to 3 114 * 115 * Returns 0 on success or -errno on error. 116 */ 117int ANativeWindow_OemStorageSet(ANativeWindow* window, uint32_t slot, intptr_t value); 118 119 120/* 121 * Retrieves a value from one of the 4 available slots 122 * By default the returned value is 0 if it wasn't set by ANativeWindow_OemStorageSet() 123 * 124 * slot: 0 to 3 125 * 126 * Returns 0 on success or -errno on error. 127 */ 128int ANativeWindow_OemStorageGet(ANativeWindow* window, uint32_t slot, intptr_t* value); 129 130 131/* 132 * Set the swap interval for this surface. 133 * 134 * Returns 0 on success or -errno on error. 135 */ 136int ANativeWindow_setSwapInterval(ANativeWindow* window, int interval); 137 138 139/* 140 * queries that can be used with ANativeWindow_query() and ANativeWindow_queryf() 141 */ 142enum ANativeWindowQuery { 143 /* The minimum number of buffers that must remain un-dequeued after a buffer 144 * has been queued. This value applies only if set_buffer_count was used to 145 * override the number of buffers and if a buffer has since been queued. 146 * Users of the set_buffer_count ANativeWindow method should query this 147 * value before calling set_buffer_count. If it is necessary to have N 148 * buffers simultaneously dequeued as part of the steady-state operation, 149 * and this query returns M then N+M buffers should be requested via 150 * native_window_set_buffer_count. 151 * 152 * Note that this value does NOT apply until a single buffer has been 153 * queued. In particular this means that it is possible to: 154 * 155 * 1. Query M = min undequeued buffers 156 * 2. Set the buffer count to N + M 157 * 3. Dequeue all N + M buffers 158 * 4. Cancel M buffers 159 * 5. Queue, dequeue, queue, dequeue, ad infinitum 160 */ 161 ANATIVEWINDOW_QUERY_MIN_UNDEQUEUED_BUFFERS = 3, 162 163 /* 164 * Default width of ANativeWindow buffers, these are the 165 * dimensions of the window buffers irrespective of the 166 * ANativeWindow_setBuffersDimensions() call and match the native window 167 * size. 168 */ 169 ANATIVEWINDOW_QUERY_DEFAULT_WIDTH = 6, 170 ANATIVEWINDOW_QUERY_DEFAULT_HEIGHT = 7, 171 172 /* 173 * transformation that will most-likely be applied to buffers. This is only 174 * a hint, the actual transformation applied might be different. 175 * 176 * INTENDED USE: 177 * 178 * The transform hint can be used by a producer, for instance the GLES 179 * driver, to pre-rotate the rendering such that the final transformation 180 * in the composer is identity. This can be very useful when used in 181 * conjunction with the h/w composer HAL, in situations where it 182 * cannot handle arbitrary rotations. 183 * 184 * 1. Before dequeuing a buffer, the GL driver (or any other ANW client) 185 * queries the ANW for NATIVE_WINDOW_TRANSFORM_HINT. 186 * 187 * 2. The GL driver overrides the width and height of the ANW to 188 * account for NATIVE_WINDOW_TRANSFORM_HINT. This is done by querying 189 * NATIVE_WINDOW_DEFAULT_{WIDTH | HEIGHT}, swapping the dimensions 190 * according to NATIVE_WINDOW_TRANSFORM_HINT and calling 191 * native_window_set_buffers_dimensions(). 192 * 193 * 3. The GL driver dequeues a buffer of the new pre-rotated size. 194 * 195 * 4. The GL driver renders to the buffer such that the image is 196 * already transformed, that is applying NATIVE_WINDOW_TRANSFORM_HINT 197 * to the rendering. 198 * 199 * 5. The GL driver calls native_window_set_transform to apply 200 * inverse transformation to the buffer it just rendered. 201 * In order to do this, the GL driver needs 202 * to calculate the inverse of NATIVE_WINDOW_TRANSFORM_HINT, this is 203 * done easily: 204 * 205 * int hintTransform, inverseTransform; 206 * query(..., NATIVE_WINDOW_TRANSFORM_HINT, &hintTransform); 207 * inverseTransform = hintTransform; 208 * if (hintTransform & HAL_TRANSFORM_ROT_90) 209 * inverseTransform ^= HAL_TRANSFORM_ROT_180; 210 * 211 * 212 * 6. The GL driver queues the pre-transformed buffer. 213 * 214 * 7. The composer combines the buffer transform with the display 215 * transform. If the buffer transform happens to cancel out the 216 * display transform then no rotation is needed. 217 * 218 */ 219 ANATIVEWINDOW_QUERY_TRANSFORM_HINT = 8, 220 221 /* 222 * Returns the age of the contents of the most recently dequeued buffer as 223 * the number of frames that have elapsed since it was last queued. For 224 * example, if the window is double-buffered, the age of any given buffer in 225 * steady state will be 2. If the dequeued buffer has never been queued, its 226 * age will be 0. 227 */ 228 ANATIVEWINDOW_QUERY_BUFFER_AGE = 13, 229 230 /* min swap interval supported by this compositor */ 231 ANATIVEWINDOW_QUERY_MIN_SWAP_INTERVAL = 0x10000, 232 233 /* max swap interval supported by this compositor */ 234 ANATIVEWINDOW_QUERY_MAX_SWAP_INTERVAL = 0x10001, 235 236 /* horizontal resolution in DPI. value is float, use queryf() */ 237 ANATIVEWINDOW_QUERY_XDPI = 0x10002, 238 239 /* vertical resolution in DPI. value is float, use queryf() */ 240 ANATIVEWINDOW_QUERY_YDPI = 0x10003, 241}; 242 243typedef enum ANativeWindowQuery ANativeWindowQuery; 244 245/* 246 * hook used to retrieve information about the native window. 247 * 248 * Returns 0 on success or -errno on error. 249 */ 250int ANativeWindow_query(const ANativeWindow* window, ANativeWindowQuery query, int* value); 251int ANativeWindow_queryf(const ANativeWindow* window, ANativeWindowQuery query, float* value); 252 253 254/* 255 * Hook called by EGL to acquire a buffer. This call may block if no 256 * buffers are available. 257 * 258 * The window holds a reference to the buffer between dequeueBuffer and 259 * either queueBuffer or cancelBuffer, so clients only need their own 260 * reference if they might use the buffer after queueing or canceling it. 261 * Holding a reference to a buffer after queueing or canceling it is only 262 * allowed if a specific buffer count has been set. 263 * 264 * The libsync fence file descriptor returned in the int pointed to by the 265 * fenceFd argument will refer to the fence that must signal before the 266 * dequeued buffer may be written to. A value of -1 indicates that the 267 * caller may access the buffer immediately without waiting on a fence. If 268 * a valid file descriptor is returned (i.e. any value except -1) then the 269 * caller is responsible for closing the file descriptor. 270 * 271 * Returns 0 on success or -errno on error. 272 */ 273int ANativeWindow_dequeueBuffer(ANativeWindow* window, ANativeWindowBuffer** buffer, int* fenceFd); 274 275 276/* 277 * Hook called by EGL when modifications to the render buffer are done. 278 * This unlocks and post the buffer. 279 * 280 * The window holds a reference to the buffer between dequeueBuffer and 281 * either queueBuffer or cancelBuffer, so clients only need their own 282 * reference if they might use the buffer after queueing or canceling it. 283 * Holding a reference to a buffer after queueing or canceling it is only 284 * allowed if a specific buffer count has been set. 285 * 286 * The fenceFd argument specifies a libsync fence file descriptor for a 287 * fence that must signal before the buffer can be accessed. If the buffer 288 * can be accessed immediately then a value of -1 should be used. The 289 * caller must not use the file descriptor after it is passed to 290 * queueBuffer, and the ANativeWindow implementation is responsible for 291 * closing it. 292 * 293 * Returns 0 on success or -errno on error. 294 */ 295int ANativeWindow_queueBuffer(ANativeWindow* window, ANativeWindowBuffer* buffer, int fenceFd); 296 297 298/* 299 * Hook used to cancel a buffer that has been dequeued. 300 * No synchronization is performed between dequeue() and cancel(), so 301 * either external synchronization is needed, or these functions must be 302 * called from the same thread. 303 * 304 * The window holds a reference to the buffer between dequeueBuffer and 305 * either queueBuffer or cancelBuffer, so clients only need their own 306 * reference if they might use the buffer after queueing or canceling it. 307 * Holding a reference to a buffer after queueing or canceling it is only 308 * allowed if a specific buffer count has been set. 309 * 310 * The fenceFd argument specifies a libsync fence file decsriptor for a 311 * fence that must signal before the buffer can be accessed. If the buffer 312 * can be accessed immediately then a value of -1 should be used. 313 * 314 * Note that if the client has not waited on the fence that was returned 315 * from dequeueBuffer, that same fence should be passed to cancelBuffer to 316 * ensure that future uses of the buffer are preceded by a wait on that 317 * fence. The caller must not use the file descriptor after it is passed 318 * to cancelBuffer, and the ANativeWindow implementation is responsible for 319 * closing it. 320 * 321 * Returns 0 on success or -errno on error. 322 */ 323int ANativeWindow_cancelBuffer(ANativeWindow* window, ANativeWindowBuffer* buffer, int fenceFd); 324 325/* 326 * Sets the intended usage flags for the next buffers. 327 * 328 * usage: one of AHARDWAREBUFFER_USAGE0_* constant 329 * privateUsage: one of AHARDWAREBUFFER_USAGE1_*_PRIVATE_* constant 330 * 331 * By default (if this function is never called), a usage of 332 * AHARDWAREBUFFER_USAGE0_GPU_SAMPLED_IMAGE | AHARDWAREBUFFER_USAGE0_GPU_COLOR_OUTPUT 333 * is assumed. 334 * 335 * Calling this function will usually cause following buffers to be 336 * reallocated. 337 */ 338int ANativeWindow_setUsage(ANativeWindow* window, uint64_t usage0, uint64_t usage1); 339 340 341/* 342 * Sets the number of buffers associated with this native window. 343 */ 344int ANativeWindow_setBufferCount(ANativeWindow* window, size_t bufferCount); 345 346 347/* 348 * All buffers dequeued after this call will have the dimensions specified. 349 * In particular, all buffers will have a fixed-size, independent from the 350 * native-window size. They will be scaled according to the scaling mode 351 * (see native_window_set_scaling_mode) upon window composition. 352 * 353 * If w and h are 0, the normal behavior is restored. That is, dequeued buffers 354 * following this call will be sized to match the window's size. 355 * 356 * Calling this function will reset the window crop to a NULL value, which 357 * disables cropping of the buffers. 358 */ 359int ANativeWindow_setBuffersDimensions(ANativeWindow* window, uint32_t w, uint32_t h); 360 361 362/* 363 * All buffers dequeued after this call will have the format specified. 364 * format: one of AHARDWAREBUFFER_FORMAT_* constant 365 * 366 * If the specified format is 0, the default buffer format will be used. 367 */ 368int ANativeWindow_setBuffersFormat(ANativeWindow* window, int format); 369 370 371/* 372 * All buffers queued after this call will be associated with the timestamp in nanosecond 373 * parameter specified. If the timestamp is set to NATIVE_WINDOW_TIMESTAMP_AUTO 374 * (the default), timestamps will be generated automatically when queueBuffer is 375 * called. The timestamp is measured in nanoseconds, and is normally monotonically 376 * increasing. The timestamp should be unaffected by time-of-day adjustments, 377 * and for a camera should be strictly monotonic but for a media player may be 378 * reset when the position is set. 379 */ 380int ANativeWindow_setBuffersTimestamp(ANativeWindow* window, int64_t timestamp); 381 382 383/* 384 * All buffers queued after this call will be associated with the dataSpace 385 * parameter specified. 386 * 387 * dataSpace specifies additional information about the buffer that's dependent 388 * on the buffer format and the endpoints. For example, it can be used to convey 389 * the color space of the image data in the buffer, or it can be used to 390 * indicate that the buffers contain depth measurement data instead of color 391 * images. The default dataSpace is 0, HAL_DATASPACE_UNKNOWN, unless it has been 392 * overridden by the consumer. 393 */ 394int ANativeWindow_setBufferDataSpace(ANativeWindow* window, android_dataspace_t dataSpace); 395 396 397/* 398 * Enable/disable shared buffer mode 399 */ 400int ANativeWindow_setSharedBufferMode(ANativeWindow* window, bool sharedBufferMode); 401 402 403/* 404 * Enable/disable auto refresh when in shared buffer mode 405 */ 406int ANativeWindow_setAutoRefresh(ANativeWindow* window, bool autoRefresh); 407 408 409/*****************************************************************************/ 410 411__END_DECLS 412 413#endif /* ANDROID_VNDK_NATIVEWINDOW_ANATIVEWINDOW_H */ 414