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 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 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
