NAME

mgl-texatlas - テクスチャアトラスジェネレータ

SYNOPSIS

mgl-texatlas [options] image-files

DESCRIPTION

mgl-texatlasは複数の画像を指定サイズの画像へと結合するためのツール です．

結合する画像は引数 image-files に複数指定します．ツールはこれらを結合 した画像を出力し，同時に元の画像にアクセスするためのロケーション情報も 出力します．ロケーション情報はバイナリおよびJSON形式で出力されます．

現在，画像ファイルのフォーマットは入出力共にPNGにのみ対応しています．

ツールが出力するファイルは次の通りです．

texture[d].png

結合された画像です．[d]の部分には0以上の数値が入ります．入力画像 が指定したサイズに収まりきらなかった場合，複数の画像に連番で出力 されます．

texture_loc.bin

ロケーション情報のバイナリファイルです．このファイルには入力画像 が何番目のテクスチャのどの座標に配置されたかの情報が格納されて います．格納形式についてはBINARY FORMATの節を参照してください．

texture_loc.json

ロケーション情報をJSON形式で出力したファイルです．内容については バイナリファイルと同等です．

出力画像のサイズやファイル名の"texture"の部分はオプションにて変更可能 です．詳細はOPTIONSの節を参照してください．

OPTIONS

--hash-seed

ロケーション名に使用するハッシュ生成関数のシード値を指定します． 指定しなかった場合は0xA3F6C23Eが使用されます．ハッシュ値が衝突を 起こす場合はこのオプションを使用してシード値を変更してください．

--help

簡易ヘルプを表示して終了します．

--margin, -m

結合する画像の間隔をドット単位で指定します．0から32の間の値で 指定し，省略時には1が使用されます．

--name, -n

出力するファイル名に付ける名前を指定します．省略時には "texture"が使用されます．

--output, -o

出力ディレクトリを指定します．指定しなかった場合はカレント ディレクトリに出力します．

--size, -s

出力する画像のサイズを指定します．幅と高さを'x'で区切って指定 してください．省略時には1024x1024が使用されます．

--verbose

より多くのメッセージを表示します．

--version, -v

バージョン情報を表示して終了します．

EXIT STATUS

0

成功

それ以外

失敗

IMAGE SPLIT

入力する画像をさらに細かく分割して扱いたい場合，同名のCSVファイルを用意 することで，その領域をロケーション情報へと追加できます．

入力ファイルが"image.png"である場合，対応するCSVファイル名は"image.csv" になります．この2つは同じディレクトリに配置されている必要があります．

CSVファイルはRFC 4180に準拠した形式である必要があります．すなわち，区切り 文字に','を使用し，改行コードはCR+LFで保存してください．推奨はしません が，UTF-8エンコーディングを用いることで非ASCII文字を扱うことも可能です．

CSVファイルのフィールドには順に名前，X座標，Y座標，幅，高さを指定します． 例えば，(8, 8)の座標にある16x16の領域を"sub_layer"として扱う場合の指定 は次の通りです．

Example: image.csv

sub_layer,8,8,16,16

この場合，ロケーション情報には"image/sub_layer"の名前で追加されます．

BINARY FORMAT

コンバータが出力するロケーション情報のバイナリデータには，次の順で内容が 格納されています．

• ヘッダ
• ロケーション情報
• フッタ

全ての値のバイトオーダーはリトルエンディアンです．

ヘッダ

ヘッダは合計24バイトで，次のパラメータが格納されています．

+0 hashSeed (4Byte)

このファイルが使用するハッシュ計算のシード値です．--hash-seed オプションで指定した値がこの領域に格納されます．mgl-texatlasが 使用するハッシュ生成アルゴリズムについてはHASH ALGORITHMの節を 参照してください．

+4 identify (4Byte)

このファイルがロケーション情報である事を確認するための識別子で， hashSeedを用いて文字列"TextureAtlasLocations"をハッシュ化した 値が格納されています．この領域はこのファイルがロケーション情報 であることを確認すると同時に，ハッシュ生成アルゴリズムが意図 した値を算出するかのチェックも兼ねています．

+8 revision (4Byte)

このバイナリフォーマットのリビジョン情報です．現在は常に0であり， 将来フォーマットの変更が行われた場合に加算される予定です．

+12 flags (4Byte)

この領域は将来のために予約されており，現在は使用されていません．

+16 imageCount (4Byte)

このロケーション情報が扱うテクスチャの数を表す値です．

+20 locationCount (4Byte)

このファイルに格納されているロケーション情報の数を表す値です．

ロケーション情報

ロケーション情報は1つあたり28バイトで構成され，ヘッダのlocationCountの 数だけ格納されています．これらはhashの値を昇順にソートした状態で格納 されています．ロケーション情報の内容は次の通りです．

+0 hash (4byte)

ロケーション名をハッシュ化した値です．バイナリファイルでは ロケーションの判別にハッシュ値を使用し，その値は入力ファイルの パスを元に算出します．ハッシュの生成アルゴリズムについては HASH ALGORITHMの節を参照してください．

+4 imageIndex (4byte)

出力した画像の番号を表す値です．この値は連番で出力した画像の 何番目に目的の領域があるかを表しています．

+8 x (4byte)

目的の領域のX座標を表す値です．

+12 y (4byte)

目的の領域のY座標を表す値です．

+16 width (4byte)

目的の領域の幅を表す値です．

+20 height (4byte)

目的の領域の高さ表す値です．

+24 flags (4byte)

この領域は将来のために予約されており，現在は使用されていません．

フッタ

フッタは4バイトで，文字列"EndOfRecord"をハッシュ化した32-bit値が格納 されています．全ての要素を読み込んだ後にこの値が読み取れない場合， ロケーション情報のパースに失敗している可能性があります．

HASH ALGORITHM

mgl-texatlasはハッシュ生成にFNV1aアルゴリズムを使用します．この アルゴリズムをC++で実装する例を次に示します．

constexpr uint32_t kFNV1aPrime32 = 0x1000193;

constexpr uint32_t FNV1a(
        const char *str,
        const uint32_t seed) noexcept
{
    if (str[0] == '\0')
    {
        return seed;
    }
    
    return FNV1a(
            &str[1],
            (seed ^ uint32_t(str[0])) * kFNV1aPrime32);
}