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 The goal is to make painting with drawing disable fast enough that it
  64 can be used after every metrics computation. Then we can separate real
  65 drawing from metrics.
  66
  67 Other changes are only clean-ups.
  68
  69 ** When a paragraph ends with a newline, compute correctly the height of the extra row.
  70 ** Rewrite TextMetrics::editXY, checkInsetHit using row information (getPosNearX)?
  71
  72    The helper version should return a Row::Element instead of an InsetTable.
  73
  74 ** Remember rtl status in the row object
  75
  76 This will avoid to pass a Paragraph object to methods that do not need it.
  77
  78 ** Rewrite RowPainter::paintSelection using row information
  79
  80 Currently it uses some very complicated code. It should be possible to
  81 reuse the logic of paintStringAndSel.
  82
  83 ** Set inset position during metrics phase
  84
  85 In order to do that, a no-paint drawing will be initiated after every
  86 redoParagraph. This code path will need to be made as fast as possible.
  87
  88 Effect: avoid depending on actual drawing having taken place. In turn,
  89 it will allow to do drawing on paint events, like any reasonable
  90 application would do.
  91
  92 ** Cleanup after complete metrics
  93    Then the following can be done:
  94    + remove hack in InsetMathNest::drawSelection
  95    + remove painting when not inside in drawParagraph
  96    + remove Cursor::inCoordCache?
  97
  98 ** Use Row for MathData
  99
 100 It may not be so difficult. Implement x2pos and pos2x from
 101 the TM:cursorX and TM::getPosNearX, and use them for both text and
 102 math.
 103
 104 Will the strings display OK if drawing string-wise?
 105
 106 Then it would be possible to streamline drawing with disabled painter.
 107
 108 ** Paint directly to screen
 109
 110 Instead of using an intermediary pixmap. I have no idea of how
 111 difficult it will prove.
 112 One benefit will be that subpixel aliasing will work again (#9972)
 113
 114 ** Merging bv::updateMetrics and tm::metrics
 115
 116 While the full metrics computation tries hard to limit the number of
 117 paragraphs that are rebroken, the version that is used for inner inset
 118 does not try any such optimization. This can be very bad for very tall
 119 insets. We should re-use the bv::updateMetrics logic:
 120  + transfer all the logic of bv::updateMetrics to tm.
 121  + Main InsetText should not be special.
 122
 123 The difficuly for a tall table cell for example, is that it may be
 124 necessary to break the whole contents to know the width of the cell.
 125
 126
 127 * Description of current drawing mechanism
 128
 129 ** Two stage drawing
 130
 131 There are two parts to drawing the work area:
 132
 133  + the metrics phase computes the size of insets and breaks the
 134    paragraphs into rows. It stores the dimension of insets (both
 135    normal and math) in bv::coordCache.
 136
 137  + the drawing phase draws the contents and caches the inset
 138    positions. Since the caching of positions is useful in itself,
 139    there is a provision for drawing "without" drawing when the only
 140    thing we want is to cache inset positions
 141    (Painter::setDrawingEnabled).
 142
 143 The machinery is controlled via bv::processUpdateFlags. This method is
 144 called at the end of bv::mouseEventDispatch and in
 145 GuiApplication::dispatch, via the updateCurrentView method. There are
 146 also several calls in code related to dialogs. We should evaluate
 147 whether this is correct.
 148
 149 Depending on the Update::flags passed to the method, it sets an update
 150 strategy in (NoScreenUpdate, SingleParUpdate, FullScreenUpdate,
 151 DecorationUpdate). It triggers a recomputation of the metrics when either:
 152
 153  + Update::Force has been specified
 154  + Update::FitCursor has been specified and there is a need to scroll
 155    the display.
 156  + the current paragraph, after rebreak, does not have the same height as in
 157    existing metrics. Note that the Update::SinglePar flag is *never*
 158    taken into account.
 159
 160 The screen is drawn (with appropriate update strategy), except when
 161 update flag is Update::None.
 162
 163
 164 ** Metrics computation
 165
 166 This is triggered by bv::updateMetrics, which calls tm::redoParagraph for
 167 all visible paragraphs. Paragraphs above or below the screen (needed
 168 for page up/down) and computed as needed.
 169
 170 tm::redoParagraph will call Inset::metrics for each inset. In the case
 171 of text insets, this will invoke recursively tm::metrics, which redoes
 172 all the paragraphs of the inset.
 173
 174
 175 ** Drawing the work area.
 176
 177 This is done in bv::draw. This method is triggered mainly by
 178 Buffer::changed, which draws all the work areas that show the given buffer.
 179
 180 Note that, When Buffer::changed is called outside of
 181 bv::processUpdateFlags, it is not clear whether the update strategy
 182 has been set to a reasonable value beforehand.
 183
 184 The action depends on the update strategy:
 185
 186  + NoScreenUpdate: repaint the whole screen with drawing disabled.
 187    This is only needed to update the inset positions. I am not sure
 188    when this is necessary, actually. This is triggered when:
 189    - Update::FitCursor is set but the cursor is already visible. It is
 190      not clear why something needs to be done in this case, since this
 191      should be equivalent to Update::None.
 192    - this is also set when update flag is Update::None, but this value
 193      is AFAICS not acted on in the code (meaning that nothing happens
 194      at all in this case).
 195
 196  + FullScreenUpdate: repaint the whole screen. This is set when:
 197    - updateMetrics has been invoked.
 198    - scroll value of current row has changed (although this should not
 199      be necessary).
 200
 201  + DecorationUpdate: actually like FullScreenUpdate, although it is
 202    intended to only update inset decorations. This triggers when:
 203    - Update::Decoration is set (without Update::Force) as flag.
 204    - An hovered inset is detected.
 205
 206  + SingleParUpdate: only tries to repaint current paragraph in a way
 207    that is not yet very clear to me.