libProcTer API reference
LibProcTer is a library for generating planetary terrains, suitable for use in realtime simulations like flight simulators. The library can use existing data and fill in missing data with procedural terrain generation.
These pages describe how to make landscape plugins for libProcTer, and how to use libProcTer in your own applications. The other pages provide documentation on the classes; the rest of this page will provide you some theory about the basic concepts used in libProcTer. You might need this theory for understanding the API and for succesfully using libProcTer.
At the detail levels used by libProcTer, it is impossible to store the map of an entire planet in RAM, or even on a single harddisk. Therefore, the surface is split into tiles, and at any moment in time, only the tiles that are necessary for a reasonably detailed landscape rendering are actually loaded. As the camera position changes over time, tile surfaces are continuously being loaded and unloaded.
libProcTer uses a square tile pattern, with multiple levels of detail. When the camera approaches a tile, and a more detailed version is needed, the tile is split into four smaller tiles (TODO: figure). Here, the original, larger tile is called the 'parent tile', and the four smaller tiles are its 'child tiles'. The parent tile is still kept in memory, and as soon as the camera moves away from the tile, the child tiles are removed, and the parent tile becomes active again.
For each tile, a 'tile surface' object is loaded. As this might involve loading files from disk, downloading data and/or procedural terrain generation, it is usually a time-consuming task. In order not to disturb the frame rate too much, this loading is done in a separate 'background process' (a thread), and once the loading has finished, the loaded surface is attached to the tile.
making realistic looking terrain is a complicated task, and a lot of possible approaches are possible. Therefore, libProcTer uses a plugin system for this task, where other programmers can use their own terrain generation algorithms in combination with libProcTer.
A plugin provides tile surface objects, with a derived virtual load() method for loading the surface data. A terrain loading algorithm has acces to:
-
The planet object, containing some generic information about the planet
-
The position of the tile on the planet surface
-
The size of the tile
-
The parent tile surface, and the three other tile surfaces that surround it at the parent level (TODO: figure)
-
And, of course, all things any piece of code has acces to, like the file system and network connections
Based on this, a plugin should generate:
-
The generic map layers used by libProcTer, like the color map and the height map
-
Optionally: any number of hidden map layers the plugin wants to use
Hidden map layers can be used for instance to store geological information. Child surfaces can have access to all map layers of their parent, if their parent allows this. In cases when the child surfaces know the exact type of the parent surfaces, they can obtain any kind of data from their parents by casting the parent pointer to the true type of the parent class. This can be useful e.g. for passing vector data, like the locations of rivers or craters.
