# Overlay and Display Controller

Display Controller is a hardware which is responsible for compositing frames into one display.
It sounds similar to GPU but they are different.

Today, I summarize the overview of the role of DisplayController and GPU + understand Overlay system.

## Overlay
Before talking about Display Controller, let's understand what overlay is.

On generating images, it sounds more efficient just to draw the area which is really necessary. The area visible to users should be enough.
However, it sometimes more efficient to draw ununsed area as well. One of the examples is "Overlay".

Overlay frame is created separately from the main frame. As you can assume from the name, overlay frame "overlays" the main frame so that it will hide some part of the main frame which is located under the overlay frame.
This system is usuful when drawing the frames seperately would make things easier. For example, if the frame is video which is converted so quickly.

### Underlay
Similar to Overlay, we also have Underlay which places the frame under the main frame.
The implementation in Chromium is same as Overlay.

Whether we should overlay or underlay is managed as a [OverlayProcessorStrategy](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/overlay_processor_strategy.h;l=23;drc=8e78783dc1f7007bad46d657c9f332614e240fd8).
We have three strategies
- OverlayStrategyFullscreen
- OverlayStrategySingleOnTop
- OverlayStrategyUnderlay

### Overlay Candidate
The number of overlay that the architecture allows is limitted.
We cannot promote every frames to overlay due to this restriction.

In Chromium, we submit frames are [OverlayCandidate](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/overlay_candidate.h;l=40;drc=fc3fcbb1933790b3bd471500b13822add5f768c8).
In order to select the most usuful one as a frame to promote to overlay, [OverlayPriotiryHint](https://source.chromium.org/chromium/chromium/src/+/main:ui/gfx/overlay_priority_hint.h;l=14-26;drc=8e78783dc1f7007bad46d657c9f332614e240fd8) specifies how the frame is prioritized.

## Display Controller vs GPU
Both GPU and display controller are the system to display the images.

GPU draws the frame buffer.
Then GPU submits the frame that are drawn, and signal that we are to present the completed result. This is Swap.

When GPU has finihsed draw and swap, it's Display Controller's turn. Display Controller starts scanning out the result. "Scan out" is the terminology meaning the frame is published to the display.
Display Controller is the one who actually shows the images.

Display Controller also handles the overlay.
When frame buffers are submitted from GPU, there could be overlay / underlay frames. Display Controller is responsible for scanning out these frame buffers in the correct order.
Also, if we need to scale the frame buffer, some Display Controller can handle this as well.

## Note: Partial Swap
Partial swap is also a concept to swap the images only on limitted area which slightly is similar to Overlay.
Partial swap will "swap" small area in the buffer directly and the completed frame will be submitted to the display while overlay creates one frame buffer and submits it to the display.
The timing of the update is different.