DSF Usage In X-Plane

Revision History:
         7/ 6/16   Added data validation rules
        12/ 8/13   Clarified DSF DEM handling
         2/18/12   Updated to docuemnt 7z
         2/12/12   Updated for X-Plane 1000
	 2/ 4/09   Updated for X-Plane 930
	12/26/07   Updated For X-Plane 900
	 7/25/07   Initial Draft

This document outlines how the DSF file format is used by X-Plane. DSF is a container format; new features can be added to the X-Plane scenery system without changing the file format. This document lists the different legal DSF configurations that X-Plane understands.

Note: this document is a low level reference, intended for programmers who intend to create tools to edit DSF files. Authors who want to edit DSFs should simply use higher level tools like OverlayEditor, or PhotoSceneryX.

DSF Compression

Starting with X-Plane 10, X-Plane will read 7z-compressed DSF files (a single DSF compressed into a 7z archive) natively. X-Plane thus installs its DSFs without decompressing them, to save disk space. You may need to un-7z DSFs to read them. 7z compression is optional.

DSF Properties

DSF contains a series of properties, with string values. These are the properties X-Plane recognizes:

Bounding Box and Location Properties

All DSFs must contain four properties indicating the bounds of the DSF tile. These bounds are in degrees and must be integers. DSFs should contain a planet tag, which is optional, and assumed to be earth if missing.

Object Density Control Properties

X-Plane only loads part of the facades and objects in a DSF, based on the “number of objects” setting in the rendering options. The “require” properties force X-Plane to load certain objects. Each require statement applies to either facades or objects, and specifies both the minimum setting where the objects are guaranteed loaded and the minimum index within the DSF of the object/facade it applies to.

More than one requirement statement can be used; all are combined together to meet all requirement constraints. Thus you can bring in objects incrementally through proper organization of the DSF object definition order.

Overlay Properties

The overlay properties control how a DSF is used as an overlay to other DSF files. The overlay property signals to X-Plane that the DSF should be loaded as an overlay and not a base mesh.

The exclude properties cause X-Plane to eliminate scenery from lower priority DSFs that are loaded underneath the overlay. Each exclusion zone is a rectangle specified in latitude and longitude. A DSF may contain multiple exclusion zones of the same type, and they may overlap.

The quality of culling depends on the type of scenery being excluded. In some cases, culling may over-remove or under-remove scenery.

[X-PLANE 9] X-Plane 9 improves the quality of forest exclusion. While X-Plane 8 forest exclusions remove a forest polygon if any vertex is in the exclusion zone, X-Plane 9 forest exclusion zones exclude on a per-tree basis for more precise cuts.

LOD Properties

[X-Plane 930:] Historically, X-Plane measures the distance of a mesh patch based on an arbitrary center point computed from the geometry. Since two different LOD mesh patches may have different vertices, their centers will be different. This cannot be predicted by authors. So for example, if a first patch has an LOD of 0 -> 20000 and the second one has 20000 -> -1, the first mesh patch may not disappear when the second one appears because they are being measured using different center points.

Setting the property sim/lod_mesh to 1 changes X-Plane’s behavior in the following way: the center point for LOD calculations of a mesh patch with a non-zero LOD start value will be taken from the previous mesh patch in the command stream.

This in turn means that a series of consecutive mesh patches with increasing LODs (starting at 0) will all have the same center point, and can be switched between using consecutive LOD values. (Also note that when this option is used, the closest LOD must come first, to establish the center point!

Other Properties

For historical reasons X-Plane will only flatten a terrain mesh if these properties are present.

Raster Layers

X-Plane 10 currently accepts one raster layers: “elevation”. Currently x-Plane can only handle a subset of raster formats: 16-bit signed integer with post-centric data. This matches what you’d find in a raw SRTM DEM.

Mesh Types and Coordinate Organization

X-Plane uses .ter files to specify the way mesh patches are drawn. The coordinate organization is:

1. Longitude
2. Latitude
3. Elevation
4. Normal – X
5. Normal – Z
6. Additional Coordinates…

These .ter files may contain “border” textures–the border feature of a .ter file is only used if the overlay flag is set in the mesh patch.

Mesh normals: the normal vector is stored as the X and Z ratio of the normal vector, based on a coordinate system of Y = up and Z = north at the mesh point’s location.

Additional coordinates are ordered optionally S1, T1, then optionally S2, T2. If an odd coordinate is provided, it is treated as alpha. If an alpha is needed but not present, X-Plane generates one using seeded random numbers.

X-Plane 8 does not use the alpha channel right now that a DSF may have.

Water terrain (“water” as a patch definition file) uses no ST or alpha coordinates.

Raster Data and Meshes

If  elevation raster data is present, it will be used for the elevation of a mesh point as long as:

• The patch vertex’s elevation is -32768.0 or
• The patch vertex’s terrain type is water.

If elevation rater data is present, all normal vectors can be left as 0.0 – X-Plane will calculate them from raster data, for all terrain types.

(By convention v10 DSFs produced with LR’s scenery tools use explicit elevation for all water vertices and all coastal vertices, to ensure precise water elevation even near dams and to keep a water-tight seal between land and water.  Interior land elevation points come from raster DEMs for data compression.)

Object Types and Coordinate Organization

Objects are placed with three or four coordinate values:

1. Longitude
2. Latitude
3. Heading
4. MSL height (optional in v10)

X-Plane 8 and 9 only allow AGL positioned objects (3 coordinates); X-Plane 10 allows for an optional 4th coordinate, interpreted as the MSL height of the object in meters.

AG Points (X-Plane 10 only) may only have three coordinates (lon, lat, heading) and are always draped.

Polygon Types and Coordinate Organization

Only one beach .bch definition may be used per DSF. Subtypes within the beach are used to create variety.

X-Plane uses a number of graphic resource files for DSF polygons. The meaning of the coordinates varies based on the type.

For forests, the density is a scaling factor–255 makes the maximum number of trees, 0 makes none. This control is multiplied by the rendering settings to set a final number of trees. Tree density will not exceed the maximum possible density from the .for file.

X-Plane 10: in X-Plan 10, a packing code is added to forest density. 0 gives the default behavior of filling the polygon with trees. 256 gives the behavior of plotting trees along every line of the polygon, treating each contour as a poly-line. 512 gives the behavior of plotting a tree on each point in every contour. Note that:

• Poly-lines are not auto-closed with line filling (to allow for U shapes) so you must duplicate the final point to make a ring.
• In point-fill mode, all points are equal, so there is no advantage to using contour rings.

For beaches, the parameter can specify a ring, which connects the end point to the beginning. This will create a correct texture transition from the end to the beginning. The dx and dz coordinates for the beaches are a normal vector, similar to a DSF’s normal vector, and are used for draping the beach. The subtype parameter is an integral subtype which describes which beach from within the .bch file is used.

X-Plane 10: in X-Plane 10, the normal vectors and elevation of beaches can optionally be omitted, as X-Plane derives this information on the fly.

For draped lines (.lin), object strings (.str) and draped polygons (.pol) if bezier coordinates are present, then bezier curves are generated.

For object strings, the spacing of objects is controlled by the polygon parameter. For draped lines, the polygon may be treated as a ring or chain. Like beaches, best results come from using the ring feature rather than duplicating the first point. For a draped polygon, texture coordinates (ST from 0 to 1) may also be included–the parameter value 65535 indicates this.

For both autogen blocks (.agb) and autogen points (.ags) the height of variable height elements is encoded in the upper 8 bits of the parameter (e.g. * 256) and represents the metric height divided by four. (In other words, some precision in height is lost to allow for a wider range of building height.

For autogen blocks, the lower 8 bits of the polygon represent a spelling set code – this is used to look up which “spelling set” in the autogen block to use. A typical use is to use different tile arrangements based on different block codes. X-Plane’s global scenery, for example, uses codes 0-7 to indicate whether the “back 3” walls are road adjacent or not.

Autogen strings represent the strangest polygon feature of all. Unlike other polygons, the contours in AGS are interpreted as poly-lines (not closed polygon rigns!); the AGS is required to be a closed polygon with holes when all contours are considered.

The first N contours (where N is the lower 8 bits of the polygon parameter) will spawn autogen buildings; the rest of the contours are used only to create a closed polygon-with-holes area.

A few examples may help clarify autogen strings:

• In the case of a single rectangle city block with houses on all sides, there would be one contour with 5 points (the start point must be duplicated) and the polygon parameter N=1.
• In the case of a single rectangle city block where the north side has no houses, there would be two contours: the first contour would contain the NE, SE, SW, NW points and the second woul contain the NW, NE points. N=1 because only the first contour has houses.
• In the case where only the east and west sides of the block have houses, there would be four contours: NE,SE then SW, NW, then NW, NE, then SE,SW. N=2. Note that the first two and last two contours can swap with each other.
• In the case where a city block has houses on all sides but a lake in the middle, the first contour is the block (with a dupe point to close), the second is the lake (with a dupe point to close) and N=1.

Road Types and Coordinate Organization

Only one road.net definition may be used per DSF. Subtypes within the road file are used to create variety.

Road network files use 4 coordinates.

1. Longitude
2. Latitude
3. Elevation
4. Junction ID

Road segments are connected via junction IDs with the following rules:

• The DSF file’s junction IDs must start at 1 and contain no gaps. 0 is reserved as the “no junction” flag.
• A road chain must start and end with a junction.
• A junction must be used any time an intersection is desired.
• A junction must be used any time a road chain changes subtype.
• All nodes that share the same junction code must share the same coordinates.
• A junction should not be used for nodes that are designed only to change the path of a road (“shape” points), because the processing overhead is higher for junctions.

X-Plane 10: if the road.net specifies a draped road type then the elevation should be a stacking layer number (0 for the ground, then 1, 2, 3, etc.) for all junctions to specify overpasses. Within the chains, the shape point should be 0 for a vertex and 1 for a bezier curve control point. There must be no more than two consecutive control points in a road. (That is, quadratic and cubic bezier curves are allowed but no higher degere polynomials.) All bridge-crossing roads should use a junction so that the sim can ensure separation.

Overlay DSF Restrictions

DSF overlays have restrictions on the types of files they may use:

• [X-Plane 8:] Road networks are not allowed in overlays.
• Mesh patches are not allowed in overlays.

X-Plane 9 relaxes the road network rule–in X-Plane 9 a DSF overlay may contain a road network, but the one-.net-per-DSF rule still holds. When a DSF overlay has a road network and the base mesh does too, the junction IDs between the two do not connect.

Guidelines for DSF Extension

• Consider all properties starting with “sim/” as reserved.
• Do not add extra coordinates to vertices beyond what is in this spec.

Data Validation

These rules place limits on the kinds of data that can be specified for various art assets.

Base Mesh

• Every point within the lat-lon rectangular boundaries of the DSF must be covered by exactly one triangle that is ‘hard’ (meaning the hard flag in its parent patch is set).
• It is illegal for a triangle’s vertex to be located on the edge of another triangle; triangles must only meet vertex-to-vertex, not vertex-to-edge. (In other words, there can be no “T” junctions in the mesh.)  Triangles meet at vertices if the coordinates of their vertices have the exact same lat, lon and elevation bit-values.

Objects/AGPs

• Objects must be within the DSF lat/lon boundaries.
• Object heading should be between [0 and 360).

Polygons

Area rules (these apply to facades with roofs, draped polygons, filled forests, AGS and AGB).

• All polygons must have counter-clockwise winding for exteriors and clockwise winding for holes.
• Polygons must not be self-intersecting.

Line rules (these apply to all polygons except for forests in “points” mode).

• Polygons must not have zero length sides.

Roads

• All roads chains must be made of at least one segment.
• All road segments must have positive length.
• It is illegal for a road segment to reverse direction (E.g. have a 180 degree turn).
• A junction must not have two roads entering the junction at the same heading and the same level.
• No more than two shape points within a chain can be bezier control points. (In other words, a cubic bezier is the highest degree bezier supported in curved roads.)
• While a bezier control point may be outside the DSF boundaries (typically the point pools contain some margin to allow this) the actual path of the road segment must remain within the DSF boundaries.

While it is not necessary, it is recommended that crossing roads share a junction at the crossing point with the roads on different levels; X-Plane can use this information to try to ensure that the roads are not reordered vertically due to the road draping and smoothing process.