About Overlays

Revision History 6/3/10         Updated for Wiki 1/19/06        Initial Draft

Introduction to Overlays
X-Plane Scenery is divided into individual one-by-one degree tiles, represented in DSF format. DSF files come in two flavors:


 * Full DSFs contain a terrain mesh for the entire 1x1 degree tile and can contain any DSF elements (roads, objects, etc.). Only one full DSF is ever loaded 			for a tile.
 * Overlay DSFs contain only objects and polygons. More than one overlay can be loaded at a time for a tile.  The overlay appears as additional scenery on top of the full DSF.

Overlay DSFs make it possible to add or refine details in scenery. Because more than one overlay can be used for a tile, multiple airports or cities can be refined by independent authors.

X-Plane loads DSF overlays in the order of the prioritization or scenery packages; all overlays must be higher priority than the full DSF they will cover. Once X-Plane finds a full DSF it stops searching for additional files.

Specifying a DSF as an Overlay
The DSF property  indicates whether a DSF is an overlay. A value of 1 indicates an overlay; a value of 0, or the absence of this property indicates a full DSF.

Overlays must have all of the regular DSF atoms (even if they are empty); limits are enforced by not using primitives and definitions. Therefore there must be no terrain or network definitions in an overlay DSF.

Limits of DSF Overlays
Warning: X-Plane does not under normal operation attempt to detect violations of DSF overlay limits. An improperly built overlay may cause the sim to crash or induce an internal error.

The following restrictions apply to overlays, but not full DSFs:
 * Overlays may not contain any terrain definitions or terrain patches.
 * Overlays may not contain any vector segments or vector definitions.

Overlays may contain objects and any form of polygon.

DSF Exclusion Zones
The 3-d objects and other 3-d stuff in an overlay are drawn on top of the underlying terrain. Since the underlying base terrain may already include objects that would conflict with the overlay, overlays may need to include exclusion zones, or areas that will delete underlying scenery.

DSF overlay exclusion zones are always specified as rectangles, bounded by latitude and longitude lines. They can be as small as you want, and you can use as many of them as you want. However exclusion zones do slow down scenery load time, so using fewer larger zones is more efficient.

Exclusion zones act on the underlying base terrain and any overlays below the overlay being loaded. For example, if one overlay replaced the entire Manhattan island with skyscrapers, and another overlay (with higher priority) replaced only the empire state-building, then with appropriate exclusion zones the 3-d objects would be merged into one city.

Exclusion zones are categorized by the type of scenery they delete. If you want to remove all types of scenery for one area, use multiple zones with the same bounds.

Exclusion zones are specified via properties in your DSF. They are only legal in overlays. The keys for overlays are:


 * to exclude objects.
 * to exclude facade polygons.
 * to exclude forest poylgons.
 * to exclude beach polygons.
 * to exclude road network segments.

The value for each sim property is a box, of the form. For example,. To make multiple zones, simply repeat the keys. The order of the keys is not important.