GBA homebrew image and video conversion tools

This folder contains some tools to convert / compress images and videos to GBA formats for homebrew development:

• gencolormaps - Generate the files colormap555.png and colormap565.png that can be used to convert images directly to the GBA RGB555 and NDS RGB565 color space with good quality.
• hex2gba - Convert a RGB888 color value to RGB555, RGB565 and BGR555, BGR565 high-color format for GBA / NDS .
• img2h - Convert / compress a (list of) image(s) that can be read with libplum to a .h / .c file to compile them into your program. Can convert images to a tile- or sprite-compatible format ("1D mapping" order) and compress them with LZ77 or LZ4. Suitable to compress small image sequences too. Documentation is here.
• vid2h - Convert / compress a video that can be read with FFmpeg to a .h / .c file to compile them into your program. Can convert images to a tile- or sprite-compatible format ("1D mapping" order) and compresses them using intra- and inter-frame techniques and LZ77, Lz4 or DXT. Documentation is here.
• vid2play - Play vid2h-compressed files.

If you find a bug or make an improvement your pull requests are appreciated.

License

All of my work is under the MIT License. It uses:

• cxxopts for command line argument parsing.
• glob for input file globbing / wildcards.
• Eigen for math and video compression.
• libplum for image I/O.
• adpcm-xq for ADPCM compression.
• Catch2 for unit tests.
• LZ77 decompression routines from Lorenzooone/Pokemon-Gen3-to-Gen-X which is in turn derived from Cult-of-GBA/BIOS. Licensed as MIT License.
• Test images and video from the Blender "Big Buck Bunny" movie (c) copyright 2008, Blender Foundation. Licensed as CC BY 3.0.
• Test images and video from the Blender "Tears of Steel" movie (c) copyright 2012, Blender Foundation. Licensed as CC BY 3.0.
• Test images from imagecompression.info resized to fit my needs.

Prerequisites

• You must have OpenMP installed for compiling. Install it with:

  apt install libomp-dev or dnf install libomp-devel

• You must have FFmpeg installed for compiling vid2h. Install it with:

  apt install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev or dnf install libavcodec-devel libavformat-devel libavutil-devel libswscale-devel

• You must have SDL3 v3.2.0 or higher installed for compiling vid2h / vid2hplay. Install it with:

  apt install libsdl3-dev or dnf install SDL3-devel

Building

From the command line

Navigate to the GBA-image-tools folder, then:

mkdir build && cd build
cmake ..
make

To build a release package, call:

make package

From Visual Studio Code

• Must: Install the "C/C++ extension" by Microsoft.
• Must: Install the "CMake Tools" extension by Microsoft.
• You might need to restart / reload Visual Studio Code if you have installed extensions.
• Open the GBA-image-tools folder using "Open folder...".
• Choose a kit of your choice as your active CMake kit if asked.
• You should be able to build now using F7 and build + run using F5.

Todo (general)

• More TESTS!
• More modern C++ constructs
• Clean up and use internal RLE + Huffman compression
• Improve documentation