| 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 | |
| 28 | struct 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 | */ |
| 37 | typedef 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 | |
| 62 | typedef 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 | */ |
| 129 | typedef 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 | |
| 137 | typedef 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 | |
| 260 | static 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 | |
| 266 | static 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 */ |