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