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 #ifndef ANDROID_VNDK_NATIVEWINDOW_ANATIVEWINDOW_H 17 #define ANDROID_VNDK_NATIVEWINDOW_ANATIVEWINDOW_H 18 #include <nativebase/nativebase.h> 19 // vndk is a superset of the NDK 20 #include <android/native_window.h> 21 __BEGIN_DECLS 22 /* 23 * Convert this ANativeWindowBuffer into a AHardwareBuffer 24 */ 25 AHardwareBuffer* ANativeWindowBuffer_getHardwareBuffer(ANativeWindowBuffer* anwb); 26 /*****************************************************************************/ 27 /* 28 * Stores a value into one of the 4 available slots 29 * Retrieve the value with ANativeWindow_OemStorageGet() 30 * 31 * slot: 0 to 3 32 * 33 * Returns 0 on success or -errno on error. 34 */ 35 int ANativeWindow_OemStorageSet(ANativeWindow* window, uint32_t slot, intptr_t value); 36 /* 37 * Retrieves a value from one of the 4 available slots 38 * By default the returned value is 0 if it wasn't set by ANativeWindow_OemStorageSet() 39 * 40 * slot: 0 to 3 41 * 42 * Returns 0 on success or -errno on error. 43 */ 44 int ANativeWindow_OemStorageGet(ANativeWindow* window, uint32_t slot, intptr_t* value); 45 /* 46 * Set the swap interval for this surface. 47 * 48 * Returns 0 on success or -errno on error. 49 */ 50 int ANativeWindow_setSwapInterval(ANativeWindow* window, int interval); 51 /* 52 * queries that can be used with ANativeWindow_query() and ANativeWindow_queryf() 53 */ 54 enum ANativeWindowQuery { 55 /* The minimum number of buffers that must remain un-dequeued after a buffer 56 * has been queued. This value applies only if set_buffer_count was used to 57 * override the number of buffers and if a buffer has since been queued. 58 * Users of the set_buffer_count ANativeWindow method should query this 59 * value before calling set_buffer_count. If it is necessary to have N 60 * buffers simultaneously dequeued as part of the steady-state operation, 61 * and this query returns M then N+M buffers should be requested via 62 * native_window_set_buffer_count. 63 * 64 * Note that this value does NOT apply until a single buffer has been 65 * queued. In particular this means that it is possible to: 66 * 67 * 1. Query M = min undequeued buffers 68 * 2. Set the buffer count to N + M 69 * 3. Dequeue all N + M buffers 70 * 4. Cancel M buffers 71 * 5. Queue, dequeue, queue, dequeue, ad infinitum 72 */ 73 ANATIVEWINDOW_QUERY_MIN_UNDEQUEUED_BUFFERS = 3, 74 /* 75 * Default width of ANativeWindow buffers, these are the 76 * dimensions of the window buffers irrespective of the 77 * ANativeWindow_setBuffersDimensions() call and match the native window 78 * size. 79 */ 80 ANATIVEWINDOW_QUERY_DEFAULT_WIDTH = 6, 81 ANATIVEWINDOW_QUERY_DEFAULT_HEIGHT = 7, 82 /* 83 * transformation that will most-likely be applied to buffers. This is only 84 * a hint, the actual transformation applied might be different. 85 * 86 * INTENDED USE: 87 * 88 * The transform hint can be used by a producer, for instance the GLES 89 * driver, to pre-rotate the rendering such that the final transformation 90 * in the composer is identity. This can be very useful when used in 91 * conjunction with the h/w composer HAL, in situations where it 92 * cannot handle arbitrary rotations. 93 * 94 * 1. Before dequeuing a buffer, the GL driver (or any other ANW client) 95 * queries the ANW for NATIVE_WINDOW_TRANSFORM_HINT. 96 * 97 * 2. The GL driver overrides the width and height of the ANW to 98 * account for NATIVE_WINDOW_TRANSFORM_HINT. This is done by querying 99 * NATIVE_WINDOW_DEFAULT_{WIDTH | HEIGHT}, swapping the dimensions 100 * according to NATIVE_WINDOW_TRANSFORM_HINT and calling 101 * native_window_set_buffers_dimensions(). 102 * 103 * 3. The GL driver dequeues a buffer of the new pre-rotated size. 104 * 105 * 4. The GL driver renders to the buffer such that the image is 106 * already transformed, that is applying NATIVE_WINDOW_TRANSFORM_HINT 107 * to the rendering. 108 * 109 * 5. The GL driver calls native_window_set_transform to apply 110 * inverse transformation to the buffer it just rendered. 111 * In order to do this, the GL driver needs 112 * to calculate the inverse of NATIVE_WINDOW_TRANSFORM_HINT, this is 113 * done easily: 114 * 115 * int hintTransform, inverseTransform; 116 * query(..., NATIVE_WINDOW_TRANSFORM_HINT, &hintTransform); 117 * inverseTransform = hintTransform; 118 * if (hintTransform & HAL_TRANSFORM_ROT_90) 119 * inverseTransform ^= HAL_TRANSFORM_ROT_180; 120 * 121 * 122 * 6. The GL driver queues the pre-transformed buffer. 123 * 124 * 7. The composer combines the buffer transform with the display 125 * transform. If the buffer transform happens to cancel out the 126 * display transform then no rotation is needed. 127 * 128 */ 129 ANATIVEWINDOW_QUERY_TRANSFORM_HINT = 8, 130 /* 131 * Returns the age of the contents of the most recently dequeued buffer as 132 * the number of frames that have elapsed since it was last queued. For 133 * example, if the window is double-buffered, the age of any given buffer in 134 * steady state will be 2. If the dequeued buffer has never been queued, its 135 * age will be 0. 136 */ 137 ANATIVEWINDOW_QUERY_BUFFER_AGE = 13, 138 /* min swap interval supported by this compositor */ 139 ANATIVEWINDOW_QUERY_MIN_SWAP_INTERVAL = 0x10000, 140 /* max swap interval supported by this compositor */ 141 ANATIVEWINDOW_QUERY_MAX_SWAP_INTERVAL = 0x10001, 142 /* horizontal resolution in DPI. value is float, use queryf() */ 143 ANATIVEWINDOW_QUERY_XDPI = 0x10002, 144 /* vertical resolution in DPI. value is float, use queryf() */ 145 ANATIVEWINDOW_QUERY_YDPI = 0x10003, 146 }; 147 typedef enum ANativeWindowQuery ANativeWindowQuery; 148 /* 149 * hook used to retrieve information about the native window. 150 * 151 * Returns 0 on success or -errno on error. 152 */ 153 int ANativeWindow_query(const ANativeWindow* window, ANativeWindowQuery query, int* value); 154 int ANativeWindow_queryf(const ANativeWindow* window, ANativeWindowQuery query, float* value); 155 /* 156 * Hook called by EGL to acquire a buffer. This call may block if no 157 * buffers are available. 158 * 159 * The window holds a reference to the buffer between dequeueBuffer and 160 * either queueBuffer or cancelBuffer, so clients only need their own 161 * reference if they might use the buffer after queueing or canceling it. 162 * Holding a reference to a buffer after queueing or canceling it is only 163 * allowed if a specific buffer count has been set. 164 * 165 * The libsync fence file descriptor returned in the int pointed to by the 166 * fenceFd argument will refer to the fence that must signal before the 167 * dequeued buffer may be written to. A value of -1 indicates that the 168 * caller may access the buffer immediately without waiting on a fence. If 169 * a valid file descriptor is returned (i.e. any value except -1) then the 170 * caller is responsible for closing the file descriptor. 171 * 172 * Returns 0 on success or -errno on error. 173 */ 174 int ANativeWindow_dequeueBuffer(ANativeWindow* window, ANativeWindowBuffer** buffer, int* fenceFd); 175 /* 176 * Hook called by EGL when modifications to the render buffer are done. 177 * This unlocks and post the buffer. 178 * 179 * The window holds a reference to the buffer between dequeueBuffer and 180 * either queueBuffer or cancelBuffer, so clients only need their own 181 * reference if they might use the buffer after queueing or canceling it. 182 * Holding a reference to a buffer after queueing or canceling it is only 183 * allowed if a specific buffer count has been set. 184 * 185 * The fenceFd argument specifies a libsync fence file descriptor for a 186 * fence that must signal before the buffer can be accessed. If the buffer 187 * can be accessed immediately then a value of -1 should be used. The 188 * caller must not use the file descriptor after it is passed to 189 * queueBuffer, and the ANativeWindow implementation is responsible for 190 * closing it. 191 * 192 * Returns 0 on success or -errno on error. 193 */ 194 int ANativeWindow_queueBuffer(ANativeWindow* window, ANativeWindowBuffer* buffer, int fenceFd); 195 /* 196 * Hook used to cancel a buffer that has been dequeued. 197 * No synchronization is performed between dequeue() and cancel(), so 198 * either external synchronization is needed, or these functions must be 199 * called from the same thread. 200 * 201 * The window holds a reference to the buffer between dequeueBuffer and 202 * either queueBuffer or cancelBuffer, so clients only need their own 203 * reference if they might use the buffer after queueing or canceling it. 204 * Holding a reference to a buffer after queueing or canceling it is only 205 * allowed if a specific buffer count has been set. 206 * 207 * The fenceFd argument specifies a libsync fence file decsriptor for a 208 * fence that must signal before the buffer can be accessed. If the buffer 209 * can be accessed immediately then a value of -1 should be used. 210 * 211 * Note that if the client has not waited on the fence that was returned 212 * from dequeueBuffer, that same fence should be passed to cancelBuffer to 213 * ensure that future uses of the buffer are preceded by a wait on that 214 * fence. The caller must not use the file descriptor after it is passed 215 * to cancelBuffer, and the ANativeWindow implementation is responsible for 216 * closing it. 217 * 218 * Returns 0 on success or -errno on error. 219 */ 220 int ANativeWindow_cancelBuffer(ANativeWindow* window, ANativeWindowBuffer* buffer, int fenceFd); 221 /* 222 * Sets the intended usage flags for the next buffers. 223 * 224 * usage: one of AHARDWAREBUFFER_USAGE_* constant 225 * 226 * By default (if this function is never called), a usage of 227 * AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE | AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT 228 * is assumed. 229 * 230 * Calling this function will usually cause following buffers to be 231 * reallocated. 232 */ 233 int ANativeWindow_setUsage(ANativeWindow* window, uint64_t usage); 234 /* 235 * Sets the number of buffers associated with this native window. 236 */ 237 int ANativeWindow_setBufferCount(ANativeWindow* window, size_t bufferCount); 238 /* 239 * All buffers dequeued after this call will have the dimensions specified. 240 * In particular, all buffers will have a fixed-size, independent from the 241 * native-window size. They will be scaled according to the scaling mode 242 * (see native_window_set_scaling_mode) upon window composition. 243 * 244 * If w and h are 0, the normal behavior is restored. That is, dequeued buffers 245 * following this call will be sized to match the window's size. 246 * 247 * Calling this function will reset the window crop to a NULL value, which 248 * disables cropping of the buffers. 249 */ 250 int ANativeWindow_setBuffersDimensions(ANativeWindow* window, uint32_t w, uint32_t h); 251 /* 252 * All buffers dequeued after this call will have the format specified. 253 * format: one of AHARDWAREBUFFER_FORMAT_* constant 254 * 255 * If the specified format is 0, the default buffer format will be used. 256 */ 257 int ANativeWindow_setBuffersFormat(ANativeWindow* window, int format); 258 /* 259 * All buffers queued after this call will be associated with the timestamp in nanosecond 260 * parameter specified. If the timestamp is set to NATIVE_WINDOW_TIMESTAMP_AUTO 261 * (the default), timestamps will be generated automatically when queueBuffer is 262 * called. The timestamp is measured in nanoseconds, and is normally monotonically 263 * increasing. The timestamp should be unaffected by time-of-day adjustments, 264 * and for a camera should be strictly monotonic but for a media player may be 265 * reset when the position is set. 266 */ 267 int ANativeWindow_setBuffersTimestamp(ANativeWindow* window, int64_t timestamp); 268 /* 269 * All buffers queued after this call will be associated with the dataSpace 270 * parameter specified. 271 * 272 * dataSpace specifies additional information about the buffer that's dependent 273 * on the buffer format and the endpoints. For example, it can be used to convey 274 * the color space of the image data in the buffer, or it can be used to 275 * indicate that the buffers contain depth measurement data instead of color 276 * images. The default dataSpace is 0, HAL_DATASPACE_UNKNOWN, unless it has been 277 * overridden by the consumer. 278 */ 279 int ANativeWindow_setBufferDataSpace(ANativeWindow* window, android_dataspace_t dataSpace); 280 /* 281 * Enable/disable shared buffer mode 282 */ 283 int ANativeWindow_setSharedBufferMode(ANativeWindow* window, bool sharedBufferMode); 284 /* 285 * Enable/disable auto refresh when in shared buffer mode 286 */ 287 int ANativeWindow_setAutoRefresh(ANativeWindow* window, bool autoRefresh); 288 /*****************************************************************************/ 289 __END_DECLS 290 #endif /* ANDROID_VNDK_NATIVEWINDOW_ANATIVEWINDOW_H */ 291