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