From fc523f12fecf2e1cdb42f7f4328d61799f295952 Mon Sep 17 00:00:00 2001
From: Myk Taylor <myk002@yahoo.com>
Date: Wed, 28 Dec 2022 16:05:27 -0800
Subject: [PATCH] expose and document dfhack.screen.getMousePixels()

---
 docs/dev/Lua API.rst | 12 ++++++++++--
 library/LuaApi.cpp   |  6 ++++++
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst
index 0fa95dd03..4b9e2e972 100644
--- a/docs/dev/Lua API.rst	
+++ b/docs/dev/Lua API.rst	
@@ -1121,7 +1121,8 @@ Other
 * ``dfhack.gui.getDepthAt(x, y)``
 
   Returns the distance from the z-level of the tile at map coordinates (x, y) to
-  the closest ground z-level below. Defaults to 0, unless overridden by plugins.
+  the closest rendered ground z-level below. Defaults to 0, unless overridden by
+  plugins.
 
 Job module
 ----------
@@ -2161,7 +2162,14 @@ Functions:
 
 * ``dfhack.screen.getMousePos()``
 
-  Returns *x,y* of the tile the mouse is over.
+  Returns *x,y* of the UI interface tile the mouse is over, with the upper left
+  corner being ``0,0``. To get the map tile coordinate that the mouse is over,
+  see ``dfhack.gui.getMousePos()``.
+
+* ``dfhack.screen.getMousePixels()``
+
+  Returns *x,y* of the screen coordinates the mouse is over in pixels, with the
+  upper left corner being ``0,0``.
 
 * ``dfhack.screen.inGraphicsMode()``
 
diff --git a/library/LuaApi.cpp b/library/LuaApi.cpp
index ef0b5c3dd..31a6ee753 100644
--- a/library/LuaApi.cpp
+++ b/library/LuaApi.cpp
@@ -2373,6 +2373,11 @@ static int screen_getMousePos(lua_State *L)
     return Lua::PushPosXY(L, Screen::getMousePos());
 }
 
+static int screen_getMousePixels(lua_State *L)
+{
+    return Lua::PushPosXY(L, Screen::getMousePixels());
+}
+
 static int screen_getWindowSize(lua_State *L)
 {
     return Lua::PushPosXY(L, Screen::getWindowSize());
@@ -2563,6 +2568,7 @@ static int screen_zoom(lua_State *L)
 
 static const luaL_Reg dfhack_screen_funcs[] = {
     { "getMousePos", screen_getMousePos },
+    { "getMousePixels", screen_getMousePixels },
     { "getWindowSize", screen_getWindowSize },
     { "paintTile", screen_paintTile },
     { "readTile", screen_readTile },