# -*- org -*- Understanding the painting process This file tries to describe the state of the metrics/painting mechanism, and identify the improvements that could be made. The first section can be read alone, although the context for them is really given in the following ones. Please keep this file up to date as the code evolves!!! Abbreviations: bv: BufferView pm: ParagraphMetrics tm::TextMetrics * Questions / Ideas These questions are consequences of the description made in the following section. Some actions are proposed. ** SinglePar update The flag Update::SinglePar is set in many places but never acted on. Instead, metrics update is skipped whenever the recorded height of current paragraph did not change and Update::Force was not specified. Is it better to keep that (which incurs extra work) or to condition it on Update::SinglePar? If the first solution is kept, the flag SingleParUpdate shall be removed. Moreover, I fail to see (yet) where the 'single' part of the program is acted on. ** Buffer::change issues When calling Buffer::changed outside of bv::processUpdateFlags, how do we now that the update strategy is set correctly? It is possible to reset the strategy at the end of bv::draw. What would be a good value? NoScreenUpdate? On a related note, what is the semantics of a call to Buffer::changed(false)? What does the caller mean? ** What happens with FitCursor when the cursor is already OK? In this case, we invoke Buffer::change(false) with drawing disabled, which means that the paint machinery is invoked to update inset positions. Actually, this was added as part of the horizontal scrolling GSoC work. We need to investigate how costly this is. * Proposals ** get rid of pm::insetDimension. The information contained there is already in bv::coordCache. Effect: only code simplification. ** set inset position during metrics phase This implies to set inset positions relative to outer isnet during metrics phase and then in a second loop to descend into insets and update positions correctly. Effect: avoid going through the painter machinery when it is not necessary. ** Merging bv::updateMetrics and tm::metrics While the full metrics computation tries hard to limit the number of paragraphs that are rebroken, the version that is used for inner inset does not try any such optimization. This can be very bad for very tall insets. We should re-use the bv::updateMetrics logic: + transfer all the logic of bv::updateMetrics to tm. + Main InsetText should not be special. ** Metrics outside of visible area Currently metrics are computed for current visible paet of text, the page above and the page below. It should be possible to compute hidden rows ony on demand, although it might be a bit slow. There was a proposal to always compute _all_ rows, but this may become expensive for large files. This would though help scrolling. * Two phase drawing There are two parts to drawing the work area: + the metrics phase computes the size of insets and breaks the paragraphs into rows. It stores the dimension of insets (both normal and math) in bv::coordCache, and the size of normal insets in pm::insetDimension. + the drawing phase draws the contents and caches the inset positions. Since the caching of positions is useful in itself, there is a provision for drawing "without" drawing when the only thing we want is to cache inset positions (Painter::setDrawingEnabled). The machinery is controlled via bv::processUpdateFlags. This method is called at the end of bv::mouseEventDispatch and in GuiApplication::dispatch, via the updateCurrentView method. There are also several calls in code related to dialogs. We should evaluate whether this is correct. Depending on the Update::flags passed to the method, it sets an update strategy in (NoScreenUpdate, SingleParUpdate, FullScreenUpdate, DecorationUpdate). It triggers a recomputation of the metrics when either: + Update::Force has been specified + Update::FitCursor has been specified and there is a need to scroll the display. + the current paragraph, after rebreak, does not have the same height as in existing metrics. Note that the Update::SinglePar flag is *never* taken into account. The screen is drawn (with appropriate update strategy), except when update flag is Update::None. * Metrics computation This is triggered by bv::updateMetrics, which calls tm::redoParagraph for + all visible paragraphs + paragraph above the screen (up to one page) + paragraphs below the screen (up to one page again) The paragraphs outside of the screen are required to make PageUp/Down work. tm::redoParagraph will call Inset::metrics for each inset. In the case of text insets, this will invoke recursively tm::metrics, which redoes all the paragraphs of the inset. * Drawing the work area. This is done in bv::draw. This method is triggered mainly by Buffer::changed, which draws all the work areas that show the given buffer. Note that, When Buffer::changed is called outside of bv::processUpdateFlags, it is not clear whether the update strategy has been set to a reasonable value beforehand. The action depends on the update strategy: + NoScreenUpdate: repaint the whole screen with drawing disabled. This is only needed to update the inset positions. I am not sure when this is necessary, actually. This is triggered when: - Update::FitCursor is set but the cursor is already visible. It is not clear why something needs to be done in this case, since this should be equivalent to Update::None. - this is also set when update flag is Update::None, but this value is AFAICS not acted on in the code (meaning that nothing happens at all in this case). + FullScreenUpdate: repaint the whole screen. This is set when: - updateMetrics has been invoked. - scroll value of current row has changed (although this should not be necessary). + DecorationUpdate: actually like FullScreenUpdate, although it is intended to only update inset decorations. This triggers when: - Update::Decoration is set (without Update::Force) as flag. - An hovered inset is detected. + SingleParUpdate: only tries to repaint current paragraph in a way that is not yet very clear to me.