hwcomposer.h revision f9d6cd7dee62789b220033c926c87deab8991bde
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 62struct hwc_composer_device_1; 63typedef struct hwc_methods_1 { 64 65 /* 66 * eventControl(..., event, enabled) 67 * Enables or disables h/w composer events for a display. 68 * 69 * eventControl can be called from any thread and takes effect 70 * immediately. 71 * 72 * Supported events are: 73 * HWC_EVENT_VSYNC 74 * 75 * returns -EINVAL if the "event" parameter is not one of the value above 76 * or if the "enabled" parameter is not 0 or 1. 77 */ 78 79 int (*eventControl)( 80 struct hwc_composer_device_1* dev, int dpy, 81 int event, int enabled); 82 83 /* 84 * This field is OPTIONAL and can be NULL. 85 * 86 * blank(..., blank) 87 * Blanks or unblanks a display's screen. 88 * 89 * Turns the screen off when blank is nonzero, on when blank is zero. 90 * Blanking may also be triggered by a call to set..., 0, 0, 0). Multiple 91 * sequential calls with the same blank value must be supported. 92 * 93 * returns 0 on success, negative on error. 94 */ 95 96 int (*blank)(struct hwc_composer_device_1* dev, int dpy, int blank); 97 98} hwc_methods_1_t; 99 100typedef struct hwc_rect { 101 int left; 102 int top; 103 int right; 104 int bottom; 105} hwc_rect_t; 106 107typedef struct hwc_region { 108 size_t numRects; 109 hwc_rect_t const* rects; 110} hwc_region_t; 111 112typedef struct hwc_color { 113 uint8_t r; 114 uint8_t g; 115 uint8_t b; 116 uint8_t a; 117} hwc_color_t; 118 119typedef struct hwc_layer_1 { 120 /* 121 * initially set to HWC_FRAMEBUFFER or HWC_BACKGROUND. 122 * HWC_FRAMEBUFFER 123 * indicates the layer will be drawn into the framebuffer 124 * using OpenGL ES. 125 * The HWC can toggle this value to HWC_OVERLAY, to indicate 126 * it will handle the layer. 127 * 128 * HWC_BACKGROUND 129 * indicates this is a special "background" layer. The only valid 130 * field is backgroundColor. HWC_BACKGROUND can only be used with 131 * HWC_API_VERSION >= 0.2 132 * The HWC can toggle this value to HWC_FRAMEBUFFER, to indicate 133 * it CANNOT handle the background color 134 * 135 */ 136 int32_t compositionType; 137 138 /* see hwc_layer_t::hints above */ 139 uint32_t hints; 140 141 /* see hwc_layer_t::flags above */ 142 uint32_t flags; 143 144 union { 145 /* color of the background. hwc_color_t.a is ignored */ 146 hwc_color_t backgroundColor; 147 148 struct { 149 /* handle of buffer to compose. This handle is guaranteed to have been 150 * allocated from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. If 151 * the layer's handle is unchanged across two consecutive prepare calls and 152 * the HWC_GEOMETRY_CHANGED flag is not set for the second call then the 153 * HWComposer implementation may assume that the contents of the buffer have 154 * not changed. */ 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 179 /* Sync fence object that will be signaled when the buffer's 180 * contents are available. May be -1 if the contents are already 181 * available. This field is only valid during set(), and should be 182 * ignored during prepare(). The set() call must not wait for the 183 * fence to be signaled before returning, but the HWC must wait for 184 * all buffers to be signaled before reading from them. 185 * 186 * The HWC takes ownership of the acquireFenceFd and is responsible 187 * for closing it when no longer needed. 188 */ 189 int acquireFenceFd; 190 191 /* During set() the HWC must set this field to a file descriptor for 192 * a sync fence object that will signal after the HWC has finished 193 * reading from the buffer. The field is ignored by prepare(). Each 194 * layer should have a unique file descriptor, even if more than one 195 * refer to the same underlying fence object; this allows each to be 196 * closed independently. 197 * 198 * If buffer reads can complete at significantly different times, 199 * then using independent fences is preferred. For example, if the 200 * HWC handles some layers with a blit engine and others with 201 * overlays, then the blit layers can be reused immediately after 202 * the blit completes, but the overlay layers can't be reused until 203 * a subsequent frame has been displayed. 204 * 205 * The HWC client taks ownership of the releaseFenceFd and is 206 * responsible for closing it when no longer needed. 207 */ 208 int releaseFenceFd; 209 }; 210 }; 211 212 /* Allow for expansion w/o breaking binary compatibility. 213 * Pad layer to 96 bytes, assuming 32-bit pointers. 214 */ 215 int32_t reserved[24 - 18]; 216 217} hwc_layer_1_t; 218 219/* This represents a display, typically an EGLDisplay object */ 220typedef void* hwc_display_t; 221 222/* This represents a surface, typically an EGLSurface object */ 223typedef void* hwc_surface_t; 224 225/* 226 * hwc_display_contents_1_t::flags values 227 */ 228enum { 229 /* 230 * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list 231 * passed to (*prepare)() has changed by more than just the buffer handles 232 * and acquire fences. 233 */ 234 HWC_GEOMETRY_CHANGED = 0x00000001, 235}; 236 237/* 238 * Description of the contents to output on a display. 239 * 240 * This is the top-level structure passed to the prepare and set calls to 241 * negotiate and commit the composition of a display image. 242 */ 243typedef struct hwc_display_contents_1 { 244 /* File descriptor referring to a Sync HAL fence object which will signal 245 * when this display image is no longer visible, i.e. when the following 246 * set() takes effect. The fence object is created and returned by the set 247 * call; this field will be -1 on entry to prepare and set. SurfaceFlinger 248 * will close the returned file descriptor. 249 */ 250 int flipFenceFd; 251 252 /* (dpy, sur) is the target of SurfaceFlinger's OpenGL ES composition. 253 * They aren't relevant to prepare. The set call should commit this surface 254 * atomically to the display along with any overlay layers. 255 */ 256 hwc_display_t dpy; 257 hwc_surface_t sur; 258 259 /* List of layers that will be composed on the display. The buffer handles 260 * in the list will be unique. If numHwLayers is 0 and/or hwLayers is NULL, 261 * all composition will be performed by SurfaceFlinger. 262 */ 263 uint32_t flags; 264 size_t numHwLayers; 265 hwc_layer_1_t hwLayers[0]; 266 267} hwc_display_contents_1_t; 268 269/* see hwc_composer_device::registerProcs() 270 * Any of the callbacks can be NULL, in which case the corresponding 271 * functionality is not supported. 272 */ 273typedef struct hwc_procs { 274 /* 275 * (*invalidate)() triggers a screen refresh, in particular prepare and set 276 * will be called shortly after this call is made. Note that there is 277 * NO GUARANTEE that the screen refresh will happen after invalidate() 278 * returns (in particular, it could happen before). 279 * invalidate() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL and 280 * it is safe to call invalidate() from any of hwc_composer_device 281 * hooks, unless noted otherwise. 282 */ 283 void (*invalidate)(struct hwc_procs* procs); 284 285 /* 286 * (*vsync)() is called by the h/w composer HAL when a vsync event is 287 * received and HWC_EVENT_VSYNC is enabled on a display 288 * (see: hwc_event_control). 289 * 290 * the "dpy" parameter indicates which display the vsync event is for. 291 * the "timestamp" parameter is the system monotonic clock timestamp in 292 * nanosecond of when the vsync event happened. 293 * 294 * vsync() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL. 295 * 296 * It is expected that vsync() is called from a thread of at least 297 * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible, 298 * typically less than 0.5 ms. 299 * 300 * It is a (silent) error to have HWC_EVENT_VSYNC enabled when calling 301 * hwc_composer_device.set(..., 0, 0, 0) (screen off). The implementation 302 * can either stop or continue to process VSYNC events, but must not 303 * crash or cause other problems. 304 */ 305 void (*vsync)(struct hwc_procs* procs, int dpy, int64_t timestamp); 306} hwc_procs_t; 307 308 309/*****************************************************************************/ 310 311typedef struct hwc_module { 312 struct hw_module_t common; 313} hwc_module_t; 314 315typedef struct hwc_composer_device_1 { 316 struct hw_device_t common; 317 318 /* 319 * (*prepare)() is called for each frame before composition and is used by 320 * SurfaceFlinger to determine what composition steps the HWC can handle. 321 * 322 * (*prepare)() can be called more than once, the last call prevails. 323 * 324 * The HWC responds by setting the compositionType field in each layer to 325 * either HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the 326 * composition for the layer is handled by SurfaceFlinger with OpenGL ES, 327 * in the later case, the HWC will have to handle the layer's composition. 328 * 329 * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the 330 * list's geometry has changed, that is, when more than just the buffer's 331 * handles have been updated. Typically this happens (but is not limited to) 332 * when a window is added, removed, resized or moved. 333 * 334 * returns: 0 on success. An negative error code on error. If an error is 335 * returned, SurfaceFlinger will assume that none of the layer will be 336 * handled by the HWC. 337 */ 338 int (*prepare)(struct hwc_composer_device_1 *dev, 339 size_t numDisplays, hwc_display_contents_1_t** displays); 340 341 /* 342 * (*set)() is used in place of eglSwapBuffers(), and assumes the same 343 * functionality, except it also commits the work list atomically with 344 * the actual eglSwapBuffers(). 345 * 346 * The layer lists are guaranteed to be the same as the ones returned from 347 * the last call to (*prepare)(). 348 * 349 * When this call returns the caller assumes that the displays will be 350 * updated in the near future with the content of their work lists, without 351 * artifacts during the transition from the previous frame. 352 * 353 * A display with a NULL layer list or a numHwLayers of zero indicates that 354 * the entire composition has been handled by SurfaceFlinger with OpenGL ES. 355 * In this case, (*set)() behaves just like eglSwapBuffers(). 356 * 357 * The dpy, surf, and layers fields are set to NULL to indicate that the 358 * screen is turning off. This happens WITHOUT prepare() being called first. 359 * This is a good time to free h/w resources and/or power down the relevant 360 * h/w blocks. 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 * This field is OPTIONAL and can be NULL. 376 * 377 * If non NULL it will be called by SurfaceFlinger on dumpsys 378 */ 379 void (*dump)(struct hwc_composer_device_1* dev, char *buff, int buff_len); 380 381 /* 382 * This field is OPTIONAL and can be NULL. 383 * 384 * (*registerProcs)() registers a set of callbacks the h/w composer HAL 385 * can later use. It is FORBIDDEN to call any of the callbacks from 386 * within registerProcs(). registerProcs() must save the hwc_procs_t pointer 387 * which is needed when calling a registered callback. 388 * Each call to registerProcs replaces the previous set of callbacks. 389 * registerProcs is called with NULL to unregister all callbacks. 390 * 391 * Any of the callbacks can be NULL, in which case the corresponding 392 * functionality is not supported. 393 */ 394 void (*registerProcs)(struct hwc_composer_device_1* dev, 395 hwc_procs_t const* procs); 396 397 /* 398 * This field is OPTIONAL and can be NULL. 399 * 400 * Used to retrieve information about the h/w composer 401 * 402 * Returns 0 on success or -errno on error. 403 */ 404 int (*query)(struct hwc_composer_device_1* dev, int what, int* value); 405 406 /* 407 * Reserved for future use. Must be NULL. 408 */ 409 void* reserved_proc[4]; 410 411 /* 412 * This field is OPTIONAL and can be NULL. 413 */ 414 hwc_methods_1_t const *methods; 415 416} hwc_composer_device_1_t; 417 418/** convenience API for opening and closing a device */ 419 420static inline int hwc_open_1(const struct hw_module_t* module, 421 hwc_composer_device_1_t** device) { 422 return module->methods->open(module, 423 HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device); 424} 425 426static inline int hwc_close_1(hwc_composer_device_1_t* device) { 427 return device->common.close(&device->common); 428} 429 430/*****************************************************************************/ 431 432#if !HWC_REMOVE_DEPRECATED_VERSIONS 433#include <hardware/hwcomposer_v0.h> 434#endif 435 436__END_DECLS 437 438#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */ 439