From: Eli Zaretskii Date: Sat, 14 Jun 2014 09:44:20 +0000 (+0300) Subject: src/xdisp.c: Enhance commentary. X-Git-Url: https://git.hcoop.net/bpt/emacs.git/commitdiff_plain/78275cd0ed1816e67f0fb331b4ebca4aac5d1cc7?hp=340ced7ecbfbc40a5db23eedc25581eb462465df src/xdisp.c: Enhance commentary. --- diff --git a/src/xdisp.c b/src/xdisp.c index f0eeb9ac60..adcd281334 100644 --- a/src/xdisp.c +++ b/src/xdisp.c @@ -98,7 +98,9 @@ along with GNU Emacs. If not, see . */ This function attempts to redisplay a window by reusing parts of its existing display. It finds and reuses the part that was not - changed, and redraws the rest. + changed, and redraws the rest. (The "id" part in the function's + name stands for "insert/delete", not for "identification" or + somesuch.) . try_window @@ -113,6 +115,19 @@ along with GNU Emacs. If not, see . */ optimizations were successful, redisplay calls redisplay_windows, which performs a full redisplay of all windows. + Note that there's one more important optimization up Emacs's + sleeve, but it is related to actually redrawing the potentially + changed portions of the window/frame, not to reproducing the + desired matrices of those potentially changed portions. Namely, + the function update_frame and its subroutines, which you will find + in dispnew.c, compare the desired matrices with the current + matrices, and only redraw the portions that changed. So it could + happen that the functions in this file for some reason decide that + the entire desired matrix needs to be regenerated from scratch, and + still only parts of the Emacs display, or even nothing at all, will + be actually delivered to the glass, because update_frame has found + that the new and the old screen contents are similar or identical. + Desired matrices. Desired matrices are always built per Emacs window. The function @@ -15757,7 +15772,51 @@ set_vertical_scroll_bar (struct window *w) selected_window is redisplayed. We can return without actually redisplaying the window if fonts has been - changed on window's frame. In that case, redisplay_internal will retry. */ + changed on window's frame. In that case, redisplay_internal will retry. + + As one of the important parts of redisplaying a window, we need to + decide whether the previous window-start position (stored in the + window's w->start marker position) is still valid, and if it isn't, + recompute it. Some details about that: + + . The previous window-start could be in a continuation line, in + which case we need to recompute it when the window width + changes. See compute_window_start_on_continuation_line and its + call below. + + . The text that changed since last redisplay could include the + previous window-start position. In that case, we try to salvage + what we can from the current glyph matrix by calling + try_scrolling, which see. + + . Some Emacs command could force us to use a specific window-start + position by setting the window's force_start flag, or gently + propose doing that by setting the window's optional_new_start + flag. In these cases, we try using the specified start point if + that succeeds (i.e. the window desired matrix is successfully + recomputed, and point location is within the window). In case + of optional_new_start, we first check if the specified start + position is feasible, i.e. if it will allow point to be + displayed in the window. If using the specified start point + fails, e.g., if new fonts are needed to be loaded, we abort the + redisplay cycle and leave it up to the next cycle to figure out + things. + + . Note that the window's force_start flag is sometimes set by + redisplay itself, when it decides that the previous window start + point is fine and should be kept. Search for "goto force_start" + below to see the details. Like the values of window-start + specified outside of redisply, these internally deduced values + are tested for feasibility, and ignored if found to be + unfeasible. + + . Note that the function try_window, used to completely redisplay + a window, accepts the window's start point as its argument. + This is used several times in the redisplay code to control + where the window start will be, according to user options such + as scroll-conservatively, and also to ensure the screen line + showing point will be fully (as opposed to partially) visible on + display. */ static void redisplay_window (Lisp_Object window, bool just_this_one_p) @@ -15803,6 +15862,8 @@ redisplay_window (Lisp_Object window, bool just_this_one_p) eassert (XMARKER (w->start)->buffer == buffer); eassert (XMARKER (w->pointm)->buffer == buffer); + /* We come here again if we need to run window-text-change-functions + below. */ restart: reconsider_clip_changes (w); frame_line_height = default_line_pixel_height (w); @@ -15867,7 +15928,7 @@ redisplay_window (Lisp_Object window, bool just_this_one_p) && !current_buffer->prevent_redisplay_optimizations_p && !window_outdated (w)); - /* Run the window-bottom-change-functions + /* Run the window-text-change-functions if it is possible that the text on the screen has changed (either due to modification of the text, or any other reason). */ if (!current_matrix_up_to_date_p