Undertanding DSF

	Revision History
		12/16/04 - Initial Draft.

NOTICE: I am looking for anyone willing to help improve this document. It is aimed at general scneery autors and could benefit from illustrations, rewrites, anything.


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

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 tool to
create scenery and then Save as... DSF to make the final product.  Always save your originals; 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 scenery system overview 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 dadta 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 lat and lon lines) are 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!  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 lcoation:

 - The "bottom" one (first one drawn, see below) should be physical but not an overlay.
 - All others should be non-physical but be overlay.

Other mesh requirements:

- The edges of triangles on the border of the mesh should have their coordinate son the exact lat/lon boundaries of the DSF
so 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 overlayed, they should be coplanar.
- You must have exactly one physical triangle under any given lat/lon coordinate within the DSF.
- You must have at least one triangle under any given lat/lon coordinate within the DSF.
- The mesh should have at least 15-20 triangles on a side...any bigger 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.  But the upper limit will grow as faster
  machines become available.

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

Triangle coordinates are specified in latitude, longitude in degrees, and elevation in meters MSL.

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

MESH LAYERS, PATCHES AND LOD

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
framerate.

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 al non-overlay (or all overlay) triangles, the order they are drawn is chosen by x-plane for maximum framerate
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 - 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
   diferent 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 typpe 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 2km x 2 km).
 - Or you can place the texture by hand, providing texture coordinates for each vertex in the mesh, similar to an object.
 - 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.

(to add - we need to explain border texturing and composite border texturing - yikes!)

MESH PARAMETERS

Each vertex on the mesh has coordinates in lat/lon/el, 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 interpretted depends on the terrain type.  The .ter file spec 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.

(todo - I need to lookup the matching number!)

MESH PERFORMANCE

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

X-Plane framerate 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 entirity than a mesh of
one layer, 20,000 patches each with one triangle, and both will be faster to draw in their entirity than a DSF with
20,000 layers, each with one patch each with one triangle.

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 tris is about as fast as drawing
a patch of 100 tris, so you don't want lots of small patches.  Even after 100 tris, the more tris, generally the higher the 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 framerate more than not-drawn patches, but both have a cost.
So only utilize LOD when you can make a significant reduction in the number of triangles.  Also remember that you always want at least
100 tris per patch, so having a near patch size of 100 tris and a far patch size of 10 tris 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 grapihc resources tend to be more high level.)

These are the types of 3-d clutter supported in x-plane 8:

 - 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 teh surface of your terrain.
 - Network (NET) - you provide an interconnected set of lines and highways and train tracks and powerlines are extruded
 				   along the network.

In addition X-plane 815 and later support two additional types of clutter:

 - 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 tree kinds of "primitives", or paintbrushes for specifying 3-d clutter:

- 2-d Points (lat/lon) 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 
	"jucntion 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 hsa 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 spec.
	
- 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 - 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 
will 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...here is some info:

- Objects take up little RAM but hit framerate a lot.  They do not take long to load.
- Facades take up a lot of RAM but don't hit framerate a lot.  They take a while to load.
- Road networks take up some RAM and don't hit framerate a lot.  They take a while to load.
- Forests take up a lot of RAM and don't hit framerate a lot; they take a while to load.
- Beaches don't take up much RAM and don't take long to load or hit framerate.

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 getting eliminated.  See the DSF spec 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 ot 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.