FURWARE text/TextureCreator/Usage

== Quick start ==
You can find download links for the tool on the TextureCreator page. To run the TextureCreator under Windows, the easiest way is probably to fetch the pre-compiled package. Otherwise (and for using it on Linux or Mac), you can get the latest Python 2 code on the GitHub page. Note that when using the Python version, you will need Python 2 (tested with 2.7.5), pyCairo, Cairo, FreeType and any dependencies of these packages. A Python 3 version is currently not available because the pyCairo package for Python 3 does not have some of the required functionality.
Once you have the TextureCreator tool running and it is able to create textures for the included fonts, you may add your own font folders to the "fonts" directory and place a ".ttf" or ".otf" font file inside it. When you execute the TextureCreator, it should create a texture using the newly added font using default settings. However, more tweaking may be necessary to really get the best out of a certain font (most notably a custom "font.conf" file), because every font is different. See below for a more in-depth description of how the TextureCreator works.
== More on the mode of operation ==
The most important items in the texture creator directory are the main program file ("TextureCreator.py" or "TextureCreator.exe"), the "fonts" directory, the "scripts" directory and the "output" directory (which might not exist initially, but it is created automatically by the tool when needed).
The basic mode of operation is to load font files together with any custom configurations from the fonts directory, process them using one or more chain and script file(s) and output the resulting texture to the output directory.
The "fonts" directory contains sub-directories; one for each font. Each of these sub-directories usually contains a font file (TrueType (ttf) or OpenType (otf)). If a sub-directory does not contain any font file, it is silently ignored. Please note that only the most basic font files come bundled with the TextureCreator; see this page for links to the rest of the standard FURWARE text font files.
The texture creator searches each of the font sub-directories for a font file and if it finds one, it continues by searching for one or more "chain" files which contain commands that shall be executed for creating a texture for the font. Such commands might be (figuratively) "create a texture of a certain size", "draw these symbols using the currently loaded font at certain positions" or "continue with commands in another file".
Thus the "chain" files may be seen as the "entry points" for execution of commands for a certain font. The way the texture creator searches for chain files is as follows: First, the font's directory is searched for chain files; this allows you to specify chains that are specific to the font. Only if no chain files are contained in the font's directory, all chains contained in the "scripts" directory are executed.
Chain files may execute commands contained in other files (".script" files). For instance, the default chain files in the scripts directory execute several script files containing commands for initializing the new texture, drawing basic symbols, special symbols, and so on. Note that the only difference between ".chain" and ".script" files is the file extension; the same set of commands is available in both chain and script files, but only files with the ".chain" extension are used as the entry points for script execution.
Note that, just like chain files, ".script" files are also searched for in the font's directory first, then in the global "scripts" directory. This, again, allows you to bundle custom script files specific to a certain font.
Each font sub-directory may also contain a "font.conf" file for font-specific configuration. These files are different from the chain and script files. They may contain font-specific offset and scaling settings, also for individual symbols of the respective font. Whenever a font is being loaded for drawing (also when it is loaded from other script files), that font's configuration is used.
After all commands in a chain file have been executed, the created texture is written out to the "output" directory. By default, the name of the font directory is used for the texture's name (plus the image format's extension), but that name may be changed using script commands.