From 83348bf3ac49adb2e142cffde1accd3b620f727c Mon Sep 17 00:00:00 2001
From: Nils Dagsson Moskopp <nils@dieweltistgarnichtso.net>
Date: Mon, 16 May 2022 20:34:33 +0200
Subject: [PATCH] Document use cases, image type support, plans

---
 README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/README.md b/README.md
index 195cb8df5..555cefd59 100644
--- a/README.md
+++ b/README.md
@@ -6,3 +6,82 @@ Created by fleckenstein for MineClone2, then improved by erlehmann.
 May be used as a Minetest mod.
 
 See `examples.lua` for example code and usage hints.
+
+## Use Cases for `tga_encoder`
+
+### Encoding Textures for Editing
+
+TGA images of types 1/2/3 consist of header data followed by a pixel array.
+
+This makes it trivial to parse TGA files – and even edit pixels in-place.
+
+No checksums need to be updated on any kind of in-place texture editing.
+
+**Tip**: When storing an editable image in item meta, use zlib compression.
+
+### Legacy Minetest Texture Encoding
+
+Minetest 5.4 did not include `minetest.encode_png()` (or any equvivalent).
+
+Since `tga_encoder` is written in pure Lua, it does not need engine support.
+
+**Tip:** Look at `examples.lua` and the Minetest mod `mcl_maps` for guidance.
+
+### Advanced Texture Format Control
+
+The function `minetest.encode_png()` always encodes images as 32bpp RGBA.
+
+`tga_encoder` allows saving images as grayscale, 16bpp RGBA and 24bpp RGB.
+
+For generating maps from terrain, color-mapped formats can be more useful.
+
+### Encoding Very Small Textures
+
+Images of size 8×8 or below are often smaller than an equivalent PNG file.
+
+Note that on many filesystems files use at least 4096 bytes (i.e. 64×64).
+
+Therefore, saving bytes on files up to a few 100 bytes is often useless.
+
+### Encoding Reference Textures
+
+TGA is a simple format, which makes it easy to create reference textures.
+
+Using a hex editor, one can trivially see how all the pixels are stored.
+
+## Supported Image Types
+
+For all types, images are encoded in a fast single pass (i.e. append-only).
+
+### Color-Mapped Images (Type 1)
+
+These images contain a palette, followed by pixel data.
+
+* `A1R5G5B5` (8bpp RGB)
+* `B8G8R8` (8bpp RGB)
+
+### True-Color Images (Type 2)
+
+These images contain uncompressed RGB(A) pixel data.
+
+* `A1R5G5B5` (16bpp RGBA)
+* `B8G8R8` (24bpp RGB)
+* `B8G8R8A8` (32bpp RGBA)
+
+### Grayscale Images (Type 3)
+
+* `Y8` (8bpp grayscale)
+
+### Run-Length Encoded (RLE), True-Color Images (Type 10)
+
+These images contain compressed RGB(A) pixel data.
+
+* `A1R5G5B5` (16bpp RGBA)
+* `B8G8R8` (24bpp RGB)
+* `B8G8R8A8` (32bpp RGBA)
+
+## TODO
+
+* Support Type 1 `B8G8R8A8` output (color-mapped 8bpp RGBA)
+* Actually support `R8G8B8A8` input for `A1R5G5B5` output
+* Add both zoomable and explorable maps to `mcl_maps`.