@@ -21,17 +21,17 @@ along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
2121
2222 Redisplay.
2323
24- Emacs separates the task of updating the display from code
25- modifying global state, e.g. buffer text. This way functions
26- operating on buffers don't also have to be concerned with updating
27- the display.
28-
29- Updating the display is triggered by the Lisp interpreter when it
30- decides it's time to do it. This is done either automatically for
31- you as part of the interpreter's command loop or as the result of
32- calling Lisp functions like `sit-for'. The C function
33- `redisplay_internal' in xdisp.c is the only entry into the inner
34- redisplay code.
24+ Emacs separates the task of updating the display -- which we call
25+ "redisplay" -- from the code modifying global state, e.g. buffer
26+ text. This way functions operating on buffers don't also have to
27+ be concerned with updating the display as result of their
28+ operations.
29+
30+ Redisplay is triggered by the Lisp interpreter when it decides it's
31+ time to do it. This is done either automatically for you as part
32+ of the interpreter's command loop, or as the result of calling Lisp
33+ functions like `sit-for'. The C function `redisplay_internal' in
34+ xdisp.c is the only entry into the inner redisplay code.
3535
3636 The following diagram shows how redisplay code is invoked. As you
3737 can see, Lisp calls redisplay and vice versa.
@@ -75,63 +75,97 @@ along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
7575 and to make these changes visible. Preferably it would do that in
7676 a moderately intelligent way, i.e. fast.
7777
78- Changes in buffer text can be deduced from window and buffer
78+ At its highest level, redisplay can be divided into 3 distinct
79+ steps, all of which are visible in `redisplay_internal':
80+
81+ . decide which frames need their windows to be considered for redisplay
82+ . for each window whose display might need to be updated, compute
83+ a structure, called "glyph matrix", which describes how it
84+ should look on display
85+ . actually update the display of windows on the glass where the
86+ newly obtained glyph matrix differs from the one produced by the
87+ previous redisplay cycle
88+
89+ The first of these steps is done by `redisplay_internal' itself, by
90+ looping through all the frames and testing their various flags,
91+ such as their visibility. The result of this could be that only
92+ the selected window on the selected frame must be redisplayed, or
93+ it could conclude that other windows need to be considered as well.
94+
95+ The second step considers each window that might need to be
96+ redisplayed. This could be only the selected window, or the window
97+ trees of one or more frames. The function which considers a window
98+ and decides whether it actually needs redisplay is
99+ `redisplay_window'. It does so by looking at the changes in
100+ position of point, in buffer text, in text properties, overlays,
101+ etc. These changes can be deduced from window and buffer
79102 structures, and from some global variables like `beg_unchanged' and
80- `end_unchanged'. The contents of the display are additionally
81- recorded in a `glyph matrix', a two-dimensional matrix of glyph
82- structures. Each row in such a matrix corresponds to a line on the
83- display, and each glyph in a row corresponds to a column displaying
84- a character, an image, or what else. This matrix is called the
85- `current glyph matrix' or `current matrix' in redisplay
86- terminology.
87-
88- For buffer parts that have been changed since the last update, a
89- second glyph matrix is constructed, the so called `desired glyph
90- matrix' or short `desired matrix'. Current and desired matrix are
91- then compared to find a cheap way to update the display, e.g. by
92- reusing part of the display by scrolling lines. The actual update
93- of the display of each window by comparing the desired and the
94- current matrix is done by `update_window', which calls functions
95- which draw to the glass (those functions are specific to the type
96- of the window's frame: X, w32, NS, etc.).
103+ `end_unchanged'. The current contents of the display are recorded
104+ in a `glyph matrix', a two-dimensional matrix of glyph structures.
105+ Each row in such a matrix corresponds to a line on the display, and
106+ each glyph in a row corresponds to a column displaying a character,
107+ an image, or what else. This matrix is called the `current glyph
108+ matrix', or `current matrix', in redisplay terminology.
109+
110+ For buffer parts that have been changed since the last redisplay,
111+ `redisplay_window' constructs a second glyph matrix, the so called
112+ `desired glyph matrix' or short `desired matrix'. It does so in
113+ the most optimal way possible, avoiding the examination of text
114+ that didn't change, reusing portions of the current matrix if
115+ possible, etc. It could, in particular, decide that a window
116+ doesn't need to be redisplayed at all.
117+
118+ This second step of redisplay also updates the parts of the desired
119+ matrix that correspond to the mode lines, header lines, and
120+ tab-lines of the windows which need that; see `display_mode_lines'.
121+
122+ In the third and last step, the current and desired matrix are then
123+ compared to find a cheap way to update the display, e.g. by reusing
124+ part of the display by scrolling lines. The actual update of the
125+ display of each window, by comparing the desired and the current
126+ matrix, is done by `update_window', which calls functions which
127+ draw to the glass (those functions are specific to the type of the
128+ window's frame: X, w32, NS, etc.).
97129
98130 Once the display of a window on the glass has been updated, its
99131 desired matrix is used to update the corresponding rows of the
100132 current matrix, and then the desired matrix is discarded.
101133
102134 You will find a lot of redisplay optimizations when you start
103- looking at the innards of redisplay . The overall goal of all these
104- optimizations is to make redisplay fast because it is done
105- frequently. Some of these optimizations are implemented by the
106- following functions:
135+ looking at the innards of `redisplay_window' . The overall goal of
136+ all these optimizations is to make redisplay fast because it is
137+ done frequently. Some of these optimizations are implemented by
138+ the following functions:
107139
108140 . try_cursor_movement
109141
110- This function tries to update the display if the text in the
111- window did not change and did not scroll, only point moved, and
112- it did not move off the displayed portion of the text.
142+ This optimization is applicable if the text in the window did
143+ not change and did not scroll, only point moved, and it did not
144+ move off the displayed portion of the text. In that case, the
145+ window's glyph matrix is still valid, and only the position of
146+ the cursor might need to be updated.
113147
114148 . try_window_reusing_current_matrix
115149
116- This function reuses the current matrix of a window when text
117- has not changed, but the window start changed (e.g., due to
150+ This function reuses the current glyph matrix of a window when
151+ text has not changed, but the window start changed (e.g., due to
118152 scrolling).
119153
120154 . try_window_id
121155
122- This function attempts to redisplay a window by reusing parts of
123- its existing display . It finds and reuses the part that was not
124- changed, and redraws the rest. (The "id" part in the function's
125- name stands for "insert/delete", not for "identification" or
126- somesuch.)
156+ This function attempts to update a window's glyph matrix by
157+ reusing parts of its current glyph matrix . It finds and reuses
158+ the part that was not changed, and regenerates the rest. (The
159+ "id" part in the function's name stands for "insert/delete", not
160+ for "identification" or somesuch.)
127161
128162 . try_window
129163
130- This function performs the full, unoptimized, redisplay of a
131- single window assuming that its fonts were not changed and that
132- the cursor will not end up in the scroll margins. (Loading
133- fonts requires re-adjustment of dimensions of glyph matrices,
134- which makes this method impossible to use.)
164+ This function performs the full, unoptimized, generation of a
165+ single window's glyph matrix, assuming that its fonts were not
166+ changed and that the cursor will not end up in the scroll
167+ margins. (Loading fonts requires re-adjustment of dimensions of
168+ glyph matrices, which makes this method impossible to use.)
135169
136170 The optimizations are tried in sequence (some can be skipped if
137171 it is known that they are not applicable). If none of the
@@ -140,16 +174,17 @@ along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
140174
141175 Note that there's one more important optimization up Emacs's
142176 sleeve, but it is related to actually redrawing the potentially
143- changed portions of the window/frame, not to reproducing the
144- desired matrices of those potentially changed portions. Namely,
145- the function update_frame and its subroutines, which you will find
146- in dispnew.c, compare the desired matrices with the current
147- matrices, and only redraw the portions that changed. So it could
148- happen that the functions in this file for some reason decide that
149- the entire desired matrix needs to be regenerated from scratch, and
150- still only parts of the Emacs display, or even nothing at all, will
151- be actually delivered to the glass, because update_frame has found
152- that the new and the old screen contents are similar or identical.
177+ changed portions of the window/frame as part of the third step, not
178+ to generating the desired matrices of those potentially changed
179+ portions. Namely, the function `update_frame' and its subroutines,
180+ which you will find in dispnew.c, compare the desired matrices with
181+ the current matrices, and only redraw the portions that changed.
182+ So it could happen that the functions in this file for some reason
183+ decide that the entire desired matrix needs to be regenerated from
184+ scratch, and still only parts of the Emacs display, or even nothing
185+ at all, will be actually delivered to the glass, because
186+ `update_frame' has found that the new and the old screen contents
187+ are similar or identical.
153188
154189 Desired matrices.
155190
@@ -159,7 +194,7 @@ along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
159194 redisplay tries to optimize its work, and thus only generates
160195 glyphs for rows that need to be updated on the screen. Rows that
161196 don't need to be updated are left "disabled", and their contents
162- should be ignored.
197+ in the desired matrix should be ignored.
163198
164199 The function `display_line' is the central function to look at if
165200 you are interested in how the rows of the desired matrix are
0 commit comments