1 /*
2  * Copyright (C) 2010 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 /**
18  * @defgroup ANativeWindow Native Window
19  *
20  * ANativeWindow represents the producer end of an image queue.
21  * It is the C counterpart of the android.view.Surface object in Java,
22  * and can be converted both ways. Depending on the consumer, images
23  * submitted to ANativeWindow can be shown on the display or sent to
24  * other consumers, such as video encoders.
25  * @{
26  */
27 
28 /**
29  * @file native_window.h
30  * @brief API for accessing a native window.
31  */
32 
33 #ifndef ANDROID_NATIVE_WINDOW_H
34 #define ANDROID_NATIVE_WINDOW_H
35 
36 #include <stdint.h>
37 #include <sys/cdefs.h>
38 
39 #include <android/data_space.h>
40 #include <android/hardware_buffer.h>
41 #include <android/rect.h>
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46 
47 /**
48  * Legacy window pixel format names, kept for backwards compatibility.
49  * New code and APIs should use AHARDWAREBUFFER_FORMAT_*.
50  */
51 enum ANativeWindow_LegacyFormat {
52     // NOTE: these values must match the values from graphics/common/x.x/types.hal
53 
54     /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Alpha: 8 bits. **/
55     WINDOW_FORMAT_RGBA_8888          = AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
56     /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Unused: 8 bits. **/
57     WINDOW_FORMAT_RGBX_8888          = AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM,
58     /** Red: 5 bits, Green: 6 bits, Blue: 5 bits. **/
59     WINDOW_FORMAT_RGB_565            = AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM,
60 };
61 
62 /**
63  * Transforms that can be applied to buffers as they are displayed to a window.
64  *
65  * Supported transforms are any combination of horizontal mirror, vertical
66  * mirror, and clockwise 90 degree rotation, in that order. Rotations of 180
67  * and 270 degrees are made up of those basic transforms.
68  */
69 enum ANativeWindowTransform {
70     ANATIVEWINDOW_TRANSFORM_IDENTITY            = 0x00,
71     ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL   = 0x01,
72     ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL     = 0x02,
73     ANATIVEWINDOW_TRANSFORM_ROTATE_90           = 0x04,
74 
75     ANATIVEWINDOW_TRANSFORM_ROTATE_180          = ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL |
76                                                   ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL,
77     ANATIVEWINDOW_TRANSFORM_ROTATE_270          = ANATIVEWINDOW_TRANSFORM_ROTATE_180 |
78                                                   ANATIVEWINDOW_TRANSFORM_ROTATE_90,
79 };
80 
81 struct ANativeWindow;
82 /**
83  * Opaque type that provides access to a native window.
84  *
85  * A pointer can be obtained using {@link ANativeWindow_fromSurface()}.
86  */
87 typedef struct ANativeWindow ANativeWindow;
88 
89 /**
90  * Struct that represents a windows buffer.
91  *
92  * A pointer can be obtained using {@link ANativeWindow_lock()}.
93  */
94 typedef struct ANativeWindow_Buffer {
95     /// The number of pixels that are shown horizontally.
96     int32_t width;
97 
98     /// The number of pixels that are shown vertically.
99     int32_t height;
100 
101     /// The number of *pixels* that a line in the buffer takes in
102     /// memory. This may be >= width.
103     int32_t stride;
104 
105     /// The format of the buffer. One of AHardwareBuffer_Format.
106     int32_t format;
107 
108     /// The actual bits.
109     void* bits;
110 
111     /// Do not touch.
112     uint32_t reserved[6];
113 } ANativeWindow_Buffer;
114 
115 /**
116  * Acquire a reference on the given {@link ANativeWindow} object. This prevents the object
117  * from being deleted until the reference is removed.
118  */
119 void ANativeWindow_acquire(ANativeWindow* window);
120 
121 /**
122  * Remove a reference that was previously acquired with {@link ANativeWindow_acquire()}.
123  */
124 void ANativeWindow_release(ANativeWindow* window);
125 
126 /**
127  * Return the current width in pixels of the window surface.
128  *
129  * \return negative value on error.
130  */
131 int32_t ANativeWindow_getWidth(ANativeWindow* window);
132 
133 /**
134  * Return the current height in pixels of the window surface.
135  *
136  * \return a negative value on error.
137  */
138 int32_t ANativeWindow_getHeight(ANativeWindow* window);
139 
140 /**
141  * Return the current pixel format (AHARDWAREBUFFER_FORMAT_*) of the window surface.
142  *
143  * \return a negative value on error.
144  */
145 int32_t ANativeWindow_getFormat(ANativeWindow* window);
146 
147 /**
148  * Change the format and size of the window buffers.
149  *
150  * The width and height control the number of pixels in the buffers, not the
151  * dimensions of the window on screen. If these are different than the
152  * window's physical size, then its buffer will be scaled to match that size
153  * when compositing it to the screen. The width and height must be either both zero
154  * or both non-zero.
155  *
156  * For all of these parameters, if 0 is supplied then the window's base
157  * value will come back in force.
158  *
159  * \param width width of the buffers in pixels.
160  * \param height height of the buffers in pixels.
161  * \param format one of the AHardwareBuffer_Format constants.
162  * \return 0 for success, or a negative value on error.
163  */
164 int32_t ANativeWindow_setBuffersGeometry(ANativeWindow* window,
165         int32_t width, int32_t height, int32_t format);
166 
167 /**
168  * Lock the window's next drawing surface for writing.
169  * inOutDirtyBounds is used as an in/out parameter, upon entering the
170  * function, it contains the dirty region, that is, the region the caller
171  * intends to redraw. When the function returns, inOutDirtyBounds is updated
172  * with the actual area the caller needs to redraw -- this region is often
173  * extended by {@link ANativeWindow_lock}.
174  *
175  * \return 0 for success, or a negative value on error.
176  */
177 int32_t ANativeWindow_lock(ANativeWindow* window, ANativeWindow_Buffer* outBuffer,
178         ARect* inOutDirtyBounds);
179 
180 /**
181  * Unlock the window's drawing surface after previously locking it,
182  * posting the new buffer to the display.
183  *
184  * \return 0 for success, or a negative value on error.
185  */
186 int32_t ANativeWindow_unlockAndPost(ANativeWindow* window);
187 
188 #if __ANDROID_API__ >= 26
189 
190 /**
191  * Set a transform that will be applied to future buffers posted to the window.
192  *
193  * Available since API level 26.
194  *
195  * \param transform combination of {@link ANativeWindowTransform} flags
196  * \return 0 for success, or -EINVAL if \p transform is invalid
197  */
198 int32_t ANativeWindow_setBuffersTransform(ANativeWindow* window, int32_t transform) __INTRODUCED_IN(26);
199 
200 #endif // __ANDROID_API__ >= 26
201 
202 #if __ANDROID_API__ >= 28
203 
204 /**
205  * All buffers queued after this call will be associated with the dataSpace
206  * parameter specified.
207  *
208  * dataSpace specifies additional information about the buffer.
209  * For example, it can be used to convey the color space of the image data in
210  * the buffer, or it can be used to indicate that the buffers contain depth
211  * measurement data instead of color images. The default dataSpace is 0,
212  * ADATASPACE_UNKNOWN, unless it has been overridden by the producer.
213  *
214  * Available since API level 28.
215  *
216  * \param dataSpace data space of all buffers queued after this call.
217  * \return 0 for success, -EINVAL if window is invalid or the dataspace is not
218  * supported.
219  */
220 int32_t ANativeWindow_setBuffersDataSpace(ANativeWindow* window, int32_t dataSpace) __INTRODUCED_IN(28);
221 
222 /**
223  * Get the dataspace of the buffers in window.
224  *
225  * Available since API level 28.
226  *
227  * \return the dataspace of buffers in window, ADATASPACE_UNKNOWN is returned if
228  * dataspace is unknown, or -EINVAL if window is invalid.
229  */
230 int32_t ANativeWindow_getBuffersDataSpace(ANativeWindow* window) __INTRODUCED_IN(28);
231 
232 #endif // __ANDROID_API__ >= 28
233 
234 #if __ANDROID_API__ >= 30
235 
236 /** Compatibility value for ANativeWindow_setFrameRate. */
237 enum ANativeWindow_FrameRateCompatibility {
238     /**
239      * There are no inherent restrictions on the frame rate of this window. When
240      * the system selects a frame rate other than what the app requested, the
241      * app will be able to run at the system frame rate without requiring pull
242      * down. This value should be used when displaying game content, UIs, and
243      * anything that isn't video.
244      */
245     ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_DEFAULT = 0,
246     /**
247      * This window is being used to display content with an inherently fixed
248      * frame rate, e.g.\ a video that has a specific frame rate. When the system
249      * selects a frame rate other than what the app requested, the app will need
250      * to do pull down or use some other technique to adapt to the system's
251      * frame rate. The user experience is likely to be worse (e.g. more frame
252      * stuttering) than it would be if the system had chosen the app's requested
253      * frame rate. This value should be used for video content.
254      */
255     ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_FIXED_SOURCE = 1
256 };
257 
258 /**
259  * Sets the intended frame rate for this window.
260  *
261  * On devices that are capable of running the display at different refresh
262  * rates, the system may choose a display refresh rate to better match this
263  * window's frame rate. Usage of this API won't introduce frame rate throttling,
264  * or affect other aspects of the application's frame production
265  * pipeline. However, because the system may change the display refresh rate,
266  * calls to this function may result in changes to Choreographer callback
267  * timings, and changes to the time interval at which the system releases
268  * buffers back to the application.
269  *
270  * Note that this only has an effect for windows presented on the display. If
271  * this ANativeWindow is consumed by something other than the system compositor,
272  * e.g. a media codec, this call has no effect.
273  *
274  * Available since API level 30.
275  *
276  * \param frameRate The intended frame rate of this window, in frames per
277  * second. 0 is a special value that indicates the app will accept the system's
278  * choice for the display frame rate, which is the default behavior if this
279  * function isn't called. The frameRate param does <em>not</em> need to be a
280  * valid refresh rate for this device's display - e.g., it's fine to pass 30fps
281  * to a device that can only run the display at 60fps.
282  *
283  * \param compatibility The frame rate compatibility of this window. The
284  * compatibility value may influence the system's choice of display refresh
285  * rate. See the ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_* values for more info.
286  *
287  * \return 0 for success, -EINVAL if the window, frame rate, or compatibility
288  * value are invalid.
289  */
290 int32_t ANativeWindow_setFrameRate(ANativeWindow* window, float frameRate, int8_t compatibility)
291         __INTRODUCED_IN(30);
292 
293 /**
294  * Provides a hint to the window that buffers should be preallocated ahead of
295  * time. Note that the window implementation is not guaranteed to preallocate
296  * any buffers, for instance if an implementation disallows allocation of new
297  * buffers, or if there is insufficient memory in the system to preallocate
298  * additional buffers
299  *
300  * Available since API level 30.
301  */
302 void ANativeWindow_tryAllocateBuffers(ANativeWindow* window);
303 
304 #endif // __ANDROID_API__ >= 30
305 
306 #ifdef __cplusplus
307 };
308 #endif
309 
310 #endif // ANDROID_NATIVE_WINDOW_H
311 
312 /** @} */
313