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