window.h revision 42cc1edfe7edf613e17bff97f30ff124ada05136
1/*
2 * Copyright (C) 2011 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 SYSTEM_CORE_INCLUDE_ANDROID_WINDOW_H
18#define SYSTEM_CORE_INCLUDE_ANDROID_WINDOW_H
19
20#include <stdint.h>
21#include <sys/cdefs.h>
22#include <system/graphics.h>
23#include <cutils/native_handle.h>
24
25__BEGIN_DECLS
26
27/*****************************************************************************/
28
29#define ANDROID_NATIVE_MAKE_CONSTANT(a,b,c,d) \
30    (((unsigned)(a)<<24)|((unsigned)(b)<<16)|((unsigned)(c)<<8)|(unsigned)(d))
31
32#define ANDROID_NATIVE_WINDOW_MAGIC \
33    ANDROID_NATIVE_MAKE_CONSTANT('_','w','n','d')
34
35#define ANDROID_NATIVE_BUFFER_MAGIC \
36    ANDROID_NATIVE_MAKE_CONSTANT('_','b','f','r')
37
38// ---------------------------------------------------------------------------
39
40typedef const native_handle_t* buffer_handle_t;
41
42// ---------------------------------------------------------------------------
43
44typedef struct android_native_rect_t
45{
46    int32_t left;
47    int32_t top;
48    int32_t right;
49    int32_t bottom;
50} android_native_rect_t;
51
52// ---------------------------------------------------------------------------
53
54typedef struct android_native_base_t
55{
56    /* a magic value defined by the actual EGL native type */
57    int magic;
58
59    /* the sizeof() of the actual EGL native type */
60    int version;
61
62    void* reserved[4];
63
64    /* reference-counting interface */
65    void (*incRef)(struct android_native_base_t* base);
66    void (*decRef)(struct android_native_base_t* base);
67} android_native_base_t;
68
69typedef struct ANativeWindowBuffer
70{
71#ifdef __cplusplus
72    ANativeWindowBuffer() {
73        common.magic = ANDROID_NATIVE_BUFFER_MAGIC;
74        common.version = sizeof(ANativeWindowBuffer);
75        memset(common.reserved, 0, sizeof(common.reserved));
76    }
77
78    // Implement the methods that sp<ANativeWindowBuffer> expects so that it
79    // can be used to automatically refcount ANativeWindowBuffer's.
80    void incStrong(const void* id) const {
81        common.incRef(const_cast<android_native_base_t*>(&common));
82    }
83    void decStrong(const void* id) const {
84        common.decRef(const_cast<android_native_base_t*>(&common));
85    }
86#endif
87
88    struct android_native_base_t common;
89
90    int width;
91    int height;
92    int stride;
93    int format;
94    int usage;
95
96    void* reserved[2];
97
98    buffer_handle_t handle;
99
100    void* reserved_proc[8];
101} ANativeWindowBuffer_t;
102
103// Old typedef for backwards compatibility.
104typedef ANativeWindowBuffer_t android_native_buffer_t;
105
106// ---------------------------------------------------------------------------
107
108/* attributes queriable with query() */
109enum {
110    NATIVE_WINDOW_WIDTH     = 0,
111    NATIVE_WINDOW_HEIGHT    = 1,
112    NATIVE_WINDOW_FORMAT    = 2,
113
114    /* The minimum number of buffers that must remain un-dequeued after a buffer
115     * has been queued.  This value applies only if set_buffer_count was used to
116     * override the number of buffers and if a buffer has since been queued.
117     * Users of the set_buffer_count ANativeWindow method should query this
118     * value before calling set_buffer_count.  If it is necessary to have N
119     * buffers simultaneously dequeued as part of the steady-state operation,
120     * and this query returns M then N+M buffers should be requested via
121     * native_window_set_buffer_count.
122     *
123     * Note that this value does NOT apply until a single buffer has been
124     * queued.  In particular this means that it is possible to:
125     *
126     * 1. Query M = min undequeued buffers
127     * 2. Set the buffer count to N + M
128     * 3. Dequeue all N + M buffers
129     * 4. Cancel M buffers
130     * 5. Queue, dequeue, queue, dequeue, ad infinitum
131     */
132    NATIVE_WINDOW_MIN_UNDEQUEUED_BUFFERS = 3,
133
134    /* Check whether queueBuffer operations on the ANativeWindow send the buffer
135     * to the window compositor.  The query sets the returned 'value' argument
136     * to 1 if the ANativeWindow DOES send queued buffers directly to the window
137     * compositor and 0 if the buffers do not go directly to the window
138     * compositor.
139     *
140     * This can be used to determine whether protected buffer content should be
141     * sent to the ANativeWindow.  Note, however, that a result of 1 does NOT
142     * indicate that queued buffers will be protected from applications or users
143     * capturing their contents.  If that behavior is desired then some other
144     * mechanism (e.g. the GRALLOC_USAGE_PROTECTED flag) should be used in
145     * conjunction with this query.
146     */
147    NATIVE_WINDOW_QUEUES_TO_WINDOW_COMPOSER = 4,
148
149    /* Get the concrete type of a ANativeWindow.  See below for the list of
150     * possible return values.
151     *
152     * This query should not be used outside the Android framework and will
153     * likely be removed in the near future.
154     */
155    NATIVE_WINDOW_CONCRETE_TYPE = 5,
156};
157
158/* valid operations for the (*perform)() hook */
159enum {
160    NATIVE_WINDOW_SET_USAGE                 =  0,
161    NATIVE_WINDOW_CONNECT                   =  1,
162    NATIVE_WINDOW_DISCONNECT                =  2,
163    NATIVE_WINDOW_SET_CROP                  =  3,
164    NATIVE_WINDOW_SET_BUFFER_COUNT          =  4,
165    NATIVE_WINDOW_SET_BUFFERS_GEOMETRY      =  5,   /* deprecated */
166    NATIVE_WINDOW_SET_BUFFERS_TRANSFORM     =  6,
167    NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP     =  7,
168    NATIVE_WINDOW_SET_BUFFERS_DIMENSIONS    =  8,
169    NATIVE_WINDOW_SET_BUFFERS_FORMAT        =  9,
170    NATIVE_WINDOW_SET_SCALING_MODE          = 10
171};
172
173/* parameter for NATIVE_WINDOW_[DIS]CONNECT */
174enum {
175    /* Buffers will be queued by EGL via eglSwapBuffers after being filled using
176     * OpenGL ES.
177     */
178    NATIVE_WINDOW_API_EGL = 1,
179
180    /* Buffers will be queued after being filled using the CPU
181     */
182    NATIVE_WINDOW_API_CPU = 2,
183
184    /* Buffers will be queued by Stagefright after being filled by a video
185     * decoder.  The video decoder can either be a software or hardware decoder.
186     */
187    NATIVE_WINDOW_API_MEDIA = 3,
188
189    /* Buffers will be queued by the the camera HAL.
190     */
191    NATIVE_WINDOW_API_CAMERA = 4,
192};
193
194/* parameter for NATIVE_WINDOW_SET_BUFFERS_TRANSFORM */
195enum {
196    /* flip source image horizontally */
197    NATIVE_WINDOW_TRANSFORM_FLIP_H = HAL_TRANSFORM_FLIP_H ,
198    /* flip source image vertically */
199    NATIVE_WINDOW_TRANSFORM_FLIP_V = HAL_TRANSFORM_FLIP_V,
200    /* rotate source image 90 degrees clock-wise */
201    NATIVE_WINDOW_TRANSFORM_ROT_90 = HAL_TRANSFORM_ROT_90,
202    /* rotate source image 180 degrees */
203    NATIVE_WINDOW_TRANSFORM_ROT_180 = HAL_TRANSFORM_ROT_180,
204    /* rotate source image 270 degrees clock-wise */
205    NATIVE_WINDOW_TRANSFORM_ROT_270 = HAL_TRANSFORM_ROT_270,
206};
207
208/* parameter for NATIVE_WINDOW_SET_SCALING_MODE */
209enum {
210    /* the window content is not updated (frozen) until a buffer of
211     * the window size is received (enqueued)
212     */
213    NATIVE_WINDOW_SCALING_MODE_FREEZE           = 0,
214    /* the buffer is scaled in both dimensions to match the window size */
215    NATIVE_WINDOW_SCALING_MODE_SCALE_TO_WINDOW  = 1,
216};
217
218/* values returned by the NATIVE_WINDOW_CONCRETE_TYPE query */
219enum {
220    NATIVE_WINDOW_FRAMEBUFFER               = 0, /* FramebufferNativeWindow */
221    NATIVE_WINDOW_SURFACE                   = 1, /* Surface */
222    NATIVE_WINDOW_SURFACE_TEXTURE_CLIENT    = 2, /* SurfaceTextureClient */
223};
224
225/* parameter for NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP
226 *
227 * Special timestamp value to indicate that timestamps should be auto-generated
228 * by the native window when queueBuffer is called.  This is equal to INT64_MIN,
229 * defined directly to avoid problems with C99/C++ inclusion of stdint.h.
230 */
231static const int64_t NATIVE_WINDOW_TIMESTAMP_AUTO = (-9223372036854775807LL-1);
232
233struct ANativeWindow
234{
235#ifdef __cplusplus
236    ANativeWindow()
237        : flags(0), minSwapInterval(0), maxSwapInterval(0), xdpi(0), ydpi(0)
238    {
239        common.magic = ANDROID_NATIVE_WINDOW_MAGIC;
240        common.version = sizeof(ANativeWindow);
241        memset(common.reserved, 0, sizeof(common.reserved));
242    }
243
244    /* Implement the methods that sp<ANativeWindow> expects so that it
245       can be used to automatically refcount ANativeWindow's. */
246    void incStrong(const void* id) const {
247        common.incRef(const_cast<android_native_base_t*>(&common));
248    }
249    void decStrong(const void* id) const {
250        common.decRef(const_cast<android_native_base_t*>(&common));
251    }
252#endif
253
254    struct android_native_base_t common;
255
256    /* flags describing some attributes of this surface or its updater */
257    const uint32_t flags;
258
259    /* min swap interval supported by this updated */
260    const int   minSwapInterval;
261
262    /* max swap interval supported by this updated */
263    const int   maxSwapInterval;
264
265    /* horizontal and vertical resolution in DPI */
266    const float xdpi;
267    const float ydpi;
268
269    /* Some storage reserved for the OEM's driver. */
270    intptr_t    oem[4];
271
272    /*
273     * Set the swap interval for this surface.
274     *
275     * Returns 0 on success or -errno on error.
276     */
277    int     (*setSwapInterval)(struct ANativeWindow* window,
278                int interval);
279
280    /*
281     * hook called by EGL to acquire a buffer. After this call, the buffer
282     * is not locked, so its content cannot be modified.
283     * this call may block if no buffers are available.
284     *
285     * Returns 0 on success or -errno on error.
286     */
287    int     (*dequeueBuffer)(struct ANativeWindow* window,
288                struct ANativeWindowBuffer** buffer);
289
290    /*
291     * hook called by EGL to lock a buffer. This MUST be called before modifying
292     * the content of a buffer. The buffer must have been acquired with
293     * dequeueBuffer first.
294     *
295     * Returns 0 on success or -errno on error.
296     */
297    int     (*lockBuffer)(struct ANativeWindow* window,
298                struct ANativeWindowBuffer* buffer);
299   /*
300    * hook called by EGL when modifications to the render buffer are done.
301    * This unlocks and post the buffer.
302    *
303    * Buffers MUST be queued in the same order than they were dequeued.
304    *
305    * Returns 0 on success or -errno on error.
306    */
307    int     (*queueBuffer)(struct ANativeWindow* window,
308                struct ANativeWindowBuffer* buffer);
309
310    /*
311     * hook used to retrieve information about the native window.
312     *
313     * Returns 0 on success or -errno on error.
314     */
315    int     (*query)(const struct ANativeWindow* window,
316                int what, int* value);
317
318    /*
319     * hook used to perform various operations on the surface.
320     * (*perform)() is a generic mechanism to add functionality to
321     * ANativeWindow while keeping backward binary compatibility.
322     *
323     * DO NOT CALL THIS HOOK DIRECTLY.  Instead, use the helper functions
324     * defined below.
325     *
326     *  (*perform)() returns -ENOENT if the 'what' parameter is not supported
327     *  by the surface's implementation.
328     *
329     * The valid operations are:
330     *     NATIVE_WINDOW_SET_USAGE
331     *     NATIVE_WINDOW_CONNECT
332     *     NATIVE_WINDOW_DISCONNECT
333     *     NATIVE_WINDOW_SET_CROP
334     *     NATIVE_WINDOW_SET_BUFFER_COUNT
335     *     NATIVE_WINDOW_SET_BUFFERS_GEOMETRY  (deprecated)
336     *     NATIVE_WINDOW_SET_BUFFERS_TRANSFORM
337     *     NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP
338     *     NATIVE_WINDOW_SET_BUFFERS_DIMENSIONS
339     *     NATIVE_WINDOW_SET_BUFFERS_FORMAT
340     *     NATIVE_WINDOW_SET_SCALING_MODE
341     *
342     */
343
344    int     (*perform)(struct ANativeWindow* window,
345                int operation, ... );
346
347    /*
348     * hook used to cancel a buffer that has been dequeued.
349     * No synchronization is performed between dequeue() and cancel(), so
350     * either external synchronization is needed, or these functions must be
351     * called from the same thread.
352     */
353    int     (*cancelBuffer)(struct ANativeWindow* window,
354                struct ANativeWindowBuffer* buffer);
355
356
357    void* reserved_proc[2];
358};
359
360 /* Backwards compatibility: use ANativeWindow (struct ANativeWindow in C).
361  * android_native_window_t is deprecated.
362  */
363typedef struct ANativeWindow ANativeWindow;
364typedef struct ANativeWindow android_native_window_t;
365
366/*
367 *  native_window_set_usage(..., usage)
368 *  Sets the intended usage flags for the next buffers
369 *  acquired with (*lockBuffer)() and on.
370 *  By default (if this function is never called), a usage of
371 *      GRALLOC_USAGE_HW_RENDER | GRALLOC_USAGE_HW_TEXTURE
372 *  is assumed.
373 *  Calling this function will usually cause following buffers to be
374 *  reallocated.
375 */
376
377static inline int native_window_set_usage(
378        struct ANativeWindow* window, int usage)
379{
380    return window->perform(window, NATIVE_WINDOW_SET_USAGE, usage);
381}
382
383/*
384 * native_window_connect(..., NATIVE_WINDOW_API_EGL)
385 * Must be called by EGL when the window is made current.
386 * Returns -EINVAL if for some reason the window cannot be connected, which
387 * can happen if it's connected to some other API.
388 */
389static inline int native_window_connect(
390        struct ANativeWindow* window, int api)
391{
392    return window->perform(window, NATIVE_WINDOW_CONNECT, api);
393}
394
395/*
396 * native_window_disconnect(..., NATIVE_WINDOW_API_EGL)
397 * Must be called by EGL when the window is made not current.
398 * An error is returned if for instance the window wasn't connected in the
399 * first place.
400 */
401static inline int native_window_disconnect(
402        struct ANativeWindow* window, int api)
403{
404    return window->perform(window, NATIVE_WINDOW_DISCONNECT, api);
405}
406
407/*
408 * native_window_set_crop(..., crop)
409 * Sets which region of the next queued buffers needs to be considered.
410 * A buffer's crop region is scaled to match the surface's size.
411 *
412 * The specified crop region applies to all buffers queued after it is called.
413 *
414 * if 'crop' is NULL, subsequently queued buffers won't be cropped.
415 *
416 * An error is returned if for instance the crop region is invalid,
417 * out of the buffer's bound or if the window is invalid.
418 */
419static inline int native_window_set_crop(
420        struct ANativeWindow* window,
421        android_native_rect_t const * crop)
422{
423    return window->perform(window, NATIVE_WINDOW_SET_CROP, crop);
424}
425
426/*
427 * native_window_set_buffer_count(..., count)
428 * Sets the number of buffers associated with this native window.
429 */
430static inline int native_window_set_buffer_count(
431        struct ANativeWindow* window,
432        size_t bufferCount)
433{
434    return window->perform(window, NATIVE_WINDOW_SET_BUFFER_COUNT, bufferCount);
435}
436
437/*
438 * native_window_set_buffers_geometry(..., int w, int h, int format)
439 * All buffers dequeued after this call will have the dimensions and format
440 * specified.  A successful call to this function has the same effect as calling
441 * native_window_set_buffers_size and native_window_set_buffers_format.
442 *
443 * XXX: This function is deprecated.  The native_window_set_buffers_dimensions
444 * and native_window_set_buffers_format functions should be used instead.
445 */
446static inline int native_window_set_buffers_geometry(
447        struct ANativeWindow* window,
448        int w, int h, int format)
449{
450    return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_GEOMETRY,
451            w, h, format);
452}
453
454/*
455 * native_window_set_buffers_dimensions(..., int w, int h)
456 * All buffers dequeued after this call will have the dimensions specified.
457 * In particular, all buffers will have a fixed-size, independent form the
458 * native-window size. They will be scaled according to the scaling mode
459 * (see native_window_set_scaling_mode) upon window composition.
460 *
461 * If w and h are 0, the normal behavior is restored. That is, dequeued buffers
462 * following this call will be sized to match the window's size.
463 *
464 * Calling this function will reset the window crop to a NULL value, which
465 * disables cropping of the buffers.
466 */
467static inline int native_window_set_buffers_dimensions(
468        struct ANativeWindow* window,
469        int w, int h)
470{
471    return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_DIMENSIONS,
472            w, h);
473}
474
475/*
476 * native_window_set_buffers_format(..., int format)
477 * All buffers dequeued after this call will have the format specified.
478 *
479 * If the specified format is 0, the default buffer format will be used.
480 */
481static inline int native_window_set_buffers_format(
482        struct ANativeWindow* window,
483        int format)
484{
485    return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_FORMAT, format);
486}
487
488/*
489 * native_window_set_buffers_transform(..., int transform)
490 * All buffers queued after this call will be displayed transformed according
491 * to the transform parameter specified.
492 */
493static inline int native_window_set_buffers_transform(
494        struct ANativeWindow* window,
495        int transform)
496{
497    return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_TRANSFORM,
498            transform);
499}
500
501/*
502 * native_window_set_buffers_timestamp(..., int64_t timestamp)
503 * All buffers queued after this call will be associated with the timestamp
504 * parameter specified. If the timestamp is set to NATIVE_WINDOW_TIMESTAMP_AUTO
505 * (the default), timestamps will be generated automatically when queueBuffer is
506 * called. The timestamp is measured in nanoseconds, and is normally monotonically
507 * increasing. The timestamp should be unaffected by time-of-day adjustments,
508 * and for a camera should be strictly monotonic but for a media player may be
509 * reset when the position is set.
510 */
511static inline int native_window_set_buffers_timestamp(
512        struct ANativeWindow* window,
513        int64_t timestamp)
514{
515    return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP,
516            timestamp);
517}
518
519/*
520 * native_window_set_scaling_mode(..., int mode)
521 * All buffers queued after this call will be associated with the scaling mode
522 * specified.
523 */
524static inline int native_window_set_scaling_mode(
525        struct ANativeWindow* window,
526        int mode)
527{
528    return window->perform(window, NATIVE_WINDOW_SET_SCALING_MODE,
529            mode);
530}
531
532__END_DECLS
533
534#endif /* SYSTEM_CORE_INCLUDE_ANDROID_WINDOW_H */
535