FAQ: add some details about the w3m img hack

... and an example patch to switch from double-buffering to a single buffer.

1 files changed, 54 insertions, 5 deletions

diff --git a/FAQ b/FAQ
index 85534a4..fb40264 100644
--- a/FAQ
+++ b/FAQ
@@ -2,12 +2,14 @@
 
 Use the excellent tool of [utmp](https://git.suckless.org/utmp/) for this task.
 
+
 ## Some _random program_ complains that st is unknown/not recognised/unsupported/whatever!
 
 It means that st doesn’t have any terminfo entry on your system. Chances are
 you did not `make install`. If you just want to test it without installing it,
 you can manually run `tic -sx st.info`.
 
+
 ## Nothing works, and nothing is said about an unknown terminal!
 
 * Some programs just assume they’re running in xterm i.e. they don’t rely on
@@ -15,6 +17,7 @@ you can manually run `tic -sx st.info`.
 * Some programs don’t complain about the lacking st description and default to
   another terminal. In that case see the question about terminfo.
 
+
 ## How do I scroll back up?
 
 * Using a terminal multiplexer.
@@ -23,11 +26,13 @@ you can manually run `tic -sx st.info`.
 * Using the excellent tool of [scroll](https://git.suckless.org/scroll/).
 * Using the scrollback [patch](https://st.suckless.org/patches/scrollback/).
 
+
 ## I would like to have utmp and/or scroll functionality by default
 
 You can add the absolute patch of both programs in your config.h
 file. You only have to modify the value of utmp and scroll variables.
 
+
 ## Why doesn't the Del key work in some programs?
 
 Taken from the terminfo manpage:
@@ -83,12 +88,14 @@ If you are using zsh, then read the zsh FAQ
 
 Putting these lines into your .zshrc will fix the problems.
 
+
 ## How can I use meta in 8bit mode?
 
 St supports meta in 8bit mode, but the default terminfo entry doesn't
 use this capability. If you want it, you have to use the 'st-meta' value
 in TERM.
 
+
 ## I cannot compile st in OpenBSD
 
 OpenBSD lacks librt, despite it being mandatory in POSIX
@@ -97,6 +104,7 @@ If you want to compile st for OpenBSD you have to remove -lrt from config.mk, an
 st will compile without any loss of functionality, because all the functions are
 included in libc on this platform.
 
+
 ## The Backspace Case
 
 St is emulating the Linux way of handling backspace being delete and delete being
@@ -158,19 +166,60 @@ terminal users wants its backspace to be how he feels it:
         [1] http://www.ibb.net/~anne/keyboard.html
         [2] http://www.tldp.org/HOWTO/Keyboard-and-Console-HOWTO-5.html
 
+
 ## But I really want the old grumpy behaviour of my terminal
 
 Apply [1].
 
 [1] https://st.suckless.org/patches/delkey
 
-## Why do images not work in st (in programs such as w3m)?
 
-This is a terrible hack that overdraws an image on top of the terminal emulator
-window. It also relies on a very specific way the terminal draws it's contents.
+## Why do images not work in st using the w3m image hack?
+
+w3mimg uses a hack that draws an image on top of the terminal emulator Drawable
+window. The hack relies on the terminal to use a single buffer to draw its
+contents directly.
+
+st uses double-buffered drawing so the image is quickly replaced and may show a
+short flicker effect.
+
+Below is a patch example to change st double-buffering to a single Drawable
+buffer.
+
+diff --git a/x.c b/x.c
+--- a/x.c
++++ b/x.c
+@@ -561,10 +561,6 @@ xresize(int col, int row)
+        win.tw = MAX(1, col * win.cw);
+        win.th = MAX(1, row * win.ch);
+ 
+-       XFreePixmap(xw.dpy, xw.buf);
+-       xw.buf = XCreatePixmap(xw.dpy, xw.win, win.w, win.h,
+-                       DefaultDepth(xw.dpy, xw.scr));
+-       XftDrawChange(xw.draw, xw.buf);
+        xclear(0, 0, win.w, win.h);
+ }
+ 
+@@ -921,8 +917,7 @@ xinit(void)
+        gcvalues.graphics_exposures = False;
+        dc.gc = XCreateGC(xw.dpy, parent, GCGraphicsExposures,
+                        &gcvalues);
+-       xw.buf = XCreatePixmap(xw.dpy, xw.win, win.w, win.h,
+-                       DefaultDepth(xw.dpy, xw.scr));
++       xw.buf = xw.win;
+        XSetForeground(xw.dpy, dc.gc, dc.col[defaultbg].pixel);
+        XFillRectangle(xw.dpy, xw.buf, dc.gc, 0, 0, win.w, win.h);
+ 
+@@ -1386,8 +1381,6 @@ void
+ draw(void)
+ {
+        drawregion(0, 0, term.col, term.row);
+-       XCopyArea(xw.dpy, xw.buf, xw.win, dc.gc, 0, 0, win.w,
+-                       win.h, 0, 0);
+        XSetForeground(xw.dpy, dc.gc,
+                        dc.col[IS_SET(MODE_REVERSE)?
+                                defaultfg : defaultbg].pixel);
 
-A more proper (but limited way) would be using sixels. Which st doesn't
-support.
 
 ## BadLength X error in Xft when trying to render emoji