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_USAGE_* constant
329 *
330 *  By default (if this function is never called), a usage of
331 *      AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE | AHARDWAREBUFFER_USAGE_GPU_COLOR_OUTPUT
332 *  is assumed.
333 *
334 *  Calling this function will usually cause following buffers to be
335 *  reallocated.
336 */
337int ANativeWindow_setUsage(ANativeWindow* window, uint64_t usage);
338
339
340/*
341 * Sets the number of buffers associated with this native window.
342 */
343int ANativeWindow_setBufferCount(ANativeWindow* window, size_t bufferCount);
344
345
346/*
347 * All buffers dequeued after this call will have the dimensions specified.
348 * In particular, all buffers will have a fixed-size, independent from the
349 * native-window size. They will be scaled according to the scaling mode
350 * (see native_window_set_scaling_mode) upon window composition.
351 *
352 * If w and h are 0, the normal behavior is restored. That is, dequeued buffers
353 * following this call will be sized to match the window's size.
354 *
355 * Calling this function will reset the window crop to a NULL value, which
356 * disables cropping of the buffers.
357 */
358int ANativeWindow_setBuffersDimensions(ANativeWindow* window, uint32_t w, uint32_t h);
359
360
361/*
362 * All buffers dequeued after this call will have the format specified.
363 * format: one of AHARDWAREBUFFER_FORMAT_* constant
364 *
365 * If the specified format is 0, the default buffer format will be used.
366 */
367int ANativeWindow_setBuffersFormat(ANativeWindow* window, int format);
368
369
370/*
371 * All buffers queued after this call will be associated with the timestamp in nanosecond
372 * parameter specified. If the timestamp is set to NATIVE_WINDOW_TIMESTAMP_AUTO
373 * (the default), timestamps will be generated automatically when queueBuffer is
374 * called. The timestamp is measured in nanoseconds, and is normally monotonically
375 * increasing. The timestamp should be unaffected by time-of-day adjustments,
376 * and for a camera should be strictly monotonic but for a media player may be
377 * reset when the position is set.
378 */
379int ANativeWindow_setBuffersTimestamp(ANativeWindow* window, int64_t timestamp);
380
381
382/*
383 * All buffers queued after this call will be associated with the dataSpace
384 * parameter specified.
385 *
386 * dataSpace specifies additional information about the buffer that's dependent
387 * on the buffer format and the endpoints. For example, it can be used to convey
388 * the color space of the image data in the buffer, or it can be used to
389 * indicate that the buffers contain depth measurement data instead of color
390 * images.  The default dataSpace is 0, HAL_DATASPACE_UNKNOWN, unless it has been
391 * overridden by the consumer.
392 */
393int ANativeWindow_setBufferDataSpace(ANativeWindow* window, android_dataspace_t dataSpace);
394
395
396/*
397 * Enable/disable shared buffer mode
398 */
399int ANativeWindow_setSharedBufferMode(ANativeWindow* window, bool sharedBufferMode);
400
401
402/*
403 * Enable/disable auto refresh when in shared buffer mode
404 */
405int ANativeWindow_setAutoRefresh(ANativeWindow* window, bool autoRefresh);
406
407
408/*****************************************************************************/
409
410__END_DECLS
411
412#endif /* ANDROID_VNDK_NATIVEWINDOW_ANATIVEWINDOW_H */
413