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 ** Inset cache
  22
  23 Why do we store inset dimensions both in bv::coordCache and in
  24 pm::insetDimension? The later one is bad when same
  25 buffer is shown in different views.
  26
  27 I propose to get rid of pm::insetDimension.
  28
  29 ** SinglePar update
  30
  31 The flag Update::SinglePar is set in many places but never acted on.
  32 Instead, metrics update is skipped whenever the recorded height of
  33 current paragraph did not change and Update::Force was not specified.
  34 Is it better to keep that (which incurs extra work) or to condition it
  35 on Update::SinglePar? If the first solution is kept, the flag
  36 SingleParUpdate shall be removed.
  37
  38 Moreover, I fail to see (yet) where the 'single' part of the program
  39 is acted on.
  40
  41 ** Two phase drawing
  42
  43 Why is it necessary to set the inset positions in the drawing phase?
  44 It seems to me that everything can be done in the metrics phase (at
  45 least for non-math insets).
  46
  47 ** Buffer::change issues
  48
  49 When calling Buffer::changed outside of bv::processUpdateFlags,
  50 how do we now that the update strategy is set correctly? It is
  51 possible to reset the strategy at the end of bv::draw. What would be
  52 a good value? NoScreenUpdate?
  53
  54 On a related note, what is the semantics of a call to
  55 Buffer::changed(false)? What does the caller mean?
  56
  57 ** Metrics outside of visible area
  58
  59 Why is it required to compute metrics on page above and below the
  60 visible area? Couldn't this be done on demand? I suspect this could be
  61 made transparent by doing it in the proper metrics-fetching method.
  62
  63 ** What happens with FitCursor when the cursor is already OK?
  64
  65 In this case, we invoke Buffer::change(false) with drawing disabled,
  66 which means that the paint machinery is invoked to update inset
  67 positions. Why is this necessary at all?
  68
  69 ** Merging bv::updateMetrics and tm::metrics
  70
  71 While the full metrics computation tries hard to limit the number of
  72 paragraphs that are rebroken, the version that is used for inner inset
  73 does not try any such optimization. This can be very bad for very tall
  74 insets. How difficult would it be to re-use the bv::updateMetrics logic?
  75
  76
  77 * Two phase drawing
  78
  79 There are two parts to drawing the work area:
  80
  81  + the metrics phase computes the size of insets and breaks the
  82    paragraphs into rows. It stores the dimension of insets (both
  83    normal and math) in bv::coordCache, and the size of normal
  84    insets in pm::insetDimension.
  85
  86  + the drawing phase draws the contents and caches the inset
  87    positions. Since the caching of positions is useful in itself,
  88    there is a provision for drawing "without" drawing when the only
  89    thing we want is to cache inset positions
  90    (Painter::setDrawingEnabled).
  91
  92
  93 The machinery is controlled via bv::processUpdateFlags. This method is
  94 called at the end of bv::mouseEventDispatch and in
  95 GuiApplication::dispatch, via the updateCurrentView method. There are
  96 also several calls in code related to dialogs. We should evaluate
  97 whether this is correct.
  98
  99 Depending on the Update::flags passed to the method, it sets an update
 100 strategy in (NoScreenUpdate, SingleParUpdate, FullScreenUpdate,
 101 DecorationUpdate). It triggers a recomputation of the metrics when either:
 102
 103  + Update::Force has been specified
 104  + Update::FitCursor has been specified and there is a need to scroll
 105    the display.
 106  + the current paragraph, after rebreak, does not have the same height as in
 107    existing metrics. Note that the Update::SinglePar flag is *never*
 108    taken into account.
 109
 110 The screen is drawn (with appropriate update strategy), except when
 111 update flag is Update::None.
 112
 113
 114 * Metrics computation
 115
 116 This is triggered by bv::updateMetrics, which calls tm::redoParagraph for
 117   + all visible paragraphs
 118   + paragraph above the screen (up to one page)
 119   + paragraphs below the screen (up to one page again)
 120
 121 The paragraphs outside of the screen are required to make PageUp/Down
 122 work.
 123
 124 tm::redoParagraph will call Inset::metrics for each inset. In the case
 125 of text insets, this will invoke recursively tm::metrics, which redoes
 126 all the paragraphs of the inset.
 127
 128
 129 * Drawing the work area.
 130
 131 This is done in bv::draw. This method is triggered mainly by
 132 Buffer::changed, which draws all the work areas that show the given buffer.
 133
 134 Note that, When Buffer::changed is called outside of
 135 bv::processUpdateFlags, it is not clear whether the update strategy
 136 has been set to a reasonable value beforehand.
 137
 138 The action depends on the update strategy:
 139
 140  + NoScreenUpdate: repaint the whole screen with drawing disabled.
 141    This is only needed to update the inset positions. I am not sure
 142    when this is necessary, actually. This is triggered when:
 143    - Update::FitCursor is set but the cursor is already visible. It is
 144      not clear why something needs to be done in this case, since this
 145      should be equivalent to Update::None.
 146    - this is also set when update flag is Update::None, but this value
 147      is AFAICS not acted on in the code (meaning that nothing happens
 148      at all in this case).
 149
 150  + FullScreenUpdate: repaint the whole screen. This is set when:
 151    - updateMetrics has been invoked.
 152    - scroll value of current row has changed (although this should not
 153      be necessary).
 154
 155  + DecorationUpdate: actually like FullScreenUpdate, although it is
 156    intended to only update inset decorations. This triggers when:
 157    - Update::Decoration is set (without Update::Force) as flag.
 158    - An hovered inset is detected.
 159
 160  + SingleParUpdate: only tries to repaint current paragraph in a way
 161    that is not yet very clear to me.