cc/README.md

   1 # cc/
   2
   3 This directory contains a compositor, used in both the renderer and the
   4 browser.  In the renderer, Blink is the client.  In the browser, both
   5 ui and Android browser compositor are the clients.
   6
   7 The public API of the compositor is LayerTreeHost and Layer and its
   8 derived types.  Embedders create a LayerTreeHost (single, multithreaded,
   9 or synchronous) and then attach a tree of Layers to it.
  10
  11 When Layers are updated they request a commit, which takes the structure
  12 of the tree of Layers, the data on each Layer, and the data of its host and
  13 atomically pushes it all to a tree of LayerImpls and a LayerTreeHostImpl
  14 and LayerTreeImpl.  The main thread (which owns the tree of Layers
  15 and the embedder) is blocked during this commit operation.
  16
  17 The commit is from the main thread Layer tree to the pending tree in
  18 multithreaded mode.  The pending tree is a staging tree for
  19 rasterization.  When enough rasterization has completed for
  20 invalidations, the pending tree is ready to activate.  Activate is an
  21 analogous operation to commit, and pushes data from the pending tree to
  22 the active tree.  The pending tree exists so that all of the updates
  23 from the main thread can be displayed to the user atomically while
  24 the previous frame can be scrolled or animated.
  25
  26 The single threaded compositor commits directly to the active
  27 tree and then stops drawing until the content is ready to be drawn.
  28
  29 The active tree is responsible for drawing.  The Scheduler and its
  30 SchedulerStateMachine decide when to draw (along with when to commit,
  31 etc etc).  "Drawing" in a compositor consists of LayerImpl::AppendQuads
  32 which batches up a set of DrawQuads and RenderPasses into a
  33 CompositorFrame which is sent via a CompositorFrameSink.
  34
  35 CompositorFrames from individual compositors are sent to the
  36 SurfaceManager (which is in the GPU process). The SurfaceAggregator combines all
  37 CompositorFrames together when asked to by the Display. These are given to the
  38 viz::DirectRenderer, which finally draws the entire composited browser contents.
  39 See //components/viz for more details on the display compositor.
  40
  41 Design documents for the graphics stack can be found at
  42 [chromium-graphics](https://www.chromium.org/developers/design-documents/chromium-graphics).
  43
  44 ## Other Docs
  45
  46 * [How cc Works](../docs/how_cc_works.md)
  47
  48 ## Glossaries
  49
  50 ### Active CompositorFrame
  51
  52 ### Active Tree
  53 The set of layers and property trees that was/will be used to submit a
  54 CompositorFrame from the layer compositor. Composited effects such as scrolling,
  55 pinch, and animations are done by modifying the active tree, which allows for
  56 producing and submitting a new CompositorFrame.
  57
  58 ### CompositorFrame
  59 A set of RenderPasses (which are a list of DrawQuads) along with metadata.
  60 Conceptually this is the instructions (transforms, texture ids, etc) for how to
  61 draw an entire scene which will be presented in a surface.
  62
  63 ### CopyOutputRequest (or Copy Request)
  64 A request for a texture (or bitmap) copy of some part of the compositor's
  65 output. Such requests force the compositor to use a separate RenderPass for the
  66 content to be copied, which allows it to do the copy operation once the
  67 RenderPass has been drawn to.
  68
  69 ### ElementID
  70 Chosen by cc's clients and can be used as a stable identifier across updates.
  71 For example, blink uses ElementIDs as a stable id for the object (opaque to cc)
  72 that is responsible for a composited animation. Some additional information in
  73 [element_id.h](https://codesearch.chromium.org/chromium/src/cc/paint/element_id.h)
  74
  75 ### DirectRenderer
  76 An abstraction that provides an API for the Display to draw a fully-aggregated
  77 CompositorFrame to a physical output. Subclasses of it provide implementations
  78 for various backends, currently GL, Skia, or Software. See [viz::DirectRenderer](https://codesearch.chromium.org/chromium/src/components/viz/service/display/direct_renderer.h)
  79 for details.
  80
  81 ### Layer
  82 A conceptual piece of content that can appear on screen and has some known
  83 position with respect to the viewport.  The Layer class only is used on the
  84 main thread.  This, along with LayerTreeHost, is the main API for the
  85 compositor.
  86
  87 ### LayerImpl
  88 The same as Layer, but on the compositor thread.
  89
  90 ### LayerTree
  91
  92 ### Occlusion Culling
  93 Avoiding work by skipping over things which are not visible due to being
  94 occluded (hidden from sight by other opaque things in front of them). Most
  95 commonly refers to skipping drawing (ie culling) of DrawQuads when other
  96 DrawQuads will be in front and occluding them.
  97
  98 ### Property Trees
  99
 100 See also presentations on [Compositor Property Trees](https://docs.google.com/presentation/d/1V7gCqKR-edNdRDv0bDnJa_uEs6iARAU2h5WhgxHyejQ/preview)
 101 and [Blink Property Trees](https://docs.google.com/presentation/u/1/d/1ak7YVrJITGXxqQ7tyRbwOuXB1dsLJlfpgC4wP7lykeo/preview).
 102
 103 ### Display
 104 A controller class that takes CompositorFrames for each surface and draws them
 105 to a physical output. See [viz::Display](https://codesearch.chromium.org/chromium/src/components/viz/service/display/display.h)  for details.
 106
 107 ### Draw
 108 Filling pixels in a physical output (technically could be to an offscreen
 109 texture), but this is the final output of the display compositor.
 110
 111 ### DrawQuad
 112 A unit of work for drawing. Each DrawQuad has its own texture id, transform,
 113 offset, etc.
 114
 115 ### Shared Quad State
 116 A shared set of states used by multiple draw quads. DrawQuads that are linked to
 117 the same shared quad state will all use the same properties from it, with the
 118 addition of things found on their individual DrawQuad structures.
 119
 120 ### Render Pass
 121 A list of DrawQuads which will all be drawn together into the same render target
 122 (either a texture or physical output). Most times all DrawQuads are part of a
 123 single RenderPass. Additional RenderPasses are used for effects that require a
 124 set of DrawQuads to be drawn together into a buffer first, with the effect
 125 applied then to the buffer instead of each individual DrawQuad.
 126
 127 ### Render Surface
 128 Synonym for RenderPass now. Historically part of the Layer tree data structures,
 129 with a 1:1 mapping to RenderPasses. RenderSurfaceImpl is a legacy piece that
 130 remains.
 131
 132 ### Surface
 133
 134 ### Record
 135
 136 ### Raster
 137
 138 ### Paint
 139
 140 ### Pending CompositorFrame
 141
 142 ### Pending Tree
 143 The set of layers and property trees that is generated from a main frame (or
 144 BeginMainFrame, or commit). The pending tree exists to do raster work in the
 145 layer compositor without clobbering the active tree until it is done. This
 146 allows the active tree to be used in the meantime.
 147
 148 ### Composite
 149 To produce a single graphical output from multiple inputs. In practice, the
 150 layer compositor does raster from recordings and manages memory, performs
 151 composited effects such as scrolling, pinch, animations, producing a
 152 CompositorFrame. The display compositor does an actual "composite" to draw the
 153 final output into a single physical output.
 154
 155 ### Invalidation
 156 Invalidation is a unit of content update.  Any content updates from
 157 Blink or ui must be accompanied by an invalidation to tell the compositor
 158 that a piece of content must be rerasterized.  For example, if a 10x10
 159 div with a background color has its width increased by 5 pixels, then
 160 there will be a 5x10 invalidation (at least) for the new space covered
 161 by the larger div.
 162
 163 Ideally, invalidations represent the minimum amount of content that must
 164 be rerastered from the previous frame.  They are passed to the compositor
 165 via Layer::SetNeedsDisplay(Rect).  Invalidation is tracked both to
 166 minimize the amount of raster work needed, but also to allow for
 167 partial raster of Tiles.  Invalidations also eventually become damage.
 168
 169 ### Damage
 170 Damage is the equivalent of invalidation, but for the final display.
 171 As invalidation is the difference between two frames worth of content,
 172 damage is the difference between two CompositorFrames.  Damage is
 173 tracked via the DamageTracker.  This allows for partial swap, where
 174 only the parts of the final CompositorFrame that touch the screen
 175 are drawn, and only that drawn portion is swapped, which saves quite
 176 a bit of power for small bits of damage.
 177
 178 Invalidation creates damage, in that if a piece of content updates, then
 179 that content invalidation creates damage on screen.  Other things that
 180 cause damage are analogous operations to invalidations, but on Layers.
 181 For example, moving a Layer around, changing properties of Layers (e.g.
 182 opacity), and adding/removing/reordering Layers will all create damage
 183 (aka screen updates) but do not create invalidations (aka raster work).
 184
 185 ### Tiles
 186 An abstraction of a piece of content of a Layer.  A tile may be
 187 rasterized or not.  It may be known to be a solid color or not.
 188 A PictureLayerImpl indirectly owns a sparse set of Tiles to
 189 represent its rasterizable content.  When tiles are invalidated,
 190 they are replaced with new tiles.
 191
 192 ### Prepare Tiles
 193 Prioritize and schedule needed tiles for raster. This is the entry point to a
 194 system that converts painting (raster sources / recording sources) into
 195 rasterized resources that live on tiles. This also kicks off any dependent image
 196 decodes for images that need to be decode for the raster to take place.
 197
 198 ### Device Scale Factor
 199 The scale at which we want to display content on the output device. For very
 200 high resolution monitors, everything would become too small if just presented
 201 1:1 with the pixels. So we use a larger number of physical pixels per logical
 202 pixels. This ratio is the device scale factor. 1 or 2 is the most common on
 203 ChromeOS. Values between 1 and 2 are common on Windows.