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 * Proposals
  62
  63
  64 * Clean-up of drawing code
  65
  66 The goal is to make painting with drawing disable fast enough that it
  67 can be used after every metrics computation. Then we can separate real
  68 drawing from metrics.
  69
  70 ** DONE RowPainter
  71
  72 Inset position is set in paintInset, paintOnlyInsets, and paintText.
  73 This should be done only once in paintInset
  74
  75 ** DONE TextMetrics::drawParagraph
  76
  77 We can really simplify the code when drawing is disabled only
  78 paintInset needs to be called.
  79  + do right at the start when drawing is already disabled
  80  + do it in the loop for rows that are not visible on screen.
  81
  82 The only thing we want to do here is to set inset positions (for
  83 text). The other insets still use the painter with drawing disabled.
  84
  85 ** DONE Painter::text
  86
  87 We cannot remove (or make private) the version that uses a
  88 FontInfo because it is used by PainterInfo::draw. Document this and
  89 remove unused arguments rtl and double spacing. This would become a specialized helper.
  90 Proposed solution: keep the existing function, but private and without
  91 optional arguments.
  92
  93 Avoid to return (and thus compute) the width of strings?
  94  + used by InsetSpecialChar (fixable)
  95  + used by textDecoration() in text(): more difficult to fix
  96
  97 Idea: add a version of text where wordspacing and textwidth (giving
  98 the width of strings) are required parameters and remove optional
  99 version.
 100
 101 ==> more versions, no optional parameters.
 102
 103 ** DONE When a document ends with a newline, add the bottom margin anyway
 104
 105 The code that tests for a newline was added at 6bb98d07 in 2007.
 106
 107 ** When a paragraph ends with a newline, compute correctly the height of the extra row.
 108 ** Rewrite TextMetrics::completionPosAndDim using row information
 109
 110 Currently it uses setRowHeight in a very weird way. In particular the
 111 topBottomSpace parameter should be removed after that.
 112
 113 ** Rewrite TextMetrics::editXY, checkInsetHit using row information (getPosNearX)?
 114
 115    The helper version should return a Row::Element instead of an InsetTable.
 116
 117 ** TODO make Inset::display() more useful
 118
 119 [This has been started in the features/betterbreak branch. Time will
 120 tell whether it really helps. The question in particular is the
 121 handling of separator insets]
 122
 123 Extending the DisplayType enum would allow to remove special cases
 124 from the code.
 125
 126 The enumeration could be like
 127 : Inline = 0
 128 : BreakBefore = 1 // break row before this inset
 129 : BreakAfter = 2 // break row after this inset
 130 : CanBreakAfter = 4 // optionally break row after this inset
 131 : AlignLeft = 8
 132 : AlignRight = 16
 133 : NoBoundary = 32 // do not allow cursor to go at the end of the row
 134 :                 //before display inset
 135 : Display = BreakBefore|BreakAfter
 136
 137 A display equation would be Display, other could be Display|AlignLeft
 138 BreakAfter can be used by Newline or separator insets
 139 CanBreakAfter can be used by the optional hyphen InsetSpecialChar.
 140
 141 ** Set inset position during metrics phase
 142
 143 In order to do that, a no-paint drawing will be initiated after every
 144 redoParagraph. This code path will need to be made as fast as possible.
 145
 146 Effect: avoid depending on actual drawing having taken place. In turn,
 147 it will allow to do drawing on paint events, like any reasonable
 148 application would do.
 149
 150 ** Cleanup after complete metrics
 151    Then the following can be done:
 152    + remove hack in InsetMathNest::drawSelection
 153    + remove painting when not inside in drawParagraph
 154    + remove Cursor::inCoordCache?
 155
 156 ** Use Row for MathData
 157
 158 It may not be so difficult. Implement x2pos and pos2x from
 159 the TM:cursorX and TM::getPosNearX, and use them for both text and
 160 math.
 161
 162 Will the strings display OK if drawing string-wise?
 163
 164 Then it would be possible to streamline drawing with disabled painter.
 165
 166 ** Paint directly to screen
 167
 168 Instead of using an intermediary pixmap. I have no idea of how
 169 difficult it will prove.
 170 One benefit will be that subpixel aliasing will work again (#9972)
 171
 172 ** Merging bv::updateMetrics and tm::metrics
 173
 174 While the full metrics computation tries hard to limit the number of
 175 paragraphs that are rebroken, the version that is used for inner inset
 176 does not try any such optimization. This can be very bad for very tall
 177 insets. We should re-use the bv::updateMetrics logic:
 178  + transfer all the logic of bv::updateMetrics to tm.
 179  + Main InsetText should not be special.
 180
 181 The difficuly for a tall table cell for example, is that it may be
 182 necessary to break the whole contents to know the width of the cell.
 183
 184
 185 * Description of current drawing mechanism
 186
 187 ** Two stage drawing
 188
 189 There are two parts to drawing the work area:
 190
 191  + the metrics phase computes the size of insets and breaks the
 192    paragraphs into rows. It stores the dimension of insets (both
 193    normal and math) in bv::coordCache.
 194
 195  + the drawing phase draws the contents and caches the inset
 196    positions. Since the caching of positions is useful in itself,
 197    there is a provision for drawing "without" drawing when the only
 198    thing we want is to cache inset positions
 199    (Painter::setDrawingEnabled).
 200
 201 The machinery is controlled via bv::processUpdateFlags. This method is
 202 called at the end of bv::mouseEventDispatch and in
 203 GuiApplication::dispatch, via the updateCurrentView method. There are
 204 also several calls in code related to dialogs. We should evaluate
 205 whether this is correct.
 206
 207 Depending on the Update::flags passed to the method, it sets an update
 208 strategy in (NoScreenUpdate, SingleParUpdate, FullScreenUpdate,
 209 DecorationUpdate). It triggers a recomputation of the metrics when either:
 210
 211  + Update::Force has been specified
 212  + Update::FitCursor has been specified and there is a need to scroll
 213    the display.
 214  + the current paragraph, after rebreak, does not have the same height as in
 215    existing metrics. Note that the Update::SinglePar flag is *never*
 216    taken into account.
 217
 218 The screen is drawn (with appropriate update strategy), except when
 219 update flag is Update::None.
 220
 221
 222 ** Metrics computation
 223
 224 This is triggered by bv::updateMetrics, which calls tm::redoParagraph for
 225   + all visible paragraphs
 226   + paragraph above the screen (up to one page)
 227   + paragraphs below the screen (up to one page again)
 228
 229 The paragraphs outside of the screen are required to make PageUp/Down
 230 work.
 231
 232 tm::redoParagraph will call Inset::metrics for each inset. In the case
 233 of text insets, this will invoke recursively tm::metrics, which redoes
 234 all the paragraphs of the inset.
 235
 236
 237 ** Drawing the work area.
 238
 239 This is done in bv::draw. This method is triggered mainly by
 240 Buffer::changed, which draws all the work areas that show the given buffer.
 241
 242 Note that, When Buffer::changed is called outside of
 243 bv::processUpdateFlags, it is not clear whether the update strategy
 244 has been set to a reasonable value beforehand.
 245
 246 The action depends on the update strategy:
 247
 248  + NoScreenUpdate: repaint the whole screen with drawing disabled.
 249    This is only needed to update the inset positions. I am not sure
 250    when this is necessary, actually. This is triggered when:
 251    - Update::FitCursor is set but the cursor is already visible. It is
 252      not clear why something needs to be done in this case, since this
 253      should be equivalent to Update::None.
 254    - this is also set when update flag is Update::None, but this value
 255      is AFAICS not acted on in the code (meaning that nothing happens
 256      at all in this case).
 257
 258  + FullScreenUpdate: repaint the whole screen. This is set when:
 259    - updateMetrics has been invoked.
 260    - scroll value of current row has changed (although this should not
 261      be necessary).
 262
 263  + DecorationUpdate: actually like FullScreenUpdate, although it is
 264    intended to only update inset decorations. This triggers when:
 265    - Update::Decoration is set (without Update::Force) as flag.
 266    - An hovered inset is detected.
 267
 268  + SingleParUpdate: only tries to repaint current paragraph in a way
 269    that is not yet very clear to me.