hwcomposer.h revision fb410365ca67d36d4c81d7826712c6a05437612f
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 44enum { 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 */ 53enum { 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 */ 76enum { 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 */ 88enum { 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 */ 99enum { 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 */ 113enum { 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 126typedef struct hwc_rect { 127 int left; 128 int top; 129 int right; 130 int bottom; 131} hwc_rect_t; 132 133typedef struct hwc_region { 134 size_t numRects; 135 hwc_rect_t const* rects; 136} hwc_region_t; 137 138typedef 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 */ 184enum { 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 */ 196typedef 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 */ 203typedef void* hwc_display_t; 204 205/* This represents a surface, typically an EGLSurface object */ 206typedef 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 */ 213typedef 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 229typedef struct hwc_module { 230 struct hw_module_t common; 231} hwc_module_t; 232 233 234typedef 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 * IMPORTANT NOTE: there is an implicit layer containing opaque black 291 * pixels behind all the layers in the list. 292 * It is the responsibility of the hwcomposer module to make 293 * sure black pixels are output (or blended from). 294 * 295 * returns: 0 on success. An negative error code on error: 296 * HWC_EGL_ERROR: eglGetError() will provide the proper error code 297 * Another code for non EGL errors. 298 * 299 */ 300 int (*set)(struct hwc_composer_device *dev, 301 hwc_display_t dpy, 302 hwc_surface_t sur, 303 hwc_layer_list_t* list); 304 /* 305 * This hook is OPTIONAL. 306 * 307 * If non NULL it will be called by SurfaceFlinger on dumpsys 308 */ 309 void (*dump)(struct hwc_composer_device* dev, char *buff, int buff_len); 310 311 /* 312 * This hook is OPTIONAL. 313 * 314 * (*registerProcs)() registers a set of callbacks the h/w composer HAL 315 * can later use. It is FORBIDDEN to call any of the callbacks from 316 * within registerProcs(). registerProcs() must save the hwc_procs_t pointer 317 * which is needed when calling a registered callback. 318 * Each call to registerProcs replaces the previous set of callbacks. 319 * registerProcs is called with NULL to unregister all callbacks. 320 * 321 * Any of the callbacks can be NULL, in which case the corresponding 322 * functionality is not supported. 323 */ 324 void (*registerProcs)(struct hwc_composer_device* dev, 325 hwc_procs_t const* procs); 326 327 void* reserved_proc[6]; 328 329} hwc_composer_device_t; 330 331 332/** convenience API for opening and closing a device */ 333 334static inline int hwc_open(const struct hw_module_t* module, 335 hwc_composer_device_t** device) { 336 return module->methods->open(module, 337 HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device); 338} 339 340static inline int hwc_close(hwc_composer_device_t* device) { 341 return device->common.close(&device->common); 342} 343 344 345/*****************************************************************************/ 346 347__END_DECLS 348 349#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */ 350