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