8.3 地形分页
8.1 的 Paging 是通用机制,8.2 的 Grid2D 决定「哪页该加载」,但页的内容从哪来?对地形来说答案由 TerrainPagedWorldSection 给出:它继承 PagedWorldSection,把「分页分区」与「TerrainGroup」绑在一起——页 ID 就是地形格子坐标,页的加载/卸载自动落到 TerrainGroup 的 defineTerrain / loadTerrain / unloadTerrain。这是整个第八章的收尾:通用分页 + 网格策略 + 地形内容。
本章与站内既有内容的分工
helio 四卷没有分页;webarch 卷讲过流式加载思路。这里解析真实 OGRE 的 TerrainPagedWorldSection:init/syncSettings 的设置桥接、pageID ↔ (x,y) 的双向转换(7.1 已见过 packIndex,这里看它如何与分页对接)、以及 mLoadingIntervalMs 的加载节流。
为什么是 PagedWorldSection 子类,而不是 PageContent
OGRE 的注释给出了设计理由:地形受益于「相邻块布局」的直接知识,而这种布局又与分页策略紧密耦合,所以干脆把地形分页做成 PagedWorldSection 的子类,自动配好正确类型的 Grid2DPageStrategy 并从地形设置推导参数:
// Components/Terrain/include/OgreTerrainPagedWorldSection.h:TerrainPagedWorldSection(v14.6.3 源码摘录,已删减)
/** A world section which includes paged terrain.
Rather than implement terrain paging as a PageContent subclass, because terrain
benefits from direct knowledge of neighbour arrangements and the tight
coupling between that and the paging strategy, instead we use a PagedWorldSection
subclass. This automatically provides a PageStrategy subclass of the
correct type (Grid2DPageStrategy) and derives the correct settings for
it compared to the terrain being used. This frees the user from having to
try to match all these up through the generic interfaces.
*/
私有成员里除地形组外,还多了一条「正在加载队列」与节流参数:
// Components/Terrain/include/OgreTerrainPagedWorldSection.h:TerrainPagedWorldSection 私有成员(v14.6.3 源码摘录)
private:
TerrainGroup* mTerrainGroup;
TerrainDefiner* mTerrainDefiner;
std::list<PageID> mPagesInLoading;
bool mHasRunningTasks;
unsigned long mNextLoadingTime;
uint32 mLoadingIntervalMs;
构造函数里 mLoadingIntervalMs(900)——两页之间至少隔 900ms,避免一次性把几十块地形塞进 IO。
init 与 syncSettings:把地形设置灌进网格策略
init(TerrainGroup*) 接管一个现成的地形组,然后清空所有已加载地形——从今往后加载/卸载全由分页系统决定:
// Components/Terrain/src/OgreTerrainPagedWorldSection.cpp:init(v14.6.3 源码摘录)
void TerrainPagedWorldSection::init(TerrainGroup* grp)
{
if (mTerrainGroup == grp)
return;
if (mTerrainGroup)
OGRE_DELETE mTerrainGroup;
mTerrainGroup = grp;
syncSettings();
// Unload all existing terrain pages, because we want the paging system
// to be in charge of this
mTerrainGroup->removeAllTerrains();
}
syncSettings() 是桥接核心:把地形组的对齐方向映射成网格模式、把原点和地形世界尺寸交给网格策略——注意格子尺寸就是 terrainWorldSize,不是某个独立配置:
// Components/Terrain/src/OgreTerrainPagedWorldSection.cpp:syncSettings(v14.6.3 源码摘录)
void TerrainPagedWorldSection::syncSettings()
{
// Base grid on terrain settings
Grid2DPageStrategyData* gridData = getGridStrategyData();
switch (mTerrainGroup->getAlignment())
{
case Terrain::ALIGN_X_Y:
gridData->setMode(G2D_X_Y);
break;
case Terrain::ALIGN_X_Z:
gridData->setMode(G2D_X_Z);
break;
case Terrain::ALIGN_Y_Z:
gridData->setMode(G2D_Y_Z);
break;
}
gridData->setOrigin(mTerrainGroup->getOrigin());
gridData->setCellSize(mTerrainGroup->getTerrainWorldSize());
}
pageID ↔ 格子坐标:packIndex / unpackIndex
网格策略算出的 PageID 与地形格子 (x, y) 是同一个数——7.1 的 TerrainGroup::packIndex 打包,这里由 unpackIndex 还原符号:
// Components/Terrain/src/OgreTerrainGroup.cpp:unpackIndex(v14.6.3 源码摘录)
void TerrainGroup::unpackIndex(uint32 key, long *x, long *y)
{
// inverse of packIndex
// unsigned versions
uint16 y16 = static_cast<uint16>(key & 0xFFFF);
uint16 x16 = static_cast<uint16>((key >> 16) & 0xFFFF);
*x = static_cast<int16>(x16);
*y = static_cast<int16>(y16);
}
pageID 的高 16 位是 x、低 16 位是 y,先无符号取位、再 static_cast<int16> 恢复符号——这样负格子(如 (2,-1))也能来回无损。
loadPage:入队 + 节流起点
TerrainPagedWorldSection::loadPage 先查「已加载」与「正在加载」两张表,都不在才入队;队列从空变 1 时启动后台任务(同步模式直接就地跑完 request+response):
// Components/Terrain/src/OgreTerrainPagedWorldSection.cpp:loadPage(v14.6.3 源码摘录,已删减)
void TerrainPagedWorldSection::loadPage(PageID pageID, bool forceSynchronous)
{
if (!mParent->getManager()->getPagingOperationsEnabled())
return;
PageMap::iterator i = mPages.find(pageID);
if (i == mPages.end())
{
std::list<PageID>::iterator it = find( mPagesInLoading.begin(), mPagesInLoading.end(), pageID);
if(it==mPagesInLoading.end())
{
mPagesInLoading.push_back(pageID);
mHasRunningTasks = true;
}
// no running tasks, start the new one
if(mPagesInLoading.size()==1)
{
if(forceSynchronous)
{
handleRequest(NULL, NULL);
handleResponse(NULL, NULL);
}
else
{
Root::getSingleton().getWorkQueue()->addTask([this]() {
handleRequest(NULL, NULL);
if(mPagesInLoading.empty())
return;
// continue loading in main thread
Root::getSingleton().getWorkQueue()->addMainThreadTask([this]() { handleResponse(NULL, NULL); });
});
}
}
}
PagedWorldSection::loadPage(pageID, forceSynchronous);
}
最后仍然调用基类的 loadPage 创建 Page 对象——基类管「页的存在」,子类管「页的内容」。
handleRequest / handleResponse:后台 define、主线程 load、900ms 节流
两个回调构成完整的加载流水线:
// Components/Terrain/src/OgreTerrainPagedWorldSection.cpp:handleRequest(v14.6.3 源码摘录,已删减)
WorkQueue::Response* TerrainPagedWorldSection::handleRequest(const WorkQueue::Request* req, const WorkQueue* srcQ)
{
if(mPagesInLoading.empty())
{
mHasRunningTasks = false;
return NULL;
}
unsigned long currentTime = Root::getSingletonPtr()->getTimer()->getMilliseconds();
if(currentTime < mNextLoadingTime)
{
// Wait until the next page is to be loaded -> we are in background thread here
OGRE_THREAD_SLEEP(mNextLoadingTime - currentTime);
}
PageID pageID = mPagesInLoading.front();
// call the TerrainDefiner from the background thread
long x, y;
// pageID is the same as a packed index
mTerrainGroup->unpackIndex(pageID, &x, &y);
if(!mTerrainDefiner)
mTerrainDefiner = OGRE_NEW TerrainDefiner();
mTerrainDefiner->define(mTerrainGroup, x, y);
return NULL;
}
// Components/Terrain/src/OgreTerrainPagedWorldSection.cpp:handleResponse(v14.6.3 源码摘录,已删减)
void TerrainPagedWorldSection::handleResponse(const WorkQueue::Response* res, const WorkQueue* srcQ)
{
if(!mPagesInLoading.empty())
{
PageID pageID = mPagesInLoading.front();
// trigger terrain load
long x, y;
// pageID is the same as a packed index
mTerrainGroup->unpackIndex(pageID, &x, &y);
mTerrainGroup->loadTerrain(x, y, false);
mPagesInLoading.pop_front();
unsigned long currentTime = Root::getSingletonPtr()->getTimer()->getMilliseconds();
mNextLoadingTime = currentTime + mLoadingIntervalMs;
// Continue loading other pages
Root::getSingleton().getWorkQueue()->addTask([this]() {
handleRequest(NULL, NULL);
if(mPagesInLoading.empty())
return;
// continue loading in main thread
Root::getSingleton().getWorkQueue()->addMainThreadTask([this]() { handleResponse(NULL, NULL); });
});
}
else
mHasRunningTasks = false;
}
| 阶段 | 线程 | 动作 |
|---|---|---|
handleRequest | 后台 | 节流等待;unpackIndex 还原格子坐标;TerrainDefiner::define(x,y) 生成地形定义 |
handleResponse | 主线程 | unpackIndex;loadTerrain(x,y,false) 载入;出队;mNextLoadingTime = now + mLoadingIntervalMs |
| 尾递归 | 后台 | 队列非空则继续下一页 |
默认的 TerrainDefiner::define 只是转发到 terrainGroup->defineTerrain(x, y),用户可以子类化它提供自己的定义来源。
unloadPage:在队移除 / 已加载卸载
卸载分两种情况:页还在加载队列里,则只从队列摘除(后台任务稍后会发现它不存在);已经加载的页,则 unpackIndex 后直接 unloadTerrain(x, y):
// Components/Terrain/src/OgreTerrainPagedWorldSection.cpp:unloadPage(v14.6.3 源码摘录)
void TerrainPagedWorldSection::unloadPage(PageID pageID, bool forceSynchronous)
{
if (!mParent->getManager()->getPagingOperationsEnabled())
return;
PagedWorldSection::unloadPage(pageID, forceSynchronous);
std::list<PageID>::iterator it = find( mPagesInLoading.begin(), mPagesInLoading.end(), pageID);
// hasn't been loaded, just remove from the queue
if(it!=mPagesInLoading.end())
{
mPagesInLoading.erase(it);
}
else
{
// trigger terrain unload
long x, y;
// pageID is the same as a packed index
mTerrainGroup->unpackIndex(pageID, &x, &y);
mTerrainGroup->unloadTerrain(x, y);
}
}
源码定位
Components/Terrain/include/OgreTerrainPagedWorldSection.h:类注释(51)、init(99)、setLoadingIntervalMs(141)、TerrainDefiner(150)、私有成员(167)Components/Terrain/src/OgreTerrainPagedWorldSection.cpp:构造函数默认mLoadingIntervalMs(900)(44)、init(68)、syncSettings(84)、loadPage(216)、unloadPage(255)、handleRequest(278)、handleResponse(308)Components/Terrain/src/OgreTerrainGroup.cpp:packIndex(798)、unpackIndex(814)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面用纯 C++ 复现「地形分页」的桥接与节流。它与 src/08-3-terrain-paging.cpp 逐字节一致:
// file: src/08-3-terrain-paging.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/08-3-terrain-paging.cpp -o bin/08-3-terrain-paging && ./bin/08-3-terrain-paging
//
// 复现 TerrainPagedWorldSection 的桥接(对应 OgreTerrainPagedWorldSection.cpp
// 68- init、84- syncSettings、216- loadPage、255- unloadPage、278- handleRequest、
// 308- handleResponse;OgreTerrainGroup.cpp 798- packIndex / 814- unpackIndex):
// init() 接管 TerrainGroup 后 removeAllTerrains(),让分页系统负责地形加载/卸载;
// syncSettings() 把 TerrainGroup 的 alignment/origin/terrainWorldSize 灌进网格策略;
// pageID 与格子 (x,y) 用 packIndex/unpackIndex 双向桥接(int16 符号恢复);
// loadPage 把「不在已加载且不在队列」的页推入 mPagesInLoading;
// 节流:mLoadingIntervalMs 决定两页之间的最少毫秒间隔,handleRequest 里
// currentTime < mNextLoadingTime 时睡眠等待;handleResponse 加载后
// 更新 mNextLoadingTime = currentTime + interval;
// unloadPage:仍在队列的页只移除,已加载的页 unpackIndex->unloadTerrain(x,y)。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <algorithm>
#include <cstdint>
#include <list>
#include <vector>
namespace ogre_repro {
using PageID = uint32_t;
enum GridMode { G2D_X_Y, G2D_X_Z, G2D_Y_Z };
enum Alignment { ALIGN_X_Y, ALIGN_X_Z, ALIGN_Y_Z };
// 简化 TerrainGroup(对应 OgreTerrainGroup.h:packIndex/unpackIndex、defineTerrain、
// loadTerrain、unloadTerrain、removeAllTerrains)
struct TerrainGroup {
Alignment alignment = ALIGN_X_Z;
float originX = 0.0f, originY = 0.0f, originZ = 0.0f;
float terrainWorldSize = 4096.0f;
int definedCount = 0; // defineTerrain 调用次数
int loadedCount = 0; // 已加载地形块数
int unloadedCount = 0; // unloadTerrain 调用次数
// 对应 packIndex(OgreTerrainGroup.cpp 798-)
PageID packIndex(long x, long y) const {
int16_t xs16 = static_cast<int16_t>(x);
int16_t ys16 = static_cast<int16_t>(y);
uint16_t x16 = static_cast<uint16_t>(xs16);
uint16_t y16 = static_cast<uint16_t>(ys16);
return (static_cast<PageID>(x16) << 16) | y16;
}
// 对应 unpackIndex(OgreTerrainGroup.cpp 814-):int16 符号恢复
void unpackIndex(PageID key, long* x, long* y) const {
uint16_t y16 = static_cast<uint16_t>(key & 0xFFFF);
uint16_t x16 = static_cast<uint16_t>((key >> 16) & 0xFFFF);
*x = static_cast<int16_t>(x16);
*y = static_cast<int16_t>(y16);
}
void defineTerrain(long, long) { ++definedCount; }
void loadTerrain(long, long) { ++loadedCount; }
void unloadTerrain(long, long) { ++unloadedCount; }
void removeAllTerrains() { loadedCount = 0; }
};
// 对应 TerrainPagedWorldSection(OgreTerrainPagedWorldSection.cpp)
class TerrainPagedWorldSection {
public:
TerrainPagedWorldSection()
: mHasRunningTasks(false), mLoadingIntervalMs(900), mNextLoadingTime(0) {}
// 对应 init()(68-):接管 TerrainGroup 并清空既有地形
void init(TerrainGroup* grp) {
mTerrainGroup = grp;
syncSettings();
mTerrainGroup->removeAllTerrains(); // 分页系统从此负责地形生命周期
}
// 对应 syncSettings()(84-):地形设置 -> 网格策略
void syncSettings() {
switch (mTerrainGroup->alignment) {
case ALIGN_X_Y: mMode = G2D_X_Y; break;
case ALIGN_X_Z: mMode = G2D_X_Z; break;
case ALIGN_Y_Z: mMode = G2D_Y_Z; break;
}
mOriginX = mTerrainGroup->originX;
mOriginY = mTerrainGroup->originY;
mCellSize = mTerrainGroup->terrainWorldSize;
}
GridMode getMode() const { return mMode; }
float getCellSize() const { return mCellSize; }
// 对应 loadPage(216-):不在已加载、不在队列则入队
void loadPage(PageID pageID) {
if (std::find(mLoaded.begin(), mLoaded.end(), pageID) != mLoaded.end()) return;
if (std::find(mPagesInLoading.begin(), mPagesInLoading.end(), pageID) !=
mPagesInLoading.end())
return;
mPagesInLoading.push_back(pageID);
mHasRunningTasks = true;
}
// 对应 handleRequest + handleResponse 的节流主循环;返回本步是否真正加载了一页
bool step(unsigned long now) {
if (mPagesInLoading.empty()) {
mHasRunningTasks = false;
return false;
}
if (now < mNextLoadingTime) return false; // 节流:未到窗口
PageID pageID = mPagesInLoading.front();
long x = 0, y = 0;
mTerrainGroup->unpackIndex(pageID, &x, &y); // handleRequest:后台 define
mTerrainGroup->defineTerrain(x, y);
mTerrainGroup->loadTerrain(x, y); // handleResponse:主线程 load
mLoaded.push_back(pageID);
mPagesInLoading.pop_front();
mNextLoadingTime = now + mLoadingIntervalMs; // handleResponse:更新节流窗
if (mPagesInLoading.empty()) mHasRunningTasks = false;
return true;
}
// 对应 unloadPage(255-):在队列则只移除,否则 unpackIndex->unloadTerrain
void unloadPage(PageID pageID) {
auto it = std::find(mPagesInLoading.begin(), mPagesInLoading.end(), pageID);
if (it != mPagesInLoading.end()) {
mPagesInLoading.erase(it);
} else {
long x = 0, y = 0;
mTerrainGroup->unpackIndex(pageID, &x, &y);
mTerrainGroup->unloadTerrain(x, y);
auto lit = std::find(mLoaded.begin(), mLoaded.end(), pageID);
if (lit != mLoaded.end()) mLoaded.erase(lit);
}
}
void setLoadingIntervalMs(uint32_t ms) { mLoadingIntervalMs = ms; }
uint32_t getLoadingIntervalMs() const { return mLoadingIntervalMs; }
size_t pendingCount() const { return mPagesInLoading.size(); }
bool hasRunningTasks() const { return mHasRunningTasks; }
private:
TerrainGroup* mTerrainGroup = nullptr;
GridMode mMode = G2D_X_Z;
float mOriginX = 0.0f, mOriginY = 0.0f, mCellSize = 0.0f;
std::list<PageID> mPagesInLoading;
std::vector<PageID> mLoaded;
bool mHasRunningTasks;
uint32_t mLoadingIntervalMs;
unsigned long mNextLoadingTime;
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// 默认节流间隔 900ms(OgreTerrainPagedWorldSection.cpp:44)
TerrainPagedWorldSection section;
CHECK_EQ(section.getLoadingIntervalMs(), 900u);
// init:接管 TerrainGroup,syncSettings 传参,并清空已加载地形
TerrainGroup group;
group.alignment = ALIGN_X_Z;
group.originX = 100.0f;
group.originY = 50.0f;
group.terrainWorldSize = 4096.0f;
section.init(&group);
CHECK_EQ(section.getMode(), G2D_X_Z); // ALIGN_X_Z -> G2D_X_Z
CHECK_EQ(section.getCellSize(), 4096.0f); // cellSize = terrainWorldSize
// packIndex/unpackIndex:pageID <-> 格子坐标 双向桥接
CHECK_EQ(group.packIndex(2, 1), 0x00020001u);
CHECK_EQ(group.packIndex(-2, -1), 0xFFFEFFFFu);
long x = 0, y = 0;
group.unpackIndex(0x00020001u, &x, &y);
CHECK_EQ(x, 2);
CHECK_EQ(y, 1);
group.unpackIndex(0xFFFEFFFFu, &x, &y); // 负格子符号恢复
CHECK_EQ(x, -2);
CHECK_EQ(y, -1);
// loadPage:入队并标记运行
PageID pid = group.packIndex(2, 1);
section.loadPage(pid);
CHECK_EQ(section.pendingCount(), 1u);
CHECK(section.hasRunningTasks());
// 重复 loadPage 不重复入队
section.loadPage(pid);
CHECK_EQ(section.pendingCount(), 1u);
// 首个页立即可加载(mNextLoadingTime 初始为 0)
CHECK(section.step(0));
CHECK_EQ(group.loadedCount, 1);
CHECK_EQ(group.definedCount, 1);
// 已加载页再次 loadPage 不入队
section.loadPage(pid);
CHECK_EQ(section.pendingCount(), 0u);
// 节流:第一页加载后 mNextLoadingTime = 0 + 900
section.loadPage(group.packIndex(1, 0));
CHECK(!section.step(500)); // 500 < 900:被节流
CHECK(section.step(900)); // 到达 900:加载第二页
CHECK_EQ(group.loadedCount, 2);
// unloadPage:已加载页 -> unloadTerrain(x, y)
section.unloadPage(pid);
CHECK_EQ(group.unloadedCount, 1);
// unloadPage:仍在队列的页只移除,不触发 unloadTerrain
section.loadPage(group.packIndex(0, 0));
section.unloadPage(group.packIndex(0, 0));
CHECK_EQ(group.unloadedCount, 1); // 未增加
return lab::report("08-3 地形分页");
}
本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 21/21 通过。
小结
TerrainPagedWorldSection继承PagedWorldSection,把TerrainGroup变成分页内容提供者;init接管后removeAllTerrains(),生命周期交给分页系统。syncSettings把alignment → Grid2D 模式、origin、terrainWorldSize → cellSize灌进网格策略。pageID与格子坐标(x,y)用packIndex/unpackIndex双向转换,int16 符号恢复支持负格子。loadPage只在「未加载且不在队列」时入队;后台handleRequest节流 +define,主线程handleResponse出队并loadTerrain。- 默认
mLoadingIntervalMs = 900ms,每两页之间至少间隔这么久,平滑 IO 峰值。 unloadPage分两种情况:还在队列只摘除,已加载则unpackIndex → unloadTerrain(x,y)。
阅读导航:上一节:8.2 分页策略 · 下一节:9.1 骨骼与骨节点 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。