-# -*- org-mode -*-
+# -*- 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
Abbreviations:
bv: BufferView
pm: ParagraphMetrics
-tm::TextMetrics
+tm: TextMetrics
* Questions / Ideas
These questions are consequences of the description made in the
following section. Some actions are proposed.
-** Inset cache
-
-Why do we store inset dimensions both in bv::coordCache and in
-pm::insetDimension? The later one is bad when same
-buffer is shown in different views.
-
-I propose to get rid of pm::insetDimension.
-
** 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.
-
-** Two phase drawing
-
-Why is it necessary to set the inset positions in the drawing phase?
-It seems to me that everything can be done in the metrics phase (at
-least for non-math insets).
+This flag only has an effect in the current BufferView and at
+top-level, but I think it is useful in other views too. Doing this
+will require some work on the update pipeline, though.
** Buffer::change issues
When calling Buffer::changed outside of bv::processUpdateFlags,
-how do we now that the update strategy is set correctly? It is
+how do we know 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?
-** Metrics outside of visible area
-Why is it required to compute metrics on page above and below the
-visible area? Couldn't this be done on demand? I suspect this could be
-made transparent by doing it in the proper metrics-fetching method.
+** How to avoid redraw with FitCursor when the cursor is already OK?
+
+In this case, we invoke Buffer::change(false) with drawing disabled
+and NoScreenUpdate strategy.
+
+In the draw phase, bv::checkCursorScrollOffset (the horizontal
+scrolling machinery) will change the strategy to FullScreenUpdate if
+the current row needs further scrolling.
+
+When the update strategy it kept to NoScreenUpdate, there is currently
+a no-draw full repaint, which should not be necessary. It would be
+possible to avoid that if the call to checkCursorScrollOffset was done
+in bv::processUpdateFlags instead of bv::draw.
+
+The global idea would be to extend FitCursor to cover also horizontal
+cursor.
+
+
+* Clean-up of drawing code
+
+** Set Row::changed() in a finer way
-** What happens with FitCursor when the cursor is already OK?
+*** singleParUpdate
-In this case, we invoke Buffer::change(false) with drawing disabled,
-which means that the paint machinery is invoked to update inset
-positions. Why is this necessary at all?
+When the height of the current paragraph changes, there is no need for
+a full screen update. Only the rows after the current one need to have
+their position recomputed.
+
+This is also true when scrolling (how to do that?)
+
+*** redoParagraph
+
+It should be possible to check whether the new row is the same as the
+old one and keep its changed() status in this case. This would reduce
+a lot the amount of stuff to redraw.
+
+** Put labels and friends in the Row as elements
+
+It should not be necessary to access the Paragraph object to draw.
+Adding the static elements to Row is a lot of work, but worth it IMO.
+
+** When a paragraph ends with a newline, compute correctly the height of the extra row.
** 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. How difficult would it be to re-use the bv::updateMetrics logic?
+insets. We should re-use the bv::updateMetrics logic:
+ + transfer all the logic of bv::updateMetrics to tm.
+ + Main InsetText should not be special.
+
+The difficulty for a tall table cell for example, is that it may be
+necessary to break the whole contents to know the width of the cell.
-* Two phase drawing
+* Description of current drawing mechanism
-There are two parts to drawing the work area:
+** Three-stage drawing
+
+There are three 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.
+ normal and math) in bv::coordCache.
- + 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 nodraw drawing phase paints the screen (see below) with a null
+ painter. The only useful effect is to store the inset positions.
+ + an update() signal is sent. This in turn will trigger a paint
+ event, and the actual screen painting will happen then.
The machinery is controlled via bv::processUpdateFlags. This method is
called at the end of bv::mouseEventDispatch and in
+ Update::Force has been specified
+ Update::FitCursor has been specified and there is a need to scroll
the display.
- + the current paragraph, after rebreak, has the same height as in
- existing metrics. Note that the Update::SinglePar flag is *never*
- taken into account.
+ + Update::SinglePar has been specified and the current paragraph has
+ not changed height.
+
+If a computation of metrics has taken place, Force is removed from the
+flags and ForceDraw is added instead.
+
+It is OK to call processUpateFlags several times before an update. In
+this case, the effects are cumulative. processUpdateFlags executes the
+metrics-related actions, but defers the actual drawing to the next
+paint event.
The screen is drawn (with appropriate update strategy), except when
update flag is Update::None.
-** Metrics computation
+** Metrics computation (and nodraw drawing phase)
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.
+all visible paragraphs. Some Paragraphs above or below the screen (needed
+for page up/down) and computed as needed.
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.
+Then, a single big row is created in tm::tokenizeParagraph, which is
+later broken in multiple rows by tm::breakParagraph.
+
+At the end of the function, bv::updatePosCache is called. It triggers
+a repaint of the document with a NullPainter (a painter that does
+nothing). This has the effect of caching all insets positions.
** 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.
+This is done in bv::draw. This method is triggered by a paint event,
+mainly called through 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
+ SingleParUpdate: only tries to repaint current paragraph in a way
that is not yet very clear to me.
+
+BufferView::draw can also be called with a null painter from
+BufferView::updateMetrics().
projects / lyx.git / blobdiff