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); } }