Fix HWC documentation.
Specify more clearly the behavior of compositionType
and hints.
Change-Id: I9abdccedd904b2fba783381bf9e2f8975ede8d67
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_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 @@
* 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 @@
* 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.
