# Frame Activation and Deadline

On commiting a frame, we may have to wait showing it.
The window is often divided into several parts and all children parts must be ready before showing a new frame committed.
This is Frame Activation.

On the other hand, we may need to forcibly show a frame before all parts are ready so that the user don't have to wait too long.
This is Frame Deadline.

Let's see each concept.

## Frame Activation
On [viz::Surface::CommitFrame](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.cc;l=246;drc=d708cc843536cc344f0f7679a978634cc14d6153), it [UpdateActivationDependencies](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.cc;l=647;drc=d708cc843536cc344f0f7679a978634cc14d6153) and add a new surface id to [`activation_dependencies_`](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.h;l=426;drc=d708cc843536cc344f0f7679a978634cc14d6153) who is stored as a flat_set of SurfaceId.
This is held to block the frame activation if one of the dependent frame is not yet ready.

[Surface::ActivateFrame](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.cc;l=547;drc=d708cc843536cc344f0f7679a978634cc14d6153) will literally activate the frame.
If `activation_dependencies_` is empty, which implies all dependent frame if any are ready, there is no blocker so activate it.
If there is, add frame to `pending_frame_data_` and wait until [ActivePendingFrame](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.cc;l=403;drc=d708cc843536cc344f0f7679a978634cc14d6153) is called.

There are two locations who call ActivationPendingFrame.
One is from [ActivatePendingFrameForDeadline](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.cc;l=370;drc=d708cc843536cc344f0f7679a978634cc14d6153) which will be explained on the next section.
Another is [OnActivationDependencyResolved](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.cc;l=358;drc=d708cc843536cc344f0f7679a978634cc14d6153).

## Frame Deadline
As mentioned above, CompositorFrame needs to be synchronized before being activated.
However, there may be a case where frame synchronization takes too long.
In such case, it's better to show something even though it's not correctly synchronized.

We have [FrameDeadline](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/common/quads/frame_deadline.h;l=27;drc=8ba1bad80dc22235693a0dd41fe55c0fd2dbdabd) class for such use.
It represents a CompositorFrame's deadline for activation and used by CompositorFrame.
[`deadline`](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/common/quads/compositor_frame_metadata.h;l=128;drc=d708cc843536cc344f0f7679a978634cc14d6153) in CompositorFrameMetadata specifies a deadline for this CompositorFrame.
CompositorFrame will be forcibly activated when deadline passes.

This metadata is constructed inside [LayerTreeHostImpl::GenerateCompositorFrame](https://source.chromium.org/chromium/chromium/src/+/main:cc/trees/layer_tree_host_impl.cc;l=2785;drc=e235f5f3dd85405849d69b529ef04c40eaad53b8) and stored to CompositorFrame.

On [viz::Surface::CommitFrame](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.cc;l=246;drc=d708cc843536cc344f0f7679a978634cc14d6153), `deadline` metadata attached to CompositorFrame is set to [`deadline_`](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.h;l=399;drc=d708cc843536cc344f0f7679a978634cc14d6153) of viz::Surface as [SurfaceDependencyDeadline](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface_dependency_deadline.h;l=22;drc=d708cc843536cc344f0f7679a978634cc14d6153).

On CommitFrame, as mentioned in Frame Activation section, it activates a frame immedialtely if there is no pending_frame_data_.
If there is, we first check whether the pending frame exceeds a deadline.
[HasDeadlinePassed](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface_dependency_deadline.cc;l=30;drc=d708cc843536cc344f0f7679a978634cc14d6153) returns true if `NowTicks` is larger than `deadline_` time.
If it exceeds, call [ActivatePendingFrameForDeadline](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.cc;l=370;drc=d708cc843536cc344f0f7679a978634cc14d6153) which calls [ActivatePendingFrame](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/surfaces/surface.cc;l=403;drc=d708cc843536cc344f0f7679a978634cc14d6153) so that the pending frame is forcibly activated.
If not, proceed with a result `QueueFrameResult::ACCEPTED_PENDING` and wait until the frame is being activated.