[gtksourceview/wip/minimap] minimap: add implementation history

[Christian Hergert <chergert src gnome org>]

commit f78e7aa3112cc1693f9e4d474c016e209d1790f9
Author: Christian Hergert <christian hergert me>
Date:   Thu May 7 12:22:37 2015 -0700

    minimap: add implementation history
    
    I went through various attempts to implement this, and that should be
    documented somewhere so we don't repeat the same mistakes.

 gtksourceview/gtksourcemap.c |   47 ++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 47 insertions(+), 0 deletions(-)
---
diff --git a/gtksourceview/gtksourcemap.c b/gtksourceview/gtksourcemap.c
index 43a2570..d92374f 100644
--- a/gtksourceview/gtksourcemap.c
+++ b/gtksourceview/gtksourcemap.c
@@ -46,6 +46,53 @@
  * be treated as a normal #GtkWidget.
  */
 
+/*
+ * Implementation Notes:
+ *
+ * I tried implementing this a few different ways. They are worth noting so
+ * that we do not repeat the same mistakes.
+ *
+ * Originally, I thought using a GtkSourceView to do the rendering was overkill
+ * and would likely slow things down too much. But it turns out to have been
+ * the best option so far.
+ *
+ *   - GtkPixelCache support results in very few GtkTextLayout relayout and
+ *     sizing changes. Since the pixel cache renders +/- half a screen outside
+ *     the visible range, scrolling is also quite smooth as we very rarely
+ *     perform a new gtk_text_layout_draw().
+ *
+ *   - Performance for this type of widget is dominated by text layout
+ *     rendering. When you scale out this car, you increase the number of
+ *     layouts to be rendered greatly.
+ *
+ *   - We can pack GtkSourceGutterRenderer into the child view to provide
+ *     additional information. This is quite handy to show information such
+ *     as errors, line changes, and anything else that can help the user
+ *     quickly jump to the target location.
+ *
+ * I also tried drawing the contents of the GtkSourceView onto a widget after
+ * performing a cairo_scale(). This does not help us much because we ignore
+ * pixel cache when cair_scale is not 1-to-1. This results in layout
+ * invalidation and worst case render paths.
+ *
+ * I also tried rendering the scrubber (overlay box) during the
+ * GtkTextView::draw_layer() vfunc. The problem with this approach is that
+ * the scrubber contents are actually pixel cached. So every time the scrubber
+ * moves we have to invalidate the GtkTextLayout and redraw cached contents.
+ * Where as using an overlay widget allows us to simply perform an alpha blend
+ * during the composite phase. The pixel cache'd GtkSourceView contents remain
+ * unchanged, and there continue to essentially be a memcpy().
+ *
+ * In the future, we might consider bundling a custom font for the source map.
+ * Other overview maps have used a "block" font. However, they typically do
+ * that because of the glyph rendering cost. Since we have pixel cache, that
+ * deficiency is largely a non-issue. But Pango recently got support for
+ * embedding fonts in the application, so it is at least possible to bundle
+ * our own font.
+ *
+ * -- Christian
+ */
+
 #define DEFAULT_WIDTH        100
 #define CONCEAL_TIMEOUT      2000