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 #ifndef ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H
18 #define ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H
19
20 #include <stdint.h>
21 #include <sys/cdefs.h>
22
23 #include <hardware/gralloc.h>
24 #include <hardware/hardware.h>
25 #include <cutils/native_handle.h>
26
27 #include <hardware/hwcomposer_defs.h>
28
29 __BEGIN_DECLS
30
31 /*****************************************************************************/
32
33 // for compatibility
34 #define HWC_MODULE_API_VERSION HWC_MODULE_API_VERSION_0_1
35 #define HWC_DEVICE_API_VERSION HWC_DEVICE_API_VERSION_0_1
36 #define HWC_API_VERSION HWC_DEVICE_API_VERSION
37
38 /**
39 * The id of this module
40 */
41 #define HWC_HARDWARE_MODULE_ID "hwcomposer"
42
43 /**
44 * Name of the sensors device to open
45 */
46 #define HWC_HARDWARE_COMPOSER "composer"
47
48
49 struct hwc_composer_device;
50
51 /*
52 * availability: HWC_DEVICE_API_VERSION_0_3
53 *
54 * struct hwc_methods cannot be embedded in other structures as
55 * sizeof(struct hwc_methods) cannot be relied upon.
56 *
57 */
58 typedef struct hwc_methods {
59
60 /*************************************************************************
61 * HWC_DEVICE_API_VERSION_0_3
62 *************************************************************************/
63
64 /*
65 * eventControl(..., event, enabled)
66 * Enables or disables h/w composer events.
67 *
68 * eventControl can be called from any thread and takes effect
69 * immediately.
70 *
71 * Supported events are:
72 * HWC_EVENT_VSYNC
73 *
74 * returns -EINVAL if the "event" parameter is not one of the value above
75 * or if the "enabled" parameter is not 0 or 1.
76 */
77
78 int (*eventControl)(
79 struct hwc_composer_device* dev, int event, int enabled);
80
81 } hwc_methods_t;
82
83 typedef struct hwc_rect {
84 int left;
85 int top;
86 int right;
87 int bottom;
88 } hwc_rect_t;
89
90 typedef struct hwc_region {
91 size_t numRects;
92 hwc_rect_t const* rects;
93 } hwc_region_t;
94
95 typedef struct hwc_color {
96 uint8_t r;
97 uint8_t g;
98 uint8_t b;
99 uint8_t a;
100 } hwc_color_t;
101
102 typedef struct hwc_layer {
103 /*
104 * initially set to HWC_FRAMEBUFFER or HWC_BACKGROUND.
105 * HWC_FRAMEBUFFER
106 * indicates the layer will be drawn into the framebuffer
107 * using OpenGL ES.
108 * The HWC can toggle this value to HWC_OVERLAY, to indicate
109 * it will handle the layer.
110 *
111 * HWC_BACKGROUND
112 * indicates this is a special "background" layer. The only valid
113 * field is backgroundColor. HWC_BACKGROUND can only be used with
114 * HWC_API_VERSION >= 0.2
115 * The HWC can toggle this value to HWC_FRAMEBUFFER, to indicate
116 * it CANNOT handle the background color
117 *
118 */
119 int32_t compositionType;
120
121 /* see hwc_layer_t::hints above */
122 uint32_t hints;
123
124 /* see hwc_layer_t::flags above */
125 uint32_t flags;
126
127 union {
128 /* color of the background. hwc_color_t.a is ignored */
129 hwc_color_t backgroundColor;
130
131 struct {
132 /* handle of buffer to compose. This handle is guaranteed to have been
133 * allocated from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. If
134 * the layer's handle is unchanged across two consecutive prepare calls and
135 * the HWC_GEOMETRY_CHANGED flag is not set for the second call then the
136 * HWComposer implementation may assume that the contents of the buffer have
137 * not changed. */
138 buffer_handle_t handle;
139
140 /* transformation to apply to the buffer during composition */
141 uint32_t transform;
142
143 /* blending to apply during composition */
144 int32_t blending;
145
146 /* area of the source to consider, the origin is the top-left corner of
147 * the buffer */
148 hwc_rect_t sourceCrop;
149
150 /* where to composite the sourceCrop onto the display. The sourceCrop
151 * is scaled using linear filtering to the displayFrame. The origin is the
152 * top-left corner of the screen.
153 */
154 hwc_rect_t displayFrame;
155
156 /* visible region in screen space. The origin is the
157 * top-left corner of the screen.
158 * The visible region INCLUDES areas overlapped by a translucent layer.
159 */
160 hwc_region_t visibleRegionScreen;
161 };
162 };
163 } hwc_layer_t;
164
165
166 /*
167 * hwc_layer_list_t::flags values
168 */
169 enum {
170 /*
171 * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list
172 * passed to (*prepare)() has changed by more than just the buffer handles.
173 */
174 HWC_GEOMETRY_CHANGED = 0x00000001,
175 };
176
177 /*
178 * List of layers.
179 * The handle members of hwLayers elements must be unique.
180 */
181 typedef struct hwc_layer_list {
182 uint32_t flags;
183 size_t numHwLayers;
184 hwc_layer_t hwLayers[0];
185 } hwc_layer_list_t;
186
187 /* This represents a display, typically an EGLDisplay object */
188 typedef void* hwc_display_t;
189
190 /* This represents a surface, typically an EGLSurface object */
191 typedef void* hwc_surface_t;
192
193
194 /* see hwc_composer_device::registerProcs()
195 * Any of the callbacks can be NULL, in which case the corresponding
196 * functionality is not supported.
197 */
198 typedef struct hwc_procs {
199 /*
200 * (*invalidate)() triggers a screen refresh, in particular prepare and set
201 * will be called shortly after this call is made. Note that there is
202 * NO GUARANTEE that the screen refresh will happen after invalidate()
203 * returns (in particular, it could happen before).
204 * invalidate() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL and
205 * it is safe to call invalidate() from any of hwc_composer_device
206 * hooks, unless noted otherwise.
207 */
208 void (*invalidate)(struct hwc_procs* procs);
209
210 /*
211 * (*vsync)() is called by the h/w composer HAL when a vsync event is
212 * received and HWC_EVENT_VSYNC is enabled (see: hwc_event_control).
213 *
214 * the "zero" parameter must always be 0.
215 * the "timestamp" parameter is the system monotonic clock timestamp in
216 * nanosecond of when the vsync event happened.
217 *
218 * vsync() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL.
219 *
220 * It is expected that vsync() is called from a thread of at least
221 * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible,
222 * typically less than 0.5 ms.
223 *
224 * It is a (silent) error to have HWC_EVENT_VSYNC enabled when calling
225 * hwc_composer_device.set(..., 0, 0, 0) (screen off). The implementation
226 * can either stop or continue to process VSYNC events, but must not
227 * crash or cause other problems.
228 *
229 */
230 void (*vsync)(struct hwc_procs* procs, int zero, int64_t timestamp);
231 } hwc_procs_t;
232
233
234 /*****************************************************************************/
235
236 typedef struct hwc_module {
237 struct hw_module_t common;
238 } hwc_module_t;
239
240
241 typedef struct hwc_composer_device {
242 struct hw_device_t common;
243
244 /*
245 * (*prepare)() is called for each frame before composition and is used by
246 * SurfaceFlinger to determine what composition steps the HWC can handle.
247 *
248 * (*prepare)() can be called more than once, the last call prevails.
249 *
250 * The HWC responds by setting the compositionType field to either
251 * HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the composition for
252 * this layer is handled by SurfaceFlinger with OpenGL ES, in the later
253 * case, the HWC will have to handle this layer's composition.
254 *
255 * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the
256 * list's geometry has changed, that is, when more than just the buffer's
257 * handles have been updated. Typically this happens (but is not limited to)
258 * when a window is added, removed, resized or moved.
259 *
260 * a NULL list parameter or a numHwLayers of zero indicates that the
261 * entire composition will be handled by SurfaceFlinger with OpenGL ES.
262 *
263 * returns: 0 on success. An negative error code on error. If an error is
264 * returned, SurfaceFlinger will assume that none of the layer will be
265 * handled by the HWC.
266 */
267 int (*prepare)(struct hwc_composer_device *dev, hwc_layer_list_t* list);
268
269
270 /*
271 * (*set)() is used in place of eglSwapBuffers(), and assumes the same
272 * functionality, except it also commits the work list atomically with
273 * the actual eglSwapBuffers().
274 *
275 * The list parameter is guaranteed to be the same as the one returned
276 * from the last call to (*prepare)().
277 *
278 * When this call returns the caller assumes that:
279 *
280 * - the display will be updated in the near future with the content
281 * of the work list, without artifacts during the transition from the
282 * previous frame.
283 *
284 * - all objects are available for immediate access or destruction, in
285 * particular, hwc_region_t::rects data and hwc_layer_t::layer's buffer.
286 * Note that this means that immediately accessing (potentially from a
287 * different process) a buffer used in this call will not result in
288 * screen corruption, the driver must apply proper synchronization or
289 * scheduling (eg: block the caller, such as gralloc_module_t::lock(),
290 * OpenGL ES, Camera, Codecs, etc..., or schedule the caller's work
291 * after the buffer is freed from the actual composition).
292 *
293 * a NULL list parameter or a numHwLayers of zero indicates that the
294 * entire composition has been handled by SurfaceFlinger with OpenGL ES.
295 * In this case, (*set)() behaves just like eglSwapBuffers().
296 *
297 * dpy, sur, and list are set to NULL to indicate that the screen is
298 * turning off. This happens WITHOUT prepare() being called first.
299 * This is a good time to free h/w resources and/or power
300 * the relevant h/w blocks down.
301 *
302 * IMPORTANT NOTE: there is an implicit layer containing opaque black
303 * pixels behind all the layers in the list.
304 * It is the responsibility of the hwcomposer module to make
305 * sure black pixels are output (or blended from).
306 *
307 * returns: 0 on success. An negative error code on error:
308 * HWC_EGL_ERROR: eglGetError() will provide the proper error code
309 * Another code for non EGL errors.
310 *
311 */
312 int (*set)(struct hwc_composer_device *dev,
313 hwc_display_t dpy,
314 hwc_surface_t sur,
315 hwc_layer_list_t* list);
316 /*
317 * This field is OPTIONAL and can be NULL.
318 *
319 * If non NULL it will be called by SurfaceFlinger on dumpsys
320 */
321 void (*dump)(struct hwc_composer_device* dev, char *buff, int buff_len);
322
323 /*
324 * This field is OPTIONAL and can be NULL.
325 *
326 * (*registerProcs)() registers a set of callbacks the h/w composer HAL
327 * can later use. It is FORBIDDEN to call any of the callbacks from
328 * within registerProcs(). registerProcs() must save the hwc_procs_t pointer
329 * which is needed when calling a registered callback.
330 * Each call to registerProcs replaces the previous set of callbacks.
331 * registerProcs is called with NULL to unregister all callbacks.
332 *
333 * Any of the callbacks can be NULL, in which case the corresponding
334 * functionality is not supported.
335 */
336 void (*registerProcs)(struct hwc_composer_device* dev,
337 hwc_procs_t const* procs);
338
339 /*
340 * This field is OPTIONAL and can be NULL.
341 * availability: HWC_DEVICE_API_VERSION_0_2
342 *
343 * Used to retrieve information about the h/w composer
344 *
345 * Returns 0 on success or -errno on error.
346 */
347 int (*query)(struct hwc_composer_device* dev, int what, int* value);
348
349 /*
350 * Reserved for future use. Must be NULL.
351 */
352 void* reserved_proc[4];
353
354 /*
355 * This field is OPTIONAL and can be NULL.
356 * availability: HWC_DEVICE_API_VERSION_0_3
357 */
358 hwc_methods_t const *methods;
359
360 } hwc_composer_device_t;
361
362
363 /** convenience API for opening and closing a device */
364
hwc_open(const struct hw_module_t * module,hwc_composer_device_t ** device)365 static inline int hwc_open(const struct hw_module_t* module,
366 hwc_composer_device_t** device) {
367 return module->methods->open(module,
368 HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device);
369 }
370
hwc_close(hwc_composer_device_t * device)371 static inline int hwc_close(hwc_composer_device_t* device) {
372 return device->common.close(&device->common);
373 }
374
375
376 /*****************************************************************************/
377
378 __END_DECLS
379
380 #endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */
381