1. How it works
    1. Terrain Generation
    2. Data Compositing
    3. Drivers
      1. Building your own driver

How it works

A technical overview for developers.

Terrain Generation

osgEarth uses OSG's osgTerrain and PagedLOD mechanisms to dynamically create a terrain model as the user navigates the scene. When OSG determines that a PagedLOD child needs to be loaded, it invokes the osgEarth ".earth" pseudo-loader and passes it a TileKey? corresponding to the geospatial extent of the new tile. The pseudo-loader then invokes one or more osgEarth driver in order to create an osg::Image or osg::Heightfield for the new tile.

Though the process for making the terrain tiles is dynamic, the results are the same as if you had pre-generated the terrain model using a tool like  VirtualPlanetBuilder. This is advantageous in that you can still use all of osgTerrain's run-time features like vertical scaling and heightfield resolution adjustment.

Data Compositing

todo.

Drivers

osgEarth uses drivers to read image and elevation tiles. In the osgEarth library, these are called TileSources. The job of a TileSource is to generate an image or heightfield tile for a given TileKey?.

osgEarth utilizes OSG's existing plugin architecture by implementing all drivers as osgDB::ReaderWriter? psuedo-loader plugins. But instead of returning osg::Image and osg::Heightfield objects directly, each osgEarth driver implements the readObject() method and returns a TileSource instance. That TileSource instance is then used to create tiles.

It should be noted that to avoid plugin naming conflicts, all osgEarth driver plugins are named in the form: osgDB_osgearth_drivername. Because these TileSource plugins are OSG psuedo-loaders, they are expected to handle a single filename of the format ".osgearth_drivername". All driver plugins are passed the key/value pairs in the earth file via the osgDB::ReaderWriter::Options object which are accessible via the osgDB::ReaderWriter::Options::getPluginData function. These settings are then used by the plugin to configure the new TileSource?.

Let's take the TMS TileSource plugin as a simple example. 

<map name="TMS" type="geocentric">
   <image name="TMS" driver="tms">
     <url>http://labs.metacarta.com/wms-c/Basic.py/1.0.0/satellite-merc/</url>
   </image>
</map>

The above map file has a single image source named "TMS" using the "tms" driver. When the map is parsed, osgEarth sees that the requested driver is named "tms" and it attempts to load a TileSource for the image by calling osgDB::readObjectFile(".osgearth_tms"). The url parameter will automatically be passed to the TMS driver via the Options object.

Building your own driver

If you want to add a new driver, you need to do two things:

* Create a class that implements the osgEarth::TileSource? interface; * Create an osgDB::ReaderWriter? implementation that returns your osgEarth::TileSource? instance from the readObject() method.

The easier way to get started it to simply copy an existing driver and use it as a template. And if you need them, the osgEarth library includes various utilities that make it easy to parse XML, fetch data over HTTP, etc.