2 * Copyright (C) 2010 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @defgroup ANativeWindow Native Window
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.
29 * @file native_window.h
30 * @brief API for accessing a native window.
33 #ifndef ANDROID_NATIVE_WINDOW_H
34 #define ANDROID_NATIVE_WINDOW_H
36 #include <sys/cdefs.h>
38 #include <android/data_space.h>
39 #include <android/hardware_buffer.h>
40 #include <android/rect.h>
47 * Legacy window pixel format names, kept for backwards compatibility.
48 * New code and APIs should use AHARDWAREBUFFER_FORMAT_*.
50 enum ANativeWindow_LegacyFormat
{
51 // NOTE: these values must match the values from graphics/common/x.x/types.hal
53 /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Alpha: 8 bits. **/
54 WINDOW_FORMAT_RGBA_8888
= AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM
,
55 /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Unused: 8 bits. **/
56 WINDOW_FORMAT_RGBX_8888
= AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM
,
57 /** Red: 5 bits, Green: 6 bits, Blue: 5 bits. **/
58 WINDOW_FORMAT_RGB_565
= AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM
,
62 * Transforms that can be applied to buffers as they are displayed to a window.
64 * Supported transforms are any combination of horizontal mirror, vertical
65 * mirror, and clockwise 90 degree rotation, in that order. Rotations of 180
66 * and 270 degrees are made up of those basic transforms.
68 enum ANativeWindowTransform
{
69 ANATIVEWINDOW_TRANSFORM_IDENTITY
= 0x00,
70 ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL
= 0x01,
71 ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL
= 0x02,
72 ANATIVEWINDOW_TRANSFORM_ROTATE_90
= 0x04,
74 ANATIVEWINDOW_TRANSFORM_ROTATE_180
= ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL
|
75 ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL
,
76 ANATIVEWINDOW_TRANSFORM_ROTATE_270
= ANATIVEWINDOW_TRANSFORM_ROTATE_180
|
77 ANATIVEWINDOW_TRANSFORM_ROTATE_90
,
82 * Opaque type that provides access to a native window.
84 * A pointer can be obtained using {@link ANativeWindow_fromSurface()}.
86 typedef struct ANativeWindow ANativeWindow
;
89 * Struct that represents a windows buffer.
91 * A pointer can be obtained using {@link ANativeWindow_lock()}.
93 typedef struct ANativeWindow_Buffer
{
94 /// The number of pixels that are shown horizontally.
97 /// The number of pixels that are shown vertically.
100 /// The number of *pixels* that a line in the buffer takes in
101 /// memory. This may be >= width.
104 /// The format of the buffer. One of AHardwareBuffer_Format.
111 uint32_t reserved
[6];
112 } ANativeWindow_Buffer
;
115 * Acquire a reference on the given {@link ANativeWindow} object. This prevents the object
116 * from being deleted until the reference is removed.
118 void ANativeWindow_acquire(ANativeWindow
* window
);
121 * Remove a reference that was previously acquired with {@link ANativeWindow_acquire()}.
123 void ANativeWindow_release(ANativeWindow
* window
);
126 * Return the current width in pixels of the window surface.
128 * \return negative value on error.
130 int32_t ANativeWindow_getWidth(ANativeWindow
* window
);
133 * Return the current height in pixels of the window surface.
135 * \return a negative value on error.
137 int32_t ANativeWindow_getHeight(ANativeWindow
* window
);
140 * Return the current pixel format (AHARDWAREBUFFER_FORMAT_*) of the window surface.
142 * \return a negative value on error.
144 int32_t ANativeWindow_getFormat(ANativeWindow
* window
);
147 * Change the format and size of the window buffers.
149 * The width and height control the number of pixels in the buffers, not the
150 * dimensions of the window on screen. If these are different than the
151 * window's physical size, then its buffer will be scaled to match that size
152 * when compositing it to the screen. The width and height must be either both zero
155 * For all of these parameters, if 0 is supplied then the window's base
156 * value will come back in force.
158 * \param width width of the buffers in pixels.
159 * \param height height of the buffers in pixels.
160 * \param format one of the AHardwareBuffer_Format constants.
161 * \return 0 for success, or a negative value on error.
163 int32_t ANativeWindow_setBuffersGeometry(ANativeWindow
* window
,
164 int32_t width
, int32_t height
, int32_t format
);
167 * Lock the window's next drawing surface for writing.
168 * inOutDirtyBounds is used as an in/out parameter, upon entering the
169 * function, it contains the dirty region, that is, the region the caller
170 * intends to redraw. When the function returns, inOutDirtyBounds is updated
171 * with the actual area the caller needs to redraw -- this region is often
172 * extended by {@link ANativeWindow_lock}.
174 * \return 0 for success, or a negative value on error.
176 int32_t ANativeWindow_lock(ANativeWindow
* window
, ANativeWindow_Buffer
* outBuffer
,
177 ARect
* inOutDirtyBounds
);
180 * Unlock the window's drawing surface after previously locking it,
181 * posting the new buffer to the display.
183 * \return 0 for success, or a negative value on error.
185 int32_t ANativeWindow_unlockAndPost(ANativeWindow
* window
);
187 #if __ANDROID_API__ >= 26
190 * Set a transform that will be applied to future buffers posted to the window.
192 * Available since API level 26.
194 * \param transform combination of {@link ANativeWindowTransform} flags
195 * \return 0 for success, or -EINVAL if \p transform is invalid
197 int32_t ANativeWindow_setBuffersTransform(ANativeWindow
* window
, int32_t transform
) __INTRODUCED_IN(26);
199 #endif // __ANDROID_API__ >= 26
201 #if __ANDROID_API__ >= 28
204 * All buffers queued after this call will be associated with the dataSpace
205 * parameter specified.
207 * dataSpace specifies additional information about the buffer.
208 * For example, it can be used to convey the color space of the image data in
209 * the buffer, or it can be used to indicate that the buffers contain depth
210 * measurement data instead of color images. The default dataSpace is 0,
211 * ADATASPACE_UNKNOWN, unless it has been overridden by the producer.
213 * Available since API level 28.
215 * \param dataSpace data space of all buffers queued after this call.
216 * \return 0 for success, -EINVAL if window is invalid or the dataspace is not
219 int32_t ANativeWindow_setBuffersDataSpace(ANativeWindow
* window
, int32_t dataSpace
) __INTRODUCED_IN(28);
222 * Get the dataspace of the buffers in window.
224 * Available since API level 28.
226 * \return the dataspace of buffers in window, ADATASPACE_UNKNOWN is returned if
227 * dataspace is unknown, or -EINVAL if window is invalid.
229 int32_t ANativeWindow_getBuffersDataSpace(ANativeWindow
* window
) __INTRODUCED_IN(28);
231 #endif // __ANDROID_API__ >= 28
237 #endif // ANDROID_NATIVE_WINDOW_H