Merge pull request #3704 from shevernitskiy/create-delete-textures

create and delete textures

docs/about/Authors.rst

@@ -203,6 +203,7 @@ Sebastian Wolfertz      Enkrod
 SeerSkye                SeerSkye
 seishuuu                seishuuu
 Seth Woodworth          sethwoodworth
+shevernitskiy           shevernitskiy
 Shim Panze              Shim-Panze
 Silver                  silverflyone
 simon

docs/dev/Lua API.rst

@@ -2581,6 +2581,56 @@ a ``dfhack.penarray`` instance to cache their output.
 
   ``bufferx`` and ``buffery`` default to 0.
 
+
+Textures module
+---------------
+
+In order for the game to render a particular tile (graphic), it needs to know the
+``texpos`` - the position in the vector of the registered game textures (also the
+graphical tile id passed as the ``tile`` field in a `Pen <lua-screen-pen>`).
+Adding new textures to the vector is not difficult, but the game periodically
+deletes textures that are in the vector, and that's a problem since it
+invalidates the ``texpos`` value that used to point to that texture.
+The ``textures`` module solves this problem by providing a stable handle instead of a
+raw ``texpos``. When we need to draw a particular tile, we can look up the current
+``texpos`` value via the handle.
+
+* ``loadTileset(file, tile_px_w, tile_px_h)``
+
+  Loads a tileset from the image ``file`` with give tile dimensions in pixels. The
+  image will be sliced in row major order. Returns an array of ``TexposHandle``.
+
+  Example usage::
+
+    local logo_textures = dfhack.textures.loadTileset('hack/data/art/dfhack.png', 8, 12)
+    local first_texposhandle = logo_textures[1]
+
+* ``getTexposByHandle(handle)``
+
+  Get the current ``texpos`` for the given ``TexposHandle``. Always use this method to
+  get the ``texpos`` for your texture. ``texpos`` can change when game textures are
+  reset, but the handle will be the same.
+
+* ``createTile(pixels, tile_px_w, tile_px_h)``
+
+  Create and register a new texture with the given tile dimensions and an array of
+  ``pixels`` in row major order. Each pixel is an integer representing color in packed
+  RBGA format (for example, #0022FF11). Returns a ``TexposHandle``.
+
+* ``createTileset(pixels, texture_px_w, texture_px_h, tile_px_w, tile_px_h)``
+
+  Create and register a new texture with the given texture dimensions and an array of
+  ``pixels`` in row major order. Then slice it into tiles with the given tile
+  dimensions. Each pixel is an integer representing color in packed RBGA format (for
+  example #0022FF11). Returns an array of ``TexposHandle``.
+
+* ``deleteHandle(handle)``
+
+  ``handle`` here can be single ``TexposHandle`` or an array of ``TexposHandle``.
+  Deletes all metadata and texture(s) related to the given handle(s). The handles
+  become invalid after this call.
+
+
 Filesystem module
 -----------------
 
@@ -5327,6 +5377,31 @@ The parent widget owns the range values, and can control them independently (e.g
 :on_left_change: Callback executed when moving the left handle.
 :on_right_change: Callback executed when moving the right handle.
 
+
+gui.textures
+============
+
+This module contains convenience methods for accessing default DFHack graphic assets.
+Pass the ``offset`` in tiles (in row major position) to get a particular tile from the
+asset. ``offset`` 0 is the first tile.
+
+* ``tp_green_pin(offset)`` tileset: ``hack/data/art/green-pin.png``
+* ``tp_red_pin(offset)`` tileset: ``hack/data/art/red-pin.png``
+* ``tp_icons(offset)`` tileset: ``hack/data/art/icons.png``
+* ``tp_on_off(offset)`` tileset: ``hack/data/art/on-off.png``
+* ``tp_control_panel(offset)`` tileset: ``hack/data/art/control-panel.png``
+* ``tp_border_thin(offset)`` tileset: ``hack/data/art/border-thin.png``
+* ``tp_border_medium(offset)`` tileset: ``hack/data/art/border-medium.png``
+* ``tp_border_bold(offset)`` tileset: ``hack/data/art/border-bold.png``
+* ``tp_border_panel(offset)`` tileset: ``hack/data/art/border-panel.png``
+* ``tp_border_window(offset)`` tileset: ``hack/data/art/order-window.png``
+
+Example usage::
+
+  local textures = require('gui.textures')
+  local first_border_texpos = textures.tp_border_thin(1)
+
+
 .. _lua-plugins:
 
 =======

library/LuaApi.cpp

@@ -1777,9 +1777,51 @@ static int textures_getTexposByHandle(lua_State *state)
     return 1;
 }
 
+static int textures_deleteHandle(lua_State *state)
+{
+    if (lua_isinteger(state,1)) {
+        auto handle = luaL_checkunsigned(state, 1);
+        Textures::deleteHandle(handle);
+    } else if (lua_istable(state,1)) {
+        std::vector<TexposHandle> handles;
+        Lua::GetVector(state, handles);
+        for (auto& handle: handles) {
+            Textures::deleteHandle(handle);
+        }
+    }
+    return 0;
+}
+
+static int textures_createTile(lua_State *state)
+{
+    std::vector<uint32_t> pixels;
+    Lua::GetVector(state, pixels);
+    auto tile_w = luaL_checkint(state, 2);
+    auto tile_h = luaL_checkint(state, 3);
+    auto handle = Textures::createTile(pixels, tile_w, tile_h);
+    Lua::Push(state, handle);
+    return 1;
+}
+
+static int textures_createTileset(lua_State *state)
+{
+    std::vector<uint32_t> pixels;
+    Lua::GetVector(state, pixels);
+    auto texture_w = luaL_checkint(state, 2);
+    auto texture_h = luaL_checkint(state, 3);
+    auto tile_w = luaL_checkint(state, 4);
+    auto tile_h = luaL_checkint(state, 5);
+    auto handles = Textures::createTileset(pixels, texture_w, texture_h, tile_w, tile_h);
+    Lua::PushVector(state, handles);
+    return 1;
+}
+
 static const luaL_Reg dfhack_textures_funcs[] = {
     { "loadTileset", textures_loadTileset },
     { "getTexposByHandle", textures_getTexposByHandle },
+    { "deleteHandle", textures_deleteHandle },
+    { "createTile", textures_createTile },
+    { "createTileset", textures_createTileset },
     { NULL, NULL }
 };
 

library/include/LuaTools.h

@@ -410,6 +410,17 @@ namespace DFHack {namespace Lua {
         }
     }
 
+    template<typename T>
+    requires std::is_arithmetic_v<T>
+    void GetVector(lua_State *state, std::vector<T> &pvec, int idx = 1) {
+        lua_pushnil(state);   // first key
+        while (lua_next(state, idx) != 0)
+        {
+            pvec.push_back(lua_tointeger(state, -1));
+            lua_pop(state, 1);  // remove value, leave key
+        }
+    }
+
     DFHACK_EXPORT void GetVector(lua_State *state, std::vector<std::string> &pvec, int idx = 1);
 
     DFHACK_EXPORT void CheckPen(lua_State *L, Screen::Pen *pen, int index, bool allow_nil = false, bool allow_color = true);

library/include/modules/DFSDL.h

@@ -48,6 +48,8 @@ DFHACK_EXPORT void DFSDL_FreeSurface(SDL_Surface *surface);
 // DFHACK_EXPORT int DFSDL_SemPost(SDL_sem *sem);
 DFHACK_EXPORT int DFSDL_PushEvent(SDL_Event *event);
 DFHACK_EXPORT void DFSDL_free(void *ptr);
+DFHACK_EXPORT SDL_PixelFormat* DFSDL_AllocFormat(uint32_t pixel_format);
+DFHACK_EXPORT SDL_Surface* DFSDL_CreateRGBSurfaceWithFormat(uint32_t flags, int width, int height, int depth, uint32_t format);
 
 // submitted and returned text is UTF-8
 // see wrapper functions below for cp-437 variants

library/include/modules/Textures.h

@@ -43,6 +43,27 @@ DFHACK_EXPORT std::vector<TexposHandle> loadTileset(const std::string& file,
  */
 DFHACK_EXPORT long getTexposByHandle(TexposHandle handle);
 
+/**
+ * Delete all info about texture by TexposHandle
+ */
+DFHACK_EXPORT void deleteHandle(TexposHandle handle);
+
+/**
+ * Create new texture with RGBA32 format and pixels as data in row major order.
+ * Register this texture and return TexposHandle.
+ */
+DFHACK_EXPORT TexposHandle createTile(std::vector<uint32_t>& pixels, int tile_px_w = TILE_WIDTH_PX,
+                                      int tile_px_h = TILE_HEIGHT_PX);
+
+/**
+ * Create new textures as tileset with RGBA32 format and pixels as data in row major order.
+ * Register this textures and return vector of TexposHandle.
+ */
+DFHACK_EXPORT std::vector<TexposHandle> createTileset(std::vector<uint32_t>& pixels,
+                                                      int texture_px_w, int texture_px_h,
+                                                      int tile_px_w = TILE_WIDTH_PX,
+                                                      int tile_px_h = TILE_HEIGHT_PX);
+
 /**
  * Call this on DFHack init just once to setup interposed handlers and
  * init static assets.

library/modules/DFSDL.cpp

@@ -41,6 +41,8 @@ SDL_bool (*g_SDL_HasClipboardText)();
 int (*g_SDL_SetClipboardText)(const char *text);
 char * (*g_SDL_GetClipboardText)();
 void (*g_SDL_free)(void *);
+SDL_PixelFormat* (*g_SDL_AllocFormat)(uint32_t pixel_format) = nullptr;
+SDL_Surface* (*g_SDL_CreateRGBSurfaceWithFormat)(uint32_t flags, int width, int height, int depth, uint32_t format) = nullptr;
 
 bool DFSDL::init(color_ostream &out) {
     for (auto &lib_str : SDL_LIBS) {
@@ -81,7 +83,9 @@ bool DFSDL::init(color_ostream &out) {
     bind(g_sdl_handle, SDL_SetClipboardText);
     bind(g_sdl_handle, SDL_GetClipboardText);
     bind(g_sdl_handle, SDL_free);
-    #undef bind
+    bind(g_sdl_handle, SDL_AllocFormat);
+    bind(g_sdl_handle, SDL_CreateRGBSurfaceWithFormat);
+#undef bind
 
     DEBUG(dfsdl,out).print("sdl successfully loaded\n");
     return true;
@@ -147,6 +151,15 @@ int DFSDL::DFSDL_SetClipboardText(const char *text) {
     return g_SDL_SetClipboardText(text);
 }
 
+SDL_PixelFormat* DFSDL::DFSDL_AllocFormat(uint32_t pixel_format) {
+    return g_SDL_AllocFormat(pixel_format);
+}
+
+SDL_Surface* DFSDL::DFSDL_CreateRGBSurfaceWithFormat(uint32_t flags, int width, int height, int depth, uint32_t format) {
+    return g_SDL_CreateRGBSurfaceWithFormat(flags, width, height, depth, format);
+}
+
+
 DFHACK_EXPORT std::string DFHack::getClipboardTextCp437() {
     if (!g_sdl_handle || g_SDL_HasClipboardText() != SDL_TRUE)
         return "";

library/modules/Textures.cpp

@@ -1,4 +1,5 @@
 #include <mutex>
+#include <numeric>
 #include <unordered_map>
 
 #include "Internal.h"
@@ -16,6 +17,7 @@
 #include "df/viewscreen_new_arenast.h"
 #include "df/viewscreen_new_regionst.h"
 
+#include <SDL_pixels.h>
 #include <SDL_surface.h>
 
 using df::global::enabler;
@@ -38,28 +40,14 @@ static std::mutex g_adding_mutex;
 // It uses the same pixel format (RGBA, R at lowest address) regardless of
 // hardware.
 SDL_Surface* canonicalize_format(SDL_Surface* src) {
-    SDL_PixelFormat fmt;
+    // even though we have null check after DFIMG_Load
-    fmt.palette = NULL;
+    // in loadTileset() (the only consumer of this method)
-    fmt.BitsPerPixel = 32;
+    // it's better put nullcheck here as well
-    fmt.BytesPerPixel = 4;
+    if (!src)
-    fmt.Rloss = fmt.Gloss = fmt.Bloss = fmt.Aloss = 0;
+        return src;
-#if SDL_BYTEORDER == SDL_BIG_ENDIAN
+
-    fmt.Rshift = 24;
+    auto fmt = DFSDL_AllocFormat(SDL_PixelFormatEnum::SDL_PIXELFORMAT_RGBA32);
-    fmt.Gshift = 16;
+    SDL_Surface* tgt = DFSDL_ConvertSurface(src, fmt, SDL_SWSURFACE);
-    fmt.Bshift = 8;
-    fmt.Ashift = 0;
-#else
-    fmt.Rshift = 0;
-    fmt.Gshift = 8;
-    fmt.Bshift = 16;
-    fmt.Ashift = 24;
-#endif
-    fmt.Rmask = 255 << fmt.Rshift;
-    fmt.Gmask = 255 << fmt.Gshift;
-    fmt.Bmask = 255 << fmt.Bshift;
-    fmt.Amask = 255 << fmt.Ashift;
-
-    SDL_Surface* tgt = DFSDL_ConvertSurface(src, &fmt, SDL_SWSURFACE);
     DFSDL_FreeSurface(src);
     for (int x = 0; x < tgt->w; ++x) {
         for (int y = 0; y < tgt->h; ++y) {
@@ -71,6 +59,7 @@ SDL_Surface* canonicalize_format(SDL_Surface* src) {
             }
         }
     }
+
     return tgt;
 }
 
@@ -82,31 +71,37 @@ static long add_texture(SDL_Surface* surface) {
     return texpos;
 }
 
-TexposHandle Textures::loadTexture(SDL_Surface* surface) {
+// delete surface from texture raws
-    if (!surface)
+static void delete_texture(long texpos) {
-        return 0; // should be some error, i guess
+    std::lock_guard<std::mutex> lg_add_texture(g_adding_mutex);
+    auto pos = static_cast<size_t>(texpos);
+    if (pos >= enabler->textures.raws.size())
+        return;
+    enabler->textures.raws[texpos] = NULL;
+}
 
-    auto handle = reinterpret_cast<uintptr_t>(surface);
+// create new surface with RGBA32 format and pixels as data
-    g_handle_to_surface.emplace(handle, surface);
+SDL_Surface* create_texture(std::vector<uint32_t>& pixels, int texture_px_w, int texture_px_h) {
-    surface->refcount++; // prevent destruct on next FreeSurface by game
+    auto surface = DFSDL_CreateRGBSurfaceWithFormat(0, texture_px_w, texture_px_h, 32,
-    auto texpos = add_texture(surface);
+                                                    SDL_PixelFormatEnum::SDL_PIXELFORMAT_RGBA32);
-    g_handle_to_texpos.emplace(handle, texpos);
+    auto canvas_length = static_cast<size_t>(texture_px_w * texture_px_h);
-    return handle;
+    for (size_t i = 0; i < pixels.size() && i < canvas_length; i++) {
+        uint32_t* p = (uint32_t*)surface->pixels + i;
+        *p = pixels[i];
+    }
+    return surface;
 }
 
-std::vector<TexposHandle> Textures::loadTileset(const std::string& file, int tile_px_w,
+// convert single surface into tiles according w/h
-                                                int tile_px_h) {
+// register tiles in texture raws and return handles
+std::vector<TexposHandle> slice_tileset(SDL_Surface* surface, int tile_px_w, int tile_px_h) {
     std::vector<TexposHandle> handles{};
-
+    if (!surface)
-    SDL_Surface* surface = DFIMG_Load(file.c_str());
-    if (!surface) {
-        ERR(textures).printerr("unable to load textures from '%s'\n", file.c_str());
         return handles;
-    }
 
-    surface = canonicalize_format(surface);
     int dimx = surface->w / tile_px_w;
     int dimy = surface->h / tile_px_h;
+
     for (int y = 0; y < dimy; y++) {
         for (int x = 0; x < dimx; x++) {
             SDL_Surface* tile = DFSDL_CreateRGBSurface(
@@ -120,6 +115,32 @@ std::vector<TexposHandle> Textures::loadTileset(const std::string& file, int til
     }
 
     DFSDL_FreeSurface(surface);
+    return handles;
+}
+
+TexposHandle Textures::loadTexture(SDL_Surface* surface) {
+    if (!surface)
+        return 0; // should be some error, i guess
+
+    auto handle = reinterpret_cast<uintptr_t>(surface);
+    g_handle_to_surface.emplace(handle, surface);
+    surface->refcount++; // prevent destruct on next FreeSurface by game
+    auto texpos = add_texture(surface);
+    g_handle_to_texpos.emplace(handle, texpos);
+    return handle;
+}
+
+std::vector<TexposHandle> Textures::loadTileset(const std::string& file, int tile_px_w,
+                                                int tile_px_h) {
+    SDL_Surface* surface = DFIMG_Load(file.c_str());
+    if (!surface) {
+        ERR(textures).printerr("unable to load textures from '%s'\n", file.c_str());
+        return std::vector<TexposHandle>{};
+    }
+
+    surface = canonicalize_format(surface);
+    auto handles = slice_tileset(surface, tile_px_w, tile_px_h);
+
     DEBUG(textures).print("loaded %zd textures from '%s'\n", handles.size(), file.c_str());
 
     return handles;
@@ -142,6 +163,33 @@ long Textures::getTexposByHandle(TexposHandle handle) {
     return -1;
 }
 
+TexposHandle Textures::createTile(std::vector<uint32_t>& pixels, int tile_px_w, int tile_px_h) {
+    auto texture = create_texture(pixels, tile_px_w, tile_px_h);
+    auto handle = Textures::loadTexture(texture);
+    return handle;
+}
+
+std::vector<TexposHandle> Textures::createTileset(std::vector<uint32_t>& pixels, int texture_px_w,
+                                                  int texture_px_h, int tile_px_w, int tile_px_h) {
+    auto texture = create_texture(pixels, texture_px_w, texture_px_h);
+    auto handles = slice_tileset(texture, tile_px_w, tile_px_h);
+    return handles;
+}
+
+void Textures::deleteHandle(TexposHandle handle) {
+    auto texpos = Textures::getTexposByHandle(handle);
+    if (texpos > 0)
+        delete_texture(texpos);
+    if (g_handle_to_texpos.contains(handle))
+        g_handle_to_texpos.erase(handle);
+    if (g_handle_to_surface.contains(handle)) {
+        auto surface = g_handle_to_surface[handle];
+        while (surface->refcount)
+            DFSDL_FreeSurface(surface);
+        g_handle_to_surface.erase(handle);
+    }
+}
+
 static void reset_texpos() {
     g_handle_to_texpos.clear();
 }