Prepare files for the Resource File System - Megatokio/kilipili GitHub Wiki

Lib kilipili provides a resource file system. In the program it can be accessed by:

using kio::Devices;
DirectoryPtr dir = openDir("rsrc:");
// or:  
setWorkDir("rsrc:");
DirectoryPtr dir = openDir(".");
FilePtr file = openFile("myfile.txt");

The files can be stored compressed or uncompressed into the resource file system. Compressed files are transparently decompressed. Uncompressed files load faster and don't allocate space for the decompressor.

The resource file system is created using the desktop tool RsrcFileWriter. This can be compiled using kilipili/desktop_tools/CMakeLists.txt. This list creates RsrcFileWriter and UnitTest. If you want to convert images for optimized display then you must run cmake with the appropriate -D define for your board:

cd kilipili/desktop_tools
mkdir build
cd build
cmake -DPICO_BOARD=my_board ..
make

Now prepare the files. Your directory may look like this:

myrsrcfs/
    +-- infiles/
            +-- info.txt
            +-- large test image 594x396.png
            +-- images/
                    +-- Foo.gif
                    +-- Bar.gif
                    +-- Alpha.png
                    +-- Bravo.png
    +-- outfiles/
            +-- images/
    make_rsrc.txt

The RsrcFileWriter normally takes one argument with a text file telling it what to do:

infiles   #1
outfiles  #2
rsrc      #3

*.txt          copy                 #4
images/*.gif   img   hwcolor W12 L8 #5
images/*.png   ham   W12 L8         #6
*594x396*png   ham                  #7
  • #1: specify input directory, if relative then you must cd to the base directory before calling RsrcFileWriter.
  • #2: specify output directory.
  • #3: specify that resource files should be created. this also creates the file rsrc.cpp in the output folder which is the file which must be linked to your project. (added to your project's cmake file.)
    If this line is omitted, then the copied&converted files are not hex-encoded for compiled into your program. This is suitable for converting files for an SDcard.
  • #4: a filename match pattern and the instruction what to do: copy as-is. If multiple patterns match then the first one is used.
  • #5: create an .img file: These can be decoded by class Graphics/img/ImageDecoder. Some additional options are set:
    • hwcolor: create a hardware dependent file which uses the Color model of your hardware. When building RsrcFileWriter you must set -DPICO_BORD properly!.
    • W12 L8: compress the file using a window of 12 bits (2*4k) and a look-ahead window of 8 bits. This amount of memory is required for decompression!! The file is compressed and transparently decompressed by the resource file system.
  • #6: create a .ham image file and compress it using the same settings. ham image files are a cross-breed between indexed color and hold-and-modify. Basically you load it into a 8-bit indexed color BitMap and display it using a Video::HoldAndModifyVideoPlane. This requires balancing between absolute and relative color codes and within each group selecting the best color points. This is done by desktop_tools/RgbImageCompressor. The result is pretty good but there is room for improvement. Hard contrasts result sometimes in visible artifacts.
    The HoldAndModifyVideoPlane can display PixMaps which are smaller than the video display. The maximum size for display is 600x400 pixels, but you will hardly achieve this. (Though it is possible).
    ham files are useful only for display of RGB images on hardware with sizeof(Color) == 2!
  • #7: create a .ham file without compressing it. This not only loads faster but also does not require a decompressor for loading which leaves more memory available while loading the file.

Options

There are currently some options for the generated files:

Compression options

The files are compressed using heatshrink. If no compression option is given, then the file is not compressed. Heatshrink options:

  • W12: define look-back window size. The value gives the size of this window as log(2). 12 <=> 4k. An entry is 2 bytes, so W12 requires 8kBytes of memory during decompression. Possible range for the window width: 6 ... 14.
  • L8: define look-ahead window size. Again, this is log(2). Possible range: 4 .. 10.

Img options

The ImageFileWriter can read .gif, .bmp, .png, .jpg and may be others with the help of the stb library. An .img file can contain true color, indexed color or grey image data optionally with an alpha channel. Indexed color images are mostly the result of .gif files, true color images are created by .png and .jpg files. Currently the .img file encoder supports the following options:

  • hwcolor: convert the image into the hardware Color model for your board. This makes the file usable only on your board (and other board with the same Color model) but reduces size and increases loading speed. Else the original RGB888 or GREY8 values are stored.
  • noalpha: Ignore the alpha channel from the source image. Currently not supported by the ImageDecoder anyway.

Ham options

The RgbImageCompressor can read .gif, .bmp, .png, .jpg and may be others with the help of the stb library. A .ham image contains a true color image compressed to 1 byte per pixel. As such it is only usefule for true color images (as opposed to indexed color and grey scale) and hardware with a Color size larger than 1 byte (that is: 2 bytes), else you can use a .img file. Ham images are loaded into a 8 bit indexed color BitMap and displayed using a HoldAndModifyVideoPlane. Currently the .ham file encoder supports the following options:

  • pattern: In a first step the source image is downsampled to the hardware Color depth. To improve color resolution 2 additional low bits per color component are simulated using dithering. pattern applies a regular diffusion pattern.
  • none: No dithering is applied to the image. Mostly for comparison.
  • diffusion: This spreads the error from one pixel to the next.
  • diff_image: also write a .png with the exagerated differences between ref_image and output image.
  • ref_image: also write a .png with the reference image, which is the image after color depth reduction.
  • stats: also write a text file with statistics. The last 3 options only work if you don't convert the files into resources, that is, if there is no option rsrc in the batch file.