add gui.TRANSPARENT_PEN for clearing the UI layer

docs/dev/Lua API.rst

@@ -3663,6 +3663,10 @@ Misc
   The black pen used to clear the screen. In graphics mode, it will clear the
   foreground and set the background to the standard black tile.
 
+* ``TRANSPARENT_PEN``
+
+  A pen that will clear all textures from the UI layer, making the tile transparent.
+
 * ``KEEP_LOWER_PEN``
 
   A pen that will write tiles over existing background tiles instead of clearing

library/lua/gui.lua

@@ -10,6 +10,7 @@ local getval = utils.getval
 local to_pen = dfhack.pen.parse
 
 CLEAR_PEN = to_pen{tile=909, ch=32, fg=0, bg=0, write_to_lower=true}
+TRANSPARENT_PEN = to_pen{tile=0, ch=0}
 KEEP_LOWER_PEN = to_pen{ch=32, fg=0, bg=0, keep_lower=true}
 
 local FAKE_INPUT_KEYS = {

library/modules/Screen.cpp

@@ -128,10 +128,10 @@ static bool doSetTile_map(const Pen &pen, int x, int y) {
         return false;
 
     long texpos = pen.tile;
-    if (texpos == 0) {
+    if (!texpos && pen.ch)
         texpos = init->font.large_font_texpos[(uint8_t)pen.ch];
-    }
-    vp->screentexpos_interface[index] = texpos;
+    if (texpos)
+        vp->screentexpos_interface[index] = texpos;
     return true;
 }
 
@@ -196,7 +196,7 @@ static bool doSetTile_default(const Pen &pen, int x, int y, bool map)
             *texpos_lower = pen.tile;
         else
             *texpos = pen.tile;
-    } else {
+    } else if (pen.ch) {
         screen[0] = uint8_t(pen.ch);
         *texpos_lower = 909; // basic black background
     }