Home | History | Annotate | Download | only in hardware
      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 #include <hardware/hwcomposer_defs.h>
     28 
     29 __BEGIN_DECLS
     30 
     31 /*****************************************************************************/
     32 
     33 /* for compatibility */
     34 #define HWC_MODULE_API_VERSION      HWC_MODULE_API_VERSION_0_1
     35 #define HWC_DEVICE_API_VERSION      HWC_DEVICE_API_VERSION_0_1
     36 #define HWC_API_VERSION             HWC_DEVICE_API_VERSION
     37 
     38 /*****************************************************************************/
     39 
     40 typedef struct hwc_layer_1 {
     41     /*
     42      * compositionType is used to specify this layer's type and is set by either
     43      * the hardware composer implementation, or by the caller (see below).
     44      *
     45      *  This field is always reset to HWC_BACKGROUND or HWC_FRAMEBUFFER
     46      *  before (*prepare)() is called when the HWC_GEOMETRY_CHANGED flag is
     47      *  also set, otherwise, this field is preserved between (*prepare)()
     48      *  calls.
     49      *
     50      * HWC_BACKGROUND
     51      *   Always set by the caller before calling (*prepare)(), this value
     52      *   indicates this is a special "background" layer. The only valid field
     53      *   is backgroundColor.
     54      *   The HWC can toggle this value to HWC_FRAMEBUFFER to indicate it CANNOT
     55      *   handle the background color.
     56      *
     57      *
     58      * HWC_FRAMEBUFFER_TARGET
     59      *   Always set by the caller before calling (*prepare)(), this value
     60      *   indicates this layer is the framebuffer surface used as the target of
     61      *   OpenGL ES composition. If the HWC sets all other layers to HWC_OVERLAY
     62      *   or HWC_BACKGROUND, then no OpenGL ES composition will be done, and
     63      *   this layer should be ignored during set().
     64      *
     65      *   This flag (and the framebuffer surface layer) will only be used if the
     66      *   HWC version is HWC_DEVICE_API_VERSION_1_1 or higher. In older versions,
     67      *   the OpenGL ES target surface is communicated by the (dpy, sur) fields
     68      *   in hwc_compositor_device_1_t.
     69      *
     70      *   This value cannot be set by the HWC implementation.
     71      *
     72      *
     73      * HWC_FRAMEBUFFER
     74      *   Set by the caller before calling (*prepare)() ONLY when the
     75      *   HWC_GEOMETRY_CHANGED flag is also set.
     76      *
     77      *   Set by the HWC implementation during (*prepare)(), this indicates
     78      *   that the layer will be drawn into the framebuffer using OpenGL ES.
     79      *   The HWC can toggle this value to HWC_OVERLAY to indicate it will
     80      *   handle the layer.
     81      *
     82      *
     83      * HWC_OVERLAY
     84      *   Set by the HWC implementation during (*prepare)(), this indicates
     85      *   that the layer will be handled by the HWC (ie: it must not be
     86      *   composited with OpenGL ES).
     87      *
     88      *
     89      * HWC_SIDEBAND
     90      *   Set by the caller before calling (*prepare)(), this value indicates
     91      *   the contents of this layer come from a sideband video stream.
     92      *
     93      *   The h/w composer is responsible for receiving new image buffers from
     94      *   the stream at the appropriate time (e.g. synchronized to a separate
     95      *   audio stream), compositing them with the current contents of other
     96      *   layers, and displaying the resulting image. This happens
     97      *   independently of the normal prepare/set cycle. The prepare/set calls
     98      *   only happen when other layers change, or when properties of the
     99      *   sideband layer such as position or size change.
    100      *
    101      *   If the h/w composer can't handle the layer as a sideband stream for
    102      *   some reason (e.g. unsupported scaling/blending/rotation, or too many
    103      *   sideband layers) it can set compositionType to HWC_FRAMEBUFFER in
    104      *   (*prepare)(). However, doing so will result in the layer being shown
    105      *   as a solid color since the platform is not currently able to composite
    106      *   sideband layers with the GPU. This may be improved in future
    107      *   versions of the platform.
    108      *
    109      *
    110      * HWC_CURSOR_OVERLAY
    111      *   Set by the HWC implementation during (*prepare)(), this value
    112      *   indicates the layer's composition will now be handled by the HWC.
    113      *   Additionally, the client can now asynchronously update the on-screen
    114      *   position of this layer using the setCursorPositionAsync() api.
    115      */
    116     int32_t compositionType;
    117 
    118     /*
    119      * hints is bit mask set by the HWC implementation during (*prepare)().
    120      * It is preserved between (*prepare)() calls, unless the
    121      * HWC_GEOMETRY_CHANGED flag is set, in which case it is reset to 0.
    122      *
    123      * see hwc_layer_t::hints
    124      */
    125     uint32_t hints;
    126 
    127     /* see hwc_layer_t::flags */
    128     uint32_t flags;
    129 
    130     union {
    131         /* color of the background.  hwc_color_t.a is ignored */
    132         hwc_color_t backgroundColor;
    133 
    134         struct {
    135             union {
    136                 /* When compositionType is HWC_FRAMEBUFFER, HWC_OVERLAY,
    137                  * HWC_FRAMEBUFFER_TARGET, this is the handle of the buffer to
    138                  * compose. This handle is guaranteed to have been allocated
    139                  * from gralloc using the GRALLOC_USAGE_HW_COMPOSER usage flag.
    140                  * If the layer's handle is unchanged across two consecutive
    141                  * prepare calls and the HWC_GEOMETRY_CHANGED flag is not set
    142                  * for the second call then the HWComposer implementation may
    143                  * assume that the contents of the buffer have not changed. */
    144                 buffer_handle_t handle;
    145 
    146                 /* When compositionType is HWC_SIDEBAND, this is the handle
    147                  * of the sideband video stream to compose. */
    148                 const native_handle_t* sidebandStream;
    149             };
    150 
    151             /* transformation to apply to the buffer during composition */
    152             uint32_t transform;
    153 
    154             /* blending to apply during composition */
    155             int32_t blending;
    156 
    157             /* area of the source to consider, the origin is the top-left corner of
    158              * the buffer. As of HWC_DEVICE_API_VERSION_1_3, sourceRect uses floats.
    159              * If the h/w can't support a non-integer source crop rectangle, it should
    160              * punt to OpenGL ES composition.
    161              */
    162             union {
    163                 // crop rectangle in integer (pre HWC_DEVICE_API_VERSION_1_3)
    164                 hwc_rect_t sourceCropi;
    165                 hwc_rect_t sourceCrop; // just for source compatibility
    166                 // crop rectangle in floats (as of HWC_DEVICE_API_VERSION_1_3)
    167                 hwc_frect_t sourceCropf;
    168             };
    169 
    170             /* where to composite the sourceCrop onto the display. The sourceCrop
    171              * is scaled using linear filtering to the displayFrame. The origin is the
    172              * top-left corner of the screen.
    173              */
    174             hwc_rect_t displayFrame;
    175 
    176             /* visible region in screen space. The origin is the
    177              * top-left corner of the screen.
    178              * The visible region INCLUDES areas overlapped by a translucent layer.
    179              */
    180             hwc_region_t visibleRegionScreen;
    181 
    182             /* Sync fence object that will be signaled when the buffer's
    183              * contents are available. May be -1 if the contents are already
    184              * available. This field is only valid during set(), and should be
    185              * ignored during prepare(). The set() call must not wait for the
    186              * fence to be signaled before returning, but the HWC must wait for
    187              * all buffers to be signaled before reading from them.
    188              *
    189              * HWC_FRAMEBUFFER layers will never have an acquire fence, since
    190              * reads from them are complete before the framebuffer is ready for
    191              * display.
    192              *
    193              * HWC_SIDEBAND layers will never have an acquire fence, since
    194              * synchronization is handled through implementation-defined
    195              * sideband mechanisms.
    196              *
    197              * The HWC takes ownership of the acquireFenceFd and is responsible
    198              * for closing it when no longer needed.
    199              */
    200             int acquireFenceFd;
    201 
    202             /* During set() the HWC must set this field to a file descriptor for
    203              * a sync fence object that will signal after the HWC has finished
    204              * reading from the buffer. The field is ignored by prepare(). Each
    205              * layer should have a unique file descriptor, even if more than one
    206              * refer to the same underlying fence object; this allows each to be
    207              * closed independently.
    208              *
    209              * If buffer reads can complete at significantly different times,
    210              * then using independent fences is preferred. For example, if the
    211              * HWC handles some layers with a blit engine and others with
    212              * overlays, then the blit layers can be reused immediately after
    213              * the blit completes, but the overlay layers can't be reused until
    214              * a subsequent frame has been displayed.
    215              *
    216              * Since HWC doesn't read from HWC_FRAMEBUFFER layers, it shouldn't
    217              * produce a release fence for them. The releaseFenceFd will be -1
    218              * for these layers when set() is called.
    219              *
    220              * Since HWC_SIDEBAND buffers don't pass through the HWC client,
    221              * the HWC shouldn't produce a release fence for them. The
    222              * releaseFenceFd will be -1 for these layers when set() is called.
    223              *
    224              * The HWC client taks ownership of the releaseFenceFd and is
    225              * responsible for closing it when no longer needed.
    226              */
    227             int releaseFenceFd;
    228 
    229             /*
    230              * Availability: HWC_DEVICE_API_VERSION_1_2
    231              *
    232              * Alpha value applied to the whole layer. The effective
    233              * value of each pixel is computed as:
    234              *
    235              *   if (blending == HWC_BLENDING_PREMULT)
    236              *      pixel.rgb = pixel.rgb * planeAlpha / 255
    237              *   pixel.a = pixel.a * planeAlpha / 255
    238              *
    239              * Then blending proceeds as usual according to the "blending"
    240              * field above.
    241              *
    242              * NOTE: planeAlpha applies to YUV layers as well:
    243              *
    244              *   pixel.rgb = yuv_to_rgb(pixel.yuv)
    245              *   if (blending == HWC_BLENDING_PREMULT)
    246              *      pixel.rgb = pixel.rgb * planeAlpha / 255
    247              *   pixel.a = planeAlpha
    248              *
    249              *
    250              * IMPLEMENTATION NOTE:
    251              *
    252              * If the source image doesn't have an alpha channel, then
    253              * the h/w can use the HWC_BLENDING_COVERAGE equations instead of
    254              * HWC_BLENDING_PREMULT and simply set the alpha channel to
    255              * planeAlpha.
    256              *
    257              * e.g.:
    258              *
    259              *   if (blending == HWC_BLENDING_PREMULT)
    260              *      blending = HWC_BLENDING_COVERAGE;
    261              *   pixel.a = planeAlpha;
    262              *
    263              */
    264             uint8_t planeAlpha;
    265 
    266             /* Pad to 32 bits */
    267             uint8_t _pad[3];
    268 
    269             /*
    270              * Availability: HWC_DEVICE_API_VERSION_1_5
    271              *
    272              * This defines the region of the source buffer that has been
    273              * modified since the last frame.
    274              *
    275              * If surfaceDamage.numRects > 0, then it may be assumed that any
    276              * portion of the source buffer not covered by one of the rects has
    277              * not been modified this frame. If surfaceDamage.numRects == 0,
    278              * then the whole source buffer must be treated as if it had been
    279              * modified.
    280              *
    281              * If the layer's contents are not modified relative to the prior
    282              * prepare/set cycle, surfaceDamage will contain exactly one empty
    283              * rect ([0, 0, 0, 0]).
    284              *
    285              * The damage rects are relative to the pre-transformed buffer, and
    286              * their origin is the top-left corner.
    287              */
    288             hwc_region_t surfaceDamage;
    289         };
    290     };
    291 
    292 #ifdef __LP64__
    293     /*
    294      * For 64-bit mode, this struct is 120 bytes (and 8-byte aligned), and needs
    295      * to be padded as such to maintain binary compatibility.
    296      */
    297     uint8_t reserved[120 - 112];
    298 #else
    299     /*
    300      * For 32-bit mode, this struct is 96 bytes, and needs to be padded as such
    301      * to maintain binary compatibility.
    302      */
    303     uint8_t reserved[96 - 84];
    304 #endif
    305 
    306 } hwc_layer_1_t;
    307 
    308 /* This represents a display, typically an EGLDisplay object */
    309 typedef void* hwc_display_t;
    310 
    311 /* This represents a surface, typically an EGLSurface object  */
    312 typedef void* hwc_surface_t;
    313 
    314 /*
    315  * hwc_display_contents_1_t::flags values
    316  */
    317 enum {
    318     /*
    319      * HWC_GEOMETRY_CHANGED is set by SurfaceFlinger to indicate that the list
    320      * passed to (*prepare)() has changed by more than just the buffer handles
    321      * and acquire fences.
    322      */
    323     HWC_GEOMETRY_CHANGED = 0x00000001,
    324 };
    325 
    326 /*
    327  * Description of the contents to output on a display.
    328  *
    329  * This is the top-level structure passed to the prepare and set calls to
    330  * negotiate and commit the composition of a display image.
    331  */
    332 typedef struct hwc_display_contents_1 {
    333     /* File descriptor referring to a Sync HAL fence object which will signal
    334      * when this composition is retired. For a physical display, a composition
    335      * is retired when it has been replaced on-screen by a subsequent set. For
    336      * a virtual display, the composition is retired when the writes to
    337      * outputBuffer are complete and can be read. The fence object is created
    338      * and returned by the set call; this field will be -1 on entry to prepare
    339      * and set. SurfaceFlinger will close the returned file descriptor.
    340      */
    341     int retireFenceFd;
    342 
    343     union {
    344         /* Fields only relevant for HWC_DEVICE_VERSION_1_0. */
    345         struct {
    346             /* (dpy, sur) is the target of SurfaceFlinger's OpenGL ES
    347              * composition for HWC_DEVICE_VERSION_1_0. They aren't relevant to
    348              * prepare. The set call should commit this surface atomically to
    349              * the display along with any overlay layers.
    350              */
    351             hwc_display_t dpy;
    352             hwc_surface_t sur;
    353         };
    354 
    355         /* These fields are used for virtual displays when the h/w composer
    356          * version is at least HWC_DEVICE_VERSION_1_3. */
    357         struct {
    358             /* outbuf is the buffer that receives the composed image for
    359              * virtual displays. Writes to the outbuf must wait until
    360              * outbufAcquireFenceFd signals. A fence that will signal when
    361              * writes to outbuf are complete should be returned in
    362              * retireFenceFd.
    363              *
    364              * This field is set before prepare(), so properties of the buffer
    365              * can be used to decide which layers can be handled by h/w
    366              * composer.
    367              *
    368              * If prepare() sets all layers to FRAMEBUFFER, then GLES
    369              * composition will happen directly to the output buffer. In this
    370              * case, both outbuf and the FRAMEBUFFER_TARGET layer's buffer will
    371              * be the same, and set() has no work to do besides managing fences.
    372              *
    373              * If the TARGET_FORCE_HWC_FOR_VIRTUAL_DISPLAYS board config
    374              * variable is defined (not the default), then this behavior is
    375              * changed: if all layers are marked for FRAMEBUFFER, GLES
    376              * composition will take place to a scratch framebuffer, and
    377              * h/w composer must copy it to the output buffer. This allows the
    378              * h/w composer to do format conversion if there are cases where
    379              * that is more desirable than doing it in the GLES driver or at the
    380              * virtual display consumer.
    381              *
    382              * If some or all layers are marked OVERLAY, then the framebuffer
    383              * and output buffer will be different. As with physical displays,
    384              * the framebuffer handle will not change between frames if all
    385              * layers are marked for OVERLAY.
    386              */
    387             buffer_handle_t outbuf;
    388 
    389             /* File descriptor for a fence that will signal when outbuf is
    390              * ready to be written. The h/w composer is responsible for closing
    391              * this when no longer needed.
    392              *
    393              * Will be -1 whenever outbuf is NULL, or when the outbuf can be
    394              * written immediately.
    395              */
    396             int outbufAcquireFenceFd;
    397         };
    398     };
    399 
    400     /* List of layers that will be composed on the display. The buffer handles
    401      * in the list will be unique. If numHwLayers is 0, all composition will be
    402      * performed by SurfaceFlinger.
    403      */
    404     uint32_t flags;
    405     size_t numHwLayers;
    406     hwc_layer_1_t hwLayers[0];
    407 
    408 } hwc_display_contents_1_t;
    409 
    410 /* see hwc_composer_device::registerProcs()
    411  * All of the callbacks are required and non-NULL unless otherwise noted.
    412  */
    413 typedef struct hwc_procs {
    414     /*
    415      * (*invalidate)() triggers a screen refresh, in particular prepare and set
    416      * will be called shortly after this call is made. Note that there is
    417      * NO GUARANTEE that the screen refresh will happen after invalidate()
    418      * returns (in particular, it could happen before).
    419      * invalidate() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL and
    420      * it is safe to call invalidate() from any of hwc_composer_device
    421      * hooks, unless noted otherwise.
    422      */
    423     void (*invalidate)(const struct hwc_procs* procs);
    424 
    425     /*
    426      * (*vsync)() is called by the h/w composer HAL when a vsync event is
    427      * received and HWC_EVENT_VSYNC is enabled on a display
    428      * (see: hwc_event_control).
    429      *
    430      * the "disp" parameter indicates which display the vsync event is for.
    431      * the "timestamp" parameter is the system monotonic clock timestamp in
    432      *   nanosecond of when the vsync event happened.
    433      *
    434      * vsync() is GUARANTEED TO NOT CALL BACK into the h/w composer HAL.
    435      *
    436      * It is expected that vsync() is called from a thread of at least
    437      * HAL_PRIORITY_URGENT_DISPLAY with as little latency as possible,
    438      * typically less than 0.5 ms.
    439      *
    440      * It is a (silent) error to have HWC_EVENT_VSYNC enabled when calling
    441      * hwc_composer_device.set(..., 0, 0, 0) (screen off). The implementation
    442      * can either stop or continue to process VSYNC events, but must not
    443      * crash or cause other problems.
    444      */
    445     void (*vsync)(const struct hwc_procs* procs, int disp, int64_t timestamp);
    446 
    447     /*
    448      * (*hotplug)() is called by the h/w composer HAL when a display is
    449      * connected or disconnected. The PRIMARY display is always connected and
    450      * the hotplug callback should not be called for it.
    451      *
    452      * The disp parameter indicates which display type this event is for.
    453      * The connected parameter indicates whether the display has just been
    454      *   connected (1) or disconnected (0).
    455      *
    456      * The hotplug() callback may call back into the h/w composer on the same
    457      * thread to query refresh rate and dpi for the display. Additionally,
    458      * other threads may be calling into the h/w composer while the callback
    459      * is in progress.
    460      *
    461      * The h/w composer must serialize calls to the hotplug callback; only
    462      * one thread may call it at a time.
    463      *
    464      * This callback will be NULL if the h/w composer is using
    465      * HWC_DEVICE_API_VERSION_1_0.
    466      */
    467     void (*hotplug)(const struct hwc_procs* procs, int disp, int connected);
    468 
    469 } hwc_procs_t;
    470 
    471 
    472 /*****************************************************************************/
    473 
    474 typedef struct hwc_module {
    475     /**
    476      * Common methods of the hardware composer module.  This *must* be the first member of
    477      * hwc_module as users of this structure will cast a hw_module_t to
    478      * hwc_module pointer in contexts where it's known the hw_module_t references a
    479      * hwc_module.
    480      */
    481     struct hw_module_t common;
    482 } hwc_module_t;
    483 
    484 typedef struct hwc_composer_device_1 {
    485     /**
    486      * Common methods of the hardware composer device.  This *must* be the first member of
    487      * hwc_composer_device_1 as users of this structure will cast a hw_device_t to
    488      * hwc_composer_device_1 pointer in contexts where it's known the hw_device_t references a
    489      * hwc_composer_device_1.
    490      */
    491     struct hw_device_t common;
    492 
    493     /*
    494      * (*prepare)() is called for each frame before composition and is used by
    495      * SurfaceFlinger to determine what composition steps the HWC can handle.
    496      *
    497      * (*prepare)() can be called more than once, the last call prevails.
    498      *
    499      * The HWC responds by setting the compositionType field in each layer to
    500      * either HWC_FRAMEBUFFER, HWC_OVERLAY, or HWC_CURSOR_OVERLAY. For the
    501      * HWC_FRAMEBUFFER type, composition for the layer is handled by
    502      * SurfaceFlinger with OpenGL ES. For the latter two overlay types,
    503      * the HWC will have to handle the layer's composition. compositionType
    504      * and hints are preserved between (*prepare)() calles unless the
    505      * HWC_GEOMETRY_CHANGED flag is set.
    506      *
    507      * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the
    508      * list's geometry has changed, that is, when more than just the buffer's
    509      * handles have been updated. Typically this happens (but is not limited to)
    510      * when a window is added, removed, resized or moved. In this case
    511      * compositionType and hints are reset to their default value.
    512      *
    513      * For HWC 1.0, numDisplays will always be one, and displays[0] will be
    514      * non-NULL.
    515      *
    516      * For HWC 1.1, numDisplays will always be HWC_NUM_PHYSICAL_DISPLAY_TYPES.
    517      * Entries for unsupported or disabled/disconnected display types will be
    518      * NULL.
    519      *
    520      * In HWC 1.3, numDisplays may be up to HWC_NUM_DISPLAY_TYPES. The extra
    521      * entries correspond to enabled virtual displays, and will be non-NULL.
    522      *
    523      * returns: 0 on success. An negative error code on error. If an error is
    524      * returned, SurfaceFlinger will assume that none of the layer will be
    525      * handled by the HWC.
    526      */
    527     int (*prepare)(struct hwc_composer_device_1 *dev,
    528                     size_t numDisplays, hwc_display_contents_1_t** displays);
    529 
    530     /*
    531      * (*set)() is used in place of eglSwapBuffers(), and assumes the same
    532      * functionality, except it also commits the work list atomically with
    533      * the actual eglSwapBuffers().
    534      *
    535      * The layer lists are guaranteed to be the same as the ones returned from
    536      * the last call to (*prepare)().
    537      *
    538      * When this call returns the caller assumes that the displays will be
    539      * updated in the near future with the content of their work lists, without
    540      * artifacts during the transition from the previous frame.
    541      *
    542      * A display with zero layers indicates that the entire composition has
    543      * been handled by SurfaceFlinger with OpenGL ES. In this case, (*set)()
    544      * behaves just like eglSwapBuffers().
    545      *
    546      * For HWC 1.0, numDisplays will always be one, and displays[0] will be
    547      * non-NULL.
    548      *
    549      * For HWC 1.1, numDisplays will always be HWC_NUM_PHYSICAL_DISPLAY_TYPES.
    550      * Entries for unsupported or disabled/disconnected display types will be
    551      * NULL.
    552      *
    553      * In HWC 1.3, numDisplays may be up to HWC_NUM_DISPLAY_TYPES. The extra
    554      * entries correspond to enabled virtual displays, and will be non-NULL.
    555      *
    556      * IMPORTANT NOTE: There is an implicit layer containing opaque black
    557      * pixels behind all the layers in the list. It is the responsibility of
    558      * the hwcomposer module to make sure black pixels are output (or blended
    559      * from).
    560      *
    561      * IMPORTANT NOTE: In the event of an error this call *MUST* still cause
    562      * any fences returned in the previous call to set to eventually become
    563      * signaled.  The caller may have already issued wait commands on these
    564      * fences, and having set return without causing those fences to signal
    565      * will likely result in a deadlock.
    566      *
    567      * returns: 0 on success. A negative error code on error:
    568      *    HWC_EGL_ERROR: eglGetError() will provide the proper error code (only
    569      *        allowed prior to HWComposer 1.1)
    570      *    Another code for non EGL errors.
    571      */
    572     int (*set)(struct hwc_composer_device_1 *dev,
    573                 size_t numDisplays, hwc_display_contents_1_t** displays);
    574 
    575     /*
    576      * eventControl(..., event, enabled)
    577      * Enables or disables h/w composer events for a display.
    578      *
    579      * eventControl can be called from any thread and takes effect
    580      * immediately.
    581      *
    582      *  Supported events are:
    583      *      HWC_EVENT_VSYNC
    584      *
    585      * returns -EINVAL if the "event" parameter is not one of the value above
    586      * or if the "enabled" parameter is not 0 or 1.
    587      */
    588     int (*eventControl)(struct hwc_composer_device_1* dev, int disp,
    589             int event, int enabled);
    590 
    591     union {
    592         /*
    593          * For HWC 1.3 and earlier, the blank() interface is used.
    594          *
    595          * blank(..., blank)
    596          * Blanks or unblanks a display's screen.
    597          *
    598          * Turns the screen off when blank is nonzero, on when blank is zero.
    599          * Multiple sequential calls with the same blank value must be
    600          * supported.
    601          * The screen state transition must be be complete when the function
    602          * returns.
    603          *
    604          * returns 0 on success, negative on error.
    605          */
    606         int (*blank)(struct hwc_composer_device_1* dev, int disp, int blank);
    607 
    608         /*
    609          * For HWC 1.4 and above, setPowerMode() will be used in place of
    610          * blank().
    611          *
    612          * setPowerMode(..., mode)
    613          * Sets the display screen's power state.
    614          *
    615          * Refer to the documentation of the HWC_POWER_MODE_* constants
    616          * for information about each power mode.
    617          *
    618          * The functionality is similar to the blank() command in previous
    619          * versions of HWC, but with support for more power states.
    620          *
    621          * The display driver is expected to retain and restore the low power
    622          * state of the display while entering and exiting from suspend.
    623          *
    624          * Multiple sequential calls with the same mode value must be supported.
    625          *
    626          * The screen state transition must be be complete when the function
    627          * returns.
    628          *
    629          * returns 0 on success, negative on error.
    630          */
    631         int (*setPowerMode)(struct hwc_composer_device_1* dev, int disp,
    632                 int mode);
    633     };
    634 
    635     /*
    636      * Used to retrieve information about the h/w composer
    637      *
    638      * Returns 0 on success or -errno on error.
    639      */
    640     int (*query)(struct hwc_composer_device_1* dev, int what, int* value);
    641 
    642     /*
    643      * (*registerProcs)() registers callbacks that the h/w composer HAL can
    644      * later use. It will be called immediately after the composer device is
    645      * opened with non-NULL procs. It is FORBIDDEN to call any of the callbacks
    646      * from within registerProcs(). registerProcs() must save the hwc_procs_t
    647      * pointer which is needed when calling a registered callback.
    648      */
    649     void (*registerProcs)(struct hwc_composer_device_1* dev,
    650             hwc_procs_t const* procs);
    651 
    652     /*
    653      * This field is OPTIONAL and can be NULL.
    654      *
    655      * If non NULL it will be called by SurfaceFlinger on dumpsys
    656      */
    657     void (*dump)(struct hwc_composer_device_1* dev, char *buff, int buff_len);
    658 
    659     /*
    660      * (*getDisplayConfigs)() returns handles for the configurations available
    661      * on the connected display. These handles must remain valid as long as the
    662      * display is connected.
    663      *
    664      * Configuration handles are written to configs. The number of entries
    665      * allocated by the caller is passed in *numConfigs; getDisplayConfigs must
    666      * not try to write more than this number of config handles. On return, the
    667      * total number of configurations available for the display is returned in
    668      * *numConfigs. If *numConfigs is zero on entry, then configs may be NULL.
    669      *
    670      * Hardware composers implementing HWC_DEVICE_API_VERSION_1_3 or prior
    671      * shall choose one configuration to activate and report it as the first
    672      * entry in the returned list. Reporting the inactive configurations is not
    673      * required.
    674      *
    675      * HWC_DEVICE_API_VERSION_1_4 and later provide configuration management
    676      * through SurfaceFlinger, and hardware composers implementing these APIs
    677      * must also provide getActiveConfig and setActiveConfig. Hardware composers
    678      * implementing these API versions may choose not to activate any
    679      * configuration, leaving configuration selection to higher levels of the
    680      * framework.
    681      *
    682      * Returns 0 on success or a negative error code on error. If disp is a
    683      * hotpluggable display type and no display is connected, an error shall be
    684      * returned.
    685      *
    686      * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later.
    687      * It shall be NULL for previous versions.
    688      */
    689     int (*getDisplayConfigs)(struct hwc_composer_device_1* dev, int disp,
    690             uint32_t* configs, size_t* numConfigs);
    691 
    692     /*
    693      * (*getDisplayAttributes)() returns attributes for a specific config of a
    694      * connected display. The config parameter is one of the config handles
    695      * returned by getDisplayConfigs.
    696      *
    697      * The list of attributes to return is provided in the attributes
    698      * parameter, terminated by HWC_DISPLAY_NO_ATTRIBUTE. The value for each
    699      * requested attribute is written in order to the values array. The
    700      * HWC_DISPLAY_NO_ATTRIBUTE attribute does not have a value, so the values
    701      * array will have one less value than the attributes array.
    702      *
    703      * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_1 and later.
    704      * It shall be NULL for previous versions.
    705      *
    706      * If disp is a hotpluggable display type and no display is connected,
    707      * or if config is not a valid configuration for the display, a negative
    708      * error code shall be returned.
    709      */
    710     int (*getDisplayAttributes)(struct hwc_composer_device_1* dev, int disp,
    711             uint32_t config, const uint32_t* attributes, int32_t* values);
    712 
    713     /*
    714      * (*getActiveConfig)() returns the index of the configuration that is
    715      * currently active on the connected display. The index is relative to
    716      * the list of configuration handles returned by getDisplayConfigs. If there
    717      * is no active configuration, -1 shall be returned.
    718      *
    719      * Returns the configuration index on success or -1 on error.
    720      *
    721      * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_4 and later.
    722      * It shall be NULL for previous versions.
    723      */
    724     int (*getActiveConfig)(struct hwc_composer_device_1* dev, int disp);
    725 
    726     /*
    727      * (*setActiveConfig)() instructs the hardware composer to switch to the
    728      * display configuration at the given index in the list of configuration
    729      * handles returned by getDisplayConfigs.
    730      *
    731      * If this function returns without error, any subsequent calls to
    732      * getActiveConfig shall return the index set by this function until one
    733      * of the following occurs:
    734      *   1) Another successful call of this function
    735      *   2) The display is disconnected
    736      *
    737      * Returns 0 on success or a negative error code on error. If disp is a
    738      * hotpluggable display type and no display is connected, or if index is
    739      * outside of the range of hardware configurations returned by
    740      * getDisplayConfigs, an error shall be returned.
    741      *
    742      * This field is REQUIRED for HWC_DEVICE_API_VERSION_1_4 and later.
    743      * It shall be NULL for previous versions.
    744      */
    745     int (*setActiveConfig)(struct hwc_composer_device_1* dev, int disp,
    746             int index);
    747     /*
    748      * Asynchronously update the location of the cursor layer.
    749      *
    750      * Within the standard prepare()/set() composition loop, the client
    751      * (surfaceflinger) can request that a given layer uses dedicated cursor
    752      * composition hardware by specifiying the HWC_IS_CURSOR_LAYER flag. Only
    753      * one layer per display can have this flag set. If the layer is suitable
    754      * for the platform's cursor hardware, hwcomposer will return from prepare()
    755      * a composition type of HWC_CURSOR_OVERLAY for that layer. This indicates
    756      * not only that the client is not responsible for compositing that layer,
    757      * but also that the client can continue to update the position of that layer
    758      * after a call to set(). This can reduce the visible latency of mouse
    759      * movement to visible, on-screen cursor updates. Calls to
    760      * setCursorPositionAsync() may be made from a different thread doing the
    761      * prepare()/set() composition loop, but care must be taken to not interleave
    762      * calls of setCursorPositionAsync() between calls of set()/prepare().
    763      *
    764      * Notes:
    765      * - Only one layer per display can be specified as a cursor layer with
    766      *   HWC_IS_CURSOR_LAYER.
    767      * - hwcomposer will only return one layer per display as HWC_CURSOR_OVERLAY
    768      * - This returns 0 on success or -errno on error.
    769      * - This field is optional for HWC_DEVICE_API_VERSION_1_4 and later. It
    770      *   should be null for previous versions.
    771      */
    772     int (*setCursorPositionAsync)(struct hwc_composer_device_1 *dev, int disp, int x_pos, int y_pos);
    773 
    774     /*
    775      * Reserved for future use. Must be NULL.
    776      */
    777     void* reserved_proc[1];
    778 
    779 } hwc_composer_device_1_t;
    780 
    781 /** convenience API for opening and closing a device */
    782 
    783 static inline int hwc_open_1(const struct hw_module_t* module,
    784         hwc_composer_device_1_t** device) {
    785     return module->methods->open(module,
    786             HWC_HARDWARE_COMPOSER, (struct hw_device_t**)device);
    787 }
    788 
    789 static inline int hwc_close_1(hwc_composer_device_1_t* device) {
    790     return device->common.close(&device->common);
    791 }
    792 
    793 /*****************************************************************************/
    794 
    795 __END_DECLS
    796 
    797 #endif /* ANDROID_INCLUDE_HARDWARE_HWCOMPOSER_H */
    798