Mobile

Desktop

Professional

Downloads

Store

Support

From X-Plane Wiki

 
	Revision History
              6/6/10   - Updated for Wiki
              12/16/04 - Initial Draft

This document provides an authoring-level description of DSF files and the X-Plane scenery system.

Contents 1 Distribution vs. Editing 2 Overall DSF Structure 3 DSF Meshes 3.1 Mesh Layers, Patches, and Levels of Detail 3.2 Mesh Texturing 3.3 Mesh Parameters 3.4 Mesh Border Conformance 3.5 Mesh Performance 4 3-D Clutter 4.1 3-D Clutter and DSF Files 4.2 3-D Clutter and Performance

Distribution vs. Editing

DSF files describe the ground and objects on the ground for a 1x1 degree tile of the earth. Tens of thousands of DSF files taken together form the whole planet, but X-Plane only loads a few at a time to save RAM.

DSF files are binary distribution files; they are the end results of your scenery editing. You will use some editing tool to create scenery and then use that editor to save a DSF file as the final product. Always save your originals separately; some parts of your work (such as layers, selections, etc.) may be stripped away when saving a DSF.

DSF files do not contain all of the data needed to draw one tile; DSF files refer to other files called graphic resources for 3-D models, textures, etc. See the Anatomy of the X-Plane Scenery System document for more about the overall layout and interaction of all files in the scenery system.

Overall DSF Structure

There are two broad classes of data in a DSF file - the mesh primitives define the terrain mesh, and all others define "3-D stuff" that sits on top of the terrain mesh or enhance it.

DSF files also contain properties, which are pairs of string names and values. For example, the bounds of the DSF file are made of four properties, indicating the north, south, east and west edges. Usually you will not need to worry about properties, since they will be written by the tool you are using, but sometimes it may be advantageous to edit them directly.

DSF Meshes

The entire area of the DSF (bounded by latitude and longitude lines) is covered by the terrain mesh. The terrain mesh is a set of triangles that define the surface of the earth in 3-D.

Triangles are the only element you can use to create terrain mesh. If you need a square, use two triangles.

The entire area of the mesh must be covered by at least one triangle--no holes are allowed! You may cover an area with more than one triangle to create complex graphics effects.

Triangles in the mesh can be physical or non-physical. A physical triangle is used by the physics engine--the plane can crash into it. A non-physical triangle is not used by the physics engine and the plane will fly through it.

You must guarantee that every point in the mesh is covered by exactly one physical triangle. If you have additional layers of triangles (for effects) on the mesh, do not render them physical, as physical triangles require more CPU processing and RAM.

A triangle can also be flagged as an "overlay" triangle. If you draw two triangles on top of each other, you must mark the second one as an overlay; X-Plane will make sure the two draw cleanly. Without the overlay flag, you will get artifacts (Z-Buffer thrash). So for a given set of triangles in the same location:

• The "bottom" one (first one drawn, see below) should be physical but not an overlay.

"* All others should be non-physical but be flagged as overlays.

Other mesh requirements:

• The edges of triangles on the border of the mesh should have their coordinates on the exact latitude/longitude boundaries of the DSF so that the whole area is covered.
• The vertex of one triangle should not meet the edge of another; OpenGL will draw this with artifacts.
• If two triangles are going to be overlaid, they should be coplanar.
• You must have exactly one physical triangle under any given latitude/longitude coordinate within the DSF.
• You must have at least one triangle under any given latitude/longitude coordinate within the DSF.
• The mesh should have at least 15-20 triangles on a side. Any fewer and the curve of the earth will be chunky, because, while the triangle mesh is curved, individually triangles are not.
• Try to avoid using more than 1,000,000 triangles...this tends to bog down X-Plane. This upper limit will grow, though, as faster machines become available.

Within those requirements, the mesh can be any shape you want.

Triangle coordinates are specified in latitude and longitude in degrees, and elevation in meters above mean sea level.

Please note that right now due to the mesh requirements, cliffs with overhangs are not yet possible--no two physical triangles may be on top of each other. A future X-Plane may relax this requirement to make overhang cliffs possible.

Mesh Layers, Patches, and Levels of Detail

First of all, a terrain type is a texture, the basic way we "paint" our triangles. A terrain type includes all textures used and any special info about how to use them (e.g. projection, how bumpy it is, night lighting, etc.)

The terrain mesh is built in layers. Each layer contains triangles of a single uniform terrain type. You may use the same terrain type in more than one layer, but try to minimize the number of layers--more layers means slower frame rate.

Your triangles are drawn by layer in the same order as the layers occur in the DSF. Within a layer, overlay triangles are drawn after non-overlay triangles. Depending on the tools you use to make DSFs, you may have direct control over layers or you may not. Given a series of triangles in the same location, but from different layers, they will overlay in the order of the layers to form potentially complex texturing effects.

Within a layer for all non-overlay (or all overlay) triangles, the order they are drawn is chosen by X-Plane for maximum frame rate and may vary with the camera angle.

Each layer's triangles are further divided into patches. A patch is just a collection of triangles. Patches define the "groups" of triangles that X-Plane chooses to draw all together or not. Basically an entire patch is drawn even if a little is onscreen.

All triangles from a patch must be part of the same layer (the patch itself is part of the layer). Within a patch, all triangles are either physical or not, and overlay or not. The triangles in a patch do not have to be touching. The edges of the patch can be any shape--they do not have to be square.

A general guideline: you want at least 100 triangles per patch if possible, and you want your patches to be smaller than 3x3 km in size. But given a choice between a patch with too few triangles and a patch that is too big, you may want to go for the big patch. Patches should not be much larger than 25x25 km in size.

Each patch has a level of detail (LOD)--a range of distances for which it will be drawn. You can therefore provide alternate versions of each patch with varying amounts of triangles. A few requirements:

• Put all of your hard polygons in the highest LOD (the one shown at the closest distance); the rule of one hard triangle per point applies across all LODs, not just the currently drawn one.
• Ideally give each LOD the same footprint so that it does not overlap its neighbors. Remember that due to distance differences different patches with the same LOD range will change visibility at different times. So if you have high and low LOD patches, at any one time a mix of high and low will be visible.
• You do not have to use the same layer for different LODs--the LOD values are just a filter on whether a patch is drawn. You could use terrain type 1 for the patch under an airport from 0-10 km and then terrain type 2 for the patch under an airport from 10-20 km.

X-Plane will not catch logic errors in LODs--you will just see strange results, like no terrain.

Mesh Texturing

The terrain type for a given layer defines how the triangles from that layer in the mesh are textured. You have a few basic options. X-Plane can place the texture for you based on a resolution you set (e.g. the whole texture is 2 km x 2 km), or you can place the texture by hand, providing texture coordinates for each vertex in the mesh, similar to an object. In addition, a texture can optionally repeat at its edges.

You can also use a second texture for night lighting or a second texture for an alpha mask, or use the alpha channel from the basic texture as a mask that shows through to the layer below it.

Mesh Parameters

Each vertex on the mesh has coordinates in latitude/longitude/elevation, a "normal" (a description of the slope of the terrain at that point) and optionally zero or more numbers indicating texture coordinates, border blending levels, etc. DSF is a flexible format--any number of parameters can be added to a mesh point. How they are interpreted depends on the terrain type. The TER File Specification has detailed information on how mesh parameters and terrains are linked up. Usually if you make a DSF with a tool this will be handled for you.

Mesh Border Conformance

When two DSF tiles are next to each other, if their edges do not align, X-Plane will move the west and south edge borders to match the east and north edge borders of the adjacent tile, to form a smooth mesh. However if your mesh contains too few triangles on the edges, this will not work. For this reason, try to have an average of _____ triangles on each side of your mesh, approximately.

Mesh Performance

The performance characteristics of the mesh are a little surprising and worth enumerating.

X-Plane frame rate is affected by the total number of triangles plus the total number of patches plus the total number of layers.

In other words, a mesh with one layer, one patch and 20,000 triangles will be faster to draw in its entirety than a mesh of one layer and 20,000 patches, each with one triangle. Both of these will be faster to draw in their entirety than a DSF with 20,000 layers, each having one patch of one triangle each.

However, things that are off screen may not be drawn. So it is advantageous to minimize the number of patches and layers, but not to the point where all of your scenery is drawn all of the time. Remember that X-Plane always draws an entire patch even if only a tiny bit is on screen.

With modern hardware, triangles tend to be cheaper-by-the-dozen; drawing a patch of less than 100 triangles is about as fast as drawing a patch of 100 triangles, so you don't want lots of small patches. Even after 100 triangles, more triangles generally result in higher overall throughput.

LOD is therefore a double-edged sword; you can use LOD to cut down your total triangle count by drawing fewer triangles for far-off patches, but in doing so you must use two patches. Drawn patches hurt frame rate more than not-drawn patches, but both have a cost.

For this reason, you should only utilize LOD when you can make a significant reduction in the number of triangles. Also remember that you always want at least 100 triangles per patch, so having a near patch size of 100 triangles and a far patch size of 10 triangles is not a win!

3-D Clutter

The terrain mesh is a mandatory part of a DSF and is always used fully by X-Plane. 3-D clutter specifies additional 3-D things on top of your mesh; the user's rendering settings may filter parts of the 3-D clutter out.

The terrain mesh is pretty specific; you specify the exact triangles you want and how they are textured. By comparison, 3-D clutter is more abstract. In your DSF you indicate a highway; a separate graphic resource defines how it is drawn. (In a DSF you specify a terrain type by a graphic resource too, but the 3-D clutter graphic resources tend to be more high level.)

These are the types of 3-D clutter supported in X-Plane 9:

• Objects (OBJ)--you specify a location and rotation and a 3-D model is placed on the surface of your scenery.
• Facades (FAC)--you provide a polygonal "floor plan" for a building and a height in meters and a building is extruded on the surface of your terrain.
• Network (NET)--you provide an interconnected set of lines and highways and train tracks and power lines are extruded along the network.
• Forests (FOR)--you provide a polygonal outline of the extent of the forest and X-Plane fills it with 3-D trees.
• Beach (BCH)--you provide the polygonal outline of a water body and X-Plane surrounds its edges with beach or sand overlays.

All of the 3-D clutter is placed on your mesh directly, except for road networks; each network segment contains an MSL height - this allows you to specify the exact height of bridges and overpasses.

3-D Clutter and DSF Files

DSF files specify 3-D clutter by one of three kinds of "primitives," or paintbrushes for specifying 3-D clutter:

• 2-D Points (latitude/longitude) are used for objects. A rotation is provided per object to orient the object. Generally, placing objects will be a matter of clicking to specify where you want it.
• Chains of 2-D points are used for road networks. Where roads connect, a unique number for the intersection called a "junction ID" helps X-Plane understand that chains of roads are connected. So when two roads meet at a 4-way stop, they share a single point; when one highway overpasses another there is no shared point. Each chain has a road type which decides whether it is a highway or city street, etc. The numeric types for chains are defined in the .net file so you can enhance this specification.
• Polygonal rings of points are used for facades, forests, and beaches. Generally they provide a polygon outline on the surface of the DSF that is then somehow processed. In the case of a facade, the building is extruded up from the polygon to a specified height. In the case of a beach, the ring represents the path the beach takes. (A beach ring can also be specified as a non-closed ring.) In the case of a forest, the trees are planted within the polygon.

A polygon is made up of one or more winding, and each winding is basically a ring. The first ring is counter clockwise and specifies the outside of the polygon; if there are more windings, they are clockwise and specify holes in the interior. This for example lets you fill in trees but then make a hole in the tree cover where a lake is present.

Multiple windings (polygons with holes) are only allowed for forests; you cannot put a hole in a facade building or beach.

3-D Clutter and Performance

3-D clutter can affect performance in the following way:

• Objects take up little RAM but hit frame rate a lot. They do not take long to load.
• Facades take up a lot of RAM but don't hit frame rate a lot. They take a while to load.
• Road networks take up some RAM and don't hit frame rate a lot. They take a while to load.
• Forests take up a lot of RAM and don't hit frame rate a lot. They take a while to load.
• Beaches don't take up much RAM, don't take long to load, and don’t hit frame rate.

The user can vary the density of objects and facades using a menu. This will randomly remove objects from the DSF. You can put some properties into the DSF to indicate that some objects or facades must always be drawn. This will prevent landmarks from being eliminated. See the DSF File Specification for more info.

Road networks can be thinned out by the user too; for example, all local roads can be stripped out. Right now X-Plane just "knows" what type of roads to rip out, but a future extension of the .net file format will let you customize which road types are kept at various settings.

Forest density is affected by a user setting, as well as the .for file itself, which specifies the tree density when X-Plane's settings are maxed out.