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.
247 */
248 ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_DEFAULT = 0,
249 /**
250 * This window is being used to display content with an inherently fixed
251 * frame rate, e.g.\ a video that has a specific frame rate. When the system
252 * selects a frame rate other than what the app requested, the app will need
253 * to do pull down or use some other technique to adapt to the system's
254 * frame rate. The user experience is likely to be worse (e.g. more frame
255 * stuttering) than it would be if the system had chosen the app's requested
256 * frame rate. This value should be used for video content.
257 */
258 ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_FIXED_SOURCE = 1,
259
260 /**
261 * The window requests a frame rate that is greater than or equal to the specified frame rate.
262 * This value should be used for UIs, animations, scrolling, and anything that is not a game
263 * or video.
264 */
265 ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_GTE = 2
266 };
267
268 /**
269 * Same as ANativeWindow_setFrameRateWithChangeStrategy(window, frameRate, compatibility,
270 * ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS).
271 *
272 * See ANativeWindow_setFrameRateWithChangeStrategy().
273 *
274 * Available since API level 30.
275 */
276 int32_t ANativeWindow_setFrameRate(ANativeWindow* window, float frameRate, int8_t compatibility)
277 __INTRODUCED_IN(30);
278
279 /**
280 * Provides a hint to the window that buffers should be preallocated ahead of
281 * time. Note that the window implementation is not guaranteed to preallocate
282 * any buffers, for instance if an implementation disallows allocation of new
283 * buffers, or if there is insufficient memory in the system to preallocate
284 * additional buffers
285 *
286 * Available since API level 30.
287 */
288 void ANativeWindow_tryAllocateBuffers(ANativeWindow* window) __INTRODUCED_IN(30);
289
290 /** Change frame rate strategy value for ANativeWindow_setFrameRate. */
291 enum ANativeWindow_ChangeFrameRateStrategy {
292 /**
293 * Change the frame rate only if the transition is going to be seamless.
294 */
295 ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS = 0,
296 /**
297 * Change the frame rate even if the transition is going to be non-seamless,
298 * i.e. with visual interruptions for the user.
299 */
300 ANATIVEWINDOW_CHANGE_FRAME_RATE_ALWAYS = 1
301 } __INTRODUCED_IN(31);
302
303 /**
304 * Sets the intended frame rate for this window.
305 *
306 * On devices that are capable of running the display at different refresh
307 * rates, the system may choose a display refresh rate to better match this
308 * window's frame rate. Usage of this API won't introduce frame rate throttling,
309 * or affect other aspects of the application's frame production
310 * pipeline. However, because the system may change the display refresh rate,
311 * calls to this function may result in changes to Choreographer callback
312 * timings, and changes to the time interval at which the system releases
313 * buffers back to the application.
314 *
315 * Note that this only has an effect for windows presented on the display. If
316 * this ANativeWindow is consumed by something other than the system compositor,
317 * e.g. a media codec, this call has no effect.
318 *
319 * You can register for changes in the refresh rate using
320 * \a AChoreographer_registerRefreshRateCallback.
321 *
322 * See ANativeWindow_clearFrameRate().
323 *
324 * Available since API level 31.
325 *
326 * \param window pointer to an ANativeWindow object.
327 *
328 * \param frameRate The intended frame rate of this window, in frames per
329 * second. 0 is a special value that indicates the app will accept the system's
330 * choice for the display frame rate, which is the default behavior if this
331 * function isn't called. The frameRate param does <em>not</em> need to be a
332 * valid refresh rate for this device's display - e.g., it's fine to pass 30fps
333 * to a device that can only run the display at 60fps.
334 *
335 * \param compatibility The frame rate compatibility of this window. The
336 * compatibility value may influence the system's choice of display refresh
337 * rate. See the ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_* values for more info.
338 * This parameter is ignored when frameRate is 0.
339 *
340 * \param changeFrameRateStrategy Whether display refresh rate transitions caused by this
341 * window should be seamless.
342 * A seamless transition is one that doesn't have any visual interruptions, such as a black
343 * screen for a second or two. See the ANATIVEWINDOW_CHANGE_FRAME_RATE_* values.
344 * This parameter is ignored when frameRate is 0.
345 *
346 * \return 0 for success, -EINVAL if the window, frame rate, or compatibility
347 * value are invalid.
348 */
349 int32_t ANativeWindow_setFrameRateWithChangeStrategy(ANativeWindow* window, float frameRate,
350 int8_t compatibility, int8_t changeFrameRateStrategy)
351 __INTRODUCED_IN(31);
352
353 /**
354 * Clears the frame rate which is set for this window.
355 *
356 * This is equivalent to calling
357 * ANativeWindow_setFrameRateWithChangeStrategy(window, 0, compatibility, changeFrameRateStrategy).
358 *
359 * Usage of this API won't introduce frame rate throttling,
360 * or affect other aspects of the application's frame production
361 * pipeline. However, because the system may change the display refresh rate,
362 * calls to this function may result in changes to Choreographer callback
363 * timings, and changes to the time interval at which the system releases
364 * buffers back to the application.
365 *
366 * Note that this only has an effect for windows presented on the display. If
367 * this ANativeWindow is consumed by something other than the system compositor,
368 * e.g. a media codec, this call has no effect.
369 *
370 * You can register for changes in the refresh rate using
371 * \a AChoreographer_registerRefreshRateCallback.
372 *
373 * See ANativeWindow_setFrameRateWithChangeStrategy().
374 *
375 * Available since API level 31.
376 *
377 * \param window pointer to an ANativeWindow object.
378 *
379 * \return 0 for success, -EINVAL if the window value is invalid.
380 */
ANativeWindow_clearFrameRate(ANativeWindow * window)381 inline int32_t ANativeWindow_clearFrameRate(ANativeWindow* window) __INTRODUCED_IN(31) {
382 return ANativeWindow_setFrameRateWithChangeStrategy(window, 0,
383 ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_DEFAULT,
384 ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS);
385 }
386
387 #ifdef __cplusplus
388 }
389 #endif
390
391 #endif // ANDROID_NATIVE_WINDOW_H
392
393 /** @} */
394