revise #4767, implementing review feedback and other improvements

Author: chdoc

docs/changelog.txt

@@ -66,8 +66,14 @@ Template for new versions:
 
 ## API
 
+``Screen``: new functions ``paintMapPortTile`` and ``readMapPortTile`` to write and read world and region map tiles.
+
 ## Lua
 
+Added ``Screen::paintMapPortTile`` as ``dfhack.screen.paintMapPortTile``
+Added ``Screen::readMapPortTile`` as ``dfhack.screen.readMapPortTile``
+
+
 ## Removed
 
 # 53.15-r2

docs/dev/Lua API.rst

@@ -2872,12 +2872,9 @@ Common parameters to these functions include:
 * ``x``, ``y``: screen coordinates in tiles; the upper left corner of the screen
   is ``x = 0, y = 0``
 * ``pen``: a `pen object <lua-screen-pen>`
-* ``map``: a boolean indicating whether to draw to a separate map buffer
-  (defaults to false, which is suitable for off-map text or a screen that hides
-  the map entirely). Note that only third-party plugins like TWBT currently
-  implement a separate map buffer. If no such plugins are enabled, passing
-  ``true`` has no effect. However, this parameter should still be used to ensure
-  that scripts work properly with such plugins.
+* ``map``: a boolean (defaults to false) indicating whether to draw to a
+  separate map buffer. The Steam version uses separate map buffers with square
+  tiles for for all types of maps (i.e. fort, region, and world).
 
 Functions:
 
@@ -2903,15 +2900,31 @@ Functions:
 * ``dfhack.screen.paintTile(pen,x,y[,char[,tile[,map]]])``
 
   Paints a tile using given parameters. `See below <lua-screen-pen>` for a
-  description of ``pen``.
+  description of ``pen``. The map argument is only supported for local maps
+  (i.e. fort mode and adventure mode outside of fast travel). The ``char`` and
+  ``tile`` arguments allow overriding the respective parts of the ``pen``
+  without constructing a new pen beforehand.
 
   Returns *false* on error, e.g., if coordinates are out of bounds
 
+* ``dfhack.screen.paintMapPortTile(pen,x,y[,char[,tile]])``
+
+  Paints a tile using given parameters onto the interface texpos layer of a map
+  port (e.g., the world map or the zoomed-in map for embark selection). The
+  ``char`` and ``tile`` arguments work as above.
+
 * ``dfhack.screen.readTile(x,y[,map])``
 
   Retrieves the contents of the specified tile from the screen buffers.
   Returns a `pen object <lua-screen-pen>`, or *nil* if invalid or TrueType.
 
+* ``dfhack.screen.readMapPortTile(x,y)``
+
+  Retrieves the contents of the specified tile from the screen buffers. Returns
+  a `pen object <lua-screen-pen>`, or *nil* if invalid.
+
+  For now only looks at the ``sites`` textpos layer.
+
 * ``dfhack.screen.paintString(pen,x,y,text[,map])``
 
   Paints the string starting at *x,y*. Uses the string characters

library/LuaApi.cpp

@@ -3129,7 +3129,7 @@ static int screen_readTile(lua_State *L)
     return 1;
 }
 
-static int screen_paintTileMapPort(lua_State *L)
+static int screen_paintMapPortTile(lua_State *L)
 {
     Pen pen;
     Lua::CheckPen(L, &pen, 1);
@@ -3144,15 +3144,15 @@ static int screen_paintTileMapPort(lua_State *L)
     }
     if (lua_gettop(L) >= 5 && !lua_isnil(L, 5))
         pen.tile = luaL_checkint(L, 5);
-    lua_pushboolean(L, Screen::paintTileMapPort(pen, x, y));
+    lua_pushboolean(L, Screen::paintMapPortTile(pen, x, y));
     return 1;
 }
 
-static int screen_readTileMapPort(lua_State *L)
+static int screen_readMapPortTile(lua_State *L)
 {
     int x = luaL_checkint(L, 1);
     int y = luaL_checkint(L, 2);
-    Pen pen = Screen::readTileMapPort(x, y);
+    Pen pen = Screen::readMapPortTile(x, y, &df::graphic_map_portst::screentexpos_site);
     Lua::Push(L, pen);
     return 1;
 }
@@ -3344,8 +3344,8 @@ static const luaL_Reg dfhack_screen_funcs[] = {
     { "getWindowSize", screen_getWindowSize },
     { "paintTile", screen_paintTile },
     { "readTile", screen_readTile },
-    { "paintTileMapPort", screen_paintTileMapPort },
-    { "readTileMapPort", screen_readTileMapPort },
+    { "paintMapPortTile", screen_paintMapPortTile },
+    { "readMapPortTile", screen_readMapPortTile },
     { "paintString", screen_paintString },
     { "fillRect", screen_fillRect },
     { "findGraphicsTile", screen_findGraphicsTile },

library/include/modules/Screen.h

@@ -202,10 +202,10 @@ namespace DFHack
         DFHACK_EXPORT Pen readTile(int x, int y, bool map = false, int32_t * df::graphic_viewportst::*texpos_field = NULL);
 
         /// Paint one world map tile with the given pen
-        DFHACK_EXPORT bool paintTileMapPort(const Pen &pen, int x, int y, int32_t * df::graphic_map_portst::*texpos_field = NULL);
+        DFHACK_EXPORT bool paintMapPortTile(const Pen &pen, int x, int y, int32_t * df::graphic_map_portst::*texpos_field = NULL);
 
         /// Retrieves one world map tile from the buffer
-        DFHACK_EXPORT Pen readTileMapPort(int x, int y, int32_t * df::graphic_map_portst::*texpos_field = NULL);
+        DFHACK_EXPORT Pen readMapPortTile(int x, int y, int32_t * df::graphic_map_portst::*texpos_field);
 
         /// Paint a string onto the screen. Ignores ch and tile of pen.
         DFHACK_EXPORT bool paintString(const Pen &pen, int x, int y, const std::string &text, bool map = false);

library/modules/Screen.cpp

@@ -372,11 +372,18 @@ Pen Screen::readTile(int x, int y, bool map, int32_t * df::graphic_viewportst::*
     return doGetTile(x, y, map, texpos_field);
 }
 
-static bool doSetTile_map_port(const Pen &pen, int x, int y, int32_t * df::graphic_map_portst::*texpos_field) {
-    auto &vp = gps->main_map_port;
+bool Screen::paintMapPortTile(const Pen &pen, int x, int y, int32_t * df::graphic_map_portst::*texpos_field)
+{
+    if (!gps || !pen.valid()) return false;
+
+    bool use_graphics = Screen::inGraphicsMode();
+    if (!use_graphics)
+        return doSetTile_char(pen, x, y, use_graphics);
+
     if (!texpos_field)
         texpos_field = &df::graphic_map_portst::screentexpos_interface;
 
+    auto &vp = gps->main_map_port;
     if (x < 0 || x >= vp->dim_x || y < 0 || y >= vp->dim_y)
         return false;
 
@@ -393,96 +400,36 @@ static bool doSetTile_map_port(const Pen &pen, int x, int y, int32_t * df::graph
     return true;
 }
 
-static bool doSetTile_map_port_default(const Pen &pen, int x, int y, int32_t * df::graphic_map_portst::*texpos_field) {
-    bool use_graphics = Screen::inGraphicsMode();
-
-    if (use_graphics)
-        return doSetTile_map_port(pen, x, y, texpos_field);
+Pen Screen::readMapPortTile(int x, int y, int32_t * df::graphic_map_portst::*texpos_field)
+{
+    CHECK_NULL_POINTER(texpos_field)
 
-    return doSetTile_char(pen, x, y, use_graphics);
-}
+    if (!gps) return Pen(0,0,0,-1);
 
-bool Screen::paintTileMapPort(const Pen &pen, int x, int y, int32_t * df::graphic_map_portst::*texpos_field)
-{
-    if (!gps || !pen.valid()) return false;
+    bool use_graphics = Screen::inGraphicsMode();
 
-    doSetTile_map_port_default(pen, x, y, texpos_field);
-    return true;
-}
+    if (!use_graphics)
+        return doGetTile_char(x, y, use_graphics);
 
-static Pen doGetTile_map_port(int x, int y, int32_t * df::graphic_map_portst::*texpos_field) {
     auto &vp = gps->main_map_port;
 
     if (x < 0 || x >= vp->dim_x || y < 0 || y >= vp->dim_y)
         return Pen(0, 0, 0, -1);
 
     size_t max_index = vp->dim_x * vp->dim_y - 1;
-    size_t index = (x * vp->dim_y) + y;
+    size_t index = (y * vp->dim_x) + x;
 
     if (index < 0 || index > max_index)
         return Pen(0, 0, 0, -1);
 
-    int tile = 0;
-    if (!texpos_field) {
-        if (tile == 0)
-            tile = vp->screentexpos_base[index];
-        if (tile == 0)
-            tile = vp->screentexpos_detail[index];
-        if (tile == 0)
-            tile = vp->screentexpos_tunnel[index];
-        if (tile == 0)
-            tile = vp->screentexpos_river[index];
-        if (tile == 0)
-            tile = vp->screentexpos_road[index];
-        if (tile == 0)
-            tile = vp->screentexpos_site[index];
-        if (tile == 0)
-            tile = vp->screentexpos_army[index];
-        if (tile == 0)
-            tile = vp->screentexpos_interface[index];
-        if (tile == 0)
-            tile = vp->screentexpos_detail_to_n[index];
-        if (tile == 0)
-            tile = vp->screentexpos_detail_to_s[index];
-        if (tile == 0)
-            tile = vp->screentexpos_detail_to_w[index];
-        if (tile == 0)
-            tile = vp->screentexpos_detail_to_e[index];
-        if (tile == 0)
-            tile = vp->screentexpos_detail_to_nw[index];
-        if (tile == 0)
-            tile = vp->screentexpos_detail_to_ne[index];
-        if (tile == 0)
-            tile = vp->screentexpos_detail_to_sw[index];
-        if (tile == 0)
-            tile = vp->screentexpos_detail_to_se[index];
-        if (tile == 0)
-            tile = vp->screentexpos_site_to_s[index];
-    } else {
-        tile = (vp->*texpos_field)[index];
-    }
+    auto tile = (vp->*texpos_field)[index];
 
     char ch = 0;
     uint8_t fg = 0;
     uint8_t bg = 0;
     return Pen(ch, fg, bg, tile, false);
 }
 
-static Pen doGetTile_map_port_default(int x, int y, int32_t * df::graphic_map_portst::*texpos_field = NULL) {
-    bool use_graphics = Screen::inGraphicsMode();
-
-    if (use_graphics)
-        return doGetTile_map_port(x, y, texpos_field);
-    return doGetTile_char(x, y, use_graphics);
-}
-
-Pen Screen::readTileMapPort(int x, int y, int32_t * df::graphic_map_portst::*texpos_field)
-{
-    if (!gps) return Pen(0,0,0,-1);
-
-    return doGetTile_map_port_default(x, y, texpos_field);
-}
-
 bool Screen::paintString(const Pen &pen, int x, int y, const std::string &text, bool map)
 {
     auto dim = getWindowSize();