# Output Surface in Chromium

[OutputSurface](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=50;drc=1c01dc9bf49e3d56bcee0a78f73f8a00bc6ebd0a) is an abstract interface in viz which represents APIs for presenting buffers to display.
Its implementation differs depending on the platform.

## Overview
OutputSurface has 4 values:
- [Capabilities](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=62;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) struct
- [Type](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=52;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) to specify software rendering or hardware rendering
- [SoftwareOutputDevie](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/software_output_device.h;l=33;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) providing software drawing support
- [`color_matrix_`](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=308;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd)

These are the parameters representing the render and output surface types.

[Capabilities](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=62;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) holds the information whether each features are supported or not.
For example, [number_of_buffers](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=71;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) is a number of buffers for the SkiaOutputDevice.
[`supports_gpu_vsync`](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=84;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) shows whether it supports gpu vsync. Vsync is a mechanism to synchronize the image frame in the certain interval.
[`needs_background_image`](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=136;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) is whether we need background image in BufferQueue.
There are many other params.

`capabilities_` are updated by each platform specific surface.
[SoftwareOutputSurface](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display_embedder/software_output_surface.cc;l=32-35;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) changes a pending swap params and so on.

### PendingSwapParams
[PandingSwapParams](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/pending_swap_params.h;l=13;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) is one of the parameters specified in Capabilities explained above.
`max_pending_swaps`, `max_pending_swaps_90hz` and `max_pending_swaps_120hz` are registered.

Max pending swap is a maximum number to keep the pending frames.
If the pending images to be swapped exceed this limit, it calls [SetIsGpuBusy](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/display_scheduler.cc;l=562-564;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) to the BeginFramrSource. If [`is_gpu_busy_`](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/common/frame_sinks/begin_frame_source.h;l=258;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) is set to true, BeginFrame messages should be stopped.

## Methods
Here are some example methods
- [SetDrawRectangle](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=196;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd): marks the give rectangle will be drawn to.
- [SwapBuffers](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=232;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd): swaps the current backbuffer to the screen and then triggers DidReceieveSwapBuffersAck
- [SetGpuVsyncCallback](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=251;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd): callback for vsync signal from gpu to dispatch BeginFrame'
- [SetNeedsSwapSizeNotifications](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=282;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd): enable DidSwapWithSize notifications
- [SetFrameRate](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/output_surface.h;l=294;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd): set frame rate

## Platform Specific Surfaces
There are OutputSurface corresponding to each [DirectRenderer](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/direct_renderer.h;l=66;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd)
- [SkiaOutputSurface](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/skia_output_surface.h;l=52;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) is for [SkiaRenderer](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/skia_renderer.h;l=44;drc=1c01dc9bf49e3d56bcee0a78f73f8a00bc6ebd0a)
- [SoftwareOutputSurface](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display_embedder/software_output_surface.h;l=27;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) is for [SoftwareRenderer](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/software_renderer.h;l=28;drc=23f55d7131aeabcfdab609de124b91fd6e3c59fd)
- [OuputSurfaceUnified](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display_embedder/output_surface_unified.h;l=23;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd) is for [NullRenderer](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/null_renderer.h;l=16;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd)

DirecrRenderer is a base class of renderer that has an implementation shared between GL and software renderer.
Software renderer composits on browser side with CPU while Skia renderer uses GPU for rendering.
In the future, SkiaRender will be the only renderer ([ref](https://source.chromium.org/chromium/chromium/src/+/main:components/viz/service/display/skia_output_surface.h;l=48-49;drc=c177416839ec7a3fe2fe6e91a7e8e519248f96bd)) and other OutputSurface implementation will be removed and overtook by SkipOutputSurface.