From 48697f6dc249d1238243677de77d3a0eb6a17b3f Mon Sep 17 00:00:00 2001
From: Mathias Agopian <mathias@google.com>
Date: Tue, 20 Nov 2012 15:23:25 -0800
Subject: Fix HWC documentation.

Specify more clearly the behavior of compositionType
and hints.

Change-Id: I9abdccedd904b2fba783381bf9e2f8975ede8d67
---
 include/hardware/hwcomposer.h | 58 +++++++++++++++++++++++++++++++++----------
 1 file changed, 45 insertions(+), 13 deletions(-)

diff --git a/include/hardware/hwcomposer.h b/include/hardware/hwcomposer.h
index 0722e32..c30ef33 100644
--- a/include/hardware/hwcomposer.h
+++ b/include/hardware/hwcomposer.h
@@ -80,21 +80,25 @@ typedef struct hwc_color {
 
 typedef struct hwc_layer_1 {
     /*
-     * Initially set to HWC_FRAMEBUFFER, HWC_BACKGROUND, or
-     * HWC_FRAMEBUFFER_TARGET.
+     * compositionType is used to specify this layer's type and is set by either
+     * the hardware composer implementation, or by the caller (see below).
      *
-     * HWC_FRAMEBUFFER
-     *   Indicates the layer will be drawn into the framebuffer
-     *   using OpenGL ES. The HWC can toggle this value to HWC_OVERLAY to
-     *   indicate it will handle the layer.
+     *  This field is always reset to HWC_BACKGROUND or HWC_FRAMEBUFFER
+     *  before (*prepare)() is called when the HWC_GEOMETRY_CHANGED flag is
+     *  also set, otherwise, this field is preserved between (*prepare)()
+     *  calls.
      *
      * HWC_BACKGROUND
-     *   Indicates this is a special "background" layer. The only valid field
-     *   is backgroundColor. The HWC can toggle this value to HWC_FRAMEBUFFER
-     *   to indicate it CANNOT handle the background color.
+     *   Always set by the caller before calling (*prepare)(), this value
+     *   indicates this is a special "background" layer. The only valid field
+     *   is backgroundColor.
+     *   The HWC can toggle this value to HWC_FRAMEBUFFER to indicate it CANNOT
+     *   handle the background color.
+     *
      *
      * HWC_FRAMEBUFFER_TARGET
-     *   Indicates this layer is the framebuffer surface used as the target of
+     *   Always set by the caller before calling (*prepare)(), this value
+     *   indicates this layer is the framebuffer surface used as the target of
      *   OpenGL ES composition. If the HWC sets all other layers to HWC_OVERLAY
      *   or HWC_BACKGROUND, then no OpenGL ES composition will be done, and
      *   this layer should be ignored during set().
@@ -103,13 +107,38 @@ typedef struct hwc_layer_1 {
      *   HWC version is HWC_DEVICE_API_VERSION_1_1 or higher. In older versions,
      *   the OpenGL ES target surface is communicated by the (dpy, sur) fields
      *   in hwc_compositor_device_1_t.
+     *
+     *   This value cannot be set by the HWC implementation.
+     *
+     *
+     * HWC_FRAMEBUFFER
+     *   Set by the caller before calling (*prepare)() ONLY when the
+     *   HWC_GEOMETRY_CHANGED flag is also set.
+     *
+     *   Set by the HWC implementation during (*prepare)(), this indicates
+     *   that the layer will be drawn into the framebuffer using OpenGL ES.
+     *   The HWC can toggle this value to HWC_OVERLAY to indicate it will
+     *   handle the layer.
+     *
+     *
+     * HWC_OVERLAY
+     *   Set by the HWC implementation during (*prepare)(), this indicates
+     *   that the layer will be handled by the HWC (ie: it must not be
+     *   composited with OpenGL ES).
+     *
      */
     int32_t compositionType;
 
-    /* see hwc_layer_t::hints above */
+    /*
+     * hints is bit mask set by the HWC implementation during (*prepare)().
+     * It is preserved between (*prepare)() calls, unless the
+     * HWC_GEOMETRY_CHANGED flag is set, in which case it is reset to 0.
+     *
+     * see hwc_layer_t::hints
+     */
     uint32_t hints;
 
-    /* see hwc_layer_t::flags above */
+    /* see hwc_layer_t::flags */
     uint32_t flags;
 
     union {
@@ -356,11 +385,14 @@ typedef struct hwc_composer_device_1 {
      * either HWC_FRAMEBUFFER or HWC_OVERLAY. In the former case, the
      * composition for the layer is handled by SurfaceFlinger with OpenGL ES,
      * in the later case, the HWC will have to handle the layer's composition.
+     * compositionType and hints are preserved between (*prepare)() calles
+     * unless the HWC_GEOMETRY_CHANGED flag is set.
      *
      * (*prepare)() is called with HWC_GEOMETRY_CHANGED to indicate that the
      * list's geometry has changed, that is, when more than just the buffer's
      * handles have been updated. Typically this happens (but is not limited to)
-     * when a window is added, removed, resized or moved.
+     * when a window is added, removed, resized or moved. In this case
+     * compositionType and hints are reset to their default value.
      *
      * For HWC 1.0, numDisplays will always be one, and displays[0] will be
      * non-NULL.
-- 
cgit v1.1