2 Understanding the painting process
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.
9 Please keep this file up to date as the code evolves!!!
18 These questions are consequences of the description made in the
19 following section. Some actions are proposed.
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.
30 Moreover, I fail to see (yet) where the 'single' part of the program
33 ** Buffer::change issues
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?
40 On a related note, what is the semantics of a call to
41 Buffer::changed(false)? What does the caller mean?
43 ** How to avoid redraw with FitCursor when the cursor is already OK?
45 In this case, we invoke Buffer::change(false) with drawing disabled
46 and NoScreenUpdate strategy.
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.
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.
57 The global idea would be to extend FitCursor to cover also horizontal
61 * Clean-up of drawing code
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
67 Other changes are only clean-ups.
71 Inset position is set in paintInset, paintOnlyInsets, and paintText.
72 This should be done only once in paintInset
74 ** DONE TextMetrics::drawParagraph
76 We can really simplify the code when drawing is disabled only
77 paintInset needs to be called.
78 + do right at the start when drawing is already disabled
79 + do it in the loop for rows that are not visible on screen.
81 The only thing we want to do here is to set inset positions (for
82 text). The other insets still use the painter with drawing disabled.
86 We cannot remove (or make private) the version that uses a
87 FontInfo because it is used by PainterInfo::draw. Document this and
88 remove unused arguments rtl and double spacing. This would become a specialized helper.
89 Proposed solution: keep the existing function, but private and without
92 Avoid to return (and thus compute) the width of strings?
93 + used by InsetSpecialChar (fixable)
94 + used by textDecoration() in text(): more difficult to fix
96 Idea: add a version of text where wordspacing and textwidth (giving
97 the width of strings) are required parameters and remove optional
100 ==> more versions, no optional parameters.
102 ** DONE When a document ends with a newline, add the bottom margin anyway
104 The code that tests for a newline was added at 6bb98d07 in 2007.
106 ** When a paragraph ends with a newline, compute correctly the height of the extra row.
107 ** Rewrite TextMetrics::completionPosAndDim using row information
109 Currently it uses setRowHeight in a very weird way. In particular the
110 topBottomSpace parameter should be removed after that.
112 ** Rewrite TextMetrics::editXY, checkInsetHit using row information (getPosNearX)?
114 The helper version should return a Row::Element instead of an InsetTable.
116 ** DONE Do not make RowPainter operations update x_
118 It is better to make them const and update x_ separately.
120 ** reorder the painting of the different elements.
122 In particular, if text is painted last, it will be more visible in the
123 presence of underlines (foreign language, change tracking, spell
126 ** DONE remove pit argument to breakRow
128 There are probably other places where the pit is not needed anymore:
129 computeRowMetrics, labelFill, setRowHeight, isLastRow, isFirstRow
131 ** Remember rtl status in the row object
133 This will avoid to pass a Paragraph object to methods that do not need it.
135 ** Rewrite RowPainter::paintSelection using row information
137 Currently it uses some very complicated code. It should be possible to
138 reuse the logic of paintStringAndSel.
140 ** Set inset position during metrics phase
142 In order to do that, a no-paint drawing will be initiated after every
143 redoParagraph. This code path will need to be made as fast as possible.
145 Effect: avoid depending on actual drawing having taken place. In turn,
146 it will allow to do drawing on paint events, like any reasonable
147 application would do.
149 ** Cleanup after complete metrics
150 Then the following can be done:
151 + remove hack in InsetMathNest::drawSelection
152 + remove painting when not inside in drawParagraph
153 + remove Cursor::inCoordCache?
155 ** Use Row for MathData
157 It may not be so difficult. Implement x2pos and pos2x from
158 the TM:cursorX and TM::getPosNearX, and use them for both text and
161 Will the strings display OK if drawing string-wise?
163 Then it would be possible to streamline drawing with disabled painter.
165 ** Paint directly to screen
167 Instead of using an intermediary pixmap. I have no idea of how
168 difficult it will prove.
169 One benefit will be that subpixel aliasing will work again (#9972)
171 ** Merging bv::updateMetrics and tm::metrics
173 While the full metrics computation tries hard to limit the number of
174 paragraphs that are rebroken, the version that is used for inner inset
175 does not try any such optimization. This can be very bad for very tall
176 insets. We should re-use the bv::updateMetrics logic:
177 + transfer all the logic of bv::updateMetrics to tm.
178 + Main InsetText should not be special.
180 The difficuly for a tall table cell for example, is that it may be
181 necessary to break the whole contents to know the width of the cell.
184 * Description of current drawing mechanism
188 There are two parts to drawing the work area:
190 + the metrics phase computes the size of insets and breaks the
191 paragraphs into rows. It stores the dimension of insets (both
192 normal and math) in bv::coordCache.
194 + the drawing phase draws the contents and caches the inset
195 positions. Since the caching of positions is useful in itself,
196 there is a provision for drawing "without" drawing when the only
197 thing we want is to cache inset positions
198 (Painter::setDrawingEnabled).
200 The machinery is controlled via bv::processUpdateFlags. This method is
201 called at the end of bv::mouseEventDispatch and in
202 GuiApplication::dispatch, via the updateCurrentView method. There are
203 also several calls in code related to dialogs. We should evaluate
204 whether this is correct.
206 Depending on the Update::flags passed to the method, it sets an update
207 strategy in (NoScreenUpdate, SingleParUpdate, FullScreenUpdate,
208 DecorationUpdate). It triggers a recomputation of the metrics when either:
210 + Update::Force has been specified
211 + Update::FitCursor has been specified and there is a need to scroll
213 + the current paragraph, after rebreak, does not have the same height as in
214 existing metrics. Note that the Update::SinglePar flag is *never*
217 The screen is drawn (with appropriate update strategy), except when
218 update flag is Update::None.
221 ** Metrics computation
223 This is triggered by bv::updateMetrics, which calls tm::redoParagraph for
224 all visible paragraphs. Paragraphs above or below the screen (needed
225 for page up/down) and computed as needed.
227 tm::redoParagraph will call Inset::metrics for each inset. In the case
228 of text insets, this will invoke recursively tm::metrics, which redoes
229 all the paragraphs of the inset.
232 ** Drawing the work area.
234 This is done in bv::draw. This method is triggered mainly by
235 Buffer::changed, which draws all the work areas that show the given buffer.
237 Note that, When Buffer::changed is called outside of
238 bv::processUpdateFlags, it is not clear whether the update strategy
239 has been set to a reasonable value beforehand.
241 The action depends on the update strategy:
243 + NoScreenUpdate: repaint the whole screen with drawing disabled.
244 This is only needed to update the inset positions. I am not sure
245 when this is necessary, actually. This is triggered when:
246 - Update::FitCursor is set but the cursor is already visible. It is
247 not clear why something needs to be done in this case, since this
248 should be equivalent to Update::None.
249 - this is also set when update flag is Update::None, but this value
250 is AFAICS not acted on in the code (meaning that nothing happens
251 at all in this case).
253 + FullScreenUpdate: repaint the whole screen. This is set when:
254 - updateMetrics has been invoked.
255 - scroll value of current row has changed (although this should not
258 + DecorationUpdate: actually like FullScreenUpdate, although it is
259 intended to only update inset decorations. This triggers when:
260 - Update::Decoration is set (without Update::Force) as flag.
261 - An hovered inset is detected.
263 + SingleParUpdate: only tries to repaint current paragraph in a way
264 that is not yet very clear to me.