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/* This header contains deprecated HWCv0 interface declarations. Don't include 18 * this header directly; it will be included by <hardware/hwcomposer.h> unless 19 * HWC_REMOVE_DEPRECATED_VERSIONS is defined to non-zero. 20 */ 21#ifndef ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H 22#error "This header should only be included by hardware/hwcomposer.h" 23#endif 24 25#ifndef ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_V0_H 26#define ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_V0_H 27 28struct hwc_composer_device; 29 30/* 31 * availability: HWC_DEVICE_API_VERSION_0_3 32 * 33 * struct hwc_methods cannot be embedded in other structures as 34 * sizeof(struct hwc_methods) cannot be relied upon. 35 * 36 */ 37typedef struct hwc_methods { 38 39 /************************************************************************* 40 * HWC_DEVICE_API_VERSION_0_3 41 *************************************************************************/ 42 43 /* 44 * eventControl(..., event, enabled) 45 * Enables or disables h/w composer events. 46 * 47 * eventControl can be called from any thread and takes effect 48 * immediately. 49 * 50 * Supported events are: 51 * HWC_EVENT_VSYNC 52 * 53 * returns -EINVAL if the "event" parameter is not one of the value above 54 * or if the "enabled" parameter is not 0 or 1. 55 */ 56 57 int (*eventControl)( 58 struct hwc_composer_device* dev, int event, int enabled); 59 60} hwc_methods_t; 61 62typedef struct hwc_layer { 63 /* 64 * initially set to HWC_FRAMEBUFFER or HWC_BACKGROUND. 65 * HWC_FRAMEBUFFER 66 * indicates the layer will be drawn into the framebuffer 67 * using OpenGL ES. 68 * The HWC can toggle this value to HWC_OVERLAY, to indicate 69 * it will handle the layer. 70 * 71 * HWC_BACKGROUND 72 * indicates this is a special "background" layer. The only valid 73 * field is backgroundColor. HWC_BACKGROUND can only be used with 74 * HWC_API_VERSION >= 0.2 75 * The HWC can toggle this value to HWC_FRAMEBUFFER, to indicate 76 * it CANNOT handle the background color 77 * 78 */ 79 int32_t compositionType; 80 81 /* see hwc_layer_t::hints above */ 82 uint32_t hints; 83 84 /* see hwc_layer_t::flags above */ 85 uint32_t flags; 86 87 union { 88 /* color of the background. hwc_color_t.a is ignored */ 89 hwc_color_t backgroundColor; 90 91 struct { 92 /* handle of buffer to compose. This handle is guaranteed to have been 93 * allocated from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag. If 94 * the layer's handle is unchanged across two consecutive prepare calls and 95 * the HWC_GEOMETRY_CHANGED flag is not set for the second call then the 96 * HWComposer implementation may assume that the contents of the buffer have 97 * not changed. */ 98 buffer_handle_t handle; 99 100 /* transformation to apply to the buffer during composition */ 101 uint32_t transform; 102 103 /* blending to apply during composition */ 104 int32_t blending; 105 106 /* area of the source to consider, the origin is the top-left corner of 107 * the buffer */ 108 hwc_rect_t sourceCrop; 109 110 /* where to composite the sourceCrop onto the display. The sourceCrop 111 * is scaled using linear filtering to the displayFrame. The origin is the 112 * top-left corner of the screen. 113 */ 114 hwc_rect_t displayFrame; 115 116 /* visible region in screen space. The origin is the 117 * top-left corner of the screen. 118 * The visible region INCLUDES areas overlapped by a translucent layer. 119 */ 120 hwc_region_t visibleRegionScreen; 121 }; 122 }; 123} hwc_layer_t; 124 125/* 126 * List of layers. 127 * The handle members of hwLayers elements must be unique. 128 */ 129typedef struct hwc_layer_list { 130 uint32_t flags; 131 size_t numHwLayers; 132 hwc_layer_t hwLayers[0]; 133} hwc_layer_list_t; 134 135/*****************************************************************************/ 136 137typedef struct hwc_composer_device { 138 struct hw_device_t common; 139 140 /* 141 * (*prepare)() is called for each frame before composition and is used by 142 * SurfaceFlinger to determine what composition steps the HWC can handle. 143 * 144 * (*prepare)() can be called more than once, the last call prevails. 145 * 146 * The HWC responds by setting the compositionType field to either 147 * HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the composition for 148 * this layer is handled by SurfaceFlinger with OpenGL ES, in the later 149 * case, the HWC will have to handle this layer's composition. 150 * 151 * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the 152 * list's geometry has changed, that is, when more than just the buffer's 153 * handles have been updated. Typically this happens (but is not limited to) 154 * when a window is added, removed, resized or moved. 155 * 156 * a NULL list parameter or a numHwLayers of zero indicates that the 157 * entire composition will be handled by SurfaceFlinger with OpenGL ES. 158 * 159 * returns: 0 on success. An negative error code on error. If an error is 160 * returned, SurfaceFlinger will assume that none of the layer will be 161 * handled by the HWC. 162 */ 163 int (*prepare)(struct hwc_composer_device *dev, hwc_layer_list_t* list); 164 165 /* 166 * (*set)() is used in place of eglSwapBuffers(), and assumes the same 167 * functionality, except it also commits the work list atomically with 168 * the actual eglSwapBuffers(). 169 * 170 * The list parameter is guaranteed to be the same as the one returned 171 * from the last call to (*prepare)(). 172 * 173 * When this call returns the caller assumes that: 174 * 175 * - the display will be updated in the near future with the content 176 * of the work list, without artifacts during the transition from the 177 * previous frame. 178 * 179 * - all objects are available for immediate access or destruction, in 180 * particular, hwc_region_t::rects data and hwc_layer_t::layer's buffer. 181 * Note that this means that immediately accessing (potentially from a 182 * different process) a buffer used in this call will not result in 183 * screen corruption, the driver must apply proper synchronization or 184 * scheduling (eg: block the caller, such as gralloc_module_t::lock(), 185 * OpenGL ES, Camera, Codecs, etc..., or schedule the caller's work 186 * after the buffer is freed from the actual composition). 187 * 188 * a NULL list parameter or a numHwLayers of zero indicates that the 189 * entire composition has been handled by SurfaceFlinger with OpenGL ES. 190 * In this case, (*set)() behaves just like eglSwapBuffers(). 191 * 192 * dpy, sur, and list are set to NULL to indicate that the screen is 193 * turning off. This happens WITHOUT prepare() being called first. 194 * This is a good time to free h/w resources and/or power 195 * the relevant h/w blocks down. 196 * 197 * IMPORTANT NOTE: there is an implicit layer containing opaque black 198 * pixels behind all the layers in the list. 199 * It is the responsibility of the hwcomposer module to make 200 * sure black pixels are output (or blended from). 201 * 202 * returns: 0 on success. An negative error code on error: 203 * HWC_EGL_ERROR: eglGetError() will provide the proper error code 204 * Another code for non EGL errors. 205 * 206 */ 207 int (*set)(struct hwc_composer_device *dev, 208 hwc_display_t dpy, 209 hwc_surface_t sur, 210 hwc_layer_list_t* list); 211 212 /* 213 * This field is OPTIONAL and can be NULL. 214 * 215 * If non NULL it will be called by SurfaceFlinger on dumpsys 216 */ 217 void (*dump)(struct hwc_composer_device* dev, char *buff, int buff_len); 218 219 /* 220 * This field is OPTIONAL and can be NULL. 221 * 222 * (*registerProcs)() registers a set of callbacks the h/w composer HAL 223 * can later use. It is FORBIDDEN to call any of the callbacks from 224 * within registerProcs(). registerProcs() must save the hwc_procs_t pointer 225 * which is needed when calling a registered callback. 226 * Each call to registerProcs replaces the previous set of callbacks. 227 * registerProcs is called with NULL to unregister all callbacks. 228 * 229 * Any of the callbacks can be NULL, in which case the corresponding 230 * functionality is not supported. 231 */ 232 void (*registerProcs)(struct hwc_composer_device* dev, 233 hwc_procs_t const* procs); 234 235 /* 236 * This field is OPTIONAL and can be NULL. 237 * availability: HWC_DEVICE_API_VERSION_0_2 238 * 239 * Used to retrieve information about the h/w composer 240 * 241 * Returns 0 on success or -errno on error. 242 */ 243 int (*query)(struct hwc_composer_device* dev, int what, int* value); 244 245 /* 246 * Reserved for future use. Must be NULL. 247 */ 248 void* reserved_proc[4]; 249 250 /* 251 * This field is OPTIONAL and can be NULL. 252 * availability: HWC_DEVICE_API_VERSION_0_3 253 */ 254 hwc_methods_t const *methods; 255 256} hwc_composer_device_t; 257 258/** convenience API for opening and closing a device */ 259 260static inline int hwc_open(const struct hw_module_t* module, 261 hwc_composer_device_t** device) { 262 return module->methods->open(module, 263 HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device); 264} 265 266static inline int hwc_close(hwc_composer_device_t* device) { 267 return device->common.close(&device->common); 268} 269 270/*****************************************************************************/ 271 272#endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_V0_H */ 273