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.
17 /* This header contains deprecated HWCv0 interface declarations. Don't include
18 * this header directly; it will be included by <hardware/hwcomposer.h> unless
19 * HWC_REMOVE_DEPRECATED_VERSIONS is defined to non-zero.
21 #ifndef ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H
22 #error "This header should only be included by hardware/hwcomposer.h"
25 #ifndef ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_V0_H
26 #define ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_V0_H
28 struct hwc_composer_device
;
31 * availability: HWC_DEVICE_API_VERSION_0_3
33 * struct hwc_methods cannot be embedded in other structures as
34 * sizeof(struct hwc_methods) cannot be relied upon.
37 typedef struct hwc_methods
{
39 /*************************************************************************
40 * HWC_DEVICE_API_VERSION_0_3
41 *************************************************************************/
44 * eventControl(..., event, enabled)
45 * Enables or disables h/w composer events.
47 * eventControl can be called from any thread and takes effect
50 * Supported events are:
53 * returns -EINVAL if the "event" parameter is not one of the value above
54 * or if the "enabled" parameter is not 0 or 1.
58 struct hwc_composer_device
* dev
, int event
, int enabled
);
62 typedef struct hwc_layer
{
64 * initially set to HWC_FRAMEBUFFER or HWC_BACKGROUND.
66 * indicates the layer will be drawn into the framebuffer
68 * The HWC can toggle this value to HWC_OVERLAY, to indicate
69 * it will handle the layer.
72 * indicates this is a special "background" layer. The only valid
73 * field is backgroundColor. HWC_BACKGROUND can only be used with
74 * HWC_API_VERSION >= 0.2
75 * The HWC can toggle this value to HWC_FRAMEBUFFER, to indicate
76 * it CANNOT handle the background color
79 int32_t compositionType
;
81 /* see hwc_layer_t::hints above */
84 /* see hwc_layer_t::flags above */
88 /* color of the background. hwc_color_t.a is ignored */
89 hwc_color_t backgroundColor
;
92 /* handle of buffer to compose. This handle is guaranteed to have been
93 * allocated from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. If
94 * the layer's handle is unchanged across two consecutive prepare calls and
95 * the HWC_GEOMETRY_CHANGED flag is not set for the second call then the
96 * HWComposer implementation may assume that the contents of the buffer have
98 buffer_handle_t handle
;
100 /* transformation to apply to the buffer during composition */
103 /* blending to apply during composition */
106 /* area of the source to consider, the origin is the top-left corner of
108 hwc_rect_t sourceCrop
;
110 /* where to composite the sourceCrop onto the display. The sourceCrop
111 * is scaled using linear filtering to the displayFrame. The origin is the
112 * top-left corner of the screen.
114 hwc_rect_t displayFrame
;
116 /* visible region in screen space. The origin is the
117 * top-left corner of the screen.
118 * The visible region INCLUDES areas overlapped by a translucent layer.
120 hwc_region_t visibleRegionScreen
;
127 * The handle members of hwLayers elements must be unique.
129 typedef struct hwc_layer_list
{
132 hwc_layer_t hwLayers
[0];
135 /*****************************************************************************/
137 typedef struct hwc_composer_device
{
138 struct hw_device_t common
;
141 * (*prepare)() is called for each frame before composition and is used by
142 * SurfaceFlinger to determine what composition steps the HWC can handle.
144 * (*prepare)() can be called more than once, the last call prevails.
146 * The HWC responds by setting the compositionType field to either
147 * HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the composition for
148 * this layer is handled by SurfaceFlinger with OpenGL ES, in the later
149 * case, the HWC will have to handle this layer's composition.
151 * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the
152 * list's geometry has changed, that is, when more than just the buffer's
153 * handles have been updated. Typically this happens (but is not limited to)
154 * when a window is added, removed, resized or moved.
156 * a NULL list parameter or a numHwLayers of zero indicates that the
157 * entire composition will be handled by SurfaceFlinger with OpenGL ES.
159 * returns: 0 on success. An negative error code on error. If an error is
160 * returned, SurfaceFlinger will assume that none of the layer will be
161 * handled by the HWC.
163 int (*prepare
)(struct hwc_composer_device
*dev
, hwc_layer_list_t
* list
);
166 * (*set)() is used in place of eglSwapBuffers(), and assumes the same
167 * functionality, except it also commits the work list atomically with
168 * the actual eglSwapBuffers().
170 * The list parameter is guaranteed to be the same as the one returned
171 * from the last call to (*prepare)().
173 * When this call returns the caller assumes that:
175 * - the display will be updated in the near future with the content
176 * of the work list, without artifacts during the transition from the
179 * - all objects are available for immediate access or destruction, in
180 * particular, hwc_region_t::rects data and hwc_layer_t::layer's buffer.
181 * Note that this means that immediately accessing (potentially from a
182 * different process) a buffer used in this call will not result in
183 * screen corruption, the driver must apply proper synchronization or
184 * scheduling (eg: block the caller, such as gralloc_module_t::lock(),
185 * OpenGL ES, Camera, Codecs, etc..., or schedule the caller's work
186 * after the buffer is freed from the actual composition).
188 * a NULL list parameter or a numHwLayers of zero indicates that the
189 * entire composition has been handled by SurfaceFlinger with OpenGL ES.
190 * In this case, (*set)() behaves just like eglSwapBuffers().
192 * dpy, sur, and list are set to NULL to indicate that the screen is
193 * turning off. This happens WITHOUT prepare() being called first.
194 * This is a good time to free h/w resources and/or power
195 * the relevant h/w blocks down.
197 * IMPORTANT NOTE: there is an implicit layer containing opaque black
198 * pixels behind all the layers in the list.
199 * It is the responsibility of the hwcomposer module to make
200 * sure black pixels are output (or blended from).
202 * returns: 0 on success. An negative error code on error:
203 * HWC_EGL_ERROR: eglGetError() will provide the proper error code
204 * Another code for non EGL errors.
207 int (*set
)(struct hwc_composer_device
*dev
,
210 hwc_layer_list_t
* list
);
213 * This field is OPTIONAL and can be NULL.
215 * If non NULL it will be called by SurfaceFlinger on dumpsys
217 void (*dump
)(struct hwc_composer_device
* dev
, char *buff
, int buff_len
);
220 * This field is OPTIONAL and can be NULL.
222 * (*registerProcs)() registers a set of callbacks the h/w composer HAL
223 * can later use. It is FORBIDDEN to call any of the callbacks from
224 * within registerProcs(). registerProcs() must save the hwc_procs_t pointer
225 * which is needed when calling a registered callback.
226 * Each call to registerProcs replaces the previous set of callbacks.
227 * registerProcs is called with NULL to unregister all callbacks.
229 * Any of the callbacks can be NULL, in which case the corresponding
230 * functionality is not supported.
232 void (*registerProcs
)(struct hwc_composer_device
* dev
,
233 hwc_procs_t
const* procs
);
236 * This field is OPTIONAL and can be NULL.
237 * availability: HWC_DEVICE_API_VERSION_0_2
239 * Used to retrieve information about the h/w composer
241 * Returns 0 on success or -errno on error.
243 int (*query
)(struct hwc_composer_device
* dev
, int what
, int* value
);
246 * Reserved for future use. Must be NULL.
248 void* reserved_proc
[4];
251 * This field is OPTIONAL and can be NULL.
252 * availability: HWC_DEVICE_API_VERSION_0_3
254 hwc_methods_t
const *methods
;
256 } hwc_composer_device_t
;
258 /** convenience API for opening and closing a device */
260 static inline int hwc_open(const struct hw_module_t
* module
,
261 hwc_composer_device_t
** device
) {
262 return module
->methods
->open(module
,
263 HWC_HARDWARE_COMPOSER
, (struct hw_device_t
**)device
);
266 static inline int hwc_close(hwc_composer_device_t
* device
) {
267 return device
->common
.close(&device
->common
);
270 /*****************************************************************************/
272 #endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_V0_H */