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 know 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 * Clean-up of drawing code
  62
  63 ** Make SinglePar update flag useful again.
  64
  65 The current code can be very expensive when moving cursor inside a
  66 huge table, for example. We should test the flag again, although this
  67 will probably lead to some glitches here and there.
  68
  69 ** Set Row::changed() in a finer way
  70
  71 *** singleParUpdate
  72
  73 When the height of the current paragraph changes, there is no need for
  74 a full screen update. Only the rows after the current one need to have
  75 their position recomputed.
  76
  77 This is also true when scrolling (how to do that?)
  78
  79 *** redoParagraph
  80
  81 It should be possible to check whether the new row is the same as the
  82 old one and keep its changed() status in this case. This would reduce
  83 a lot the amount of stuff to redraw.
  84
  85 ** Put labels and friends in the Row as elements
  86
  87 It should not be necessary to access the Paragraph object to draw.
  88 Adding the static elements to Row is a lot of work, but worth it IMO.
  89
  90 ** Create a unique row by paragraph and break it afterwards
  91
  92 This should be a performance gain (only if paragraph breaking still
  93 shows as expensive after the rest is done)
  94
  95 ** do not add the vertical margin of main text to first/last row
  96
  97 Would make code cleaner. Probably no so difficult.
  98
  99 ** When a paragraph ends with a newline, compute correctly the height of the extra row.
 100 ** Merging bv::updateMetrics and tm::metrics
 101
 102 While the full metrics computation tries hard to limit the number of
 103 paragraphs that are rebroken, the version that is used for inner inset
 104 does not try any such optimization. This can be very bad for very tall
 105 insets. We should re-use the bv::updateMetrics logic:
 106  + transfer all the logic of bv::updateMetrics to tm.
 107  + Main InsetText should not be special.
 108
 109 The difficulty for a tall table cell for example, is that it may be
 110 necessary to break the whole contents to know the width of the cell.
 111
 112
 113 * Description of current drawing mechanism
 114
 115 ** Three-stage drawing
 116
 117 There are three parts to drawing the work area:
 118
 119  + the metrics phase computes the size of insets and breaks the
 120    paragraphs into rows. It stores the dimension of insets (both
 121    normal and math) in bv::coordCache.
 122
 123  + the nodraw drawing phase paints the screen (see below) with a null
 124    painter. The only useful effect is to store the inset positions.
 125
 126  + an update() signal is sent. This in turn will trigger a paint
 127    event, and the actual screen painting will happen then.
 128
 129 The machinery is controlled via bv::processUpdateFlags. This method is
 130 called at the end of bv::mouseEventDispatch and in
 131 GuiApplication::dispatch, via the updateCurrentView method. There are
 132 also several calls in code related to dialogs. We should evaluate
 133 whether this is correct.
 134
 135 Depending on the Update::flags passed to the method, it sets an update
 136 strategy in (NoScreenUpdate, SingleParUpdate, FullScreenUpdate,
 137 DecorationUpdate). It triggers a recomputation of the metrics when either:
 138
 139  + Update::Force has been specified
 140  + Update::FitCursor has been specified and there is a need to scroll
 141    the display.
 142  + the current paragraph, after rebreak, does not have the same height as in
 143    existing metrics. Note that the Update::SinglePar flag is *never*
 144    taken into account.
 145
 146 If a computation of metrics has taken place, Force is removed from the
 147 flags and ForceDraw is added instead.
 148
 149 It is OK to call processUptateFlags several times before an update. In
 150 this case, the effects are cumulative.processUpdateFlags execute the
 151 metrics-related actions, but defers the actual drawing to the next
 152 paint event.
 153
 154 The screen is drawn (with appropriate update strategy), except when
 155 update flag is Update::None.
 156
 157
 158 ** Metrics computation (and nodraw drawing phase)
 159
 160 This is triggered by bv::updateMetrics, which calls tm::redoParagraph for
 161 all visible paragraphs. Some Paragraphs above or below the screen (needed
 162 for page up/down) and computed as needed.
 163
 164 tm::redoParagraph will call Inset::metrics for each inset. In the case
 165 of text insets, this will invoke recursively tm::metrics, which redoes
 166 all the paragraphs of the inset.
 167
 168 At the end of the function, bv::updatePosCache is called. It triggers
 169 a repaint of the document with a NullPainter (a painter that does
 170 nothing). This has the effect of caching all insets positions.
 171
 172 ** Drawing the work area.
 173
 174 This is done in bv::draw. This method is triggered by a paint event,
 175 mainly called through Buffer::changed, which draws all the work areas
 176 that show the given buffer.
 177
 178 Note that, When Buffer::changed is called outside of
 179 bv::processUpdateFlags, it is not clear whether the update strategy
 180 has been set to a reasonable value beforehand.
 181
 182 The action depends on the update strategy:
 183
 184  + NoScreenUpdate: repaint the whole screen with drawing disabled.
 185    This is only needed to update the inset positions. I am not sure
 186    when this is necessary, actually. This is triggered when:
 187    - Update::FitCursor is set but the cursor is already visible. It is
 188      not clear why something needs to be done in this case, since this
 189      should be equivalent to Update::None.
 190    - this is also set when update flag is Update::None, but this value
 191      is AFAICS not acted on in the code (meaning that nothing happens
 192      at all in this case).
 193
 194  + FullScreenUpdate: repaint the whole screen. This is set when:
 195    - updateMetrics has been invoked.
 196    - scroll value of current row has changed (although this should not
 197      be necessary).
 198
 199  + DecorationUpdate: actually like FullScreenUpdate, although it is
 200    intended to only update inset decorations. This triggers when:
 201    - Update::Decoration is set (without Update::Force) as flag.
 202    - An hovered inset is detected.
 203
 204  + SingleParUpdate: only tries to repaint current paragraph in a way
 205    that is not yet very clear to me.
 206
 207 BufferView::draw can also be called with a null painter from
 208 BufferView::updateMetrics().