window.h revision 000879a0eb2156727a2221e42d04b6f3e150aa79
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 239/* 240 * hook used to retrieve information about the native window. 241 * 242 * Returns 0 on success or -errno on error. 243 */ 244int ANativeWindow_query(const ANativeWindow* window, ANativeWindowQuery query, int* value); 245int ANativeWindow_queryf(const ANativeWindow* window, ANativeWindowQuery query, float* value); 246 247 248/* 249 * Hook called by EGL to acquire a buffer. This call may block if no 250 * buffers are available. 251 * 252 * The window holds a reference to the buffer between dequeueBuffer and 253 * either queueBuffer or cancelBuffer, so clients only need their own 254 * reference if they might use the buffer after queueing or canceling it. 255 * Holding a reference to a buffer after queueing or canceling it is only 256 * allowed if a specific buffer count has been set. 257 * 258 * The libsync fence file descriptor returned in the int pointed to by the 259 * fenceFd argument will refer to the fence that must signal before the 260 * dequeued buffer may be written to. A value of -1 indicates that the 261 * caller may access the buffer immediately without waiting on a fence. If 262 * a valid file descriptor is returned (i.e. any value except -1) then the 263 * caller is responsible for closing the file descriptor. 264 * 265 * Returns 0 on success or -errno on error. 266 */ 267int ANativeWindow_dequeueBuffer(ANativeWindow* window, ANativeWindowBuffer** buffer, int* fenceFd); 268 269 270/* 271 * Hook called by EGL when modifications to the render buffer are done. 272 * This unlocks and post the buffer. 273 * 274 * The window holds a reference to the buffer between dequeueBuffer and 275 * either queueBuffer or cancelBuffer, so clients only need their own 276 * reference if they might use the buffer after queueing or canceling it. 277 * Holding a reference to a buffer after queueing or canceling it is only 278 * allowed if a specific buffer count has been set. 279 * 280 * The fenceFd argument specifies a libsync fence file descriptor for a 281 * fence that must signal before the buffer can be accessed. If the buffer 282 * can be accessed immediately then a value of -1 should be used. The 283 * caller must not use the file descriptor after it is passed to 284 * queueBuffer, and the ANativeWindow implementation is responsible for 285 * closing it. 286 * 287 * Returns 0 on success or -errno on error. 288 */ 289int ANativeWindow_queueBuffer(ANativeWindow* window, ANativeWindowBuffer* buffer, int fenceFd); 290 291 292/* 293 * Hook used to cancel a buffer that has been dequeued. 294 * No synchronization is performed between dequeue() and cancel(), so 295 * either external synchronization is needed, or these functions must be 296 * called from the same thread. 297 * 298 * The window holds a reference to the buffer between dequeueBuffer and 299 * either queueBuffer or cancelBuffer, so clients only need their own 300 * reference if they might use the buffer after queueing or canceling it. 301 * Holding a reference to a buffer after queueing or canceling it is only 302 * allowed if a specific buffer count has been set. 303 * 304 * The fenceFd argument specifies a libsync fence file decsriptor for a 305 * fence that must signal before the buffer can be accessed. If the buffer 306 * can be accessed immediately then a value of -1 should be used. 307 * 308 * Note that if the client has not waited on the fence that was returned 309 * from dequeueBuffer, that same fence should be passed to cancelBuffer to 310 * ensure that future uses of the buffer are preceded by a wait on that 311 * fence. The caller must not use the file descriptor after it is passed 312 * to cancelBuffer, and the ANativeWindow implementation is responsible for 313 * closing it. 314 * 315 * Returns 0 on success or -errno on error. 316 */ 317int ANativeWindow_cancelBuffer(ANativeWindow* window, ANativeWindowBuffer* buffer, int fenceFd); 318 319/* 320 * Sets the intended usage flags for the next buffers. 321 * 322 * usage: one of AHARDWAREBUFFER_USAGE0_* constant 323 * privateUsage: one of AHARDWAREBUFFER_USAGE1_*_PRIVATE_* constant 324 * 325 * By default (if this function is never called), a usage of 326 * AHARDWAREBUFFER_USAGE0_GPU_SAMPLED_IMAGE | AHARDWAREBUFFER_USAGE0_GPU_COLOR_OUTPUT 327 * is assumed. 328 * 329 * Calling this function will usually cause following buffers to be 330 * reallocated. 331 */ 332int ANativeWindow_setUsage(ANativeWindow* window, uint64_t usage0, uint64_t usage1); 333 334 335/* 336 * Sets the number of buffers associated with this native window. 337 */ 338int ANativeWindow_setBufferCount(ANativeWindow* window, size_t bufferCount); 339 340 341/* 342 * All buffers dequeued after this call will have the dimensions specified. 343 * In particular, all buffers will have a fixed-size, independent from the 344 * native-window size. They will be scaled according to the scaling mode 345 * (see native_window_set_scaling_mode) upon window composition. 346 * 347 * If w and h are 0, the normal behavior is restored. That is, dequeued buffers 348 * following this call will be sized to match the window's size. 349 * 350 * Calling this function will reset the window crop to a NULL value, which 351 * disables cropping of the buffers. 352 */ 353int ANativeWindow_setBuffersDimensions(ANativeWindow* window, uint32_t w, uint32_t h); 354 355 356/* 357 * All buffers dequeued after this call will have the format specified. 358 * format: one of AHARDWAREBUFFER_FORMAT_* constant 359 * 360 * If the specified format is 0, the default buffer format will be used. 361 */ 362int ANativeWindow_setBuffersFormat(ANativeWindow* window, int format); 363 364 365/* 366 * All buffers queued after this call will be associated with the timestamp in nanosecond 367 * parameter specified. If the timestamp is set to NATIVE_WINDOW_TIMESTAMP_AUTO 368 * (the default), timestamps will be generated automatically when queueBuffer is 369 * called. The timestamp is measured in nanoseconds, and is normally monotonically 370 * increasing. The timestamp should be unaffected by time-of-day adjustments, 371 * and for a camera should be strictly monotonic but for a media player may be 372 * reset when the position is set. 373 */ 374int ANativeWindow_setBuffersTimestamp(ANativeWindow* window, int64_t timestamp); 375 376 377/* 378 * All buffers queued after this call will be associated with the dataSpace 379 * parameter specified. 380 * 381 * dataSpace specifies additional information about the buffer that's dependent 382 * on the buffer format and the endpoints. For example, it can be used to convey 383 * the color space of the image data in the buffer, or it can be used to 384 * indicate that the buffers contain depth measurement data instead of color 385 * images. The default dataSpace is 0, HAL_DATASPACE_UNKNOWN, unless it has been 386 * overridden by the consumer. 387 */ 388int ANativeWindow_setBufferDataSpace(ANativeWindow* window, android_dataspace_t dataSpace); 389 390 391/* 392 * Enable/disable shared buffer mode 393 */ 394int ANativeWindow_setSharedBufferMode(ANativeWindow* window, bool sharedBufferMode); 395 396 397/* 398 * Enable/disable auto refresh when in shared buffer mode 399 */ 400int ANativeWindow_setAutoRefresh(ANativeWindow* window, bool autoRefresh); 401 402 403/*****************************************************************************/ 404 405__END_DECLS 406 407#endif /* ANDROID_VNDK_NATIVEWINDOW_ANATIVEWINDOW_H */ 408