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