Autogen blocks are autogen elements made up of a 2-d grid of adjacent tiles. AG Blocks are designed to tightly fill and pack rectangular areas, e.g. a city grid.
Unlike AG strings and points, the tiles in AG blocks are not specified individually, but rather by a 2-d grid. It is a requirement that the grid be built as a 2-d grid in the tile texture sheet. (The optimization is that for long strings of adjacent tiles, the entire set of tiles is drawn at once.)
An AG Block contains one or more grids; rules define which grid is used in which cases.
An AG block also contains spelling sets that indicate how the tiles in a given grid are included or removed from the grid. The relationship is many to many: any spelling set can reference any grid.
Slop and Anti-Slop
The majority of the size changes of an AGB are made by adding and removing tiles from the grid. However, the AGB also features resizable “slop” tiles that can be overlapped by their neighbors for the purpose of resizing the grid by small arbitrary distances.
Slop is defined by setting an entire row or column of the tile array as a ‘slop’ tile. A slop tile can be overlapped by its neighbor (to the right or above in the texture), and annotations that would be covered are dynamically removed if their point location is covered.
A slop tile can define “overlap” – the number of pixels of the slop zone that will be covered by the next tile over. This allows the next tile (which is on top of the slop tile) to contain a soft alpha edge that will always have the slop tile underneath it.
Thus the minimum size of a slop tile in an AGB is zero – it can be entirely compressed and serve as backing underneath the next tile. At its maximum stretch, the size of the tile is the tile size minus the overlap, since the next tile must start.
There is a second way to control alpha overlap: for any non-slop tile, an “anti-slop” parameter can be defined that causes this tile to be started some number of pixels to the left or below of its normal location, overlapping the previous tile. This can be used to make tiles with alpha edges that always overlap the previous tile.
DSF Usage
Autogen blocks in a DSF are specified by a four-point single-contour DSF polygon, counter-clockwise. Holes are not permitted. The upper 8 bits of the DSF parameter is the object height divided by four, and the lower 8 bits of the DSF parameter matches a particular spelling set.
The first segment of the AG block defines the orientation of the block. By convention, the bottom of the texture is aligned with this first side and forms the “S” or “H” axis.
Properties of the Entire .AGB
CROP 0|1
The crop directive defines whether tiles that go outside the DSF polygon are cut at the DSF polygon. The default behavior is false. Because the AGB can hang over the edge of the DSF polygon (when the DSF polygon is not a perfect rectangle), cropping can be useful to remove tile artifacts that cover other parts of the scenery like roads.
FLIP_180
Normally the first edge of the DSF polygon runs along the bottom of the AGB grid texture, with the left side of the directed polygon edge touching the AGB. When FLIP_180 is included, the first side of the DSF polygon runs along the top of the texture from right to left, flipping the entire AGB by 180 degrees.
Grid Specification and Properties
A sub-grid is a 2-d array of tiles specified together. The AGB contains one or more sub-grids.
SUB_GRID
This directive marks the beginning of a grid within the AGB. Unlike AGS and AGP files, all tiles are specified at once within the grid. Grids are numbered consecutively with the first grid having index 0. If the SUB_GRID directive is omitted, the first grid defined in the file is treated as GRID 0.
OVERLAP_H pixels
OVERLAP_V pixels
These directives define how many pixels of slop tiles must be overlapped by the next tile. Typically the tile following a slop tile will have alpha on the left edge; the overlap is the size of this alpha zone. Overlap ensures that the slop zone will not be stretched so much that there is no tile below the alpha.
These directives set a default slop – the SLOP_H/V directives let you override it on a per-tile basis.
ANTISLOP_H pixels
ANTISLOP_V pixels
These directives define the number of pixels of overlap that a non-slop tile will cover of the tile to the left or below them.
CUT_H pixels
CUT_V pixels
The CUT directives define the grid lines of the AG grid. For N h-cut lines there are N-1 horizontal tiles and for N v-cut lines, there are N-1 v-cut tiles. Properties defining the tiles (slop, anti-slop) must be defined after a cut directive but before the very last cut directives.
Cut directives must occur in increasing order of pixel grid line location. An AGB must have at least two cuts in each direction.
SLOP_H [pixels]
SLOP_V [pixels]
These define the preceding horizontal or vertical tile (whose left or bottom edge have just been defined with a cut directive) as a slop tile row or column. If pixels is included, it defines the amount of overlap that the next tile will cover the slop zone with; if it is omitted, the last OVERLAP_H/OVERLAP_V directive is used.
END_CUTS
This marks the end of the sub-grid definition; no more cuts or slop directives can occur until the next sub-grid.
Unlike AGS and AGP, annotations are placed on the entire grid – you do not need to tell X-Plane which tile an annotation is for. All annotations must occur after END_CUTS and before the next sub-grid.
EDGE_MIN left bottom right top
EDGE_BEST left bottom right top
EDGE_MAX left bottom right top
X-Plane aligns the tile grid to the DSF rectangle by aligning the bottom edge of the tile grid (or top for flip-180) with the first edge of the DSF polygon. The grid is then sized so that the DSF polygon goes through the tiles somewhere between EDGE_MAX and EDGE_MIN, as close to EDGE_BEST as possible. (In other words, in a perfectly rectangular DSF, EDGE_BEST is used, but if the DSF polygon is trapezoidal, then parts of it may come closer to edge min/max.
EDGE_MAX is the largest acceptable rectangle, e.g. it defines how far away from the center of the grid the DSF polygon can be; EDGE_MIN defines how close to the contents of the tiles the DSF boundary can get. When cropping is on, no content inside EDGE_MIN will ever be cropped.
GROUND_PT_FORMULA x-ratio x-delta y-ratio y-delta
When a tile contains the GROUND_PT_FORMULA directive, the point used to align graded objects with the ground is calculated using a formula based on the entire DSF boundary rectangle:
- A blending weight is found between the four corners of the ideal square rectangel using x-ratio and y-ratio.
- The location of the four corners are averaged using these blending ratios.
- The x and y delta (in meters) are then applied, where X is a direction along the first DSF polygon side and Y is a direction perpendicular and counter clockwise from it.
The intention of this directive is that a number of tiles sharing parts of a common building can all use the same formula to achieve a common grading point somewhere within the AGB.
Note that since there are no tile directives, the tile that this directive applies to is based on the previous annotation that is placed. The intended use is to use this after the OBJ_GRADED directive that defines the object that needs special registration.
Spelling Set and Tile Selection Properties
The AGB also contains spelling sets. Each spelling set contains rules for how to use a grid (with tiles added and removed) and matching parameters for when it may be used. Note: if no spelling set matches the required situation, the first one in the AGB is used as a default.
SPELLING_SET param
This defines a new spelling set. The param value must match the low 8 bits of the DSF parameter. (This lets the DSF select variants on an AGB.) By convention, X-Plane scenery often uses these values:
HEIGHT_RANGE min-height-meters max-height-meters
WIDTH_RANGE min-width-meters max-width-meters
DEPTH_RANGE min-depth-meters max-depth-meters
These parameters require that the spelling set only be used when the width, height, or depth of the AGB is within certain metric ranges. The width is the shortest width across the DSF polygon along the direction of the first side; the depth is the shortest distance normal to it. The height is the metric height passed in the DSF parameter.
FREQUENCY ratio
This controls the relative frequency of this spelling set compared to others. When a random spelling set is picked from all spelling sets that match filtering criteria above, the relative frequencies weight the random drawing. The default weight is 1.0.
USE_GRID index
This indicates which grid to use with this spelling set, by zero-based index.
SPELLING_S col-index col-index […col-index]
SPELLING_T row-index row-index […row-index]
The spelling directives each define one spelling (of horizontal columns or vertical rows) that can be used to build real tile grids out of the grid for this spelling set. X-Plane will re-assemble the AGB grid from the columns and rows specified in the order specified.
You should include many spelling directives to provide spellings of different lengths to cover the entire size range the AGB spelling set is filtered to fulfill.
From a performance perspective, consecutively increasing non-anti-slop tiles are more efficient than arbitrary tiles because they can be drawn as a group.
DEFINE_SPELLING_S namecol-index col-index […col-index]
DEFINE_SPELLING_Trow-index row-index […row-index]
USE_SPELLING_S name
USE_SPELLING_t name
The define-spelling directives simply create a recallable name (within this .agb) for a given spelling column or row list. The USE_SPELLING directive with that name is the same as having a duplicate SPELLING_S or SPELLING_T directive with that set of tiles.
The use case for named spelling sets is when the same texture space is used to create a grid with the same cut lines and slop, with only the autogen annotations changing. In this case, it might be useful to simply have the exact same spellings for each grid.