support offset text in graphics mode for pens

docs/changelog.txt

@@ -62,6 +62,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 ## API
 - ``Buildings::containsTile()``: no longer takes a ``room`` parameter since that's not how rooms work anymore. If the building has extents, the extents will be checked. otherwise, the result just depends on whether the tile is within the building's bounding box.
 - ``Units::getCitizens()``: gets a list of citizens, which otherwise you'd have to iterate over all units the world to discover
+- ``Screen::Pen``: now accepts ``top_of_text`` and ``bottom_of_text`` properties to support offset text in graphics mode
 
 ## Lua
 - `helpdb`: new function: ``helpdb.refresh()`` to force a refresh of the database. Call if you are a developer adding new scripts, loading new plugins, or changing help text during play

docs/dev/Lua API.rst

@@ -2292,6 +2292,12 @@ a table with the following possible fields:
   ``write_to_lower``
     If set to true, the specified ``tile`` will be written to the background
     instead of the foreground.
+  ``top_of_text``
+    If set to true, the specified ``tile`` will have the top half of the specified
+    ``ch`` character superimposed over the lower half of the tile.
+  ``bottom_of_text``
+    If set to true, the specified ``tile`` will have the bottom half of the specified
+    ``ch`` character superimposed over the top half of the tile.
 
 Alternatively, it may be a pre-parsed native object with the following API:
 

library/LuaApi.cpp

@@ -222,6 +222,8 @@ static void decode_pen(lua_State *L, Pen &pen, int idx)
 
     get_bool_field(L, &pen.keep_lower, idx, "keep_lower", false);
     get_bool_field(L, &pen.write_to_lower, idx, "write_to_lower", false);
+    get_bool_field(L, &pen.top_of_text, idx, "top_of_text", false);
+    get_bool_field(L, &pen.bottom_of_text, idx, "bottom_of_text", false);
 }
 
 /**************************************************

library/include/modules/Screen.h

@@ -86,6 +86,8 @@ namespace DFHack
 
             bool write_to_lower = false;
             bool keep_lower = false;
+            bool top_of_text = false;
+            bool bottom_of_text = false;
 
             bool valid() const { return tile >= 0; }
             bool empty() const { return ch == 0 && tile == 0; }

library/modules/Screen.cpp

@@ -155,14 +155,18 @@ static bool doSetTile_default(const Pen &pen, int x, int y, bool map)
     long *texpos_lower = &gps->screentexpos_lower[index];
     uint32_t *flag = &gps->screentexpos_flag[index];
 
+    // keep SCREENTEXPOS_FLAG_ANCHOR_SUBORDINATE so occluded anchored textures
+    // don't appear corrupted
+    uint32_t flag_mask = 0x4;
+    if (pen.write_to_lower)
+        flag_mask |= 0x18;
+
     *screen = 0;
     *texpos = 0;
     if (!pen.keep_lower)
         *texpos_lower = 0;
     gps->screentexpos_anchored[index] = 0;
-    // keep SCREENTEXPOS_FLAG_ANCHOR_SUBORDINATE so occluded anchored textures
+    *flag &= flag_mask;
-    // don't appear corrupted
-    *flag &= 4;
 
     if (gps->top_in_use) {
         screen = &gps->screen_top[index * 8];
@@ -175,7 +179,7 @@ static bool doSetTile_default(const Pen &pen, int x, int y, bool map)
         if (!pen.keep_lower)
             *texpos_lower = 0;
         gps->screentexpos_top_anchored[index] = 0;
-        *flag &= 4; // keep SCREENTEXPOS_FLAG_ANCHOR_SUBORDINATE
+        *flag &= flag_mask;
     }
 
     uint8_t fg = pen.fg | (pen.bold << 3);
@@ -196,6 +200,14 @@ static bool doSetTile_default(const Pen &pen, int x, int y, bool map)
             *texpos_lower = pen.tile;
         else
             *texpos = pen.tile;
+
+        if (pen.top_of_text || pen.bottom_of_text) {
+            screen[0] = uint8_t(pen.ch);
+            if (pen.top_of_text)
+                *flag |= 0x8;
+            if (pen.bottom_of_text)
+                *flag |= 0x10;
+        }
     } else if (pen.ch) {
         screen[0] = uint8_t(pen.ch);
         *texpos_lower = 909; // basic black background