FURWARE text/TextureCreator/Reference

== Chain/script commands ==
The following commands may be used in "chain" and "script" files.
=== runScript ===
Parameters: scriptName
Executes commands from another script file (usually with the extension ".script"; file name only, not a full path; note that scriptName must include the file name extension). The given script file ist first searched for in the folder of the font that is currently being processed and, if not found, in the global "scripts" directory. After successful execution of the commands in the other script, execution continues where runScript was called.
=== init ===
Parameters: sizeX sizeY scaleX scaleY
Initializes a new texture to draw to. This command should generally be one of the first things to call, except for "runScript" commands. The sizeX, sizeY values set the size of the drawing area in pixels. However, this only equals the size of the resulting texture if scaleX, scaleY is set to 1.0, 1.0. The scale parameters may be used to create larger or smaller versions of a texture without having to tweak any positioning of characters, etc. because everything will be scaled relative to these values.
For instance, the configs that come with the creator are made for 1024x1024 textures. If you set the size* values to 1024 and the scale* values to 0.5, you will get a 512x512 texture with the same content as the 1024x1024 version, just smaller. In contrast, if you set the size* values to 512 and keep the scale values set to 1.0, you will get a cropped version of the 1024x1024 version, showing only the upper-left quarter of the texture. Note that the scaling is not performed by scaling the final texture but during the drawing, yielding smooth and detailed textures at all scales.
=== setOutputName ===
Parameters: outputName
Sets the name of the texture file to be created. Note that outputName should not include the file extension, for instance .tga. When you do not call setOutputName, the name of the folder of the font currently being processed is used as the texture name. This command may be used for creating multiple versions of a texture from the same font.
=== setOutputNameSuffix ===
Parameters: outputNameSuffix
Similar to setOutputName, with the difference that outputNameSuffix is appended to the currently set output name. This allows you to append suffixes like -512 or -1024 to different versions of textures created from the same font.
=== setCellSize ===
Parameters: sizeX sizeY
Sets the size of one character cell to sizeX, sizeY (in pixels, assuming a scale of 1.0).
=== setCellOffset ===
Parameters: offsetX offsetY
Sets the distance of the center of the upper-left cell to the upper-left corner of the texture to offsetX, offsetY (in pixels, assuming a scale of 1.0).
=== setCellSpacing ===
Parameters: spaceX spaceY
Sets the horizontal and vertical spacing between the centers of two cells to spaceX, spaceY (in pixels, assuming a scale of 1.0).
=== setCellCount ===
Parameters: numX numY
Sets the number of cells in horizontal and vertical direction. Used for various purposes, especially for determining when to go to the next row when drawing many characters at once.
=== setBaselineOffset ===
Parameters: value unit
Sets the vertical offset of the font's native baseline from the cell centers. The unit parameter determines how value is interpreted; see below for possible values of unit.
=== jumpToCell ===
Parameters: cellX cellY
Sets the position of the virtual "cursor" in the cell grid to cellX, cellY. The next call of drawChars will then draw the next character to that cell.
=== loadFont ===
Parameters: fontName
Loads a font for drawing, also loading the respective font.conf file, if there is one in the same folder as the font file. fontName may be empty to load the font that is currently being processed by the tool. If it is not empty, it must be the name of one of the directories in the "fonts" directory. This command may be used to use symbols from other fonts, for instance when they offer special characters that are not available in the font being processed.
=== drawChars ===
Parameters: listOfChars
Draws the characters given in listOfChars to the current cursor position (see also jumpToCell). When multiple characters are specified, the virtual cursor will automatically be moved forward and, if necessary, to the next row.
=== drawLineBetweenCells ===
Parameters: thickness startX startY endX endY startOffsetX startOffsetY endOffsetX endOffsetY
Used to draw a line between two cells with the given line thickness. The startX, startY and endX, endY values are the coordinates of the start/end cells in the cell grid, starting from 0. The *Offset* values are offsets of the line endpoints from the start/end cells' center, in pixels.
=== drawRectBetweenCells ===
Parameters: thickness startX startY endX endY startOffsetX startOffsetY endOffsetX endOffsetY
Similar to drawLineBetweenCells, but draws the outline of a rectangle between two cells instead of a line, with the given stroke thickness. The start coordinates specify the upper-left, the end coordinates for the lower-right corner of the rectangle.
=== drawFilledRectBetweenCells ===
Parameters: thickness startX startY endX endY startOffsetX startOffsetY endOffsetX endOffsetY
Similar to drawRectBetweenCells, but draws a filled rectangle. Note that the thickness parameter does not actually have any effect for this command.
=== noBuild ===
Parameters: none
Causes script execution for the current font to be stopped and no texture is created. Used for fonts which are only there for usage from other scripts but for which no complete textures shall be created.
=== drawDebugGrid ===
Parameters: none
Draws an opaque grid showing the grid layout behind any drawn characters or geometry. Shall be called after the grid has been set up completely using init and the necessary set* functions, but before drawing any characters, etc.
== Font configuration files ==
The following commands may be used in font.conf files to tweak per-font and per-character settings.
=== offset ===
Parameters: offsetX offsetY unitX unitY
Sets the offset of all characters drawn using this font. See below for possible values of unitX, unitY which decides in which unit the offset* values are given.
=== scale ===
Parameters: value unit
Sets the scaling (text size) for all characters drawn using this font. See below for possible values of unit which decides in which unit the value argument is given.
=== charSettings ===
Parameters: char offsetX offsetY scaleX scaleY
Set per-character offset and scaling values. The char parameter shall be exactly one character for which the settings are being set. The offset* parameters set an offset that should be added to the global offset set using the offset setting when drawing the character char; given in pixels (assuming a scale of 1.0). The scale parameters are floats where a value of 1.0 means "no scaling".
=== enableAutoShrink ===
Parameters: none
If this line is given in the font config, a heuristic is activated that tries to guess a horizontal down-scaling for characters that would otherwise be too wide to fit in a cell. The idea is to automatically tweak the wider characters of non-monospace fonts (like W) to fit into the grid cells. This is very experimental.
== The unit* parameters ==
Some functions have unit* parameters that specify how the given values (offsets, sizes) shall be interpreted. Each unit* parameter may be one of:
* cellWidth: The offset/size value is interpreted relative to the set cell width, so a value of 1.0 means equal to the cell width.
* cellHeight: Same as cellWidth, but using the cell height.
* Any other value, recommended is abs: Absolute pixel values (assuming a texture scale of 1.0).