Project Information

Proposal and discussion thread: http://www.ogre3d.org/forums/viewtopic.php?f=13&t=69553
Mercurial repository: https://bitbucket.org/xiaoxq/ogre_soc_tpi/overview
The basement project: SoC2011 Terrain Paging Improvements

Known Issues

Hiccups when loading page

Implementation Design

New Terrain File Format

To be able to load LOD asynchronously, we should save height/delta data separately according to the lowest level it belongs to. So the terrain file format has been adjusted as follows:

The new TERRAIN_CHUNK_ID has been upgraded to 2.
The LOD saving process happens at TerrainLodManager::saveLodData(); When a LOD is requested, the TerrainLodManager just open the file, skip the TERRAINGENERALINFO_CHUNK chunk, and skip the unmatched TERRAINLODDATA_CHUNK chunk, then read the height/delta data into memory. These are done at TerrainLodManager::readLodData();

LOD State Machine

Previously, the terrain has only 3 states: Not Prepared, Fully Prepared, Fully Loaded. But now LODs are loaded asynchronously, so the terrain may be only partially prepared/loaded. Every LOD gets its own 3-states, as shown below:

LOD Requests Interface and Implementation

The state machine looks somewhat complicated. Luckily we'll hide the details in TerrainLodManager. The interface for users is very simple:

class Terrain
{
  ...
  void load(int lodLevel, bool synchronous); //request a specified LOD
  void increaseLodLevel(bool synchronous); //increase the current LOD by 1
  void decreaseLodLevel(); //decrease the current LOD by 1
  ...
}

In fact, they are just proxies for TerrainLodManager, which holds three LOD status: HighestLodPrepared, HighestLodLoaded, TargetLodLevel.
Every LOD request will finally call the updateToLodLevel(int lodLevel, bool synchronous). It acts like:

• Update the TargetLodLevel.
• If TargetLodLevel is higher than HighestLodPrepared, prepare it/them
• If TargetLodLevel is higher than HighestLodLoaded, load it/them
• If TargetLodLevel is lower than HighestLodLoaded, unload it/them

Currently we won't unprepare LODs. If wanted, the rule is:

• If TargetLodLevel is lower than HighestLodPrepared, unprepare it/them

Asynchronous LOD Loading

Asynchronously-loading of LOD data is the core feature of this project, the logic is very simple, as shown below.

It's also the biggest source of bugs. My work is to make it safe and stable.

Guide for Users

How to make use of the Asynchronous-Loading feature

The simplest way is to manipulate the terrain LOD manually, I mean, calling the APIs above directly. As an example, you can run the EndlessWorld sample, and use PAGE-UP/PAGE-DOWN to increase/decrease terrains' LOD manually.
Another way is to ask an Auto-Update-Lod strategy to call those APIs for you. To support this, the TerrainGroup supplies APIs:
class TerrainGroup
{

...

/// Loads terrain's next LOD level.

void increaseLodLevel(long x, long y, bool synchronous = false);

/// Removes terrain's highest LOD level.

void decreaseLodLevel(long x, long y);

void setAutoUpdateLodStrategy(uint32 strategy);

/// Automatically checks if terrain's LOD level needs to be updated.

void autoUpdateLod(long x, long y, bool synchronous, const Any &data);

void autoUpdateLodAll(bool synchronous, const Any &data);

...
}

How to add my own strategy of Auto-Update-Lod

Weekly Progress

2012-04-29

• Create repository by importing from kuxv's, and create this wiki page.
• A small fix to make it compilable on my x64 system. Then it runs quite well.
• Merge new changesets from trunk.
• Confirm my development environment: Thinkpad T410s( Intel i5, Nvidia NVS 3100M, 8G memory ), Ubuntu 12.04 64bit. I also have a Win7 64bit, but only for testing.

2012-05-06

• Some code cleanup.

2012-05-14

• Keep on warming up with the code.
• Start drawing a sequence diagram to show the work flow of LOD and paging.

2012-05-20

• Finish the sequence diagram, and get to understand most of the previous implementation ideas.
• Have found some possible buggy point. See them above for detail.

2012-05-27

• Start reviewing the code, I think I have understood the idea deeply.
• Small refactoring, extract out a TerrainLodManager, which makes the Terrain component as clear as the original.(80% completed)

2012-06-03

• Almost finish extracting the LodManager from Terrain.
• Going to read height/delta once for all.

2012-06-10

• Alpha release.

2012-06-25

• Write some wiki.

2012-07-02

• Almost finished the Implementation Design section of the wiki.
• Use LodManager though no file bound.
• Fix an "Empty CPU Buffer" exception.

2012-07-10

• After 2 big fixes, it works quite better, now.
• But if set paging ON, it still has some bugs.