Revision History: 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.
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.
| Property Name | Default | Value |
|---|---|---|
| sim/north | (Required) | degrees |
| sim/south | (Required) | degrees |
| sim/east | (Required) | degrees |
| sim/west | (Required) | degrees |
| sim/planet | earth | earth|mars |
X-Plane only loads part of the facades and objects in a DSF, based on the "number of objects" setting. 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.
| Property Name | Value |
|---|---|
| sim/require_object | obj_level/first_required_index |
| sim/require_facade | obj_level/first_required_index |
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.
| Property Name | Value |
|---|---|
| sim/overlay | 0|1 |
| sim/exclude_obj | west/south/east/north |
| sim/exclude_fac | west/south/east/north |
| sim/exclude_for | west/south/east/north |
| sim/exclude_bch | west/south/east/north |
| sim/exclude_net | west/south/east/north |
| sim/exclude_lin | west/south/east/north |
| sim/exclude_pol | west/south/east/north |
| sim/exclude_str | west/south/east/north |
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.
[X-Plane 930:] Historically, X-Plane measures the distance of a mesh patch based on an arbitrary center point computed from the geomerty. 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 ad 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 commadn 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!
For historical reasons X-Plane will only flatten a terrain mesh if these properties are present.
| Property Name | Value |
|---|---|
| sim/creation_agent | X-Plane Scenery Creator 0.9 |
| sim/internal_revision | 0 |
X-Plane uses .ter files to specify the way mesh patches are drawn. The coordinate organization is:
.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, basde on a coordinate system of Y = up and Z = north at the mesh point's location.
Additional coordinates are ordered optionally S1, T1, then optionaly 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.
| Base Texture is Projected | Composite Texture Is Projected | Border+Overlay Flag | ST1 Controls | ST2 Controls |
|---|---|---|---|---|
| no | no | no | base | - |
| no | no | yes | base | border |
| no | yes | no | base | - |
| no | yes | yes | base | border |
| yes | no | no | base | - |
| yes | no | yes | base | border |
| yes | yes | no | - | - |
| yes | yes | yes | border | - |
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.
Objects are placed with three coordinate values:
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.
| File Type | Holes Allowed? | Parameter Meaning | Coordinates | |||||
|---|---|---|---|---|---|---|---|---|
| Facade | No | Height (meters) | Lon | Lat | ||||
| Forest | Yes | Density (0-255) | Lon | Lat | ||||
| Beach | No | 0=chain,1=ring | Lon | Lat | Elevation | dx | dz | subtype |
| Line | No | 0=chain,1=ring | Lon | Lat | ||||
| Lon | Lat | Ctrl Lon | Ctrl Lat | |||||
| String | No | Spacing (meters) | Lon | Lat | ||||
| Lon | Lat | Ctrl Lon | Ctrl Lat | |||||
| Draped Polygon | Yes | Texture Heading | Lon | Lat | ||||
| Lon | Lat | Ctrl Lon | Ctrl Lat | |||||
| 65535 | Lon | Lat | S | T | ||||
| Lon | Lat | Ctrl Lon | Ctrl Lat | S | T | Ctrl S | Ctrl T |
For forests, the density is a scaling factor - 255 makes the maximum number of trees, 0 makes none. This control is mulitplied by the rendering settings to set a final number of trees. Tree density will not exceed the maximum possible density from the .for file.
For beaches, the parameter can specify a ring, which connects the end point to the beginning - this will create a correct texture transisition 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.
For draped lines (.lin), object strings (.str) and draped polygons (.pol) if bezier coordinates are present, then bezeir 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.
Only one road.net definition may be used per DSF. Subtypes within the road file are used to create variety.
Road network files use 7 coordinates. The last 3 are optional (used only for bezier roads). Note: x-Plane does not yet visualize bezier roads -- while the DSF spec and X-Plane's usage of it call for bezier curves, the control points are ignored as of X-Plane 860.
Road segments are connected via junction IDs with the following rules:
DSF overlays have restrictions on the types of files they may use:
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.