The UAW_Extension_Terrain_API Interface

Overview

UAW is callback-based; terrain extensions pass their functions to UAW by implementing the UAW_Extension_Terrain_API interface.

Extensions must implement the functions of this interface.

The callbacks must remain available to UAW throughout the entire runtime of the process! If you use a garbage-collected or interpreted language, mind memory pinning!

This chapter gives a quick overview; detailled examples follow.

Lifetime Management

populateScenario()

Called exactly once by UAW when the scenario initializes. Gives extensions the opportunity to place buildings by using the context-sensitive API that is being passed.

Since a terrain may be used in different scenarios, place only buildings which are independent of specific scenarios!

unload()

Called at most once by UAW when the scenario exits and the terrain is no longer used. If you have any resources to release, do it here.

Tile Management

Terrain extensions can manage per-tile information via UAW_Extension_TerrainTile pointers. This type is opaque to UAW – it is fully under control over the extension; UAW never accesses it. Use it for whatever you like.

UAW_Extension_TerrainTile * loadTileAt(int indexNorth, int indexEast)

Create the extension’s data for the specified tile. Return NULL if there is no tile in this specific place, or if the extensions does not have any data for this tile.

The indices may be beyond terrain bounds! Check them if you cannot handle that!

releaseTile(UAW_Extension_TerrainTile *)

Release the extension’s data for this tile.

Terrain Views

Terrain extensions can manage per-view information via UAW_Extension_TerrainView pointers. This type is opaque to UAW – it is fully under control over the extension; UAW never accesses it. Use it for whatever you like.

UAW_Extension_TerrainView * onViewCreate(int indexNorth, int indexEast, int range)

Create the extension’s data for a new view. The viewer is placed at the given tile indices. The viewing range is given in tiles, too. Return NULL if there is nothing to manage.

onViewChange(UAW_Extension_TerrainView * view, int indexNorth, int indexEast, int range)

Either the viewer has moved to a different tile (as specified by the given tile indices) or the viewing range has changed.

onViewDestroy(UAW_Extension_TerrainView * view)

The specified view has ceased to exist. Release all data associated with it.

Rendering

TODO

Map Views

UAW can use terrain maps for several reasons: For display on flight control systems, or for enhancing the GUI.

Maps are handled very similar to terrain views: Through an opaque pointer type UAW_Extension_TerrainMapView that is filled by extensions with whatever they need to manage maps.

UAW_Extension_TerrainMapView * createMapView(UAW_API_StartScreens *)

TODO

drawMap(UAW_API_Screen *)

TODO

destroyMapView(UAW_API_StopScreens *, UAW_Extension_TerrainMapView *)

TODO

Physics

Terrain extensions provide a small set of collision detection functions to UAW. This set is used to perform complex physics interactions with vehicles and bullets.

int LEGACY_tileMaxElevation(UAW_Extension_TerrainTile *)

TODO

UAW_Lvl_ElevationAndNormal elevationAt(UAW_Extension_TerrainTile *, UAW_NE_float)

TODO

UAW_TerrainRayHit rayVsTerrainTile(UAW_Extension_TerrainTile *, UAW_NED_float origin, UAW_NED_float direction)

TODO

onExplosion(…)

TODO

Gameplay

UAW_Scn_Party territoryOf(UAW_Extension_TerrainTile *, UAW_NE_float)

TODO