development/PAINTING_ANALYSIS

   1 # -*- org -*-
   2 Understanding the painting process
   3
   4 This file tries to describe the state of the metrics/painting
   5 mechanism, and identify the improvements that could be made. The first
   6 section can be read alone, although the context for them is really
   7 given in the following ones.
   8
   9 Please keep this file up to date as the code evolves!!!
  10
  11 Abbreviations:
  12 bv: BufferView
  13 pm: ParagraphMetrics
  14 tm::TextMetrics
  15
  16 * Questions / Ideas
  17
  18 These questions are consequences of the description made in the
  19 following section. Some actions are proposed.
  20
  21 ** SinglePar update
  22
  23 The flag Update::SinglePar is set in many places but never acted on.
  24 Instead, metrics update is skipped whenever the recorded height of
  25 current paragraph did not change and Update::Force was not specified.
  26 Is it better to keep that (which incurs extra work) or to condition it
  27 on Update::SinglePar? If the first solution is kept, the flag
  28 SingleParUpdate shall be removed.
  29
  30 Moreover, I fail to see (yet) where the 'single' part of the program
  31 is acted on.
  32
  33 ** Buffer::change issues
  34
  35 When calling Buffer::changed outside of bv::processUpdateFlags,
  36 how do we now that the update strategy is set correctly? It is
  37 possible to reset the strategy at the end of bv::draw. What would be
  38 a good value? NoScreenUpdate?
  39
  40 On a related note, what is the semantics of a call to
  41 Buffer::changed(false)? What does the caller mean?
  42
  43 ** How to avoid  redraw with FitCursor when the cursor is already OK?
  44
  45 In this case, we invoke Buffer::change(false) with drawing disabled
  46 and NoScreenUpdate strategy.
  47
  48 In the draw phase, bv::checkCursorScrollOffset (the horizontal
  49 scrolling machinery) will change the strategy to FullScreenUpdate if
  50 the current row needs further scrolling.
  51
  52 When the update strategy it kept to NoScreenUpdate, there is currently
  53 a no-draw full repaint, which should not be necessary. It would be
  54 possible to avoid that if the call to checkCursorScrollOffset was done
  55 in bv::processUpdateFlags instead of bv::draw.
  56
  57 The global idea would be to extend FitCursor to cover also horizontal
  58 cursor.
  59
  60
  61 * Proposals
  62
  63 ** get rid of pm::insetDimension.
  64
  65 The information contained there is already in bv::coordCache.
  66
  67 Effect: only code simplification.
  68
  69 ** set inset position during metrics phase
  70
  71 This implies to set inset positions relative to outer isnet during
  72 metrics phase and then in a second loop to descend into insets and
  73 update positions correctly.
  74
  75 Effect: avoid going through the painter machinery when it is not necessary.
  76
  77 ** Merging bv::updateMetrics and tm::metrics
  78
  79 While the full metrics computation tries hard to limit the number of
  80 paragraphs that are rebroken, the version that is used for inner inset
  81 does not try any such optimization. This can be very bad for very tall
  82 insets. We should re-use the bv::updateMetrics logic:
  83  + transfer all the logic of bv::updateMetrics to tm.
  84  +  Main InsetText should not be special.
  85
  86 ** Metrics outside of visible area
  87
  88 Currently metrics are computed for current visible paet of text, the
  89 page above and the page below. It should be possible to compute hidden
  90 rows ony on demand, although it might be a bit slow.
  91
  92 There was a proposal to always compute _all_ rows, but this may become
  93 expensive for large files. This would though help scrolling.
  94
  95
  96 * Description of current drawing mechanism
  97
  98 ** Two phase drawing
  99
 100 There are two parts to drawing the work area:
 101
 102  + the metrics phase computes the size of insets and breaks the
 103    paragraphs into rows. It stores the dimension of insets (both
 104    normal and math) in bv::coordCache, and the size of normal
 105    insets in pm::insetDimension.
 106
 107  + the drawing phase draws the contents and caches the inset
 108    positions. Since the caching of positions is useful in itself,
 109    there is a provision for drawing "without" drawing when the only
 110    thing we want is to cache inset positions
 111    (Painter::setDrawingEnabled).
 112
 113
 114 The machinery is controlled via bv::processUpdateFlags. This method is
 115 called at the end of bv::mouseEventDispatch and in
 116 GuiApplication::dispatch, via the updateCurrentView method. There are
 117 also several calls in code related to dialogs. We should evaluate
 118 whether this is correct.
 119
 120 Depending on the Update::flags passed to the method, it sets an update
 121 strategy in (NoScreenUpdate, SingleParUpdate, FullScreenUpdate,
 122 DecorationUpdate). It triggers a recomputation of the metrics when either:
 123
 124  + Update::Force has been specified
 125  + Update::FitCursor has been specified and there is a need to scroll
 126    the display.
 127  + the current paragraph, after rebreak, does not have the same height as in
 128    existing metrics. Note that the Update::SinglePar flag is *never*
 129    taken into account.
 130
 131 The screen is drawn (with appropriate update strategy), except when
 132 update flag is Update::None.
 133
 134
 135 ** Metrics computation
 136
 137 This is triggered by bv::updateMetrics, which calls tm::redoParagraph for
 138   + all visible paragraphs
 139   + paragraph above the screen (up to one page)
 140   + paragraphs below the screen (up to one page again)
 141
 142 The paragraphs outside of the screen are required to make PageUp/Down
 143 work.
 144
 145 tm::redoParagraph will call Inset::metrics for each inset. In the case
 146 of text insets, this will invoke recursively tm::metrics, which redoes
 147 all the paragraphs of the inset.
 148
 149
 150 ** Drawing the work area.
 151
 152 This is done in bv::draw. This method is triggered mainly by
 153 Buffer::changed, which draws all the work areas that show the given buffer.
 154
 155 Note that, When Buffer::changed is called outside of
 156 bv::processUpdateFlags, it is not clear whether the update strategy
 157 has been set to a reasonable value beforehand.
 158
 159 The action depends on the update strategy:
 160
 161  + NoScreenUpdate: repaint the whole screen with drawing disabled.
 162    This is only needed to update the inset positions. I am not sure
 163    when this is necessary, actually. This is triggered when:
 164    - Update::FitCursor is set but the cursor is already visible. It is
 165      not clear why something needs to be done in this case, since this
 166      should be equivalent to Update::None.
 167    - this is also set when update flag is Update::None, but this value
 168      is AFAICS not acted on in the code (meaning that nothing happens
 169      at all in this case).
 170
 171  + FullScreenUpdate: repaint the whole screen. This is set when:
 172    - updateMetrics has been invoked.
 173    - scroll value of current row has changed (although this should not
 174      be necessary).
 175
 176  + DecorationUpdate: actually like FullScreenUpdate, although it is
 177    intended to only update inset decorations. This triggers when:
 178    - Update::Decoration is set (without Update::Force) as flag.
 179    - An hovered inset is detected.
 180
 181  + SingleParUpdate: only tries to repaint current paragraph in a way
 182    that is not yet very clear to me.