hwcomposer.h revision af05c912e1afa1f7d7b3f4b1d8b3034427abc37b
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 40/** 41 * The id of this module 42 */ 43#define HWC_HARDWARE_MODULE_ID "hwcomposer" 44 45/** 46 * Name of the sensors device to open 47 */ 48#define HWC_HARDWARE_COMPOSER "composer" 49 50typedef struct hwc_rect { 51 int left; 52 int top; 53 int right; 54 int bottom; 55} hwc_rect_t; 56 57typedef struct hwc_region { 58 size_t numRects; 59 hwc_rect_t const* rects; 60} hwc_region_t; 61 62typedef struct hwc_color { 63 uint8_t r; 64 uint8_t g; 65 uint8_t b; 66 uint8_t a; 67} hwc_color_t; 68 69typedef struct hwc_layer_1 { 70 /* 71 * compositionType is used to specify this layer's type and is set by either 72 * the hardware composer implementation, or by the caller (see below). 73 * 74 * This field is always reset to HWC_BACKGROUND or HWC_FRAMEBUFFER 75 * before (*prepare)() is called when the HWC_GEOMETRY_CHANGED flag is 76 * also set, otherwise, this field is preserved between (*prepare)() 77 * calls. 78 * 79 * HWC_BACKGROUND 80 * Always set by the caller before calling (*prepare)(), this value 81 * indicates this is a special "background" layer. The only valid field 82 * is backgroundColor. 83 * The HWC can toggle this value to HWC_FRAMEBUFFER to indicate it CANNOT 84 * handle the background color. 85 * 86 * 87 * HWC_FRAMEBUFFER_TARGET 88 * Always set by the caller before calling (*prepare)(), this value 89 * indicates this layer is the framebuffer surface used as the target of 90 * OpenGL ES composition. If the HWC sets all other layers to HWC_OVERLAY 91 * or HWC_BACKGROUND, then no OpenGL ES composition will be done, and 92 * this layer should be ignored during set(). 93 * 94 * This flag (and the framebuffer surface layer) will only be used if the 95 * HWC version is HWC_DEVICE_API_VERSION_1_1 or higher. In older versions, 96 * the OpenGL ES target surface is communicated by the (dpy, sur) fields 97 * in hwc_compositor_device_1_t. 98 * 99 * This value cannot be set by the HWC implementation. 100 * 101 * 102 * HWC_FRAMEBUFFER 103 * Set by the caller before calling (*prepare)() ONLY when the 104 * HWC_GEOMETRY_CHANGED flag is also set. 105 * 106 * Set by the HWC implementation during (*prepare)(), this indicates 107 * that the layer will be drawn into the framebuffer using OpenGL ES. 108 * The HWC can toggle this value to HWC_OVERLAY to indicate it will 109 * handle the layer. 110 * 111 * 112 * HWC_OVERLAY 113 * Set by the HWC implementation during (*prepare)(), this indicates 114 * that the layer will be handled by the HWC (ie: it must not be 115 * composited with OpenGL ES). 116 * 117 */ 118 int32_t compositionType; 119 120 /* 121 * hints is bit mask set by the HWC implementation during (*prepare)(). 122 * It is preserved between (*prepare)() calls, unless the 123 * HWC_GEOMETRY_CHANGED flag is set, in which case it is reset to 0. 124 * 125 * see hwc_layer_t::hints 126 */ 127 uint32_t hints; 128 129 /* see hwc_layer_t::flags */ 130 uint32_t flags; 131 132 union { 133 /* color of the background. hwc_color_t.a is ignored */ 134 hwc_color_t backgroundColor; 135 136 struct { 137 /* handle of buffer to compose. This handle is guaranteed to have been 138 * allocated from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. If 139 * the layer's handle is unchanged across two consecutive prepare calls and 140 * the HWC_GEOMETRY_CHANGED flag is not set for the second call then the 141 * HWComposer implementation may assume that the contents of the buffer have 142 * not changed. */ 143 buffer_handle_t handle; 144 145 /* transformation to apply to the buffer during composition */ 146 uint32_t transform; 147 148 /* blending to apply during composition */ 149 int32_t blending; 150 151 /* area of the source to consider, the origin is the top-left corner of 152 * the buffer */ 153 hwc_rect_t sourceCrop; 154 155 /* where to composite the sourceCrop onto the display. The sourceCrop 156 * is scaled using linear filtering to the displayFrame. The origin is the 157 * top-left corner of the screen. 158 */ 159 hwc_rect_t displayFrame; 160 161 /* visible region in screen space. The origin is the 162 * top-left corner of the screen. 163 * The visible region INCLUDES areas overlapped by a translucent layer. 164 */ 165 hwc_region_t visibleRegionScreen; 166 167 /* Sync fence object that will be signaled when the buffer's 168 * contents are available. May be -1 if the contents are already 169 * available. This field is only valid during set(), and should be 170 * ignored during prepare(). The set() call must not wait for the 171 * fence to be signaled before returning, but the HWC must wait for 172 * all buffers to be signaled before reading from them. 173 * 174 * HWC_FRAMEBUFFER layers will never have an acquire fence, since 175 * reads from them are complete before the framebuffer is ready for 176 * display. 177 * 178 * The HWC takes ownership of the acquireFenceFd and is responsible 179 * for closing it when no longer needed. 180 */ 181 int acquireFenceFd; 182 183 /* During set() the HWC must set this field to a file descriptor for 184 * a sync fence object that will signal after the HWC has finished 185 * reading from the buffer. The field is ignored by prepare(). Each 186 * layer should have a unique file descriptor, even if more than one 187 * refer to the same underlying fence object; this allows each to be 188 * closed independently. 189 * 190 * If buffer reads can complete at significantly different times, 191 * then using independent fences is preferred. For example, if the 192 * HWC handles some layers with a blit engine and others with 193 * overlays, then the blit layers can be reused immediately after 194 * the blit completes, but the overlay layers can't be reused until 195 * a subsequent frame has been displayed. 196 * 197 * Since HWC doesn't read from HWC_FRAMEBUFFER layers, it shouldn't 198 * produce a release fence for them. The releaseFenceFd will be -1 199 * for these layers when set() is called. 200 * 201 * The HWC client taks ownership of the releaseFenceFd and is 202 * responsible for closing it when no longer needed. 203 */ 204 int releaseFenceFd; 205 }; 206 }; 207 208 /* Allow for expansion w/o breaking binary compatibility. 209 * Pad layer to 96 bytes, assuming 32-bit pointers. 210 */ 211 int32_t reserved[24 - 18]; 212 213} hwc_layer_1_t; 214 215/* This represents a display, typically an EGLDisplay object */ 216typedef void* hwc_display_t; 217 218/* This represents a surface, typically an EGLSurface object */ 219typedef void* hwc_surface_t; 220 221/* 222 * hwc_display_contents_1_t::flags values 223 */ 224enum { 225 /* 226 * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list 227 * passed to (*prepare)() has changed by more than just the buffer handles 228 * and acquire fences. 229 */ 230 HWC_GEOMETRY_CHANGED = 0x00000001, 231}; 232 233/* 234 * Description of the contents to output on a display. 235 * 236 * This is the top-level structure passed to the prepare and set calls to 237 * negotiate and commit the composition of a display image. 238 */ 239typedef struct hwc_display_contents_1 { 240 /* File descriptor referring to a Sync HAL fence object which will signal 241 * when this composition is retired. For a physical display, a composition 242 * is retired when it has been replaced on-screen by a subsequent set. For 243 * a virtual display, the composition is retired when the writes to 244 * outputBuffer are complete and can be read. The fence object is created 245 * and returned by the set call; this field will be -1 on entry to prepare 246 * and set. SurfaceFlinger will close the returned file descriptor. 247 */ 248 int retireFenceFd; 249 250 union { 251 /* Fields only relevant for HWC_DEVICE_VERSION_1_0. */ 252 struct { 253 /* (dpy, sur) is the target of SurfaceFlinger's OpenGL ES 254 * composition for HWC_DEVICE_VERSION_1_0. They aren't relevant to 255 * prepare. The set call should commit this surface atomically to 256 * the display along with any overlay layers. 257 */ 258 hwc_display_t dpy; 259 hwc_surface_t sur; 260 }; 261 262 /* Fields only relevant for HWC_DEVICE_VERSION_1_2 and later. */ 263 struct { 264 /* outbuf is the buffer that receives the composed image for 265 * virtual displays. Writes to the outbuf must wait until 266 * outbufAcquireFenceFd signals. A fence that will signal when 267 * writes to outbuf are complete should be returned in 268 * retireFenceFd. 269 * 270 * For physical displays, outbuf will be NULL. 271 */ 272 buffer_handle_t outbuf; 273 274 /* File descriptor for a fence that will signal when outbuf is 275 * ready to be written. The h/w composer is responsible for closing 276 * this when no longer needed. 277 * 278 * Will be -1 whenever outbuf is NULL, or when the outbuf can be 279 * written immediately. 280 */ 281 int outbufAcquireFenceFd; 282 }; 283 }; 284 285 /* List of layers that will be composed on the display. The buffer handles 286 * in the list will be unique. If numHwLayers is 0, all composition will be 287 * performed by SurfaceFlinger. 288 */ 289 uint32_t flags; 290 size_t numHwLayers; 291 hwc_layer_1_t hwLayers[0]; 292 293} hwc_display_contents_1_t; 294 295/* see hwc_composer_device::registerProcs() 296 * All of the callbacks are required and non-NULL unless otherwise noted. 297 */ 298typedef struct hwc_procs { 299 /* 300 * (*invalidate)() triggers a screen refresh, in particular prepare and set 301 * will be called shortly after this call is made. Note that there is 302 * NO GUARANTEE that the screen refresh will happen after invalidate() 303 * returns (in particular, it could happen before). 304 * invalidate() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL and 305 * it is safe to call invalidate() from any of hwc_composer_device 306 * hooks, unless noted otherwise. 307 */ 308 void (*invalidate)(const struct hwc_procs* procs); 309 310 /* 311 * (*vsync)() is called by the h/w composer HAL when a vsync event is 312 * received and HWC_EVENT_VSYNC is enabled on a display 313 * (see: hwc_event_control). 314 * 315 * the "disp" parameter indicates which display the vsync event is for. 316 * the "timestamp" parameter is the system monotonic clock timestamp in 317 * nanosecond of when the vsync event happened. 318 * 319 * vsync() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL. 320 * 321 * It is expected that vsync() is called from a thread of at least 322 * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, 323 * typically less than 0.5 ms. 324 * 325 * It is a (silent) error to have HWC_EVENT_VSYNC enabled when calling 326 * hwc_composer_device.set(..., 0, 0, 0) (screen off). The implementation 327 * can either stop or continue to process VSYNC events, but must not 328 * crash or cause other problems. 329 */ 330 void (*vsync)(const struct hwc_procs* procs, int disp, int64_t timestamp); 331 332 /* 333 * (*hotplug)() is called by the h/w composer HAL when a display is 334 * connected or disconnected. The PRIMARY display is always connected and 335 * the hotplug callback should not be called for it. 336 * 337 * The disp parameter indicates which display type this event is for. 338 * The connected parameter indicates whether the display has just been 339 * connected (1) or disconnected (0). 340 * 341 * The hotplug() callback may call back into the h/w composer on the same 342 * thread to query refresh rate and dpi for the display. Additionally, 343 * other threads may be calling into the h/w composer while the callback 344 * is in progress. 345 * 346 * The h/w composer must serialize calls to the hotplug callback; only 347 * one thread may call it at a time. 348 * 349 * This callback will be NULL if the h/w composer is using 350 * HWC_DEVICE_API_VERSION_1_0. 351 */ 352 void (*hotplug)(const struct hwc_procs* procs, int disp, int connected); 353 354} hwc_procs_t; 355 356 357/*****************************************************************************/ 358 359typedef struct hwc_module { 360 struct hw_module_t common; 361} hwc_module_t; 362 363typedef struct hwc_composer_device_1 { 364 struct hw_device_t common; 365 366 /* 367 * (*prepare)() is called for each frame before composition and is used by 368 * SurfaceFlinger to determine what composition steps the HWC can handle. 369 * 370 * (*prepare)() can be called more than once, the last call prevails. 371 * 372 * The HWC responds by setting the compositionType field in each layer to 373 * either HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the 374 * composition for the layer is handled by SurfaceFlinger with OpenGL ES, 375 * in the later case, the HWC will have to handle the layer's composition. 376 * compositionType and hints are preserved between (*prepare)() calles 377 * unless the HWC_GEOMETRY_CHANGED flag is set. 378 * 379 * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the 380 * list's geometry has changed, that is, when more than just the buffer's 381 * handles have been updated. Typically this happens (but is not limited to) 382 * when a window is added, removed, resized or moved. In this case 383 * compositionType and hints are reset to their default value. 384 * 385 * For HWC 1.0, numDisplays will always be one, and displays[0] will be 386 * non-NULL. 387 * 388 * For HWC 1.1, numDisplays will always be HWC_NUM_DISPLAY_TYPES. Entries 389 * for unsupported or disabled/disconnected display types will be NULL. 390 * 391 * For HWC 1.2 and later, numDisplays will be HWC_NUM_DISPLAY_TYPES or more. 392 * The extra entries correspond to enabled virtual displays, and will be 393 * non-NULL. In HWC 1.2, support for one virtual display is required, and 394 * no more than one will be used. Future HWC versions might require more. 395 * 396 * returns: 0 on success. An negative error code on error. If an error is 397 * returned, SurfaceFlinger will assume that none of the layer will be 398 * handled by the HWC. 399 */ 400 int (*prepare)(struct hwc_composer_device_1 *dev, 401 size_t numDisplays, hwc_display_contents_1_t** displays); 402 403 /* 404 * (*set)() is used in place of eglSwapBuffers(), and assumes the same 405 * functionality, except it also commits the work list atomically with 406 * the actual eglSwapBuffers(). 407 * 408 * The layer lists are guaranteed to be the same as the ones returned from 409 * the last call to (*prepare)(). 410 * 411 * When this call returns the caller assumes that the displays will be 412 * updated in the near future with the content of their work lists, without 413 * artifacts during the transition from the previous frame. 414 * 415 * A display with zero layers indicates that the entire composition has 416 * been handled by SurfaceFlinger with OpenGL ES. In this case, (*set)() 417 * behaves just like eglSwapBuffers(). 418 * 419 * For HWC 1.0, numDisplays will always be one, and displays[0] will be 420 * non-NULL. 421 * 422 * For HWC 1.1, numDisplays will always be HWC_NUM_DISPLAY_TYPES. Entries 423 * for unsupported or disabled/disconnected display types will be NULL. 424 * 425 * For HWC 1.2 and later, numDisplays will be HWC_NUM_DISPLAY_TYPES or more. 426 * The extra entries correspond to enabled virtual displays, and will be 427 * non-NULL. In HWC 1.2, support for one virtual display is required, and 428 * no more than one will be used. Future HWC versions might require more. 429 * 430 * IMPORTANT NOTE: There is an implicit layer containing opaque black 431 * pixels behind all the layers in the list. It is the responsibility of 432 * the hwcomposer module to make sure black pixels are output (or blended 433 * from). 434 * 435 * IMPORTANT NOTE: In the event of an error this call *MUST* still cause 436 * any fences returned in the previous call to set to eventually become 437 * signaled. The caller may have already issued wait commands on these 438 * fences, and having set return without causing those fences to signal 439 * will likely result in a deadlock. 440 * 441 * returns: 0 on success. A negative error code on error: 442 * HWC_EGL_ERROR: eglGetError() will provide the proper error code (only 443 * allowed prior to HWComposer 1.1) 444 * Another code for non EGL errors. 445 */ 446 int (*set)(struct hwc_composer_device_1 *dev, 447 size_t numDisplays, hwc_display_contents_1_t** displays); 448 449 /* 450 * eventControl(..., event, enabled) 451 * Enables or disables h/w composer events for a display. 452 * 453 * eventControl can be called from any thread and takes effect 454 * immediately. 455 * 456 * Supported events are: 457 * HWC_EVENT_VSYNC 458 * 459 * returns -EINVAL if the "event" parameter is not one of the value above 460 * or if the "enabled" parameter is not 0 or 1. 461 */ 462 int (*eventControl)(struct hwc_composer_device_1* dev, int disp, 463 int event, int enabled); 464 465 /* 466 * blank(..., blank) 467 * Blanks or unblanks a display's screen. 468 * 469 * Turns the screen off when blank is nonzero, on when blank is zero. 470 * Multiple sequential calls with the same blank value must be supported. 471 * The screen state transition must be be complete when the function 472 * returns. 473 * 474 * returns 0 on success, negative on error. 475 */ 476 int (*blank)(struct hwc_composer_device_1* dev, int disp, int blank); 477 478 /* 479 * Used to retrieve information about the h/w composer 480 * 481 * Returns 0 on success or -errno on error. 482 */ 483 int (*query)(struct hwc_composer_device_1* dev, int what, int* value); 484 485 /* 486 * (*registerProcs)() registers callbacks that the h/w composer HAL can 487 * later use. It will be called immediately after the composer device is 488 * opened with non-NULL procs. It is FORBIDDEN to call any of the callbacks 489 * from within registerProcs(). registerProcs() must save the hwc_procs_t 490 * pointer which is needed when calling a registered callback. 491 */ 492 void (*registerProcs)(struct hwc_composer_device_1* dev, 493 hwc_procs_t const* procs); 494 495 /* 496 * This field is OPTIONAL and can be NULL. 497 * 498 * If non NULL it will be called by SurfaceFlinger on dumpsys 499 */ 500 void (*dump)(struct hwc_composer_device_1* dev, char *buff, int buff_len); 501 502 /* 503 * (*getDisplayConfigs)() returns handles for the configurations available 504 * on the connected display. These handles must remain valid as long as the 505 * display is connected. 506 * 507 * Configuration handles are written to configs. The number of entries 508 * allocated by the caller is passed in *numConfigs; getDisplayConfigs must 509 * not try to write more than this number of config handles. On return, the 510 * total number of configurations available for the display is returned in 511 * *numConfigs. If *numConfigs is zero on entry, then configs may be NULL. 512 * 513 * HWC_DEVICE_API_VERSION_1_1 does not provide a way to choose a config. 514 * For displays that support multiple configurations, the h/w composer 515 * implementation should choose one and report it as the first config in 516 * the list. Reporting the not-chosen configs is not required. 517 * 518 * Returns 0 on success or -errno on error. If disp is a hotpluggable 519 * display type and no display is connected, an error should be returned. 520 * 521 * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later. 522 * It should be NULL for previous versions. 523 */ 524 int (*getDisplayConfigs)(struct hwc_composer_device_1* dev, int disp, 525 uint32_t* configs, size_t* numConfigs); 526 527 /* 528 * (*getDisplayAttributes)() returns attributes for a specific config of a 529 * connected display. The config parameter is one of the config handles 530 * returned by getDisplayConfigs. 531 * 532 * The list of attributes to return is provided in the attributes 533 * parameter, terminated by HWC_DISPLAY_NO_ATTRIBUTE. The value for each 534 * requested attribute is written in order to the values array. The 535 * HWC_DISPLAY_NO_ATTRIBUTE attribute does not have a value, so the values 536 * array will have one less value than the attributes array. 537 * 538 * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later. 539 * It should be NULL for previous versions. 540 * 541 * If disp is a hotpluggable display type and no display is connected, 542 * or if config is not a valid configuration for the display, a negative 543 * value should be returned. 544 */ 545 int (*getDisplayAttributes)(struct hwc_composer_device_1* dev, int disp, 546 uint32_t config, const uint32_t* attributes, int32_t* values); 547 548 /* 549 * Reserved for future use. Must be NULL. 550 */ 551 void* reserved_proc[4]; 552 553} hwc_composer_device_1_t; 554 555/** convenience API for opening and closing a device */ 556 557static inline int hwc_open_1(const struct hw_module_t* module, 558 hwc_composer_device_1_t** device) { 559 return module->methods->open(module, 560 HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device); 561} 562 563static inline int hwc_close_1(hwc_composer_device_1_t* device) { 564 return device->common.close(&device->common); 565} 566 567/*****************************************************************************/ 568 569__END_DECLS 570 571#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */ 572