hwcomposer.h revision 0a0a41653d82552e601980c8793fcb07e3863044
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(); the HWC_SKIP_LAYER flag 101 * will indicate this case. 102 * 103 * This flag (and the framebuffer surface layer) will only be used if the 104 * HWC version is HWC_DEVICE_API_VERSION_1_1 or higher. In older versions, 105 * the OpenGL ES target surface is communicated by the (dpy, sur) fields 106 * in hwc_compositor_device_1_t. 107 */ 108 int32_t compositionType; 109 110 /* see hwc_layer_t::hints above */ 111 uint32_t hints; 112 113 /* see hwc_layer_t::flags above */ 114 uint32_t flags; 115 116 union { 117 /* color of the background. hwc_color_t.a is ignored */ 118 hwc_color_t backgroundColor; 119 120 struct { 121 /* handle of buffer to compose. This handle is guaranteed to have been 122 * allocated from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. If 123 * the layer's handle is unchanged across two consecutive prepare calls and 124 * the HWC_GEOMETRY_CHANGED flag is not set for the second call then the 125 * HWComposer implementation may assume that the contents of the buffer have 126 * not changed. */ 127 buffer_handle_t handle; 128 129 /* transformation to apply to the buffer during composition */ 130 uint32_t transform; 131 132 /* blending to apply during composition */ 133 int32_t blending; 134 135 /* area of the source to consider, the origin is the top-left corner of 136 * the buffer */ 137 hwc_rect_t sourceCrop; 138 139 /* where to composite the sourceCrop onto the display. The sourceCrop 140 * is scaled using linear filtering to the displayFrame. The origin is the 141 * top-left corner of the screen. 142 */ 143 hwc_rect_t displayFrame; 144 145 /* visible region in screen space. The origin is the 146 * top-left corner of the screen. 147 * The visible region INCLUDES areas overlapped by a translucent layer. 148 */ 149 hwc_region_t visibleRegionScreen; 150 151 /* Sync fence object that will be signaled when the buffer's 152 * contents are available. May be -1 if the contents are already 153 * available. This field is only valid during set(), and should be 154 * ignored during prepare(). The set() call must not wait for the 155 * fence to be signaled before returning, but the HWC must wait for 156 * all buffers to be signaled before reading from them. 157 * 158 * HWC_FRAMEBUFFER layers will never have an acquire fence, since 159 * reads from them are complete before the framebuffer is ready for 160 * display. 161 * 162 * The HWC takes ownership of the acquireFenceFd and is responsible 163 * for closing it when no longer needed. 164 */ 165 int acquireFenceFd; 166 167 /* During set() the HWC must set this field to a file descriptor for 168 * a sync fence object that will signal after the HWC has finished 169 * reading from the buffer. The field is ignored by prepare(). Each 170 * layer should have a unique file descriptor, even if more than one 171 * refer to the same underlying fence object; this allows each to be 172 * closed independently. 173 * 174 * If buffer reads can complete at significantly different times, 175 * then using independent fences is preferred. For example, if the 176 * HWC handles some layers with a blit engine and others with 177 * overlays, then the blit layers can be reused immediately after 178 * the blit completes, but the overlay layers can't be reused until 179 * a subsequent frame has been displayed. 180 * 181 * Since HWC doesn't read from HWC_FRAMEBUFFER layers, it shouldn't 182 * produce a release fence for them. The releaseFenceFd will be -1 183 * for these layers when set() is called. 184 * 185 * The HWC client taks ownership of the releaseFenceFd and is 186 * responsible for closing it when no longer needed. 187 */ 188 int releaseFenceFd; 189 }; 190 }; 191 192 /* Allow for expansion w/o breaking binary compatibility. 193 * Pad layer to 96 bytes, assuming 32-bit pointers. 194 */ 195 int32_t reserved[24 - 18]; 196 197} hwc_layer_1_t; 198 199/* This represents a display, typically an EGLDisplay object */ 200typedef void* hwc_display_t; 201 202/* This represents a surface, typically an EGLSurface object */ 203typedef void* hwc_surface_t; 204 205/* 206 * hwc_display_contents_1_t::flags values 207 */ 208enum { 209 /* 210 * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list 211 * passed to (*prepare)() has changed by more than just the buffer handles 212 * and acquire fences. 213 */ 214 HWC_GEOMETRY_CHANGED = 0x00000001, 215}; 216 217/* 218 * Description of the contents to output on a display. 219 * 220 * This is the top-level structure passed to the prepare and set calls to 221 * negotiate and commit the composition of a display image. 222 */ 223typedef struct hwc_display_contents_1 { 224 /* File descriptor referring to a Sync HAL fence object which will signal 225 * when this display image is no longer visible, i.e. when the following 226 * set() takes effect. The fence object is created and returned by the set 227 * call; this field will be -1 on entry to prepare and set. SurfaceFlinger 228 * will close the returned file descriptor. 229 */ 230 int flipFenceFd; 231 232 /* (dpy, sur) is the target of SurfaceFlinger's OpenGL ES composition for 233 * HWC versions before HWC_DEVICE_VERSION_1_1. They aren't relevant to 234 * prepare. The set call should commit this surface atomically to the 235 * display along with any overlay layers. 236 * 237 * For HWC_DEVICE_VERSION_1_1 and later, these will always be set to 238 * EGL_NO_DISPLAY and EGL_NO_SURFACE. 239 */ 240 hwc_display_t dpy; 241 hwc_surface_t sur; 242 243 /* List of layers that will be composed on the display. The buffer handles 244 * in the list will be unique. If numHwLayers is 0, all composition will be 245 * performed by SurfaceFlinger. 246 */ 247 uint32_t flags; 248 size_t numHwLayers; 249 hwc_layer_1_t hwLayers[0]; 250 251} hwc_display_contents_1_t; 252 253/* see hwc_composer_device::registerProcs() 254 * All of the callbacks are required and non-NULL unless otherwise noted. 255 */ 256typedef struct hwc_procs { 257 /* 258 * (*invalidate)() triggers a screen refresh, in particular prepare and set 259 * will be called shortly after this call is made. Note that there is 260 * NO GUARANTEE that the screen refresh will happen after invalidate() 261 * returns (in particular, it could happen before). 262 * invalidate() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL and 263 * it is safe to call invalidate() from any of hwc_composer_device 264 * hooks, unless noted otherwise. 265 */ 266 void (*invalidate)(const struct hwc_procs* procs); 267 268 /* 269 * (*vsync)() is called by the h/w composer HAL when a vsync event is 270 * received and HWC_EVENT_VSYNC is enabled on a display 271 * (see: hwc_event_control). 272 * 273 * the "dpy" parameter indicates which display the vsync event is for. 274 * the "timestamp" parameter is the system monotonic clock timestamp in 275 * nanosecond of when the vsync event happened. 276 * 277 * vsync() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL. 278 * 279 * It is expected that vsync() is called from a thread of at least 280 * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, 281 * typically less than 0.5 ms. 282 * 283 * It is a (silent) error to have HWC_EVENT_VSYNC enabled when calling 284 * hwc_composer_device.set(..., 0, 0, 0) (screen off). The implementation 285 * can either stop or continue to process VSYNC events, but must not 286 * crash or cause other problems. 287 */ 288 void (*vsync)(const struct hwc_procs* procs, int dpy, int64_t timestamp); 289} hwc_procs_t; 290 291 292/*****************************************************************************/ 293 294typedef struct hwc_module { 295 struct hw_module_t common; 296} hwc_module_t; 297 298typedef struct hwc_composer_device_1 { 299 struct hw_device_t common; 300 301 /* 302 * (*prepare)() is called for each frame before composition and is used by 303 * SurfaceFlinger to determine what composition steps the HWC can handle. 304 * 305 * (*prepare)() can be called more than once, the last call prevails. 306 * 307 * The HWC responds by setting the compositionType field in each layer to 308 * either HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the 309 * composition for the layer is handled by SurfaceFlinger with OpenGL ES, 310 * in the later case, the HWC will have to handle the layer's composition. 311 * 312 * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the 313 * list's geometry has changed, that is, when more than just the buffer's 314 * handles have been updated. Typically this happens (but is not limited to) 315 * when a window is added, removed, resized or moved. 316 * 317 * For HWC 1.0, numDisplays will always be one, and displays[0] will be 318 * non-NULL. 319 * 320 * For HWC 1.1, numDisplays will always be HWC_NUM_DISPLAY_TYPES. Entries 321 * for unsupported or disabled/disconnected display types will be NULL. 322 * 323 * For HWC 1.2 and later, numDisplays will be HWC_NUM_DISPLAY_TYPES or more. 324 * The extra entries correspond to enabled virtual displays, and will be 325 * non-NULL. In HWC 1.2, support for one virtual display is required, and 326 * no more than one will be used. Future HWC versions might require more. 327 * 328 * returns: 0 on success. An negative error code on error. If an error is 329 * returned, SurfaceFlinger will assume that none of the layer will be 330 * handled by the HWC. 331 */ 332 int (*prepare)(struct hwc_composer_device_1 *dev, 333 size_t numDisplays, hwc_display_contents_1_t** displays); 334 335 /* 336 * (*set)() is used in place of eglSwapBuffers(), and assumes the same 337 * functionality, except it also commits the work list atomically with 338 * the actual eglSwapBuffers(). 339 * 340 * The layer lists are guaranteed to be the same as the ones returned from 341 * the last call to (*prepare)(). 342 * 343 * When this call returns the caller assumes that the displays will be 344 * updated in the near future with the content of their work lists, without 345 * artifacts during the transition from the previous frame. 346 * 347 * A display with zero layers indicates that the entire composition has 348 * been handled by SurfaceFlinger with OpenGL ES. In this case, (*set)() 349 * behaves just like eglSwapBuffers(). 350 * 351 * For HWC 1.0, numDisplays will always be one, and displays[0] will be 352 * non-NULL. 353 * 354 * For HWC 1.1, numDisplays will always be HWC_NUM_DISPLAY_TYPES. Entries 355 * for unsupported or disabled/disconnected display types will be NULL. 356 * 357 * For HWC 1.2 and later, numDisplays will be HWC_NUM_DISPLAY_TYPES or more. 358 * The extra entries correspond to enabled virtual displays, and will be 359 * non-NULL. In HWC 1.2, support for one virtual display is required, and 360 * no more than one will be used. Future HWC versions might require more. 361 * 362 * IMPORTANT NOTE: there is an implicit layer containing opaque black 363 * pixels behind all the layers in the list. It is the responsibility of 364 * the hwcomposer module to make sure black pixels are output (or blended 365 * from). 366 * 367 * returns: 0 on success. An negative error code on error: 368 * HWC_EGL_ERROR: eglGetError() will provide the proper error code 369 * Another code for non EGL errors. 370 */ 371 int (*set)(struct hwc_composer_device_1 *dev, 372 size_t numDisplays, hwc_display_contents_1_t** displays); 373 374 /* 375 * eventControl(..., event, enabled) 376 * Enables or disables h/w composer events for a display. 377 * 378 * eventControl can be called from any thread and takes effect 379 * immediately. 380 * 381 * Supported events are: 382 * HWC_EVENT_VSYNC 383 * 384 * returns -EINVAL if the "event" parameter is not one of the value above 385 * or if the "enabled" parameter is not 0 or 1. 386 */ 387 int (*eventControl)(struct hwc_composer_device_1* dev, int dpy, 388 int event, int enabled); 389 390 /* 391 * blank(..., blank) 392 * Blanks or unblanks a display's screen. 393 * 394 * Turns the screen off when blank is nonzero, on when blank is zero. 395 * Multiple sequential calls with the same blank value must be supported. 396 * The screen state transition must be be complete when the function 397 * returns. 398 * 399 * returns 0 on success, negative on error. 400 */ 401 int (*blank)(struct hwc_composer_device_1* dev, int dpy, int blank); 402 403 /* 404 * Used to retrieve information about the h/w composer 405 * 406 * Returns 0 on success or -errno on error. 407 */ 408 int (*query)(struct hwc_composer_device_1* dev, int what, int* value); 409 410 /* 411 * (*registerProcs)() registers callbacks that the h/w composer HAL can 412 * later use. It will be called immediately after the composer device is 413 * opened with non-NULL procs. It is FORBIDDEN to call any of the callbacks 414 * from within registerProcs(). registerProcs() must save the hwc_procs_t 415 * pointer which is needed when calling a registered callback. 416 */ 417 void (*registerProcs)(struct hwc_composer_device_1* dev, 418 hwc_procs_t const* procs); 419 420 /* 421 * This field is OPTIONAL and can be NULL. 422 * 423 * If non NULL it will be called by SurfaceFlinger on dumpsys 424 */ 425 void (*dump)(struct hwc_composer_device_1* dev, char *buff, int buff_len); 426 427 /* 428 * Reserved for future use. Must be NULL. 429 */ 430 void* reserved_proc[4]; 431 432} hwc_composer_device_1_t; 433 434/** convenience API for opening and closing a device */ 435 436static inline int hwc_open_1(const struct hw_module_t* module, 437 hwc_composer_device_1_t** device) { 438 return module->methods->open(module, 439 HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device); 440} 441 442static inline int hwc_close_1(hwc_composer_device_1_t* device) { 443 return device->common.close(&device->common); 444} 445 446/*****************************************************************************/ 447 448#if !HWC_REMOVE_DEPRECATED_VERSIONS 449#include <hardware/hwcomposer_v0.h> 450#endif 451 452__END_DECLS 453 454#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */ 455