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 sections 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 This flag only has an effect in the current BufferView, but I think it
  24 is useful in other views too. Doing this will require some work on the
  25 update pipeline, though.
  26
  27
  28 ** Buffer::change issues
  29
  30 When calling Buffer::changed outside of bv::processUpdateFlags,
  31 how do we know that the update strategy is set correctly? It is
  32 possible to reset the strategy at the end of bv::draw. What would be
  33 a good value? NoScreenUpdate?
  34
  35 On a related note, what is the semantics of a call to
  36 Buffer::changed(false)? What does the caller mean?
  37
  38
  39 ** How to avoid redraw with FitCursor when the cursor is already OK?
  40
  41 In this case, we invoke Buffer::change(false) with drawing disabled
  42 and NoScreenUpdate strategy.
  43
  44 In the draw phase, bv::checkCursorScrollOffset (the horizontal
  45 scrolling machinery) will change the strategy to FullScreenUpdate if
  46 the current row needs further scrolling.
  47
  48 When the update strategy it kept to NoScreenUpdate, there is currently
  49 a no-draw full repaint, which should not be necessary. It would be
  50 possible to avoid that if the call to checkCursorScrollOffset was done
  51 in bv::processUpdateFlags instead of bv::draw.
  52
  53 The global idea would be to extend FitCursor to cover also horizontal
  54 cursor.
  55
  56
  57 * TODO Clean-up of drawing code
  58
  59 ** Set Row::changed() in a finer way
  60
  61 *** singleParUpdate
  62
  63 When the height of the current paragraph changes, there is no need for
  64 a full screen update (at top level, at least). Only the rows after the
  65 current one need to have their position recomputed.
  66
  67
  68 *** redoParagraph
  69
  70 It should be possible to check whether the new row is the same as the
  71 old one and keep its changed() status in this case. This would reduce
  72 a lot the amount of stuff to redraw.
  73
  74
  75 ** Put labels and friends in the Row as elements
  76
  77 It should not be necessary to access the Paragraph object to draw.
  78 Adding the static elements to Row is a lot of work, but worth it IMO.
  79
  80
  81 ** When a paragraph ends with a newline, compute correctly the height of the extra row.
  82
  83
  84 ** Merging bv::updateMetrics and tm::metrics
  85
  86 While the full metrics computation tries hard to limit the number of
  87 paragraphs that are rebroken, the version that is used for inner inset
  88 does not try any such optimization. This can be very bad for very tall
  89 insets. We should re-use the bv::updateMetrics logic:
  90  + transfer all the logic of bv::updateMetrics to tm.
  91  + Main InsetText should not be special.
  92
  93 The difficulty for a tall table cell for example, is that it may be
  94 necessary to break the whole contents to know the width of the cell.
  95 Also, the anchor is relative to the outer paragraph, which means that
  96 for a very long inset it is necessary to rebreak until the contents
  97 that needs to be shown (to compute the heights).
  98
  99 All in all, this is difficult to get right. This is less important now
 100 that SinglePar updates work in nested insets.
 101
 102
 103 * Description of current drawing mechanism
 104
 105 ** Three-stage drawing
 106
 107 There are three parts to drawing the work area:
 108
 109  + the metrics phase computes the size of insets and breaks the
 110    paragraphs into rows. It stores the dimension of insets (both
 111    normal and math) in bv::coordCache and the vertical position of the
 112    top-level paragraphs.
 113
 114  + the nodraw drawing phase paints the screen (see below) with a null
 115    painter. The only useful effect is to store the positions of
 116    visible insets.
 117
 118  + an update() signal is sent. This in turn will trigger a paint
 119    event, and the actual screen painting will happen then.
 120
 121 The machinery is controlled via bv::processUpdateFlags. This method is
 122 called at the end of bv::mouseEventDispatch and in
 123 GuiApplication::dispatch, via the updateCurrentView method. There are
 124 also several calls in code related to dialogs. We should evaluate
 125 whether this is correct.
 126
 127 Depending on the Update::flags passed to the method, it sets an update
 128 strategy in (NoScreenUpdate, SingleParUpdate, FullScreenUpdate,
 129 DecorationUpdate). It triggers a call to updateMetrics when either:
 130
 131  + Update::Force has been specified
 132  + Update::FitCursor has been specified and there is a need to scroll
 133    the display.
 134  + Update::SinglePar has been specified and the current paragraph has
 135    changed height.
 136
 137 If a computation of metrics has taken place, Force is removed from the
 138 flags and ForceDraw is added instead.
 139
 140 It is OK to call processUpdateFlags several times before an update. In
 141 this case, the effects are cumulative. processUpdateFlags executes the
 142 metrics-related actions, but defers the actual drawing to the next
 143 paint event.
 144
 145 The screen is drawn (with appropriate update strategy), except when
 146 update flag is Update::None.
 147
 148
 149 ** Metrics computation (and nodraw drawing phase)
 150
 151 This is done bv::updateMetrics. When the parameter 'force' of this
 152 method is true, that first thing that is done is to clear the metrics
 153 caches to start from a clean slate.
 154
 155 Then, starting upwards then downwards from the anchor paragraph
 156 (anchor_pit_) and its vertical position (anchor_ypos_),
 157 tm::updateMetrics every visible paragraph whose metrics is not know
 158 (all of them when force==true) is recomputed using tm::redoParagraph.
 159
 160 tm::redoParagraph will call Inset::metrics for each inset. In the case
 161 of text insets, this will invoke recursively tm::metrics, which redoes
 162 all the paragraphs of the inset. Then, a single big row is created in
 163 tm::tokenizeParagraph, which is later broken in multiple rows by
 164 tm::breakParagraph.
 165
 166 If it turns out that the top or bottom margin are incorrect (paragraphs
 167 are too high/low), tm::updateMetrics will be called again with fixed
 168 values of anchor_ypos_ (this does not incur much extra work).
 169
 170 At the end of bv::updateMetrics, bv::updatePosCache is called. It triggers
 171 a repaint of the document with a NullPainter (a painter that does
 172 nothing). This has the effect of caching all insets positions.
 173
 174 This way of working means that scrolling can be achieved by just
 175 updating anchor_ypos_ and calling bv::processUpdateFlags(Update::ForceDraw).
 176
 177 ** Drawing the work area.
 178
 179 This is done in bv::draw. This method is triggered by a paint event,
 180 mainly called through Buffer::changed, which draws all the work areas
 181 that show the given buffer.
 182
 183 Note that, When Buffer::changed is called outside of
 184 bv::processUpdateFlags, it is not clear whether the update strategy
 185 has been set to a reasonable value beforehand.
 186
 187 The action depends on the update strategy:
 188
 189  + NoScreenUpdate: repaint the whole screen with drawing disabled.
 190    This is only needed to update the inset positions. I am not sure
 191    when this is necessary, actually. This is triggered when:
 192    - Update::FitCursor is set but the cursor is already visible. It is
 193      not clear why something needs to be done in this case, since this
 194      should be equivalent to Update::None.
 195    - this is also set when update flag is Update::None, but this value
 196      is AFAICS not acted on in the code (meaning that nothing happens
 197      at all in this case).
 198
 199  + FullScreenUpdate: repaint the whole screen. This is set when:
 200    - updateMetrics has been invoked.
 201    - scroll value of current row has changed (although this should not
 202      be necessary).
 203
 204  + DecorationUpdate: actually like FullScreenUpdate, although it is
 205    intended to only update inset decorations. This triggers when:
 206    - Update::Decoration is set (without Update::Force) as flag.
 207    - An hovered inset is detected.
 208
 209  + SingleParUpdate: only tries to repaint current paragraph in a way
 210    that is not yet very clear to me.
 211
 212 BufferView::draw can also be called with a null painter from
 213 BufferView::updateMetrics().