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