Commit | Line | Data |
---|---|---|
1e494cf4 JB |
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 | /* 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. | |
20 | */ | |
21 | #ifndef ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H | |
22 | #error "This header should only be included by hardware/hwcomposer.h" | |
23 | #endif | |
24 | ||
25 | #ifndef ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_V0_H | |
26 | #define ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_V0_H | |
27 | ||
28 | struct hwc_composer_device; | |
29 | ||
30 | /* | |
31 | * availability: HWC_DEVICE_API_VERSION_0_3 | |
32 | * | |
33 | * struct hwc_methods cannot be embedded in other structures as | |
34 | * sizeof(struct hwc_methods) cannot be relied upon. | |
35 | * | |
36 | */ | |
37 | typedef struct hwc_methods { | |
38 | ||
39 | /************************************************************************* | |
40 | * HWC_DEVICE_API_VERSION_0_3 | |
41 | *************************************************************************/ | |
42 | ||
43 | /* | |
44 | * eventControl(..., event, enabled) | |
45 | * Enables or disables h/w composer events. | |
46 | * | |
47 | * eventControl can be called from any thread and takes effect | |
48 | * immediately. | |
49 | * | |
50 | * Supported events are: | |
51 | * HWC_EVENT_VSYNC | |
52 | * | |
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. | |
55 | */ | |
56 | ||
57 | int (*eventControl)( | |
58 | struct hwc_composer_device* dev, int event, int enabled); | |
59 | ||
60 | } hwc_methods_t; | |
61 | ||
62 | typedef struct hwc_layer { | |
63 | /* | |
64 | * initially set to HWC_FRAMEBUFFER or HWC_BACKGROUND. | |
65 | * HWC_FRAMEBUFFER | |
66 | * indicates the layer will be drawn into the framebuffer | |
67 | * using OpenGL ES. | |
68 | * The HWC can toggle this value to HWC_OVERLAY, to indicate | |
69 | * it will handle the layer. | |
70 | * | |
71 | * HWC_BACKGROUND | |
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 | |
77 | * | |
78 | */ | |
79 | int32_t compositionType; | |
80 | ||
81 | /* see hwc_layer_t::hints above */ | |
82 | uint32_t hints; | |
83 | ||
84 | /* see hwc_layer_t::flags above */ | |
85 | uint32_t flags; | |
86 | ||
87 | union { | |
88 | /* color of the background. hwc_color_t.a is ignored */ | |
89 | hwc_color_t backgroundColor; | |
90 | ||
91 | struct { | |
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 | |
97 | * not changed. */ | |
98 | buffer_handle_t handle; | |
99 | ||
100 | /* transformation to apply to the buffer during composition */ | |
101 | uint32_t transform; | |
102 | ||
103 | /* blending to apply during composition */ | |
104 | int32_t blending; | |
105 | ||
106 | /* area of the source to consider, the origin is the top-left corner of | |
107 | * the buffer */ | |
108 | hwc_rect_t sourceCrop; | |
109 | ||
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. | |
113 | */ | |
114 | hwc_rect_t displayFrame; | |
115 | ||
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. | |
119 | */ | |
120 | hwc_region_t visibleRegionScreen; | |
121 | }; | |
122 | }; | |
123 | } hwc_layer_t; | |
124 | ||
125 | /* | |
126 | * List of layers. | |
127 | * The handle members of hwLayers elements must be unique. | |
128 | */ | |
129 | typedef struct hwc_layer_list { | |
130 | uint32_t flags; | |
131 | size_t numHwLayers; | |
132 | hwc_layer_t hwLayers[0]; | |
133 | } hwc_layer_list_t; | |
134 | ||
135 | /*****************************************************************************/ | |
136 | ||
137 | typedef struct hwc_composer_device { | |
138 | struct hw_device_t common; | |
139 | ||
140 | /* | |
141 | * (*prepare)() is called for each frame before composition and is used by | |
142 | * SurfaceFlinger to determine what composition steps the HWC can handle. | |
143 | * | |
144 | * (*prepare)() can be called more than once, the last call prevails. | |
145 | * | |
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. | |
150 | * | |
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. | |
155 | * | |
156 | * a NULL list parameter or a numHwLayers of zero indicates that the | |
157 | * entire composition will be handled by SurfaceFlinger with OpenGL ES. | |
158 | * | |
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. | |
162 | */ | |
163 | int (*prepare)(struct hwc_composer_device *dev, hwc_layer_list_t* list); | |
164 | ||
165 | /* | |
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(). | |
169 | * | |
170 | * The list parameter is guaranteed to be the same as the one returned | |
171 | * from the last call to (*prepare)(). | |
172 | * | |
173 | * When this call returns the caller assumes that: | |
174 | * | |
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 | |
177 | * previous frame. | |
178 | * | |
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). | |
187 | * | |
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(). | |
191 | * | |
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. | |
196 | * | |
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). | |
201 | * | |
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. | |
205 | * | |
206 | */ | |
207 | int (*set)(struct hwc_composer_device *dev, | |
208 | hwc_display_t dpy, | |
209 | hwc_surface_t sur, | |
210 | hwc_layer_list_t* list); | |
211 | ||
212 | /* | |
213 | * This field is OPTIONAL and can be NULL. | |
214 | * | |
215 | * If non NULL it will be called by SurfaceFlinger on dumpsys | |
216 | */ | |
217 | void (*dump)(struct hwc_composer_device* dev, char *buff, int buff_len); | |
218 | ||
219 | /* | |
220 | * This field is OPTIONAL and can be NULL. | |
221 | * | |
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. | |
228 | * | |
229 | * Any of the callbacks can be NULL, in which case the corresponding | |
230 | * functionality is not supported. | |
231 | */ | |
232 | void (*registerProcs)(struct hwc_composer_device* dev, | |
233 | hwc_procs_t const* procs); | |
234 | ||
235 | /* | |
236 | * This field is OPTIONAL and can be NULL. | |
237 | * availability: HWC_DEVICE_API_VERSION_0_2 | |
238 | * | |
239 | * Used to retrieve information about the h/w composer | |
240 | * | |
241 | * Returns 0 on success or -errno on error. | |
242 | */ | |
243 | int (*query)(struct hwc_composer_device* dev, int what, int* value); | |
244 | ||
245 | /* | |
246 | * Reserved for future use. Must be NULL. | |
247 | */ | |
248 | void* reserved_proc[4]; | |
249 | ||
250 | /* | |
251 | * This field is OPTIONAL and can be NULL. | |
252 | * availability: HWC_DEVICE_API_VERSION_0_3 | |
253 | */ | |
254 | hwc_methods_t const *methods; | |
255 | ||
256 | } hwc_composer_device_t; | |
257 | ||
258 | /** convenience API for opening and closing a device */ | |
259 | ||
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); | |
264 | } | |
265 | ||
266 | static inline int hwc_close(hwc_composer_device_t* device) { | |
267 | return device->common.close(&device->common); | |
268 | } | |
269 | ||
270 | /*****************************************************************************/ | |
271 | ||
272 | #endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_V0_H */ |