From 6f11812729e42e720544e7157b29e728cf4fc667 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Mon, 28 Aug 2023 10:00:39 +0300 Subject: [PATCH 01/18] create and delete textures --- docs/about/Authors.rst | 1 + library/LuaApi.cpp | 42 ++++++++++ library/include/LuaTools.h | 11 +++ library/include/modules/DFSDL.h | 2 + library/include/modules/Textures.h | 21 +++++ library/modules/DFSDL.cpp | 15 +++- library/modules/Textures.cpp | 127 ++++++++++++++++++++--------- 7 files changed, 179 insertions(+), 40 deletions(-) diff --git a/docs/about/Authors.rst b/docs/about/Authors.rst index cf74c6412..ba556ab64 100644 --- a/docs/about/Authors.rst +++ b/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 diff --git a/library/LuaApi.cpp b/library/LuaApi.cpp index a1821d2fb..241d1888b 100644 --- a/library/LuaApi.cpp +++ b/library/LuaApi.cpp @@ -1775,9 +1775,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 handles; + Lua::GetVector(state, handles); + for (auto& handle: handles) { + Textures::deleteHandle(handle); + } + } + return 0; +} + +static int textures_createTile(lua_State *state) +{ + std::vector 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 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 } }; diff --git a/library/include/LuaTools.h b/library/include/LuaTools.h index cab3ee9cc..188d63854 100644 --- a/library/include/LuaTools.h +++ b/library/include/LuaTools.h @@ -410,6 +410,17 @@ namespace DFHack {namespace Lua { } } + template + requires std::is_arithmetic_v + void GetVector(lua_State *state, std::vector &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 &pvec, int idx = 1); DFHACK_EXPORT void CheckPen(lua_State *L, Screen::Pen *pen, int index, bool allow_nil = false, bool allow_color = true); diff --git a/library/include/modules/DFSDL.h b/library/include/modules/DFSDL.h index 36dd641d5..b70255ec8 100644 --- a/library/include/modules/DFSDL.h +++ b/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 diff --git a/library/include/modules/Textures.h b/library/include/modules/Textures.h index fa1f743be..e371df90e 100644 --- a/library/include/modules/Textures.h +++ b/library/include/modules/Textures.h @@ -43,6 +43,27 @@ DFHACK_EXPORT std::vector 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. + * Register this texture and return TexposHandle. + */ +DFHACK_EXPORT TexposHandle createTile(std::vector& 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. + * Register this textures and return vector of TexposHandle. + */ +DFHACK_EXPORT std::vector createTileset(std::vector& 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. diff --git a/library/modules/DFSDL.cpp b/library/modules/DFSDL.cpp index 72105b2e6..398a9c8b2 100644 --- a/library/modules/DFSDL.cpp +++ b/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 ""; diff --git a/library/modules/Textures.cpp b/library/modules/Textures.cpp index 48bc71e3c..26a769e48 100644 --- a/library/modules/Textures.cpp +++ b/library/modules/Textures.cpp @@ -1,4 +1,5 @@ #include +#include #include #include "Internal.h" @@ -30,6 +31,10 @@ static std::unordered_map g_handle_to_texpos; static std::unordered_map g_handle_to_surface; static std::mutex g_adding_mutex; +// it is SDL_PixelFormatEnum::SDL_PIXELFORMAT_RGBA32 +// initialized inplace to avoid including SDL_pixels.h +static const uint32_t RGBA32 = 376840196; + // Converts an arbitrary Surface to something like the display format // (32-bit RGBA), and converts magenta to transparency if convert_magenta is set // and the source surface didn't already have an alpha channel. @@ -38,28 +43,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; - fmt.palette = NULL; - fmt.BitsPerPixel = 32; - fmt.BytesPerPixel = 4; - fmt.Rloss = fmt.Gloss = fmt.Bloss = fmt.Aloss = 0; -#if SDL_BYTEORDER == SDL_BIG_ENDIAN - fmt.Rshift = 24; - fmt.Gshift = 16; - 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); + // however we have null check after DFIMG_Load + // in loadTileset() (the only consumer of this method) + // it's better put nullcheck here as well + if (!src) + return src; + + auto fmt = DFSDL_AllocFormat(RGBA32); + 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 +62,7 @@ SDL_Surface* canonicalize_format(SDL_Surface* src) { } } } + return tgt; } @@ -82,31 +74,34 @@ static long add_texture(SDL_Surface* surface) { return texpos; } -TexposHandle Textures::loadTexture(SDL_Surface* surface) { - if (!surface) - return 0; // should be some error, i guess +// delete surface from texture raws +static void delete_texture(long texpos) { + std::lock_guard lg_add_texture(g_adding_mutex); + if (texpos >= enabler->textures.raws.size()) + return; + enabler->textures.raws[texpos] = NULL; +} - auto handle = reinterpret_cast(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; +// create new surface with RGBA32 format and pixels as data +SDL_Surface* create_texture(std::vector& pixels, int texture_px_w, int texture_px_h) { + auto surface = DFSDL_CreateRGBSurfaceWithFormat(0, texture_px_w, texture_px_h, 32, RGBA32); + for (auto i = 0; i < pixels.size() && i < texture_px_w * texture_px_h; i++) { + uint32_t* p = (uint32_t*)surface->pixels + i; + *p = pixels[i]; + } + return surface; } -std::vector Textures::loadTileset(const std::string& file, int tile_px_w, - int tile_px_h) { +// convert single surface into tiles according w/h +// register tiles in texture raws and return handles +std::vector slice_tileset(SDL_Surface* surface, int tile_px_w, int tile_px_h) { std::vector handles{}; - - SDL_Surface* surface = DFIMG_Load(file.c_str()); - if (!surface) { - ERR(textures).printerr("unable to load textures from '%s'\n", file.c_str()); + if (!surface) 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 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(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 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{}; + } + + 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,34 @@ long Textures::getTexposByHandle(TexposHandle handle) { return -1; } +TexposHandle Textures::createTile(std::vector& 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 Textures::createTileset(std::vector& 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]; + for (auto i = 0; i < surface->refcount; i++) { + DFSDL_FreeSurface(surface); + } + g_handle_to_surface.erase(handle); + } +} + static void reset_texpos() { g_handle_to_texpos.clear(); } From 51baa0d674999fe786dbfaf4d089940cfefca3cc Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Mon, 28 Aug 2023 10:46:59 +0300 Subject: [PATCH 02/18] fix linux build --- library/modules/Textures.cpp | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/library/modules/Textures.cpp b/library/modules/Textures.cpp index 26a769e48..85ce5d2b6 100644 --- a/library/modules/Textures.cpp +++ b/library/modules/Textures.cpp @@ -77,7 +77,8 @@ static long add_texture(SDL_Surface* surface) { // delete surface from texture raws static void delete_texture(long texpos) { std::lock_guard lg_add_texture(g_adding_mutex); - if (texpos >= enabler->textures.raws.size()) + auto pos = static_cast(texpos); + if (pos >= enabler->textures.raws.size()) return; enabler->textures.raws[texpos] = NULL; } @@ -85,7 +86,7 @@ static void delete_texture(long texpos) { // create new surface with RGBA32 format and pixels as data SDL_Surface* create_texture(std::vector& pixels, int texture_px_w, int texture_px_h) { auto surface = DFSDL_CreateRGBSurfaceWithFormat(0, texture_px_w, texture_px_h, 32, RGBA32); - for (auto i = 0; i < pixels.size() && i < texture_px_w * texture_px_h; i++) { + for (size_t i = 0; i < pixels.size() && i < texture_px_w * texture_px_h; i++) { uint32_t* p = (uint32_t*)surface->pixels + i; *p = pixels[i]; } From 4b0219e2254f347850cf24450b62a304a0bf62d0 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Mon, 28 Aug 2023 10:56:08 +0300 Subject: [PATCH 03/18] fix stupid linux build again --- library/modules/Textures.cpp | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/library/modules/Textures.cpp b/library/modules/Textures.cpp index 85ce5d2b6..e6f6d5aaa 100644 --- a/library/modules/Textures.cpp +++ b/library/modules/Textures.cpp @@ -86,7 +86,8 @@ static void delete_texture(long texpos) { // create new surface with RGBA32 format and pixels as data SDL_Surface* create_texture(std::vector& pixels, int texture_px_w, int texture_px_h) { auto surface = DFSDL_CreateRGBSurfaceWithFormat(0, texture_px_w, texture_px_h, 32, RGBA32); - for (size_t i = 0; i < pixels.size() && i < texture_px_w * texture_px_h; i++) { + auto canvas_length = static_cast(texture_px_w * texture_px_h); + for (size_t i = 0; i < pixels.size() && i < canvas_length; i++) { uint32_t* p = (uint32_t*)surface->pixels + i; *p = pixels[i]; } From 8a015f7f87ead789bc7cb79fdea35a167ad79b38 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 07:38:21 +0300 Subject: [PATCH 04/18] review --- docs/dev/Lua API.rst | 45 ++++++++++++++++++++++++++++++ library/include/modules/Textures.h | 4 +-- library/modules/Textures.cpp | 15 ++++------ 3 files changed, 53 insertions(+), 11 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index d14e56640..110834c34 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -3864,6 +3864,9 @@ These modules make extensive use of the ``class`` module, and define things ranging from the basic ``Painter``, ``View`` and ``Screen`` classes, to fully functional predefined dialogs. +In addition to the ``gui`` module, there is a ``textures`` module that allows +you to perform actions on textures to use them as tiles during rendering. + gui === @@ -5342,6 +5345,48 @@ 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. +textures +======== + +In order for the game to render a particular tile (graphic), it needs to know ``texpos`` - the position in the vector of the registered game textures. +Add your own texture to it and get ``texpos`` is not difficult. But the game periodically deletes textures that are in the vector, and that's the problem. +Because the ``texpos`` we got earlier no longer points to our added texture. +The ``texture`` module solves this problem. Instead of ``texpos`` directly, it operates on the ``TexposHandle`` entity, which is essentially a reference to ``texpos``. +Thanks to this handle, it is possible to get a valid ``texpos`` at any time. + +* ``loadTileset(file, tile_px_w, tile_px_h)`` + + Loads tileset from the image ``file`` with give tile dimension in pixels (image will be sliced in row major order). + + Returns an array of ``TexposHandle`` + +* ``getTexposByHandle(handle)`` + + Get ``texpos`` by ``TexposHandle``. + Always use this method if you need to get valid texpos for your texture. + ``texpos`` can change on game textures reset, but the handle will be the same. + +* ``createTile(pixels, tile_px_w, tile_px_h)`` + + Create and register new a texture with the given tile dimension and array of ``pixels`` as data in row major order. + Each pixel is an integer representing color in packed RBGA format (for example, #0022FF11). + + Returns ``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 dimension and array of ``pixels`` as data in row major order. + Then slice it on tiles with the given dimension in row major order. + 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 signle ``TexposHandle``, or array of ``TexposHandle``. + Deletes all metadata and texture(s) itself by given handle(s). + You must be sure that the game does not use this texture in rendering process. + .. _lua-plugins: ======= diff --git a/library/include/modules/Textures.h b/library/include/modules/Textures.h index e371df90e..5b238a4fd 100644 --- a/library/include/modules/Textures.h +++ b/library/include/modules/Textures.h @@ -49,14 +49,14 @@ DFHACK_EXPORT long getTexposByHandle(TexposHandle handle); DFHACK_EXPORT void deleteHandle(TexposHandle handle); /** - * Create new texture with RGBA32 format and pixels as data. + * 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& 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. + * 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 createTileset(std::vector& pixels, diff --git a/library/modules/Textures.cpp b/library/modules/Textures.cpp index e6f6d5aaa..25af2135a 100644 --- a/library/modules/Textures.cpp +++ b/library/modules/Textures.cpp @@ -17,6 +17,7 @@ #include "df/viewscreen_new_arenast.h" #include "df/viewscreen_new_regionst.h" +#include #include using df::global::enabler; @@ -31,10 +32,6 @@ static std::unordered_map g_handle_to_texpos; static std::unordered_map g_handle_to_surface; static std::mutex g_adding_mutex; -// it is SDL_PixelFormatEnum::SDL_PIXELFORMAT_RGBA32 -// initialized inplace to avoid including SDL_pixels.h -static const uint32_t RGBA32 = 376840196; - // Converts an arbitrary Surface to something like the display format // (32-bit RGBA), and converts magenta to transparency if convert_magenta is set // and the source surface didn't already have an alpha channel. @@ -43,13 +40,13 @@ static const uint32_t RGBA32 = 376840196; // It uses the same pixel format (RGBA, R at lowest address) regardless of // hardware. SDL_Surface* canonicalize_format(SDL_Surface* src) { - // however we have null check after DFIMG_Load + // even though we have null check after DFIMG_Load // in loadTileset() (the only consumer of this method) // it's better put nullcheck here as well if (!src) return src; - auto fmt = DFSDL_AllocFormat(RGBA32); + auto fmt = DFSDL_AllocFormat(SDL_PixelFormatEnum::SDL_PIXELFORMAT_RGBA32); SDL_Surface* tgt = DFSDL_ConvertSurface(src, fmt, SDL_SWSURFACE); DFSDL_FreeSurface(src); for (int x = 0; x < tgt->w; ++x) { @@ -85,7 +82,8 @@ static void delete_texture(long texpos) { // create new surface with RGBA32 format and pixels as data SDL_Surface* create_texture(std::vector& pixels, int texture_px_w, int texture_px_h) { - auto surface = DFSDL_CreateRGBSurfaceWithFormat(0, texture_px_w, texture_px_h, 32, RGBA32); + auto surface = DFSDL_CreateRGBSurfaceWithFormat(0, texture_px_w, texture_px_h, 32, + SDL_PixelFormatEnum::SDL_PIXELFORMAT_RGBA32); auto canvas_length = static_cast(texture_px_w * texture_px_h); for (size_t i = 0; i < pixels.size() && i < canvas_length; i++) { uint32_t* p = (uint32_t*)surface->pixels + i; @@ -186,9 +184,8 @@ void Textures::deleteHandle(TexposHandle handle) { g_handle_to_texpos.erase(handle); if (g_handle_to_surface.contains(handle)) { auto surface = g_handle_to_surface[handle]; - for (auto i = 0; i < surface->refcount; i++) { + while (surface->refcount) DFSDL_FreeSurface(surface); - } g_handle_to_surface.erase(handle); } } From ff82cb2dfca7e24c8b2eaefebddbb3d545f6050b Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 10:05:23 +0300 Subject: [PATCH 05/18] docs work --- docs/dev/Lua API.rst | 100 ++++++++++++++++++++++++++++--------------- 1 file changed, 65 insertions(+), 35 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 110834c34..f983031ee 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2596,6 +2596,55 @@ 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 ``texpos`` - the position in the vector of the registered game textures (also the graphical tile id passed as the tile field in a `Pen `). +Add your own texture to it and get ``texpos`` is not difficult. But the game periodically deletes textures that are in the vector, and that's the problem. +Because the ``texpos`` we got earlier no longer points to our added texture. +The ``texture`` module solves this problem. Instead of ``texpos`` directly, it operates on the ``TexposHandle`` entity, which is essentially a reference to ``texpos``. +Thanks to this handle, it is possible to get a valid ``texpos`` at any time. + +* ``loadTileset(file, tile_px_w, tile_px_h)`` + + Loads tileset from the image ``file`` with give tile dimension in pixels (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 ``texpos`` by ``TexposHandle``. + Always use this method if you need to get valid texpos for your texture. + ``texpos`` can change on game textures reset, but the handle will be the same. + +* ``createTile(pixels, tile_px_w, tile_px_h)`` + + Create and register new a texture with the given tile dimension and array of ``pixels`` as data in row major order. + Each pixel is an integer representing color in packed RBGA format (for example, #0022FF11). + + Returns ``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 dimension and array of ``pixels`` as data in row major order. + Then slice it on tiles with the given dimension in row major order. + 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 signle ``TexposHandle``, or array of ``TexposHandle``. + Deletes all metadata and texture(s) itself by given handle(s). + You must be sure that the game does not use this texture in rendering process. + + Filesystem module ----------------- @@ -5345,47 +5394,28 @@ 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. -textures -======== - -In order for the game to render a particular tile (graphic), it needs to know ``texpos`` - the position in the vector of the registered game textures. -Add your own texture to it and get ``texpos`` is not difficult. But the game periodically deletes textures that are in the vector, and that's the problem. -Because the ``texpos`` we got earlier no longer points to our added texture. -The ``texture`` module solves this problem. Instead of ``texpos`` directly, it operates on the ``TexposHandle`` entity, which is essentially a reference to ``texpos``. -Thanks to this handle, it is possible to get a valid ``texpos`` at any time. - -* ``loadTileset(file, tile_px_w, tile_px_h)`` - - Loads tileset from the image ``file`` with give tile dimension in pixels (image will be sliced in row major order). - - Returns an array of ``TexposHandle`` -* ``getTexposByHandle(handle)`` - - Get ``texpos`` by ``TexposHandle``. - Always use this method if you need to get valid texpos for your texture. - ``texpos`` can change on game textures reset, but the handle will be the same. +gui.textures +============ -* ``createTile(pixels, tile_px_w, tile_px_h)`` +This module contains preloaded ``DFHack`` graphic assets and provide several helper methods to get ``texpos`` by offset in tilest (in row major position). - Create and register new a texture with the given tile dimension and array of ``pixels`` as data in row major order. - Each pixel is an integer representing color in packed RBGA format (for example, #0022FF11). +* ``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`` - Returns ``TexposHandle``. +Example usega:: -* ``createTileset(pixels, texture_px_w, texture_px_h, tile_px_w, tile_px_h)`` + local textures = require('gui.textures') + local first_border_texpos = textures.tp_border_thin(1) - Create and register a new texture with the given texture dimension and array of ``pixels`` as data in row major order. - Then slice it on tiles with the given dimension in row major order. - 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 signle ``TexposHandle``, or array of ``TexposHandle``. - Deletes all metadata and texture(s) itself by given handle(s). - You must be sure that the game does not use this texture in rendering process. .. _lua-plugins: From a1fe49e52af2d1f34c7c1a4e46d65965291e7ce1 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 10:37:23 +0300 Subject: [PATCH 06/18] typo --- docs/dev/Lua API.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index f983031ee..c52f39269 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2597,7 +2597,7 @@ a ``dfhack.penarray`` instance to cache their output. ``bufferx`` and ``buffery`` default to 0. -Textures Module +Textures module --------------- In order for the game to render a particular tile (graphic), it needs to know ``texpos`` - the position in the vector of the registered game textures (also the graphical tile id passed as the tile field in a `Pen `). From 5c6942a89cf7145a6501fcfab76443932741d509 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 10:45:17 +0300 Subject: [PATCH 07/18] intendation for example --- docs/dev/Lua API.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index c52f39269..e4bbd59e2 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2614,8 +2614,8 @@ Thanks to this handle, it is possible to get a valid ``texpos`` at any time. Example usage:: - local logo_textures = dfhack.textures.loadTileset('hack/data/art/dfhack.png', 8, 12) - local first_texposhandle = logo_textures[1] + local logo_textures = dfhack.textures.loadTileset('hack/data/art/dfhack.png', 8, 12) + local first_texposhandle = logo_textures[1] * ``getTexposByHandle(handle)`` From 7ce7bd15f655d9d9f88be7683bc5167b7c44bc49 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:48:14 +0300 Subject: [PATCH 08/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index e4bbd59e2..f002297ad 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2600,7 +2600,9 @@ a ``dfhack.penarray`` instance to cache their output. Textures module --------------- -In order for the game to render a particular tile (graphic), it needs to know ``texpos`` - the position in the vector of the registered game textures (also the graphical tile id passed as the tile field in a `Pen `). +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 `). Add your own texture to it and get ``texpos`` is not difficult. But the game periodically deletes textures that are in the vector, and that's the problem. Because the ``texpos`` we got earlier no longer points to our added texture. The ``texture`` module solves this problem. Instead of ``texpos`` directly, it operates on the ``TexposHandle`` entity, which is essentially a reference to ``texpos``. From b3d423b8a4bc654b39cf5da5c916d84f918bbb7c Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:48:26 +0300 Subject: [PATCH 09/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index f002297ad..0dac09a64 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2603,8 +2603,9 @@ 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 `). -Add your own texture to it and get ``texpos`` is not difficult. But the game periodically deletes textures that are in the vector, and that's the problem. -Because the ``texpos`` we got earlier no longer points to our added texture. +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 ``texture`` module solves this problem. Instead of ``texpos`` directly, it operates on the ``TexposHandle`` entity, which is essentially a reference to ``texpos``. Thanks to this handle, it is possible to get a valid ``texpos`` at any time. From 13e0a49eef12e008aa24159c4f52f8ec43d5cf2a Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:48:36 +0300 Subject: [PATCH 10/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 0dac09a64..3f93a09b4 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2606,8 +2606,9 @@ graphical tile id passed as the ``tile`` field in a `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 ``texture`` module solves this problem. Instead of ``texpos`` directly, it operates on the ``TexposHandle`` entity, which is essentially a reference to ``texpos``. -Thanks to this handle, it is possible to get a valid ``texpos`` at any time. +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)`` From c0ac7ad8a259ba88fbfe1906adf2b2a2aacbced4 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:48:47 +0300 Subject: [PATCH 11/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 3f93a09b4..b7c226ff1 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2612,9 +2612,8 @@ raw ``texpos``. When we need to draw a particular tile, we can look up the curre * ``loadTileset(file, tile_px_w, tile_px_h)`` - Loads tileset from the image ``file`` with give tile dimension in pixels (image will be sliced in row major order). - - Returns an array of ``TexposHandle`` + 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:: From 72dbb68a5cf38c22104426618d16cd677e3b75d9 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:48:54 +0300 Subject: [PATCH 12/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index b7c226ff1..35e2372f3 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2622,9 +2622,9 @@ raw ``texpos``. When we need to draw a particular tile, we can look up the curre * ``getTexposByHandle(handle)`` - Get ``texpos`` by ``TexposHandle``. - Always use this method if you need to get valid texpos for your texture. - ``texpos`` can change on game textures reset, but the handle will be the same. + 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)`` From 14c4e948ba4115b1c9f236ce7fde340113460472 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:49:01 +0300 Subject: [PATCH 13/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 35e2372f3..44512c010 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2635,11 +2635,10 @@ raw ``texpos``. When we need to draw a particular tile, we can look up the curre * ``createTileset(pixels, texture_px_w, texture_px_h, tile_px_w, tile_px_h)`` - Create and register a new texture with the given texture dimension and array of ``pixels`` as data in row major order. - Then slice it on tiles with the given dimension in row major order. - Each pixel is an integer representing color in packed RBGA format (for example #0022FF11). - - Returns an array of ``TexposHandle``. + 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)`` From a2d1d416c432aad961a9261a34be0f1247959112 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:49:09 +0300 Subject: [PATCH 14/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 44512c010..e06d75b09 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -5400,7 +5400,9 @@ The parent widget owns the range values, and can control them independently (e.g gui.textures ============ -This module contains preloaded ``DFHack`` graphic assets and provide several helper methods to get ``texpos`` by offset in tilest (in row major position). +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`` From 72a985c3b0c74b3dcd6c5a6e7a4330b72973679f Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:49:17 +0300 Subject: [PATCH 15/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index e06d75b09..c25de597a 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -5415,7 +5415,7 @@ asset. ``offset`` 0 is the first tile. * ``tp_border_panel(offset)`` tileset: ``hack/data/art/border-panel.png`` * ``tp_border_window(offset)`` tileset: ``hack/data/art/order-window.png`` -Example usega:: +Example usage:: local textures = require('gui.textures') local first_border_texpos = textures.tp_border_thin(1) From 63913567cf75d67229f40856c1dc83567c840997 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:49:28 +0300 Subject: [PATCH 16/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index c25de597a..fe5e19865 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -3915,9 +3915,6 @@ These modules make extensive use of the ``class`` module, and define things ranging from the basic ``Painter``, ``View`` and ``Screen`` classes, to fully functional predefined dialogs. -In addition to the ``gui`` module, there is a ``textures`` module that allows -you to perform actions on textures to use them as tiles during rendering. - gui === From 02d33e532dd78b8693d7134159816894dedbee98 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:49:40 +0300 Subject: [PATCH 17/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index fe5e19865..63901529a 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2642,9 +2642,9 @@ raw ``texpos``. When we need to draw a particular tile, we can look up the curre * ``deleteHandle(handle)`` - ``handle`` here can be signle ``TexposHandle``, or array of ``TexposHandle``. - Deletes all metadata and texture(s) itself by given handle(s). - You must be sure that the game does not use this texture in rendering process. + ``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 From 47a22025a0dedf2eca1ade4cf55adabda21530a8 Mon Sep 17 00:00:00 2001 From: shevernitskiy Date: Wed, 30 Aug 2023 12:49:48 +0300 Subject: [PATCH 18/18] Update docs/dev/Lua API.rst Co-authored-by: Myk --- docs/dev/Lua API.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst index 63901529a..8096b1375 100644 --- a/docs/dev/Lua API.rst +++ b/docs/dev/Lua API.rst @@ -2628,10 +2628,9 @@ raw ``texpos``. When we need to draw a particular tile, we can look up the curre * ``createTile(pixels, tile_px_w, tile_px_h)`` - Create and register new a texture with the given tile dimension and array of ``pixels`` as data in row major order. - Each pixel is an integer representing color in packed RBGA format (for example, #0022FF11). - - Returns ``TexposHandle``. + 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)``