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