View source for Platform/GFX/hwcomposer

= What is Hardware Composer? =
Android Hardware composer HAL([https://github.com/android/platform_hardware_libhardware/blob/master/include/hardware/hwcomposer.h 1]) is an abstract 2D composer library that can help to offload GPU resource for screen composition. Based on HWC HAL, chipset vendor(like Qcom, nVidia) can implement their own 2D composer library to integrate with platform's 2D HW composer.

Think of hardware composer as a fast-path for the compositor, that is limited but provides better performance and battery consumption characteristics.

* Different chipset vendor could have different 2D HW componment
**Qcom supports copybit and overlay, nVidia support overlay, Mali(reuse 2D core from GPU TODO)
**B2G ICS on leo/hamachi use copybit by default
**B2G JB on Nexus 4 use overlay by default (will support partial HWC composition bug 915729)

* HWComposer Requirement:
** Scaling: HWC does not support scaling (at least in its current form)
** Axis Aligned Rotate (0, 90, 180, 270)
** Flip_V/Flip_H
** RGB/YUV content
** Layer number: HWC can only composite a limited amount of layers depending on the hardware:
*** TODO: per device numbers?

Each time we composite, we first go through the layer tree, see if we can use HWComposer and fallback to the Compositor API (OpenGL based on Firefox OS) if we can't use it.

Links to relevent files: TODO

Android doc about HWComposer: http://source.android.com/devices/graphics.html#hwc

== What are the wins of using HWComposer over an OpenGL compositor? ==

*Lower Power consumption
**Chipset vendors could use simple HW layout to fullfill the needs of HWComposer, compared to GPU complex layout. Therefore, HWComposer could have the following benefits.
*Offer all GPU resource for application
** Offload GPU task for screen composition

*Memory bandwidth for write(TODO)
** HWComposer will have each layer's graphic buffer as input and combine these graphic buffers directly output to screen.
** No need to write back composition result to framebuffer

== When do we expect to be using HWComposer ==

Full-screen video playback is the place where we really want to be using HWComposer, because of battery usage. If something makes us not use HWComposer there, it should be considered as a bug.
Currently the home screen when idle is using HWComposer, but it is not a hard requirement.

== Buffer Synchronization ==

JB

TODO