hardware/hwcomposer_v0.h

   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 */