Harmonic Flow Framework

Harmonic Flow Blog

Harmonic Flow Framework v0-8-0

What's new in version 0.8.0:

Added new command-line tool hftexpack. hftexpack is a tool for packing textures into an ImageAtlas.

  • Added new command line tool 'hftexpack'.
  • A new class 'ImageHelper' has been added which acts as a simple wrapper around 'stb_image', 'stb_image_resize' and 'stb_image_write'. Due to the new class ImageHelper the following methods in Environment interface has been removed: loadImage and freeImage.
  • Added 'stb_image_resize.h' v0.95 for image resizing. ImageHelper acts as a wrapper around it.
  • HFImageAtlas class added to load XML file generated by the new tool 'hftexpack'.
  • Removed AtlasMaker 3rd party java tool from 'additional_tools' folder as it's no longer needed. It's replaced by new tool 'hftexpack' which is more flexible and packs textures better.
  • Updated ImageAtlas documentation.

hftexpack info

hftexpack is a new flexible command-line tool for packing textures into a ImageAtlas. It supports PNG RGB/RGBA images as input and outputs PNG RGBA + XML. The tool can be found in 'src/tools/hftexpack' folder.

See hftexpack --help for available options:

hftexpack [OPTIONS...]

hftexpack -i=data/characters,data/tiles -o=out/atlas -m -t -u -r -s=1024 -p=8
hftexpack -i=data -e=data/tiles -o=out/atlas -d -s=1024 -rh=3
hftexpack -if=input.txt -ef=exclude.txt -o=out/atlas -d -s=1024 -rh=1

Only PNG (RGB/RGBA) textures are supported as input! It will only
load PNG in supplied input directories.

hftexpack Options:
-d, --default           Default options (-m -t -u -r)
-i=#, --input=#         Input files/directories comma separated.
-if=#, --input-file=#   Input file containing files/directories. Each entry needs to be on a new line.
-e=#, --exclude=#       Exclude files/directories comma separated.
-ef=#, --exclude-file=# Exclude file containing files/directories. Each entry needs to be on a new line.
-o=# --output=#         Output file.
-m, --premultiply       Premultiply the pixels of the textures by their alpha channel.
-t, --trim              Trim excess transparency off the textures.
-f, --force             Force packer to re-pack (ignore stored hashes).
-u, --unique            Remove duplicate textures from the atlas.
-r, --rotate            Enable rotation of textures (90 degrees clockwise).
-fs, --force-square     Force Atlas POT Square size.
-as, --adjust-size      Adjust Atlas size automatically so that texture will fit.
-af, --adjust-fit       Adjust texture size so that it will fit given Atlas size.
-ma=#, --max-atlases=#  Max atlases that can be created (default is 64).
-s=#, --size=#          Max atlas size (POT). (# should be: 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384)
-p=#, --pad=#           Padding between textures. (# should be a value from 0 - 16)
-rh=#, --rect-heuristic=# Specifies the different heuristic rules that can
                        be used when deciding where to place a new
                        rectangle. Valid numbers are (0 - 4):
                        0 = Positions the rectangle against the short
                            side of a free rectangle into which it fits
                            the best. (RectBestShortSideFit) ** DEFAULT
                        1 = Positions the rectangle against the long side
                            of a free rectangle into which it fits the
                            best. (RectBestLongSideFit)
                        2 = Positions the rectangle into the smallest
                            free rect into which it fits.
                        3 = Does the Tetris placement.
                        4 = Chooses the placement where the rectangle
                            touches other rects as much as possible.
-v, --verbose           Verbose output of progress.

Help Options:
-h, --help              Show help options
-v, --version           Print version information and exit

hftexpack examples

Pack textures in folder data but exclude data/fonts folder and output in folder out:

hftexpack -i=data -e=data/fonts -o=out/atlas

Same as above but using a input text file instead:

hftexpack -if=input/files.txt -ef=input/exclude.txt -o=out/atlas

Use default options (-m -t -u -r), set atlas size and make sure that atlas size automatically increase to next power-of-two size if needed to fit texture original size. Also show verbose output of progress:

hftexpack -i=data -e=data/fonts -o=out/atlas -d -s=2048 -as -v

Same as above but instead making sure textures are resized if needed to fit given atlas size:

hftexpack -i=data -e=data/fonts -o=out/atlas -d -s=512 -af -v

Same as above but also force square output texture size, set padding between textures to 1 pixel, use another packing option and some additional include/exclude folders/files:

hftexpack -i=data,data2,data3/file.png -e=data/fonts,data2/bgr.png -o=out/atlas -d -s=512 -af -fs -p=1 -rh=3 -v

Load ImageAtlas example C++

In 'data/resources.xml':

<?xml version="1.0" ?>
    <Resources id="init">
        <ImageAtlas id="IMAGEATLAS_TEST" path="data/atlas/atlas.xml"/>

In C++ source code:

// parse resource file:
bool result = HFCORE_RESMGR->parseResourceFile("data/resources.xml");

// load resource group needed:

// Get ImageAtlas from Resource file by it's name:
HFCore::ImageAtlas *atlas =

// Get Rect for image:
HFCore::Rect atlasRect = atlas->getRect("cursor_default");

// Get Atlas image image resides in:
HFCore::Image *image = atlas->getImage("cursor_default");

// Load ImageAtlas from given path:
HFCore::ImageAtlas *atlas =

Download the latest version here. Submit any bugs or thoughts here.

Posted on Wed, 29 Aug 2018
Tags: harmonic-flow-framework, harmonic-flow-news, image-atlas, libhffwk, texture-atlas, texture-packer

Comment On This Entry

Submit a comment on this entry.