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 __BEGIN_DECLS 28 29 /*****************************************************************************/ 30 31 #define HWC_API_VERSION 1 32 33 /** 34 * The id of this module 35 */ 36 #define HWC_HARDWARE_MODULE_ID "hwcomposer" 37 38 /** 39 * Name of the sensors device to open 40 */ 41 #define HWC_HARDWARE_COMPOSER "composer" 42 43 44 enum { 45 /* hwc_composer_device_t::set failed in EGL */ 46 HWC_EGL_ERROR = -1 47 }; 48 49 /* 50 * hwc_layer_t::hints values 51 * Hints are set by the HAL and read by SurfaceFlinger 52 */ 53 enum { 54 /* 55 * HWC can set the HWC_HINT_TRIPLE_BUFFER hint to indicate to SurfaceFlinger 56 * that it should triple buffer this layer. Typically HWC does this when 57 * the layer will be unavailable for use for an extended period of time, 58 * e.g. if the display will be fetching data directly from the layer and 59 * the layer can not be modified until after the next set(). 60 */ 61 HWC_HINT_TRIPLE_BUFFER = 0x00000001, 62 63 /* 64 * HWC sets HWC_HINT_CLEAR_FB to tell SurfaceFlinger that it should clear the 65 * framebuffer with transparent pixels where this layer would be. 66 * SurfaceFlinger will only honor this flag when the layer has no blending 67 * 68 */ 69 HWC_HINT_CLEAR_FB = 0x00000002 70 }; 71 72 /* 73 * hwc_layer_t::flags values 74 * Flags are set by SurfaceFlinger and read by the HAL 75 */ 76 enum { 77 /* 78 * HWC_SKIP_LAYER is set by SurfaceFlnger to indicate that the HAL 79 * shall not consider this layer for composition as it will be handled 80 * by SurfaceFlinger (just as if compositionType was set to HWC_OVERLAY). 81 */ 82 HWC_SKIP_LAYER = 0x00000001, 83 }; 84 85 /* 86 * hwc_layer_t::compositionType values 87 */ 88 enum { 89 /* this layer is to be drawn into the framebuffer by SurfaceFlinger */ 90 HWC_FRAMEBUFFER = 0, 91 92 /* this layer will be handled in the HWC */ 93 HWC_OVERLAY = 1, 94 }; 95 96 /* 97 * hwc_layer_t::blending values 98 */ 99 enum { 100 /* no blending */ 101 HWC_BLENDING_NONE = 0x0100, 102 103 /* ONE / ONE_MINUS_SRC_ALPHA */ 104 HWC_BLENDING_PREMULT = 0x0105, 105 106 /* SRC_ALPHA / ONE_MINUS_SRC_ALPHA */ 107 HWC_BLENDING_COVERAGE = 0x0405 108 }; 109 110 /* 111 * hwc_layer_t::transform values 112 */ 113 enum { 114 /* flip source image horizontally */ 115 HWC_TRANSFORM_FLIP_H = HAL_TRANSFORM_FLIP_H, 116 /* flip source image vertically */ 117 HWC_TRANSFORM_FLIP_V = HAL_TRANSFORM_FLIP_V, 118 /* rotate source image 90 degrees clock-wise */ 119 HWC_TRANSFORM_ROT_90 = HAL_TRANSFORM_ROT_90, 120 /* rotate source image 180 degrees */ 121 HWC_TRANSFORM_ROT_180 = HAL_TRANSFORM_ROT_180, 122 /* rotate source image 270 degrees clock-wise */ 123 HWC_TRANSFORM_ROT_270 = HAL_TRANSFORM_ROT_270, 124 }; 125 126 typedef struct hwc_rect { 127 int left; 128 int top; 129 int right; 130 int bottom; 131 } hwc_rect_t; 132 133 typedef struct hwc_region { 134 size_t numRects; 135 hwc_rect_t const* rects; 136 } hwc_region_t; 137 138 typedef struct hwc_layer { 139 /* 140 * initially set to HWC_FRAMEBUFFER, indicates the layer will 141 * be drawn into the framebuffer using OpenGL ES. 142 * The HWC can toggle this value to HWC_OVERLAY, to indicate 143 * it will handle the layer. 144 */ 145 int32_t compositionType; 146 147 /* see hwc_layer_t::hints above */ 148 uint32_t hints; 149 150 /* see hwc_layer_t::flags above */ 151 uint32_t flags; 152 153 /* handle of buffer to compose. this handle is guaranteed to have been 154 * allocated with gralloc */ 155 buffer_handle_t handle; 156 157 /* transformation to apply to the buffer during composition */ 158 uint32_t transform; 159 160 /* blending to apply during composition */ 161 int32_t blending; 162 163 /* area of the source to consider, the origin is the top-left corner of 164 * the buffer */ 165 hwc_rect_t sourceCrop; 166 167 /* where to composite the sourceCrop onto the display. The sourceCrop 168 * is scaled using linear filtering to the displayFrame. The origin is the 169 * top-left corner of the screen. 170 */ 171 hwc_rect_t displayFrame; 172 173 /* visible region in screen space. The origin is the 174 * top-left corner of the screen. 175 * The visible region INCLUDES areas overlapped by a translucent layer. 176 */ 177 hwc_region_t visibleRegionScreen; 178 } hwc_layer_t; 179 180 181 /* 182 * hwc_layer_list_t::flags values 183 */ 184 enum { 185 /* 186 * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list 187 * passed to (*prepare)() has changed by more than just the buffer handles. 188 */ 189 HWC_GEOMETRY_CHANGED = 0x00000001, 190 }; 191 192 /* 193 * List of layers. 194 * The handle members of hwLayers elements must be unique. 195 */ 196 typedef struct hwc_layer_list { 197 uint32_t flags; 198 size_t numHwLayers; 199 hwc_layer_t hwLayers[0]; 200 } hwc_layer_list_t; 201 202 /* This represents a display, typically an EGLDisplay object */ 203 typedef void* hwc_display_t; 204 205 /* This represents a surface, typically an EGLSurface object */ 206 typedef void* hwc_surface_t; 207 208 209 /* see hwc_composer_device::registerProcs() 210 * Any of the callbacks can be NULL, in which case the corresponding 211 * functionality is not supported. 212 */ 213 typedef struct hwc_procs { 214 /* 215 * (*invalidate)() triggers a screen refresh, in particular prepare and set 216 * will be called shortly after this call is made. Note that there is 217 * NO GUARANTEE that the screen refresh will happen after invalidate() 218 * returns (in particular, it could happen before). 219 * invalidate() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL and 220 * it is safe to call invalidate() from any of hwc_composer_device 221 * hooks, unless noted otherwise. 222 */ 223 void (*invalidate)(struct hwc_procs* procs); 224 } hwc_procs_t; 225 226 227 /*****************************************************************************/ 228 229 typedef struct hwc_module { 230 struct hw_module_t common; 231 } hwc_module_t; 232 233 234 typedef struct hwc_composer_device { 235 struct hw_device_t common; 236 237 /* 238 * (*prepare)() is called for each frame before composition and is used by 239 * SurfaceFlinger to determine what composition steps the HWC can handle. 240 * 241 * (*prepare)() can be called more than once, the last call prevails. 242 * 243 * The HWC responds by setting the compositionType field to either 244 * HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the composition for 245 * this layer is handled by SurfaceFlinger with OpenGL ES, in the later 246 * case, the HWC will have to handle this layer's composition. 247 * 248 * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the 249 * list's geometry has changed, that is, when more than just the buffer's 250 * handles have been updated. Typically this happens (but is not limited to) 251 * when a window is added, removed, resized or moved. 252 * 253 * a NULL list parameter or a numHwLayers of zero indicates that the 254 * entire composition will be handled by SurfaceFlinger with OpenGL ES. 255 * 256 * returns: 0 on success. An negative error code on error. If an error is 257 * returned, SurfaceFlinger will assume that none of the layer will be 258 * handled by the HWC. 259 */ 260 int (*prepare)(struct hwc_composer_device *dev, hwc_layer_list_t* list); 261 262 263 /* 264 * (*set)() is used in place of eglSwapBuffers(), and assumes the same 265 * functionality, except it also commits the work list atomically with 266 * the actual eglSwapBuffers(). 267 * 268 * The list parameter is guaranteed to be the same as the one returned 269 * from the last call to (*prepare)(). 270 * 271 * When this call returns the caller assumes that: 272 * 273 * - the display will be updated in the near future with the content 274 * of the work list, without artifacts during the transition from the 275 * previous frame. 276 * 277 * - all objects are available for immediate access or destruction, in 278 * particular, hwc_region_t::rects data and hwc_layer_t::layer's buffer. 279 * Note that this means that immediately accessing (potentially from a 280 * different process) a buffer used in this call will not result in 281 * screen corruption, the driver must apply proper synchronization or 282 * scheduling (eg: block the caller, such as gralloc_module_t::lock(), 283 * OpenGL ES, Camera, Codecs, etc..., or schedule the caller's work 284 * after the buffer is freed from the actual composition). 285 * 286 * a NULL list parameter or a numHwLayers of zero indicates that the 287 * entire composition has been handled by SurfaceFlinger with OpenGL ES. 288 * In this case, (*set)() behaves just like eglSwapBuffers(). 289 * 290 * dpy, sur, and list are set to NULL to indicate that the screen is 291 * turning off. This happens WITHOUT prepare() being called first. 292 * This is a good time to free h/w resources and/or power 293 * the relevant h/w blocks down. 294 * 295 * IMPORTANT NOTE: there is an implicit layer containing opaque black 296 * pixels behind all the layers in the list. 297 * It is the responsibility of the hwcomposer module to make 298 * sure black pixels are output (or blended from). 299 * 300 * returns: 0 on success. An negative error code on error: 301 * HWC_EGL_ERROR: eglGetError() will provide the proper error code 302 * Another code for non EGL errors. 303 * 304 */ 305 int (*set)(struct hwc_composer_device *dev, 306 hwc_display_t dpy, 307 hwc_surface_t sur, 308 hwc_layer_list_t* list); 309 /* 310 * This hook is OPTIONAL. 311 * 312 * If non NULL it will be called by SurfaceFlinger on dumpsys 313 */ 314 void (*dump)(struct hwc_composer_device* dev, char *buff, int buff_len); 315 316 /* 317 * This hook is OPTIONAL. 318 * 319 * (*registerProcs)() registers a set of callbacks the h/w composer HAL 320 * can later use. It is FORBIDDEN to call any of the callbacks from 321 * within registerProcs(). registerProcs() must save the hwc_procs_t pointer 322 * which is needed when calling a registered callback. 323 * Each call to registerProcs replaces the previous set of callbacks. 324 * registerProcs is called with NULL to unregister all callbacks. 325 * 326 * Any of the callbacks can be NULL, in which case the corresponding 327 * functionality is not supported. 328 */ 329 void (*registerProcs)(struct hwc_composer_device* dev, 330 hwc_procs_t const* procs); 331 332 void* reserved_proc[6]; 333 334 } hwc_composer_device_t; 335 336 337 /** convenience API for opening and closing a device */ 338 339 static inline int hwc_open(const struct hw_module_t* module, 340 hwc_composer_device_t** device) { 341 return module->methods->open(module, 342 HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device); 343 } 344 345 static inline int hwc_close(hwc_composer_device_t* device) { 346 return device->common.close(&device->common); 347 } 348 349 350 /*****************************************************************************/ 351 352 __END_DECLS 353 354 #endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */ 355
