Add modern REXPaint load/save functions.

Author: HexDecimal

CHANGELOG.rst

@@ -8,6 +8,13 @@ v2.0.0
 
 Unreleased
 ------------------
+Added
+ - Added modernized REXPaint saving/loading functions.
+   - `tcod.console.load_xp`
+   - `tcod.console.save_xp`
+
+Changed
+ - Using `libtcod 1.18.0`.
 
 12.3.2 - 2021-05-15
 -------------------

libtcod

@@ -3,9 +3,10 @@
 To render a console you need a tileset and a window to render to.
 See :ref:`getting-started` for info on how to set those up.
 """
-
+import os
+import pathlib
 import warnings
-from typing import Any, Optional, Tuple, Union  # noqa: F401
+from typing import Any, Iterable, Optional, Tuple, Union
 
 import numpy as np
 from typing_extensions import Literal
@@ -1229,3 +1230,102 @@ def recommended_size() -> Tuple[int, int]:
         w = max(1, xy[0] // lib.TCOD_ctx.tileset.tile_width)
         h = max(1, xy[1] // lib.TCOD_ctx.tileset.tile_height)
     return w, h
+
+
+def load_xp(
+    path: Union[str, pathlib.Path], order: Literal["C", "F"] = "C"
+) -> Tuple[Console, ...]:
+    """Load a REXPaint file as a tuple of consoles.
+
+    `path` is the name of the REXPaint file to load.
+    Usually ending with `.xp`.
+
+    `order` is the memory order of the Console's array buffer,
+    see :any:`tcod.console.Console`.
+
+    .. versionadded:: 12.4
+
+    Example::
+        import tcod
+        from numpy import np
+
+        path = "example.xp"  # REXPaint file with one layer.
+
+        # Load a REXPaint file with a single layer.
+        # The comma after console is used to unpack a single item tuple.
+        console, = tcod.console.load_xp(path, order="F")
+
+        # Convert from REXPaint's encoding to Unicode.
+        CP437_TO_UNICODE = np.asarray(tcod.tileset.CHARMAP_CP437)
+        console.ch[:] = CP437_TO_UNICODE[console.ch]
+
+        # Apply REXPaint's alpha key color.
+        KEY_COLOR = (255, 0, 255)
+        is_transparent = console.rgb["bg"] == KEY_COLOR
+        console.rgba[is_transparent] = (ord(" "), (0,), (0,))
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"File not found:\n\t{os.path.abspath(path)}")
+    layers = _check(
+        tcod.lib.TCOD_load_xp(str(path).encode("utf-8"), 0, ffi.NULL)
+    )
+    consoles = ffi.new("TCOD_Console*[]", layers)
+    _check(tcod.lib.TCOD_load_xp(str(path).encode("utf-8"), layers, consoles))
+    return tuple(
+        Console._from_cdata(console_p, order=order) for console_p in consoles
+    )
+
+
+def save_xp(
+    path: Union[str, pathlib.Path],
+    consoles: Iterable[Console],
+    compress_level: int = 9,
+) -> None:
+    """Save tcod Consoles to a REXPaint file.
+
+    `path` is where to save the file.
+
+    `consoles` are the :any:`tcod.console.Console` objects to be saved.
+
+    `compress_level` is the zlib compression level to be used.
+
+    Color alpha will be lost during saving.
+
+    Consoles will be saved as-is as much as possible.  You may need to convert
+    characters from Unicode to CP437 if you want to load the file in REXPaint.
+
+    .. versionadded:: 12.4
+
+    Example::
+        import tcod
+        from numpy import np
+
+        console = tcod.Console(80, 24)  # Example console.
+
+        # Load a REXPaint file with a single layer.
+        # The comma after console is used to unpack a single item tuple.
+        console, = tcod.console.load_xp(path, order="F")
+
+        # Convert from Unicode to REXPaint's encoding.
+        # Required to load this console correctly in the REXPaint tool.
+        CP437_TO_UNICODE = np.asarray(tcod.tileset.CHARMAP_CP437)
+        UNICODE_TO_CP437 = np.full(0x1FFFF, fill_value=ord("?"))
+        UNICODE_TO_CP437[CP437_TO_UNICODE] = np.arange(len(CP437_TO_UNICODE))
+        console.ch[:] = UNICODE_TO_CP437[console.ch]
+
+        # Convert console alpha into REXPaint's alpha key color.
+        KEY_COLOR = (255, 0, 255)
+        is_transparent = console.rgba["bg"][:, :, 3] == 0
+        console.rgb["bg"][is_transparent] = KEY_COLOR
+
+        tcod.console.save_xp("example.xp", [console])
+    """
+    consoles_c = ffi.new("TCOD_Console*[]", [c.console_c for c in consoles])
+    _check(
+        tcod.lib.TCOD_save_xp(
+            len(consoles_c),
+            consoles_c,
+            str(path).encode("utf-8"),
+            compress_level,
+        )
+    )

tcod/console.py

@@ -2078,7 +2078,7 @@ def console_save_apf(con: tcod.console.Console, filename: str) -> bool:
     )
 
 
-@deprecate("Use tcod.console_from_xp to load this file.")
+@deprecate("Use tcod.console.load_xp to load this file.")
 def console_load_xp(con: tcod.console.Console, filename: str) -> bool:
     """Update a console from a REXPaint `.xp` file.
 
@@ -2091,6 +2091,7 @@ def console_load_xp(con: tcod.console.Console, filename: str) -> bool:
     )
 
 
+@deprecate("Use tcod.console.save_xp to save this console.")
 def console_save_xp(
     con: tcod.console.Console, filename: str, compress_level: int = 9
 ) -> bool:
@@ -2102,6 +2103,7 @@ def console_save_xp(
     )
 
 
+@deprecate("Use tcod.console.load_xp to load this file.")
 def console_from_xp(filename: str) -> tcod.console.Console:
     """Return a single console from a REXPaint `.xp` file."""
     if not os.path.exists(filename):
@@ -2113,6 +2115,7 @@ def console_from_xp(filename: str) -> tcod.console.Console:
     )
 
 
+@deprecate("Use tcod.console.load_xp to load this file.")
 def console_list_load_xp(
     filename: str,
 ) -> Optional[List[tcod.console.Console]]:
@@ -2136,6 +2139,7 @@ def console_list_load_xp(
         lib.TCOD_list_delete(tcod_list)
 
 
+@deprecate("Use tcod.console.save_xp to save these consoles.")
 def console_list_save_xp(
     console_list: Sequence[tcod.console.Console],
     filename: str,

tcod/libtcodpy.py

@@ -129,3 +129,15 @@ def test_console_semigraphics():
     console.draw_semigraphics(
         [[[255, 255, 255], [255, 255, 255]], [[255, 255, 255], [0, 0, 0]]],
     )
+
+def test_rexpaint(tmp_path) -> None:
+    xp_path = tmp_path / "test.xp"
+    consoles = tcod.Console(80, 24, order="F"), tcod.Console(8, 8, order="F")
+    tcod.console.save_xp(xp_path, consoles, compress_level=0)
+    loaded = tcod.console.load_xp(xp_path, order="F")
+    assert len(consoles) == len(loaded)
+    assert loaded[0].rgba.flags["F_CONTIGUOUS"]
+    assert consoles[0].rgb.shape == loaded[0].rgb.shape
+    assert consoles[1].rgb.shape == loaded[1].rgb.shape
+    with pytest.raises(FileNotFoundError):
+        tcod.console.load_xp(tmp_path / "non_existant")