hwcomposer.h revision e99520400f228e45b1feff28eb4105b8e5599196
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_API_VERSION 1 32 33/** 34 * The id of this module 35 */ 36#define HWC_HARDWARE_MODULE_ID "hwcomposer" 37 38/** 39 * Name of the sensors device to open 40 */ 41#define HWC_HARDWARE_COMPOSER "composer" 42 43 44enum { 45 /* hwc_composer_device_t::set failed in EGL */ 46 HWC_EGL_ERROR = -1 47}; 48 49/* 50 * hwc_layer_t::hints values 51 * Hints are set by the HAL and read by SurfaceFlinger 52 */ 53enum { 54 /* 55 * HWC can set the HWC_HINT_TRIPLE_BUFFER hint to indicate to SurfaceFlinger 56 * that it should triple buffer this layer. Typically HWC does this when 57 * the layer will be unavailable for use for an extended period of time, 58 * e.g. if the display will be fetching data directly from the layer and 59 * the layer can not be modified until after the next set(). 60 */ 61 HWC_HINT_TRIPLE_BUFFER = 0x00000001, 62 63 /* 64 * HWC sets HWC_HINT_CLEAR_FB to tell SurfaceFlinger that it should clear the 65 * framebuffer with transparent pixels where this layer would be. 66 * SurfaceFlinger will only honor this flag when the layer has no blending 67 * 68 */ 69 HWC_HINT_CLEAR_FB = 0x00000002 70}; 71 72/* 73 * hwc_layer_t::flags values 74 * Flags are set by SurfaceFlinger and read by the HAL 75 */ 76enum { 77 /* 78 * HWC_SKIP_LAYER is set by SurfaceFlnger to indicate that the HAL 79 * shall not consider this layer for composition as it will be handled 80 * by SurfaceFlinger (just as if compositionType was set to HWC_OVERLAY). 81 */ 82 HWC_SKIP_LAYER = 0x00000001, 83}; 84 85/* 86 * hwc_layer_t::compositionType values 87 */ 88enum { 89 /* this layer is to be drawn into the framebuffer by SurfaceFlinger */ 90 HWC_FRAMEBUFFER = 0, 91 92 /* this layer will be handled in the HWC */ 93 HWC_OVERLAY = 1, 94}; 95 96/* 97 * hwc_layer_t::blending values 98 */ 99enum { 100 /* no blending */ 101 HWC_BLENDING_NONE = 0x0100, 102 103 /* ONE / ONE_MINUS_SRC_ALPHA */ 104 HWC_BLENDING_PREMULT = 0x0105, 105 106 /* SRC_ALPHA / ONE_MINUS_SRC_ALPHA */ 107 HWC_BLENDING_COVERAGE = 0x0405 108}; 109 110/* 111 * hwc_layer_t::transform values 112 */ 113enum { 114 /* flip source image horizontally */ 115 HWC_TRANSFORM_FLIP_H = HAL_TRANSFORM_FLIP_H, 116 /* flip source image vertically */ 117 HWC_TRANSFORM_FLIP_V = HAL_TRANSFORM_FLIP_V, 118 /* rotate source image 90 degrees clock-wise */ 119 HWC_TRANSFORM_ROT_90 = HAL_TRANSFORM_ROT_90, 120 /* rotate source image 180 degrees */ 121 HWC_TRANSFORM_ROT_180 = HAL_TRANSFORM_ROT_180, 122 /* rotate source image 270 degrees clock-wise */ 123 HWC_TRANSFORM_ROT_270 = HAL_TRANSFORM_ROT_270, 124}; 125 126typedef struct hwc_rect { 127 int left; 128 int top; 129 int right; 130 int bottom; 131} hwc_rect_t; 132 133typedef struct hwc_region { 134 size_t numRects; 135 hwc_rect_t const* rects; 136} hwc_region_t; 137 138typedef struct hwc_layer { 139 /* 140 * initially set to HWC_FRAMEBUFFER, indicates the layer will 141 * be drawn into the framebuffer using OpenGL ES. 142 * The HWC can toggle this value to HWC_OVERLAY, to indicate 143 * it will handle the layer. 144 */ 145 int32_t compositionType; 146 147 /* see hwc_layer_t::hints above */ 148 uint32_t hints; 149 150 /* see hwc_layer_t::flags above */ 151 uint32_t flags; 152 153 /* handle of buffer to compose. this handle is guaranteed to have been 154 * allocated with gralloc */ 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} hwc_layer_t; 179 180 181/* 182 * hwc_layer_list_t::flags values 183 */ 184enum { 185 /* 186 * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list 187 * passed to (*prepare)() has changed by more than just the buffer handles. 188 */ 189 HWC_GEOMETRY_CHANGED = 0x00000001, 190}; 191 192/* 193 * List of layers. 194 * The handle members of hwLayers elements must be unique. 195 */ 196typedef struct hwc_layer_list { 197 uint32_t flags; 198 size_t numHwLayers; 199 hwc_layer_t hwLayers[0]; 200} hwc_layer_list_t; 201 202/* This represents a display, typically an EGLDisplay object */ 203typedef void* hwc_display_t; 204 205/* This represents a surface, typically an EGLSurface object */ 206typedef void* hwc_surface_t; 207 208/*****************************************************************************/ 209 210 211typedef struct hwc_module { 212 struct hw_module_t common; 213} hwc_module_t; 214 215 216typedef struct hwc_composer_device { 217 struct hw_device_t common; 218 219 /* 220 * (*prepare)() is called for each frame before composition and is used by 221 * SurfaceFlinger to determine what composition steps the HWC can handle. 222 * 223 * (*prepare)() can be called more than once, the last call prevails. 224 * 225 * The HWC responds by setting the compositionType field to either 226 * HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the composition for 227 * this layer is handled by SurfaceFlinger with OpenGL ES, in the later 228 * case, the HWC will have to handle this layer's composition. 229 * 230 * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the 231 * list's geometry has changed, that is, when more than just the buffer's 232 * handles have been updated. Typically this happens (but is not limited to) 233 * when a window is added, removed, resized or moved. 234 * 235 * a NULL list parameter or a numHwLayers of zero indicates that the 236 * entire composition will be handled by SurfaceFlinger with OpenGL ES. 237 * 238 * returns: 0 on success. An negative error code on error. If an error is 239 * returned, SurfaceFlinger will assume that none of the layer will be 240 * handled by the HWC. 241 */ 242 int (*prepare)(struct hwc_composer_device *dev, hwc_layer_list_t* list); 243 244 245 /* 246 * (*set)() is used in place of eglSwapBuffers(), and assumes the same 247 * functionality, except it also commits the work list atomically with 248 * the actual eglSwapBuffers(). 249 * 250 * The list parameter is guaranteed to be the same as the one returned 251 * from the last call to (*prepare)(). 252 * 253 * When this call returns the caller assumes that: 254 * 255 * - the display will be updated in the near future with the content 256 * of the work list, without artifacts during the transition from the 257 * previous frame. 258 * 259 * - all objects are available for immediate access or destruction, in 260 * particular, hwc_region_t::rects data and hwc_layer_t::layer's buffer. 261 * Note that this means that immediately accessing (potentially from a 262 * different process) a buffer used in this call will not result in 263 * screen corruption, the driver must apply proper synchronization or 264 * scheduling (eg: block the caller, such as gralloc_module_t::lock(), 265 * OpenGL ES, Camera, Codecs, etc..., or schedule the caller's work 266 * after the buffer is freed from the actual composition). 267 * 268 * a NULL list parameter or a numHwLayers of zero indicates that the 269 * entire composition has been handled by SurfaceFlinger with OpenGL ES. 270 * In this case, (*set)() behaves just like eglSwapBuffers(). 271 * 272 * returns: 0 on success. An negative error code on error: 273 * HWC_EGL_ERROR: eglGetError() will provide the proper error code 274 * Another code for non EGL errors. 275 * 276 */ 277 int (*set)(struct hwc_composer_device *dev, 278 hwc_display_t dpy, 279 hwc_surface_t sur, 280 hwc_layer_list_t* list); 281 282 void* reserved_proc[8]; 283 284} hwc_composer_device_t; 285 286 287/** convenience API for opening and closing a device */ 288 289static inline int hwc_open(const struct hw_module_t* module, 290 hwc_composer_device_t** device) { 291 return module->methods->open(module, 292 HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device); 293} 294 295static inline int hwc_close(hwc_composer_device_t* device) { 296 return device->common.close(&device->common); 297} 298 299 300/*****************************************************************************/ 301 302__END_DECLS 303 304#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */ 305