Vectorial Tile Format (VTF) is a format to store large tilemaps in small bytespaces.
There are two kinds of VTF: XVTF (XML-based Vectorial Tile Format) and BVTF (Binary Vectorial Tile Format). Both share a specification in common, but each uses their own structure to store it.
XVTF is an XML document that stores VTF data using a structure that looks like the following:
<xvtf>
<tilemap default="0" sizeX="50" sizeY="30"> // every tile not filled by any object is
// assigned 0. This includes missing value,
// fillValue and contourValue fields.
<line layer="0" ax="12" ay="20" bx="19" by="20" value="30" antiAlias="false"/>
// a line that sets everything in it's
// span to 30. It is always straight.
<point layer="0" x="14" y="20" value="15"/> // changes that one spot in the line
// to 15. Objects that share the same
// space and layer are ordered using
// line position in the XML document.
// Objects of dimension 0 (point) and 1 (line, bezierNormal, ) always have
// a single 'value' property.
<bezierLoop layer="1" fillValue="9" antialias="false"> // Objects of dimension 2
// (bezierLoop, border,
// polygon, rectangle,
// circle...) value
// fieldsare fillValue
// and contourValue.
<control x="2" y="4" ax="3" ay="3" bx="7" by="2"/> // ax, ay are the 1st handle's'
// coords, bx and by are the 2nd
// handle's' coords, and x and y
// are the control point's coords.
<control x="8" y="3" ax="6" ay="2" bx="4" by="3"/>
</bezierLoop>
</tilemap>
</xvtf>
The example can also be further examined for some clues on the specification's workings.
BVTF is a compressed, human-unreadable, binary, unique document structure made specifically to store VTF data with efficiency and compression.
It's structure can be used via the following C++ snippet:
enum FillerType
{
FT_Point, // 0
FT_Line, // 1
FT_Bezier, // 2
FT_Border, // 3
FT_Polygon, // 4
FT_Rectangle, // 5
FT_Circle, // 6
FT_BezierLoop // 7
};
struct FillerObject
{
char* objectName;
FillerProperty objectProperties[8];
}
struct FillerProperty
{
char* propertyName;
bool bExists;
bool bValue;
int iValue;
}
struct Filler
{
FillerType type;
int numProperties;
int layer;
FillerProperty properties[32];
FillerObject subObjects[32];
}
struct Tilemap
{
int defaultValue;
int numFillers;
Filler fillers[512];
}
struct BVTF
{
Tilemap tilemaps[64];
}
Tilemaps are the main structure used to hold VTF tilemaps. They contain two numbers that define their size, a default value (which is usually 0 but can be used to reduce redundancy with fillers that try to set non-occupied space to some other value) and a list of fillers, which is limited on binary but unlimited on XML versions (just like any other structural lists held in this specification).
Fillers are what define the VTF tilemaps. Each filler has it's type, which defines how it is rendered into the final tilemap, and a list of properties.
Each filler also has a layer number. Fillers with lower layers are rendered below. Fillers with same layer are rendered from the bottom to the top in the order they appear in the file.
Sets a single XY point in the tilemap to a certain value. Since they aren't very effective, avoid when possible.
Properties:
x, y -> Their coordinates.
value -> Their value.
Sets all points along the line to a certain value. Aren't very effective, but better than using points.
Properties:
ax, ay -> Coordinates of the line start.
bx, by -> Coordinates of the line end.
value -> Their value.
antiAlias-> Whether to antialias the curved points or not. Defaults to false (boolean property).
Sets all points along the Bezier path to a certain value.
Properties:
value -> Their value.
control
Control points along the path.
Subobject's properties:
x, y -> Control point coordinates.
ax, ay -> Previous handle coordinates.
bx, by -> Next handle coordinates.
Sets all points that aren't outside a border of Points to a certain value.
Properties:
contourValue -> The border's value.
fillValue -> The inside points' values.
borderPointPoints that form the border. Those are different from Polygons below in that the border is formed not by lines, but by points, that act like "bricks".
WARNING: If this "wall of bricks" isn't complete, then fillValue will simply set the whole
tilemap's value!
Subobject's properties:
x, y -> The coordinates of that point.
Sets all points in the border or inside the polygonal object to some value.
Properties:
contourValue -> The border's value.
fillValue -> The inside points' values.
vertex
Points that the polygon's border changes direction.
Subobject's properties:
x, y -> The coordinates of that point.
Sets all points in the border or inside the rectangle to some value.
Properties:
x, y -> The X and Y coordinates.
width, height -> The rectangle's size.
contourValue -> The border's value.
fillValue -> The inside points' values.
Sets all points in the radius or border of this circle to some value.
Properties:
x, y -> The X and Y coordinates of the center.
radius -> The radius of the circle.
contourValue -> The border's value.
fillValue -> The inside points' values.
This is a hybrid between Border and Bezier, since it's a Bezier curve where the last control point is linked to the first one, forming a loop. Everything inside that loop is colored like in a Border.
The differences are that there are the following properties:
contourValue -> The border's value.
fillValue -> The inside points' values.
Instead of just a single value property.